@agent-native/core 0.71.0 → 0.72.1

package/corpus/README.md

@@ -27,5 +27,5 @@ rg -n "defineAction|useActionQuery" node_modules/@agent-native/core/corpus
 
 ## Generated Counts
 
-- core files: 1148
-- template files: 4000
+- core files: 1160
+- template files: 4005

package/corpus/core/CHANGELOG.md

@@ -1,5 +1,65 @@
 # @agent-native/core
 
+## 0.72.1
+
+### Patch Changes
+
+- b2a5931: Fix `value "<ms epoch>" is out of range for type integer` aborting agent chat on
+  Postgres/Neon at the start of every turn.
+
+  The background-aware stale-run cutoff built SQL like
+  `COALESCE(heartbeat_at, started_at) >= (? - CASE WHEN dispatch_mode LIKE
+'background%' THEN 90000 ELSE 15000 END)` and bound `Date.now()` to the
+  parameter. Postgres infers an untyped parameter's type from its surrounding
+  expression, and because the `15000`/`90000` window literals are `int4`, it typed
+  the parameter as `int4` too — so a millisecond epoch like `1782295529106`
+  overflowed even though every column involved is already `BIGINT`. This is a
+  query-level type-inference bug, independent of column types, which is why the
+  `widenIntColumnsToBigInt()` shim could never fix it.
+
+  The cutoff now wraps the parameter in `CAST(? AS BIGINT)`, pinning it to int8 so
+  the subtraction stays 64-bit. SQLite treats `CAST(x AS BIGINT)` as INTEGER
+  affinity, so it is a no-op there. Fixes `tryClaimRunSlot`, `reapIfStale`,
+  `reapAllStaleRuns`, and `cleanupOldRuns`, which all share the cutoff.
+
+## 0.72.0
+
+### Minor Changes
+
+- 9a984f2: Add a framework audit log: a durable, complete, access-scoped, append-only record of who mutated what app data, when, from where, and — when it was the agent — in which run. Capture is automatic at the `defineAction` seam (default-on for mutating actions; read-only actions opt in via `audit.onRead`), with credential redaction, agent-vs-human actor attribution, and agent thread/turn linkage. Reads go through two new core actions every app inherits — `list-audit-events` and `get-audit-event` — scoped in SQL to the caller's identity and org. Stored in `agent_audit_log` (provider-agnostic), with a retention purge configurable via `AGENT_NATIVE_AUDIT_RETENTION_DAYS` (default 365) and a global kill switch `AGENT_NATIVE_AUDIT_ENABLED=false`. Distinct from observability (sampled telemetry) and tracking (fire-and-forget analytics).
+
+### Patch Changes
+
+- 9a984f2: Relax the default `Permissions-Policy` from `camera=()` to `camera=*` so media-capture UI is no longer blocked at the policy level. `camera=()` disabled the camera for the page **and every iframe inside it**, which broke same-page recording UI and the Clips browser extension's camera bubble (injected as a cross-origin iframe, so it can't be re-enabled per-frame). Microphone stays `self`, geolocation and wake-lock stay disabled, and the browser still gates actual camera/mic use behind a per-origin permission prompt — this only removes the policy-level block, not user consent.
+- 9a984f2: Fix a chat crash where the agent transcript could fail to render with
+  "MessageRepository(performOp/link): A message with the same id already exists in
+  the parent tree". Thread repositories whose message list contained a repeated id
+  (from optimistic+echo races, streaming reconnect replays, or multi-tab merges)
+  were imported into assistant-ui verbatim, and its `MessageRepository` throws on a
+  duplicate id. The import path now collapses duplicate ids to their most recent
+  copy before handing the repository to assistant-ui, so the throw can't occur. The
+  no-duplicate case is an exact no-op, leaving normal threads unchanged.
+- 9a984f2: Fix `value "<ms epoch>" is out of range for type integer` on long-lived
+  Postgres/Neon databases — most visibly, agent chat failing on **every** prompt.
+  Millisecond `Date.now()` timestamps are written into columns that, on databases
+  created before the Postgres BIGINT-compatibility shim, are physically 32-bit
+  `INTEGER` (int4, max 2,147,483,647); a millisecond epoch like `1782269273204`
+  overflows. The source had since switched to `BIGINT`, but `CREATE TABLE IF NOT
+EXISTS` can't re-type an existing column, so those databases kept the int4
+  column and writes kept failing (`insertRun()` runs at the start of every turn,
+  so the agent chat aborted as a `connection_error`).
+
+  Adds a `widenIntColumnsToBigInt()` helper (new module
+  `@agent-native/core/db/widen-columns`) that, on Postgres only, widens such
+  columns in place to `BIGINT` once via each store's existing `ensureTable()`
+  bootstrap. It is idempotent (only ALTERs columns still typed `integer`, so
+  already-bigint tables are never rewritten), non-destructive (int4 → int8
+  widening), and a no-op on SQLite. Applied to the millisecond-timestamp columns
+  of `agent_runs`, `agent_tool_ledger`, `chat_threads`, `application_state`,
+  `token_usage`, `settings`, `oauth_tokens`, `resources`, `sessions`, and
+  `custom_api_providers`. (`staged_datasets` already self-heals via its own
+  widener.)
+
 ## 0.71.0
 
 ### Minor Changes

package/corpus/core/docs/content/actions.md

@@ -329,6 +329,28 @@ export default defineAction({
 > [!WARNING]
 > Keep approvals rare. Each gated action is a hard stop in the agent loop. The default is **off**, and almost every action should leave it off. See [Human-in-the-Loop Approvals](/docs/human-approval) for the predicate API, the `approval_required` event, and the full flow.
 
+### Audit logging {#audit}
+
+Every mutating action is **audited automatically** — the framework records who ran it, when, from which surface, and (when it was the agent) which thread/turn, with credential-redacted inputs. Read-only (`GET`) actions are skipped. You don't write any code for this; it happens at the `defineAction` seam.
+
+Add an `audit` block only to _tune_ capture — most usefully to declare the resource the action changed so the change shows up in that resource's owner's trail:
+
+```ts
+export default defineAction({
+  description: "Delete a recording.",
+  schema: z.object({ id: z.string() }),
+  audit: {
+    target: (args, result) => ({ type: "recording", id: args.id }),
+    summary: (args) => `Deleted recording ${args.id}`,
+  },
+  run: async (args, ctx) => {
+    /* ...delete... */
+  },
+});
+```
+
+Other knobs: `audit: { onRead: true }` audits a sensitive read (secret access, bulk export); `audit: { enabled: false }` opts a noisy write out; `audit: { recordInputs: false }` skips capturing arguments. Read the trail back with the built-in `list-audit-events` / `get-audit-event` actions. Full details in [Audit Log](/docs/audit-log).
+
 ## Calling it from the UI {#ui}
 
 Two hooks, both in `@agent-native/core/client`. Types are inferred from your `defineAction` schemas — no manual type declarations.
@@ -553,6 +575,7 @@ const args = parseArgs(["--name", "Steve", "--verbose", "--count=3"]);
 
 ## What's next
 
+- [**Audit Log**](/docs/audit-log) — the automatic who-changed-what trail around every action
 - [**Human-in-the-Loop Approvals**](/docs/human-approval) — the `needsApproval` gate in depth
 - [**Drop-in Agent**](/docs/drop-in-agent) — `useActionMutation` / `useActionQuery` in React
 - [**Context Awareness**](/docs/context-awareness) — the `view-screen` + `navigate` pattern in depth

package/corpus/core/docs/content/audit-log.md

@@ -0,0 +1,111 @@
+---
+title: "Audit Log"
+description: "A durable, append-only record of who changed what app data, when, and whether it was you or the agent — captured automatically at the action seam."
+---
+
+# Audit Log
+
+Every agent-native app gets an audit log out of the box: a durable, complete, access-scoped, append-only record of **who mutated what app data, when, from where, and — when it was the agent — in which run.** Capture is automatic at the action seam; you write no code for it.
+
+Because the agent can change data on your behalf, the headline question an audit log answers here isn't just "who edited this record" — it's **"was that me or the agent, and which turn caused it?"** No other system in the framework can answer that.
+
+## Audit vs. observability vs. tracking {#which}
+
+Three systems record "what happened," for three different reasons. Pick by the question you're asking:
+
+| System                                   | The question it answers                                | Fidelity                         | Audience                      |
+| ---------------------------------------- | ------------------------------------------------------ | -------------------------------- | ----------------------------- |
+| **Audit Log** (this page)                | "Who changed this record, when, and was it the agent?" | **Complete, durable, scoped**    | User, admin, the agent itself |
+| **[Observability](/docs/observability)** | "Why did the agent do that, and what did it cost?"     | Sampled span telemetry           | Developer                     |
+| **[Tracking](/docs/tracking)**           | "How are people using the product?"                    | Fire-and-forget to external SaaS | PM / growth                   |
+
+An audit log that's sampled or shipped off to an analytics provider is useless — the whole point is that it's complete, local, and queryable. So it's its own subsystem, not a mode of the other two.
+
+## What's captured automatically {#captured}
+
+When any **mutating** action runs (anything that isn't a read-only `GET`), the framework appends one row to `agent_audit_log` with:
+
+- **Action** — the action name (e.g. `delete-recording`).
+- **Actor** — `agent`, `human`, or `system`, plus the actor's email — populated **even for agent calls**, so you get "the agent, acting for alice@, …".
+- **Run linkage** — the agent `threadId` / `turnId` that triggered the call (a tool call), so a mutation traces back to the exact agent turn.
+- **Surface** — `tool` (agent), `frontend`, `http`, `cli`, `mcp`, or `a2a`.
+- **Outcome** — `success`, `error` (with an error code), or `denied` (blocked by a human-approval gate).
+- **Inputs** — the call arguments, with credential-shaped values [redacted](#privacy).
+- **Target & owner** — the resource the action changed, used to [scope reads](#reading).
+
+No wiring needed — the capture hooks into `defineAction` transparently. Read-only actions are skipped, and a few high-frequency framework actions (app-state sync, context-xray, navigation) are skipped by default to avoid flooding the log.
+
+## Declare what an action changed {#target}
+
+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 also appear in the **owner's** trail, and to label events by resource, declare a `target`:
+
+```ts
+export default defineAction({
+  description: "Delete a recording.",
+  schema: z.object({ id: z.string() }),
+  audit: {
+    target: (args, result) => ({
+      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) => {
+    /* ...delete... */
+  },
+});
+```
+
+Everything in `audit` is optional. The minimum useful addition is `target: () => ({ type, id })`.
+
+### Tuning capture {#tuning}
+
+| Option               | Effect                                                          |
+| -------------------- | --------------------------------------------------------------- |
+| `audit.target`       | Label the event with the resource and scope reads to its owner. |
+| `audit.summary`      | A short human-readable line for the event.                      |
+| `audit.onRead`       | Audit a sensitive **read** (secret access, bulk export).        |
+| `audit.enabled`      | `true` forces capture on; `false` opts a noisy mutation out.    |
+| `audit.recordInputs` | `false` skips capturing the (already redacted) arguments.       |
+
+## Reading the trail {#reading}
+
+Two read actions are available to the agent **and** the frontend in every app, scoped in SQL to the caller — they never return another tenant's rows:
+
+- **`list-audit-events`** — filter by `targetType` / `targetId`, `actorKind` (`agent` | `human` | `system`), `status`, `threadId` / `turnId`, `action`, `sinceMs`, and `limit`.
+- **`get-audit-event`** — one event by id, including its redacted input payload.
+
+Build an activity feed or a "who changed this" line by calling `list-audit-events` from the UI with `useActionQuery` — never hand-write a fetch to the audit table:
+
+```tsx
+import { useActionQuery } from "@agent-native/core/client";
+
+const { data } = useActionQuery("list-audit-events", {
+  targetType: "recording",
+  targetId: recordingId,
+});
+// data.events → [{ action, actorKind, actorEmail, turnId, status, summary, createdAt }, …]
+```
+
+The agent can call the same action — ask it "what did you change on this recording?" and it answers from the trail.
+
+## Privacy & retention {#privacy}
+
+- **Redaction** — before any inputs are stored, credential-shaped keys and values (tokens, secrets, passwords, bearer strings) are stripped and oversized payloads truncated. The audit log never becomes a secondary store of secrets. Keep `summary` text free of sensitive data too.
+- **Append-only** — there is no update or delete action for audit rows. The only deletion is the retention purge, which makes the log trustworthy as an audit trail.
+- **Tenant isolation** — reads are scoped to the caller's identity and org; with no identity, nothing matches.
+
+Configure via environment:
+
+- `AGENT_NATIVE_AUDIT_RETENTION_DAYS` — how long rows are kept (default `365`; `0` = keep forever).
+- `AGENT_NATIVE_AUDIT_ENABLED=false` — global kill switch.
+
+## What's next
+
+- [**Actions**](/docs/actions) — the `defineAction` seam where capture happens
+- [**Human-in-the-Loop Approvals**](/docs/human-approval) — gated actions, recorded as `denied`
+- [**Security & Data Scoping**](/docs/security) — the ownership model audit reads reuse
+- [**Observability**](/docs/observability) — agent-run telemetry (the other "what happened")

package/corpus/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.71.0",
+  "version": "0.72.1",
   "type": "module",
   "engines": {
     "node": ">=22"
@@ -97,6 +97,7 @@
     "./org": "./dist/org/index.js",
     "./client/org": "./dist/client/org/index.js",
     "./client/db-admin": "./dist/client/db-admin/index.js",
+    "./audit": "./dist/audit/index.js",
     "./sharing": "./dist/sharing/index.js",
     "./sharing/actions/share-resource": "./dist/sharing/actions/share-resource.js",
     "./sharing/actions/unshare-resource": "./dist/sharing/actions/unshare-resource.js",

package/corpus/core/src/action.ts

@@ -7,6 +7,8 @@ import {
   normalizeActionChatUIConfig,
   type ActionChatUIConfig,
 } from "./action-ui.js";
+import type { ActionAuditConfig } from "./audit/types.js";
+import { normalizeAuditConfig, resolveAuditAttach } from "./audit/config.js";
 import type { StandardSchemaV1 } from "@standard-schema/spec";
 
 /**
@@ -75,6 +77,21 @@ export interface ActionRunContext {
    * attaching an `"abort"` listener is always safe.
    */
   signal?: AbortSignal;
+  /**
+   * Name of the action being invoked (the registry key, e.g.
+   * `delete-recording`). Set at each dispatch site so cross-cutting concerns —
+   * notably the audit log — can attribute the call. `undefined` for direct
+   * programmatic `run()` calls that bypass the dispatcher.
+   */
+  actionName?: string;
+  /**
+   * Agent conversation thread + turn that triggered this call, populated only
+   * inside the agent tool loop (`caller: "tool"`). Lets the audit log link a
+   * mutation to the specific agent run/turn that caused it. `undefined` on
+   * every human/programmatic surface.
+   */
+  threadId?: string;
+  turnId?: string;
 }
 
 export interface AgentActionStopOptions {
@@ -378,6 +395,14 @@ interface DefineActionWithSchema<
         args: StandardSchemaV1.InferOutput<TSchema>,
         ctx?: ActionRunContext,
       ) => boolean | Promise<boolean>);
+  /**
+   * Audit-log configuration. **Default-on for mutating actions** — you only
+   * need this to tune capture: declare the mutated `target` (so the change
+   * shows up in the owner's audit trail) and/or a `summary`, opt a read-only
+   * action in via `onRead`, or opt a noisy action out via `enabled: false`.
+   * See the `audit-log` skill.
+   */
+  audit?: ActionAuditConfig;
 }
 
 // ---------------------------------------------------------------------------
@@ -443,6 +468,9 @@ interface DefineActionWithParams<
         args: InferParams<TParams>,
         ctx?: ActionRunContext,
       ) => boolean | Promise<boolean>);
+  /** Audit-log configuration (default-on for mutations). See the schema
+   *  overload above and the `audit-log` skill. */
+  audit?: ActionAuditConfig;
 }
 
 // ---------------------------------------------------------------------------
@@ -497,6 +525,10 @@ export interface ActionDefinition<TInput, TReturn> {
   readonly needsApproval?:
     | boolean
     | ((args: TInput, ctx?: ActionRunContext) => boolean | Promise<boolean>);
+  /** Resolved audit-log configuration. Present only when the caller passed
+   *  `audit`. The audit capture wrapper is baked into `run`; this field is for
+   *  introspection. */
+  readonly audit?: ActionAuditConfig;
 }
 
 // ---------------------------------------------------------------------------
@@ -617,6 +649,16 @@ export function defineAction(options: any) {
         ? true
         : undefined;
 
+  // Audit: wrap the validated run so every mutating call records an audit
+  // event (who/what/when/from-where, and for the agent which run). Default-on
+  // for mutations; read-only actions opt in via `audit.onRead`. The wrapper
+  // lazily imports the DB-touching recorder so `action.ts` keeps no static DB
+  // dependency.
+  const auditConfig = normalizeAuditConfig(options.audit);
+  const finalRun = resolveAuditAttach(auditConfig, readOnly)
+    ? wrapRunWithAudit(run, auditConfig)
+    : run;
+
   // toolCallable: thread through whatever the caller declared. We DO NOT
   // default to `true` here — the absence of an explicit field is meaningful
   // to the tools bridge: it lets us emit a one-shot warning when an action
@@ -675,7 +717,7 @@ export function defineAction(options: any) {
       description: options.description,
       parameters: toolParameters,
     },
-    run,
+    run: finalRun,
     ...(hasSchema ? { schema: options.schema } : {}),
     ...(options.http !== undefined ? { http: options.http } : {}),
     ...(typeof options.requiresAuth === "boolean"
@@ -702,6 +744,43 @@ export function defineAction(options: any) {
     typeof options.needsApproval === "function"
       ? { needsApproval: options.needsApproval }
       : {}),
+    ...(auditConfig ? { audit: auditConfig } : {}),
+  };
+}
+
+/**
+ * Wrap an action's (already input/output-validated) run so each call records an
+ * audit event after it resolves — on success and on error. Best-effort: the
+ * recorder swallows its own failures and the original result/throw is always
+ * preserved, so auditing can never change an action's behavior. The DB-touching
+ * recorder is imported lazily so merely defining an action pulls in no DB code.
+ */
+function wrapRunWithAudit(
+  run: (args: any, ctx?: ActionRunContext) => any,
+  auditConfig: ActionAuditConfig | undefined,
+): (args: any, ctx?: ActionRunContext) => Promise<any> {
+  return async function auditedRun(args: any, ctx?: ActionRunContext) {
+    let result: any;
+    let error: unknown;
+    let threw = false;
+    try {
+      result = await run(args, ctx);
+    } catch (err) {
+      error = err;
+      threw = true;
+    }
+    try {
+      const { recordActionAudit } = await import("./audit/record.js");
+      await recordActionAudit(
+        threw
+          ? { config: auditConfig, args, ctx, status: "error", error }
+          : { config: auditConfig, args, ctx, status: "success", result },
+      );
+    } catch {
+      // Recorder failed to load/run — never affect the action.
+    }
+    if (threw) throw error;
+    return result;
   };
 }
 

package/corpus/core/src/agent/production-agent.ts

@@ -2958,6 +2958,28 @@ export async function runAgentLoop(opts: {
             approvalKey,
             ...(toolCall.id ? { toolCallId: toolCall.id } : {}),
           });
+          // Audit the blocked attempt: the action did NOT run, but "the agent
+          // tried to do X and was gated" is itself worth recording. Best-effort,
+          // but AWAITED (not fire-and-forget) so the row isn't lost to a
+          // serverless freeze / request teardown when the turn pauses.
+          try {
+            const { recordActionAudit } = await import("../audit/record.js");
+            await recordActionAudit({
+              config: undefined,
+              args: toolCall.input,
+              ctx: {
+                actionName: toolCall.name,
+                caller: "tool",
+                userEmail: getRequestUserEmail(),
+                orgId: getRequestOrgId() ?? null,
+                ...(opts.threadId ? { threadId: opts.threadId } : {}),
+                ...(opts.turnId ? { turnId: opts.turnId } : {}),
+              },
+              status: "denied",
+            });
+          } catch {
+            // Best-effort — auditing must never break the approval pause.
+          }
           const result =
             `Awaiting human approval to run "${toolCall.name}". This action did ` +
             `NOT execute — a human must approve this specific call before it ` +
@@ -3227,6 +3249,11 @@ export async function runAgentLoop(opts: {
             caller: "tool",
             attachments: opts.attachments,
             signal,
+            // Audit attribution: the action name + the agent thread/turn that
+            // triggered this call, so a mutation can be traced to its run.
+            actionName: toolCall.name,
+            ...(opts.threadId ? { threadId: opts.threadId } : {}),
+            ...(opts.turnId ? { turnId: opts.turnId } : {}),
           }),
         );
 

package/corpus/core/src/agent/run-store.ts

@@ -4,6 +4,7 @@
  * reliable reconnection after page refreshes.
  */
 import { getDbExec, intType, isPostgres } from "../db/client.js";
+import { widenIntColumnsToBigInt } from "../db/widen-columns.js";
 import { captureError } from "../server/capture-error.js";
 import type { AgentChatEvent } from "./types.js";
 
@@ -159,6 +160,19 @@ async function ensureRunTables(): Promise<void> {
           PRIMARY KEY (thread_id, tool_key)
         )
       `);
+      // Widen millisecond-timestamp columns that older deployments created as
+      // 32-bit `INTEGER`. `insertRun()` writes `Date.now()` into `started_at`
+      // on every turn, so an int4 column makes every agent prompt fail on
+      // Postgres with "value … is out of range for type integer". No-op once
+      // widened (and on fresh DBs that already use BIGINT). See
+      // widenIntColumnsToBigInt.
+      await widenIntColumnsToBigInt("agent_runs", [
+        "started_at",
+        "completed_at",
+        "heartbeat_at",
+        "last_progress_at",
+      ]);
+      await widenIntColumnsToBigInt("agent_tool_ledger", ["completed_at"]);
     })().catch((err) => {
       // Retry init on the next call after a failed startup.
       _initPromise = undefined;
@@ -292,7 +306,10 @@ export async function insertRun(
  * states get the wider window via a LIKE-prefix match.
  */
 function backgroundAwareStaleCutoffSql(): string {
-  return `(? - CASE WHEN dispatch_mode LIKE 'background%' THEN ${BACKGROUND_RUN_STALE_MS} ELSE ${RUN_STALE_MS} END)`;
+  // `CAST(? AS BIGINT)` is required: without it Postgres infers the param as
+  // int4 from the int4 window literals, so the bound `Date.now()` ms epoch
+  // overflows int4. The cast keeps the subtraction 64-bit; a no-op on SQLite.
+  return `(CAST(? AS BIGINT) - CASE WHEN dispatch_mode LIKE 'background%' THEN ${BACKGROUND_RUN_STALE_MS} ELSE ${RUN_STALE_MS} END)`;
 }
 
 /**

package/corpus/core/src/application-state/store.ts

@@ -4,6 +4,7 @@ import {
   isPostgres,
   intType,
 } from "../db/client.js";
+import { widenIntColumnsToBigInt } from "../db/widen-columns.js";
 import { emitAppStateChange, emitAppStateDelete } from "./emitter.js";
 import type { StoreWriteOptions } from "../settings/store.js";
 
@@ -30,6 +31,10 @@ async function ensureTable(): Promise<void> {
           PRIMARY KEY (session_id, key)
         )
       `);
+      // Older deployments created `updated_at` as 32-bit `INTEGER`; on Postgres
+      // the `Date.now()` written by appStatePut() on every turn overflows int4.
+      // Widen it in place (no-op once done / on fresh BIGINT databases).
+      await widenIntColumnsToBigInt("application_state", ["updated_at"]);
       // Indexes for the two hot poll paths:
       //  - `SELECT … WHERE updated_at > ?` (watermark scan, every poll cycle)
       //  - `SELECT … WHERE key = ? … ORDER BY updated_at ASC` (marker lookups)

package/corpus/core/src/audit/actions/get-audit-event.ts

@@ -0,0 +1,23 @@
+import { z } from "zod";
+import { defineAction } from "../../action.js";
+import { getAuditEventById } from "../store.js";
+
+/**
+ * Fetch a single audit event by id, including its redacted input payload.
+ * Scoped to the caller's identity — returns null if they can't access it.
+ */
+export default defineAction({
+  description:
+    "Get one audit-log event by id, with its full redacted input payload. Returns null if you don't have access to it.",
+  schema: z.object({
+    id: z.string().describe("The audit event id."),
+  }),
+  http: { method: "GET" },
+  run: async (args, ctx) => {
+    const event = await getAuditEventById(args.id, {
+      userEmail: ctx?.userEmail,
+      orgId: ctx?.orgId ?? null,
+    });
+    return { event };
+  },
+});

package/corpus/core/src/audit/actions/list-audit-events.ts

@@ -0,0 +1,65 @@
+import { z } from "zod";
+import { defineAction } from "../../action.js";
+import { queryAuditEvents } from "../store.js";
+
+/**
+ * List audit-log events the current user can see — their own actions plus the
+ * agent's actions on their behalf, scoped in SQL to the caller's identity and
+ * org. Read-only; never exposes other tenants' rows.
+ */
+export default defineAction({
+  description:
+    "List audit-log events (who changed what, when, and whether it was you or the agent) for resources you can access. Supports filtering by target resource, actor (agent vs human), status, agent thread/turn, and time. Use this to answer 'what did the agent change', 'who edited this record', or 'show recent changes'.",
+  schema: z.object({
+    targetType: z
+      .string()
+      .optional()
+      .describe("Filter to one resource type, e.g. 'recording'."),
+    targetId: z
+      .string()
+      .optional()
+      .describe("Filter to one resource id (pair with targetType)."),
+    actorKind: z
+      .enum(["agent", "human", "system"])
+      .optional()
+      .describe("Filter to changes made by the agent, a human, or the system."),
+    actorEmail: z.string().optional().describe("Filter to one actor's email."),
+    status: z
+      .enum(["success", "error", "denied"])
+      .optional()
+      .describe("Filter by outcome."),
+    threadId: z.string().optional().describe("Filter to one agent thread."),
+    turnId: z
+      .string()
+      .optional()
+      .describe("Filter to one agent turn (a single agent response)."),
+    action: z.string().optional().describe("Filter to one action name."),
+    sinceMs: z
+      .number()
+      .optional()
+      .describe("Only events at or after this Unix epoch (ms)."),
+    limit: z
+      .number()
+      .optional()
+      .describe("Max events to return (default 100, max 500)."),
+  }),
+  http: { method: "GET" },
+  run: async (args, ctx) => {
+    const events = await queryAuditEvents(
+      { userEmail: ctx?.userEmail, orgId: ctx?.orgId ?? null },
+      {
+        ...(args.targetType ? { targetType: args.targetType } : {}),
+        ...(args.targetId ? { targetId: args.targetId } : {}),
+        ...(args.actorKind ? { actorKind: args.actorKind } : {}),
+        ...(args.actorEmail ? { actorEmail: args.actorEmail } : {}),
+        ...(args.status ? { status: args.status } : {}),
+        ...(args.threadId ? { threadId: args.threadId } : {}),
+        ...(args.turnId ? { turnId: args.turnId } : {}),
+        ...(args.action ? { action: args.action } : {}),
+        ...(typeof args.sinceMs === "number" ? { sinceMs: args.sinceMs } : {}),
+        ...(typeof args.limit === "number" ? { limit: args.limit } : {}),
+      },
+    );
+    return { events, count: events.length };
+  },
+});

package/corpus/core/src/audit/cleanup-job.ts

@@ -0,0 +1,100 @@
+/**
+ * Audit-log retention job.
+ *
+ * Periodically purges `agent_audit_log` rows older than the configured horizon
+ * so the log doesn't grow unbounded. Retention is configurable via
+ * `AGENT_NATIVE_AUDIT_RETENTION_DAYS` (default: 365 days — audit trails are kept
+ * far longer than sampled traces). Setting it to `0` disables the purge (keep
+ * forever). Mirrors observability/cleanup-job.ts.
+ *
+ * Runs once on startup after a short delay, then on a 24-hour interval. Timers
+ * are unref'd so they never keep the process alive on their own.
+ */
+import { deleteOldAuditEvents } from "./store.js";
+
+const DEFAULT_RETENTION_DAYS = 365;
+const ONE_DAY_MS = 24 * 60 * 60 * 1000;
+const STARTUP_DELAY_MS = 5 * 60 * 1000;
+
+let _cleanupTimer: NodeJS.Timeout | null = null;
+let _intervalTimer: NodeJS.Timeout | null = null;
+
+function resolveRetentionDays(): number {
+  const raw = process.env.AGENT_NATIVE_AUDIT_RETENTION_DAYS;
+  if (raw === undefined || raw === null || raw === "") {
+    return DEFAULT_RETENTION_DAYS;
+  }
+  const parsed = Number.parseInt(raw, 10);
+  if (!Number.isFinite(parsed) || parsed < 0) return DEFAULT_RETENTION_DAYS;
+  return parsed;
+}
+
+/**
+ * Run the audit cleanup once. Returns the deleted row count, or null when
+ * retention is disabled (`AGENT_NATIVE_AUDIT_RETENTION_DAYS=0`).
+ */
+export async function runAuditCleanupOnce(): Promise<number | null> {
+  const days = resolveRetentionDays();
+  if (days === 0) return null;
+  const cutoff = Date.now() - days * ONE_DAY_MS;
+  return deleteOldAuditEvents(cutoff);
+}
+
+/**
+ * Start the recurring audit-cleanup job. Idempotent — calling more than once is
+ * a no-op while a previous schedule is active. Returns a stop function.
+ */
+export function startAuditCleanupJob(): () => void {
+  if (_cleanupTimer || _intervalTimer) return stopAuditCleanupJob;
+  const days = resolveRetentionDays();
+  if (days === 0) {
+    if (process.env.DEBUG)
+      // eslint-disable-next-line no-console
+      console.log(
+        "[audit] Audit cleanup disabled (AGENT_NATIVE_AUDIT_RETENTION_DAYS=0)",
+      );
+    return () => {};
+  }
+
+  const tick = () => {
+    runAuditCleanupOnce()
+      .then((deleted) => {
+        if (deleted == null) return;
+        if (process.env.DEBUG) {
+          // eslint-disable-next-line no-console
+          console.log(
+            `[audit] Audit cleanup purged ${deleted} rows (retention=${days}d)`,
+          );
+        }
+      })
+      .catch((err) => {
+        // eslint-disable-next-line no-console
+        console.error("[audit] Audit cleanup failed:", err?.message ?? err);
+      });
+  };
+
+  _cleanupTimer = setTimeout(() => {
+    _cleanupTimer = null;
+    tick();
+    _intervalTimer = setInterval(tick, ONE_DAY_MS);
+    if (typeof _intervalTimer.unref === "function") _intervalTimer.unref();
+  }, STARTUP_DELAY_MS);
+  if (typeof _cleanupTimer.unref === "function") _cleanupTimer.unref();
+
+  if (process.env.DEBUG)
+    // eslint-disable-next-line no-console
+    console.log(`[audit] Audit cleanup scheduled (retention=${days}d, daily)`);
+
+  return stopAuditCleanupJob;
+}
+
+export function stopAuditCleanupJob(): void {
+  if (_cleanupTimer) {
+    clearTimeout(_cleanupTimer);
+    _cleanupTimer = null;
+  }
+  if (_intervalTimer) {
+    clearInterval(_intervalTimer);
+    _intervalTimer = null;
+  }
+}