Audit Log
Rule
Every mutating action automatically records an audit event — no wiring
needed. The framework captures who/what/when/from-where at the defineAction
seam, redacts credentials, and attributes the change to a human or the agent
(with the agent thread/turn that caused it). You only touch audit config to
make events more useful (declare the target) or to opt a read in / a noisy
write out.
This is distinct from:
- observability — sampled agent-run telemetry (traces, evals), developer-facing.
- tracking — fire-and-forget product analytics to external SaaS.
Audit is complete, durable, locally queryable, and scoped to the data it
describes.
Declare the target so it lands in the owner's trail
By default an event is scoped to the actor (you see your own changes and the
agent's changes on your behalf). To make a change to a shared resource show up
in the owner's audit trail, declare the target:
defineAction({
description: "Delete a recording",
schema: z.object({ id: z.string() }),
audit: {
// type + id label the event; ownerEmail/orgId/visibility scope who can read it.
target: (args, result, meta) => ({
type: "recording",
id: args.id,
// Optional — defaults to the actor. Set when editing someone else's resource.
ownerEmail: result?.ownerEmail,
visibility: "org",
}),
summary: (args) => `Deleted recording ${args.id}`,
},
run: async (args, ctx) => { /* ... */ },
});
target, ownerEmail, visibility, and summary are all optional. The
minimum useful addition is target: () => ({ type, id }).
Defaults and how to override them
- Mutations (anything not GET /
readOnly) are audited automatically.
- Read-only actions are skipped. Audit a sensitive read (secret access, bulk
export) with
audit: { onRead: true }.
- High-frequency framework actions (app-state sync, context-xray, navigate,
appearance) are skipped by default. Force one on with
audit: { enabled: true }.
- Opt a noisy write out with
audit: { enabled: false }.
- Skip capturing arguments (large/sensitive payloads) with
audit: { recordInputs: false }. Inputs are credential-redacted regardless.
- Refusals — a thrown error with
statusCode 401 or 403 records as
status: "denied", so a refused attempt shows up as an attempt.
- Probes — a health or capability probe sends
{ "__probe__": true } as
its only argument. If it is rejected it records nothing; if it executes, or
carries any other argument, it records like any call. Do not invent another
probe shape in a client; the recorder only knows this one.
- Outside agents — a call over an agent protocol (
mcp, webmcp, or
a2a) records as agent with the user's email, like the app's own agent
(tool); caller names the protocol. Classify a new agent-only caller in
AGENT_AUDIT_CALLERS, not in a per-action audit config.
- Client and approval — keep four facts in four fields.
actorEmail is
the principal the call runs as, never evidence of approval. caller and
actorKind are the execution source. reportedClientName /
reportedClientVersion are the MCP client's self-reported clientInfo for
that individual tools/call; initialize-only values are not carried
forward. oauthClientId is the OAuth client its credential was issued to.
approval (agent-chat, a2a-review, mcp-client-accepted or
mcp-review) records the authorization signal for that call. agent-chat
is a person's approval in agent chat; a2a-review is the owner's approval
of a paused A2A call on its review page; mcp-client-accepted means the MCP
client accepted its elicitation, and the server cannot verify who responded;
mcp-review is the signed-in owner's approval of a direct MCP call on its
review page. The recorder reads approval from the invocation's execution
frame, never from its context.
Never infer approval from the email, and never backfill these fields on
older rows.
- Attribution comes from one helper —
recordActionAudit and
recordOrgAdminAuditEvent require an attribution (source, reported
client, OAuth client, approval, run and network ids), and only
auditAttribution(ctx) makes one; a Nitro route outside any action uses
routeAuditAttribution(event). Never copy caller, threadId or the client
fields into a hand-built context: a field the copy forgets is stored as null.
A call without one throws AuditAttributionError instead of losing its row.
- Approval and an audit override belong to one invocation — the
dispatcher that runs a call opens its execution frame and puts the evidence
there: the agent loop's approval key for a call a person approved, the MCP
handler's accepted elicitation, and an approved A2A replay's task ids and
a2a-review, which must not become its threadId or runId because those
load the task's journal and ledger. auditAttribution(ctx) reads only the
current frame, so the action's own row and a row its body records carry
them. Every defineAction call and every runActionInvocation opens a new
frame, so another action it calls, a recursive call, or a later call with a
kept context records none, whatever context it is given. A frame's evidence
belongs only to rows about its own call, written before the promise run
returned settles: a timer, unawaited promise or job write it leaves
running records none, and neither does work done later while consuming a
stream or iterator it returned. The attribution auditAttribution returns
is a snapshot: passing one made during the call to a later write records
that write as part of the approved call, so call auditAttribution at write
time for work that is not.
recordServicePrincipalDenial records only the source its caller knows,
outside the running frame, unless the caller passes the refused call's run
context as ownInvocation. Only defineAction's own grant check does: its
row keeps that call's client, network and run ids and its frame's approval,
while a refused child or agent run borrows none of the enclosing call's. A
dispatcher that pauses another call records that row inside
runOutsideActionInvocation, and recordInvalidActionCall records a call
refused for invalid arguments there too. A dispatcher vouches for the call
it runs with vouchedOutcome(outcome, evidence), and the frame that call
opens holds it. The frame and its evidence live in action-frame.ts, and
runActionInvocation in action-invocation.ts, both outside the package
exports: the action entry exposes no frame-evidence helpers, and request
input or ActionRunContext fields never become evidence. Trusted server
dispatcher APIs (executeAgentToolCall, runAgentLoop) can still supply
approval and attribution.
ctx.approvedToolCallKey stays on the context only for approval gates. Two
limits: a raw entry called straight from an action's body shares that
frame, so define it with defineAction (a framework dispatcher runs it
through runActionInvocation); and a wrapper around run
must spread the entry to keep ACTION_EXECUTION_KEY, or the action runs as
the wrapper's child and records no approval. Without async-local storage no
approval or override is recorded. Never add a context field that changes
what a row records.
- Source is verified, not claimed — on an action route, a request that
authenticated with an MCP OAuth or connect token records as
mcp with that
token's oauthClientId, whatever headers it sends. getMcpOAuthBearerSession
marks the event after verifying the token, and the route reads that mark; a
self-reported value (the x-agent-native-frontend header, clientInfo) never
sets caller, actorKind or the principal.
- A row is never silently lost — the recorder replaces control characters
in the self-reported labels, and the store replaces NUL in every text value,
because PostgreSQL rejects NUL and the insert would drop the row. A write
that still fails is logged and sent to
captureError; it never fails the
action. Don't wrap recordActionAudit in a catch that discards the error.
- App — every event records the app that wrote it (
app.id, else
app.name, the same key usage uses).
Who reads an event
visibility decides who reads an event besides its owner (ownerEmail, which
defaults to the actor):
| Visibility |
Readers |
Recorded for |
private (default) |
The owner only, admins included |
Personal content and personal connections |
org |
Every member of orgId |
Changes to resources shared with the org; integration-triggered runs |
admins |
Owners and admins of orgId |
Organization settings and admin actions |
The admins events today: default model (agent-default-model), app member
roles, app permission roles, workspace app access, org member role changes
(org-member-role), sent invitations (org-invitation), file storage (file-storage), and org-scoped Builder.io
connect and disconnect (builder-connection). A member's personal Builder.io
connection is private.
Record an organization settings or admin change
Use the helpers in @agent-native/core/audit instead of hand-setting
visibility, so every org setting lands in the organization trail the same way:
import {
orgAdminAudit,
recordOrgAdminAuditEvent,
routeAuditAttribution,
} from "@agent-native/core/audit";
defineAction({
// ...
audit: orgAdminAudit({
targetType: "org-thing",
targetId: (args) => args.id,
summary: (args) => `Set the thing to ${args.value}`,
}),
});
// From a Nitro route (OAuth callback, upload) that is not an action:
await recordOrgAdminAuditEvent({
action: "builder-connect",
targetType: "builder-connection",
summary: "Connected Builder.io for the organization",
userEmail,
orgId,
attribution: routeAuditAttribution(event),
});
Pass personal: true to recordOrgAdminAuditEvent when the change affects
only the actor. An action that records by hand instead of through
orgAdminAudit passes attribution: auditAttribution(ctx).
Reading the log
These actions are available to the agent and the frontend in every app, scoped
in SQL to the caller — they never leak another tenant's rows:
list-audit-events — filter by targetType/targetId, actorKind
(agent | human | system), status, threadId/turnId, action,
app, sinceMs (inclusive), beforeMs (exclusive), with limit and
offset paging; returns hasMore and nextOffset. includeApps: true
also returns apps, the app ids with events in the scope, for an app
filter. scope: "organization" reads only the org's shared trail (org and
admins events) and is refused with a 403 for anyone but owners and admins.
This is the Settings audit log.
get-audit-event — one event by id, with its redacted input payload. Owners
and admins can open admins events.
export-audit-events — bulk CSV/NDJSON export (same filters minus limit
and offset, plus format and maxRows) for offline/compliance pulls;
itself audited via onRead.
CSV output prefixes formula-like values in every column with an apostrophe
before escaping.
export-audit-ocsf — the org trail as OCSF 1.9.0 API Activity events (class
- for a SIEM. Owners and admins only, through
resolveAuditReadScope(ctx, "organization"), so it never reads past
list-audit-events. Oldest first; pass the previous nextCursor as cursor
and store every returned nextCursor, including on empty pages (they advance
the ready watermark). since/until take ISO or epoch ms.
The mapper is auditEventToOcsf in audit/ocsf.ts; framework ids (run, task,
thread, turn, app) go under unmapped, never an invented OCSF field, and
input is never exported.
Call them from the UI with useActionQuery to build an activity feed or a
"who changed this" line — never hand-write a fetch to the audit table.
Settings › Organization › Audit log (/settings/audit, owners and admins) is
that trail's page, in
packages/toolkit/src/app/settings/shell/pages/audit.tsx. Its range and app
filters are sinceMs and app; "Show N more" is the next offset page; a
row opens get-audit-event. When a user asks what changed in the org, call
list-audit-events with scope: "organization" instead of reading the page.
Never
- Don't write a parallel "history" table for a resource — declare an
audit.target
and read it back instead.
- Don't put secrets in
summary or rely on inputs being safe — redaction covers
credential-shaped values, but keep summaries free of sensitive data.
- Don't expose an update/delete path for audit rows. The log is append-only; the
only deletion is the retention purge (
AGENT_NATIVE_AUDIT_RETENTION_DAYS,
default 365 days; 0 = keep forever). Global kill switch:
AGENT_NATIVE_AUDIT_ENABLED=false.
1---2name: audit-log3description: >-4 Durable, access-scoped, append-only record of who changed what app data,5 when, and whether it was the agent or a human. Use when adding an activity6 feed or change history, declaring what a mutating action targets, auditing7 sensitive reads, or answering "what did the agent change / who edited this".8scope: dev9metadata:10 source: https://skillmd.com/skills/builderio/audit-log11 internal: true12---1314# Audit Log1516## Rule1718Every mutating action automatically records an audit event — **no wiring19needed**. The framework captures who/what/when/from-where at the `defineAction`20seam, redacts credentials, and attributes the change to a human or the agent21(with the agent thread/turn that caused it). You only touch `audit` config to22make events *more useful* (declare the target) or to opt a read in / a noisy23write out.2425This is distinct from:2627- **observability** — sampled agent-run telemetry (traces, evals), developer-facing.28- **tracking** — fire-and-forget product analytics to external SaaS.2930Audit is complete, durable, locally queryable, and scoped to the data it31describes.3233## Declare the target so it lands in the owner's trail3435By default an event is scoped to the **actor** (you see your own changes and the36agent's changes on your behalf). To make a change to a *shared* resource show up37in the **owner's** audit trail, declare the target:3839```ts40defineAction({41 description: "Delete a recording",42 schema: z.object({ id: z.string() }),43 audit: {44 // type + id label the event; ownerEmail/orgId/visibility scope who can read it.45 target: (args, result, meta) => ({46 type: "recording",47 id: args.id,48 // Optional — defaults to the actor. Set when editing someone else's resource.49 ownerEmail: result?.ownerEmail,50 visibility: "org",51 }),52 summary: (args) => `Deleted recording ${args.id}`,53 },54 run: async (args, ctx) => { /* ... */ },55});56```5758`target`, `ownerEmail`, `visibility`, and `summary` are all optional. The59minimum useful addition is `target: () => ({ type, id })`.6061## Defaults and how to override them6263- **Mutations** (anything not GET / `readOnly`) are audited automatically.64- **Read-only** actions are skipped. Audit a sensitive read (secret access, bulk65 export) with `audit: { onRead: true }`.66- **High-frequency framework actions** (app-state sync, context-xray, navigate,67 appearance) are skipped by default. Force one on with `audit: { enabled: true }`.68- **Opt a noisy write out** with `audit: { enabled: false }`.69- **Skip capturing arguments** (large/sensitive payloads) with70 `audit: { recordInputs: false }`. Inputs are credential-redacted regardless.71- **Refusals** — a thrown error with `statusCode` 401 or 403 records as72 `status: "denied"`, so a refused attempt shows up as an attempt.73- **Probes** — a health or capability probe sends `{ "__probe__": true }` as74 its only argument. If it is rejected it records nothing; if it executes, or75 carries any other argument, it records like any call. Do not invent another76 probe shape in a client; the recorder only knows this one.77- **Outside agents** — a call over an agent protocol (`mcp`, `webmcp`, or78 `a2a`) records as `agent` with the user's email, like the app's own agent79 (`tool`); `caller` names the protocol. Classify a new agent-only caller in80 `AGENT_AUDIT_CALLERS`, not in a per-action `audit` config.81- **Client and approval** — keep four facts in four fields. `actorEmail` is82 the principal the call runs as, never evidence of approval. `caller` and83 `actorKind` are the execution source. `reportedClientName` /84 `reportedClientVersion` are the MCP client's self-reported `clientInfo` for85 that individual `tools/call`; `initialize`-only values are not carried86 forward. `oauthClientId` is the OAuth client its credential was issued to.87 `approval` (`agent-chat`, `a2a-review`, `mcp-client-accepted` or88 `mcp-review`) records the authorization signal for that call. `agent-chat`89 is a person's approval in agent chat; `a2a-review` is the owner's approval90 of a paused A2A call on its review page; `mcp-client-accepted` means the MCP91 client accepted its elicitation, and the server cannot verify who responded;92 `mcp-review` is the signed-in owner's approval of a direct MCP call on its93 review page. The recorder reads approval from the invocation's execution94 frame, never from its context.95 Never infer approval from the email, and never backfill these fields on96 older rows.97- **Attribution comes from one helper** — `recordActionAudit` and98 `recordOrgAdminAuditEvent` require an `attribution` (source, reported99 client, OAuth client, approval, run and network ids), and only100 `auditAttribution(ctx)` makes one; a Nitro route outside any action uses101 `routeAuditAttribution(event)`. Never copy `caller`, `threadId` or the client102 fields into a hand-built context: a field the copy forgets is stored as null.103 A call without one throws `AuditAttributionError` instead of losing its row.104- **Approval and an audit override belong to one invocation** — the105 dispatcher that runs a call opens its execution frame and puts the evidence106 there: the agent loop's approval key for a call a person approved, the MCP107 handler's accepted elicitation, and an approved A2A replay's task ids and108 `a2a-review`, which must not become its `threadId` or `runId` because those109 load the task's journal and ledger. `auditAttribution(ctx)` reads only the110 current frame, so the action's own row and a row its body records carry111 them. Every `defineAction` call and every `runActionInvocation` opens a new112 frame, so another action it calls, a recursive call, or a later call with a113 kept context records none, whatever context it is given. A frame's evidence114 belongs only to rows about its own call, written before the promise `run`115 returned settles: a timer, unawaited promise or job write it leaves116 running records none, and neither does work done later while consuming a117 stream or iterator it returned. The attribution `auditAttribution` returns118 is a snapshot: passing one made during the call to a later write records119 that write as part of the approved call, so call `auditAttribution` at write120 time for work that is not.121 `recordServicePrincipalDenial` records only the source its caller knows,122 outside the running frame, unless the caller passes the refused call's run123 context as `ownInvocation`. Only `defineAction`'s own grant check does: its124 row keeps that call's client, network and run ids and its frame's approval,125 while a refused child or agent run borrows none of the enclosing call's. A126 dispatcher that pauses another call records that row inside127 `runOutsideActionInvocation`, and `recordInvalidActionCall` records a call128 refused for invalid arguments there too. A dispatcher vouches for the call129 it runs with `vouchedOutcome(outcome, evidence)`, and the frame that call130 opens holds it. The frame and its evidence live in `action-frame.ts`, and131 `runActionInvocation` in `action-invocation.ts`, both outside the package132 exports: the action entry exposes no frame-evidence helpers, and request133 input or `ActionRunContext` fields never become evidence. Trusted server134 dispatcher APIs (`executeAgentToolCall`, `runAgentLoop`) can still supply135 approval and attribution.136 `ctx.approvedToolCallKey` stays on the context only for approval gates. Two137 limits: a raw entry called straight from an action's body shares that138 frame, so define it with `defineAction` (a framework dispatcher runs it139 through `runActionInvocation`); and a wrapper around `run`140 must spread the entry to keep `ACTION_EXECUTION_KEY`, or the action runs as141 the wrapper's child and records no approval. Without async-local storage no142 approval or override is recorded. Never add a context field that changes143 what a row records.144- **Source is verified, not claimed** — on an action route, a request that145 authenticated with an MCP OAuth or connect token records as `mcp` with that146 token's `oauthClientId`, whatever headers it sends. `getMcpOAuthBearerSession`147 marks the event after verifying the token, and the route reads that mark; a148 self-reported value (the `x-agent-native-frontend` header, `clientInfo`) never149 sets `caller`, `actorKind` or the principal.150- **A row is never silently lost** — the recorder replaces control characters151 in the self-reported labels, and the store replaces NUL in every text value,152 because PostgreSQL rejects NUL and the insert would drop the row. A write153 that still fails is logged and sent to `captureError`; it never fails the154 action. Don't wrap `recordActionAudit` in a `catch` that discards the error.155- **App** — every event records the app that wrote it (`app.id`, else156 `app.name`, the same key usage uses).157158## Who reads an event159160`visibility` decides who reads an event besides its owner (`ownerEmail`, which161defaults to the actor):162163| Visibility | Readers | Recorded for |164|---|---|---|165| `private` (default) | The owner only, admins included | Personal content and personal connections |166| `org` | Every member of `orgId` | Changes to resources shared with the org; integration-triggered runs |167| `admins` | Owners and admins of `orgId` | Organization settings and admin actions |168169The `admins` events today: default model (`agent-default-model`), app member170roles, app permission roles, workspace app access, org member role changes171(`org-member-role`), sent invitations (`org-invitation`), file storage (`file-storage`), and org-scoped Builder.io172connect and disconnect (`builder-connection`). A member's personal Builder.io173connection is `private`.174175## Record an organization settings or admin change176177Use the helpers in `@agent-native/core/audit` instead of hand-setting178`visibility`, so every org setting lands in the organization trail the same way:179180```ts181import {182 orgAdminAudit,183 recordOrgAdminAuditEvent,184 routeAuditAttribution,185} from "@agent-native/core/audit";186187defineAction({188 // ...189 audit: orgAdminAudit({190 targetType: "org-thing",191 targetId: (args) => args.id,192 summary: (args) => `Set the thing to ${args.value}`,193 }),194});195196// From a Nitro route (OAuth callback, upload) that is not an action:197await recordOrgAdminAuditEvent({198 action: "builder-connect",199 targetType: "builder-connection",200 summary: "Connected Builder.io for the organization",201 userEmail,202 orgId,203 attribution: routeAuditAttribution(event),204});205```206207Pass `personal: true` to `recordOrgAdminAuditEvent` when the change affects208only the actor. An action that records by hand instead of through209`orgAdminAudit` passes `attribution: auditAttribution(ctx)`.210211## Reading the log212213These actions are available to the agent and the frontend in every app, scoped214in SQL to the caller — they never leak another tenant's rows:215216- `list-audit-events` — filter by `targetType`/`targetId`, `actorKind`217 (`agent` | `human` | `system`), `status`, `threadId`/`turnId`, `action`,218 `app`, `sinceMs` (inclusive), `beforeMs` (exclusive), with `limit` and219 `offset` paging; returns `hasMore` and `nextOffset`. `includeApps: true`220 also returns `apps`, the app ids with events in the scope, for an app221 filter. `scope: "organization"` reads only the org's shared trail (`org` and222 `admins` events) and is refused with a 403 for anyone but owners and admins.223 This is the Settings audit log.224- `get-audit-event` — one event by id, with its redacted input payload. Owners225 and admins can open `admins` events.226- `export-audit-events` — bulk CSV/NDJSON export (same filters minus `limit`227 and `offset`, plus `format` and `maxRows`) for offline/compliance pulls;228 itself audited via `onRead`.229 CSV output prefixes formula-like values in every column with an apostrophe230 before escaping.231232- `export-audit-ocsf` — the org trail as OCSF 1.9.0 API Activity events (class233 6003) for a SIEM. Owners and admins only, through234 `resolveAuditReadScope(ctx, "organization")`, so it never reads past235 `list-audit-events`. Oldest first; pass the previous `nextCursor` as `cursor`236 and store every returned `nextCursor`, including on empty pages (they advance237 the ready watermark). `since`/`until` take ISO or epoch ms.238 The mapper is `auditEventToOcsf` in `audit/ocsf.ts`; framework ids (run, task,239 thread, turn, app) go under `unmapped`, never an invented OCSF field, and240 `input` is never exported.241242Call them from the UI with `useActionQuery` to build an activity feed or a243"who changed this" line — never hand-write a fetch to the audit table.244245Settings › Organization › Audit log (`/settings/audit`, owners and admins) is246that trail's page, in247`packages/toolkit/src/app/settings/shell/pages/audit.tsx`. Its range and app248filters are `sinceMs` and `app`; "Show N more" is the next `offset` page; a249row opens `get-audit-event`. When a user asks what changed in the org, call250`list-audit-events` with `scope: "organization"` instead of reading the page.251252## Never253254- Don't write a parallel "history" table for a resource — declare an `audit.target`255 and read it back instead.256- Don't put secrets in `summary` or rely on inputs being safe — redaction covers257 credential-shaped values, but keep summaries free of sensitive data.258- Don't expose an update/delete path for audit rows. The log is append-only; the259 only deletion is the retention purge (`AGENT_NATIVE_AUDIT_RETENTION_DAYS`,260 default 365 days; `0` = keep forever). Global kill switch:261 `AGENT_NATIVE_AUDIT_ENABLED=false`.