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