@agent-native/core 0.71.0 → 0.72.0

package/corpus/core/src/audit/types.ts

@@ -0,0 +1,125 @@
+/**
+ * Types for the framework audit log.
+ *
+ * The audit log is 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*. It is deliberately distinct from observability (sampled
+ * agent-run telemetry) and tracking (fire-and-forget product analytics): audit
+ * rows are complete, locally queryable, and scoped to the data they describe.
+ *
+ * Capture happens automatically at the action-execution seam (`defineAction`):
+ * every mutating action records an audit event after it runs. Read-only (GET /
+ * `readOnly`) actions are skipped unless they opt in via `audit.onRead`.
+ */
+
+/** Outcome of an audited action call. */
+export type AuditStatus = "success" | "error" | "denied";
+
+/**
+ * Who performed the mutation.
+ * - `agent` — the in-app assistant / sub-agents / A2A (caller `"tool"`).
+ * - `human` — a person via the UI, HTTP, CLI, or an external MCP client.
+ * - `system` — no resolved identity (background jobs, schedules).
+ */
+export type AuditActorKind = "agent" | "human" | "system";
+
+export type AuditVisibility = "private" | "org" | "public";
+
+/**
+ * The resource an action mutated, plus the ownership used to scope who can
+ * read the resulting audit event. Returned by an action's `audit.target`.
+ *
+ * `ownerEmail` / `orgId` / `visibility` default to the actor's identity when
+ * omitted, which is correct for the common case where a user mutates their own
+ * data. Provide them explicitly when a user edits a resource owned by someone
+ * else so the *owner* sees the change in their audit trail.
+ */
+export interface AuditTarget {
+  type?: string;
+  id?: string;
+  ownerEmail?: string | null;
+  orgId?: string | null;
+  visibility?: AuditVisibility;
+}
+
+/** Metadata about the call, passed to `audit.target` / `audit.summary`. */
+export interface AuditCallMeta {
+  status: AuditStatus;
+  caller: string;
+  userEmail?: string;
+  orgId?: string | null;
+}
+
+/**
+ * Per-action audit configuration, set on `defineAction({ audit })`.
+ *
+ * Audit is **default-on for mutating actions** — you only need this object to
+ * *tune* capture (declare the target, customize the summary) or to opt a
+ * read-only action in / a noisy action out.
+ */
+export interface ActionAuditConfig {
+  /**
+   * Force audit on (`true`) or off (`false`). Overrides every default,
+   * including the read-only skip and the high-frequency denylist. When
+   * omitted, mutating actions are audited and read-only actions are not.
+   */
+  enabled?: boolean;
+  /**
+   * Audit this action even though it is read-only (GET). Use for sensitive
+   * reads worth recording — secret access, bulk export. Ignored when
+   * `enabled` is set explicitly.
+   */
+  onRead?: boolean;
+  /** Capture the (redacted) call arguments. Default `true`. */
+  recordInputs?: boolean;
+  /** Resolve the mutated resource + its ownership for scoped reads. */
+  target?: (
+    args: any,
+    result: unknown,
+    meta: AuditCallMeta,
+  ) => AuditTarget | null | undefined;
+  /** Build a short human-readable summary line for the event. */
+  summary?: (args: any, result: unknown, meta: AuditCallMeta) => string;
+}
+
+/** A persisted audit event. */
+export interface AuditEvent {
+  id: string;
+  createdAt: number;
+  /** Action name (the registry key, e.g. `delete-recording`). */
+  action: string;
+  /** Invocation surface: tool | frontend | http | cli | mcp | a2a. */
+  caller: string;
+  actorKind: AuditActorKind;
+  /** Human on whose behalf it ran — populated even for agent calls. */
+  actorEmail: string | null;
+  orgId: string | null;
+  /** Agent conversation thread, when caller is the agent loop. */
+  threadId: string | null;
+  /** Agent turn that produced the mutation — the unit of one agent response. */
+  turnId: string | null;
+  targetType: string | null;
+  targetId: string | null;
+  status: AuditStatus;
+  summary: string | null;
+  /** Redacted JSON of the call arguments, or null. */
+  input: string | null;
+  errorCode: string | null;
+  /** Denormalized owner used to scope reads (defaults to the actor). */
+  ownerEmail: string | null;
+  visibility: AuditVisibility;
+}
+
+/** Filters for `queryAuditEvents`. */
+export interface AuditQueryFilters {
+  targetType?: string;
+  targetId?: string;
+  actorKind?: AuditActorKind;
+  actorEmail?: string;
+  status?: AuditStatus;
+  threadId?: string;
+  turnId?: string;
+  action?: string;
+  sinceMs?: number;
+  limit?: number;
+}

package/corpus/core/src/chat-threads/store.ts

@@ -1,5 +1,6 @@
 import crypto from "node:crypto";
 import { getDbExec, intType } from "../db/client.js";
+import { widenIntColumnsToBigInt } from "../db/widen-columns.js";
 import {
   mergeThreadDataForClientSave,
   normalizeThreadRepository,
@@ -87,6 +88,15 @@ async function ensureTable(): Promise<void> {
           // Column already exists.
         }
       }
+      // Widen millisecond-timestamp columns that older deployments created as
+      // 32-bit `INTEGER`; on Postgres the `Date.now()` written on every turn
+      // overflows int4. No-op once widened / on fresh BIGINT databases.
+      await widenIntColumnsToBigInt("chat_threads", [
+        "created_at",
+        "updated_at",
+        "pinned_at",
+        "archived_at",
+      ]);
       // Indexes for the hot read paths. Both the sidebar list and the
       // scoped/per-resource list filter on owner_email (and optionally
       // scope) and sort by updated_at. Keep these dialect-agnostic (no

package/corpus/core/src/client/AssistantChat.tsx

@@ -151,6 +151,7 @@ import {
   getRepoMessages,
   getRepoMessage,
   shouldImportServerThreadData,
+  dedupeRepoMessagesById,
 } from "./chat/repo-helpers.js";
 
 export {
@@ -829,6 +830,11 @@ export function clearChatStorage(tabId?: string) {
  * messages missing these fields crash.
  */
 function ensureMessageMetadata(repo: any): any {
+  // Drop duplicate message ids before import — assistant-ui's MessageRepository
+  // throws "performOp/link: A message with the same id already exists in the
+  // parent tree" (Sentry AGENT-NATIVE-BROWSER-2Q) when fed repeated ids. No-op
+  // for the normal no-duplicate case. See dedupeRepoMessagesById.
+  repo = dedupeRepoMessagesById(repo);
   if (!repo?.messages || !Array.isArray(repo.messages)) return repo;
   for (const entry of repo.messages) {
     // Handle both wrapped ({ message: { ... } }) and flat ({ role, ... }) formats

package/corpus/core/src/client/chat/repo-helpers.ts

@@ -56,6 +56,44 @@ export function getRepoMessage(entry: RepoEntry): RepoMessage | null {
   return (entry?.message ?? entry) as RepoMessage | null;
 }
 
+/**
+ * Collapse duplicate message ids before a repository is handed to
+ * `threadRuntime.import()`. assistant-ui's `MessageRepository` throws
+ * "MessageRepository(performOp/link): A message with the same id already exists
+ * in the parent tree" when the imported messages contain the same id more than
+ * once (Sentry AGENT-NATIVE-BROWSER-2Q). Duplicate ids are never valid thread
+ * data — they come from optimistic+echo races, streaming reconnect replays, or
+ * multi-tab merges — so keep only the LAST occurrence of each id (the most
+ * recent, most complete copy). parentId references stay valid because the
+ * surviving entry keeps the same id.
+ *
+ * Returns the input unchanged (same reference) when there are no duplicates, so
+ * the overwhelmingly common no-dupe case is a cheap no-op with zero behavioural
+ * change for normal threads.
+ */
+export function dedupeRepoMessagesById<T extends NormalizedRepo>(
+  repo: T | null | undefined,
+): T | null | undefined {
+  if (!repo || !Array.isArray(repo.messages)) return repo;
+  const entries = repo.messages;
+  const lastIndexById = new Map<string, number>();
+  let hasDuplicate = false;
+  entries.forEach((entry, index) => {
+    const id = getRepoMessage(entry)?.id;
+    if (typeof id !== "string" || !id) return;
+    if (lastIndexById.has(id)) hasDuplicate = true;
+    lastIndexById.set(id, index);
+  });
+  if (!hasDuplicate) return repo;
+  const deduped = entries.filter((entry, index) => {
+    const id = getRepoMessage(entry)?.id;
+    // Keep id-less entries untouched; for duplicated ids keep only the last.
+    if (typeof id !== "string" || !id) return true;
+    return lastIndexById.get(id) === index;
+  });
+  return { ...repo, messages: deduped };
+}
+
 export function isAssistantMessageTerminal(
   message: RepoMessage | null,
 ): boolean {

package/corpus/core/src/db/client.ts

@@ -318,6 +318,10 @@ export function intType(): string {
   return isPostgres() ? "BIGINT" : "INTEGER";
 }
 
+// `widenIntColumnsToBigInt` lives in `./widen-columns.js` (it depends only on
+// `isPostgres`/`getDbExec` from here) so stores can import it without every
+// `vi.mock("./client.js")` test having to stub the export.
+
 // ---------------------------------------------------------------------------
 // Parameter conversion: ? -> $1, $2, $3
 // ---------------------------------------------------------------------------

package/corpus/core/src/db/widen-columns.ts

@@ -0,0 +1,75 @@
+/**
+ * In-place widening of legacy 32-bit `integer` columns to 64-bit `BIGINT` on
+ * Postgres.
+ *
+ * Lives in its own module (rather than `client.js`) so that stores can import
+ * it without every `vi.mock("../db/client.js")` test needing to stub it: the
+ * helper resolves `isPostgres()` / `getDbExec()` through `client.js`, so a test
+ * that mocks the client to SQLite (`isPostgres: () => false`) makes this a
+ * no-op automatically.
+ */
+
+import { isPostgres, getDbExec, type DbExec } from "./client.js";
+
+const PLAIN_IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+/**
+ * Widen pre-existing 32-bit `integer` columns to 64-bit `BIGINT` in place on
+ * Postgres. No-op on SQLite, whose `INTEGER` is already 64-bit.
+ *
+ * Several stores historically created millisecond-timestamp columns (e.g.
+ * `agent_runs.started_at`, `application_state.updated_at`) as a literal
+ * `INTEGER`. On Postgres that is int4 (max 2,147,483,647), so a millisecond
+ * epoch such as 1782269273204 overflows with:
+ *   `value "1782269273204" is out of range for type integer`
+ * The CREATE TABLE source was later switched to `intType()` (BIGINT on PG),
+ * but `CREATE TABLE IF NOT EXISTS` cannot re-type a column that already
+ * exists, so long-lived Neon databases keep the int4 column and every write
+ * into it fails. (Migrations don't hit this — the migration runner rewrites
+ * `INTEGER` → `BIGINT` for Postgres; only raw `ensureTable()` CREATE strings
+ * that predate `intType()` are affected.)
+ *
+ * This widens such columns once, then no-ops: it only ALTERs columns whose
+ * current type is `integer`, so already-bigint tables are never rewritten.
+ * Widening int4 → int8 is additive and non-destructive (no data loss, no
+ * narrowing), so it is safe to run unconditionally on every boot.
+ *
+ * Call from a store's `ensureTable()` right after its `CREATE TABLE IF NOT
+ * EXISTS`, passing the millisecond-timestamp columns for that table. Pass the
+ * UNQUALIFIED table name (the lookup is scoped to the `public` schema); the
+ * `ALTER` resolves the table through the search path.
+ */
+export async function widenIntColumnsToBigInt(
+  table: string,
+  columns: string[],
+  // Injectable for tests; production callers use the configured client.
+  injectedClient?: DbExec,
+): Promise<void> {
+  if (!isPostgres() || columns.length === 0) return;
+  if (!PLAIN_IDENTIFIER.test(table)) return;
+  const client = injectedClient ?? getDbExec();
+  let int4Columns: Set<string>;
+  try {
+    const { rows } = await client.execute({
+      sql: `SELECT column_name FROM information_schema.columns
+            WHERE table_schema = 'public' AND table_name = ? AND data_type = 'integer'`,
+      args: [table],
+    });
+    int4Columns = new Set(rows.map((r) => String(r.column_name)));
+  } catch {
+    // information_schema unreadable (permissions / non-standard backend) —
+    // skip silently and leave the pre-existing behaviour unchanged.
+    return;
+  }
+  for (const col of columns) {
+    if (!int4Columns.has(col) || !PLAIN_IDENTIFIER.test(col)) continue;
+    try {
+      await client.execute(
+        `ALTER TABLE ${table} ALTER COLUMN ${col} TYPE BIGINT`,
+      );
+    } catch {
+      // A concurrent boot already widened it, or the role lacks ALTER — both
+      // are safe to ignore; a later boot retries if still needed.
+    }
+  }
+}

package/corpus/core/src/mcp/build-server.ts

@@ -1531,6 +1531,7 @@ export async function createMCPServerForRequest(
           userEmail: getRequestUserEmail(),
           orgId: getRequestOrgId() ?? null,
           caller: "mcp",
+          actionName: name,
         });
         const mcpResult = isMcpActionResult(result) ? result : null;
         const rawResult = mcpResult ? mcpResult.raw : result;

package/corpus/core/src/oauth-tokens/store.ts

@@ -1,4 +1,5 @@
 import { getDbExec, isPostgres, intType } from "../db/client.js";
+import { widenIntColumnsToBigInt } from "../db/widen-columns.js";
 import {
   encryptSecretValue,
   decryptSecretValue,
@@ -81,6 +82,11 @@ async function ensureTable(): Promise<void> {
       await client.execute(
         `UPDATE ${table} SET owner = account_id WHERE owner IS NULL`,
       );
+      // Older deployments have a 32-bit `updated_at`; on Postgres the
+      // `Date.now()` written on every token save overflows int4. Widen in place
+      // (no-op once done / on fresh DBs). Unqualified name — the helper scopes
+      // to the `public` schema.
+      await widenIntColumnsToBigInt("oauth_tokens", ["updated_at"]);
     })().catch((err) => {
       // Retry init on the next call after a failed startup.
       _initPromise = undefined;

package/corpus/core/src/provider-api/custom-registry.ts

@@ -21,6 +21,7 @@
  */
 
 import { getDbExec, isPostgres } from "../db/client.js";
+import { widenIntColumnsToBigInt } from "../db/widen-columns.js";
 import { isBlockedExtensionUrlWithDns } from "../extensions/url-safety.js";
 
 // ---------------------------------------------------------------------------
@@ -94,6 +95,13 @@ async function ensureTable(): Promise<void> {
         ? CREATE_SQL.replace(/\bINTEGER\b/g, "BIGINT")
         : CREATE_SQL;
       await client.execute(sql);
+      // Fresh Postgres tables get BIGINT via the replace above, but tables
+      // created before that compat existed kept int4 timestamp columns; widen
+      // them so `Date.now()` writes don't overflow. No-op once done.
+      await widenIntColumnsToBigInt("custom_api_providers", [
+        "created_at",
+        "updated_at",
+      ]);
     })().catch((err) => {
       _initPromise = undefined;
       throw err;

package/corpus/core/src/resources/store.ts

@@ -5,6 +5,7 @@ import {
   retryOnDdlRace,
   type DbExec,
 } from "../db/client.js";
+import { widenIntColumnsToBigInt } from "../db/widen-columns.js";
 import { emitResourceChange, emitResourceDelete } from "./emitter.js";
 import type { StoreWriteOptions } from "../settings/store.js";
 import {
@@ -781,6 +782,15 @@ async function _doEnsureTable(): Promise<void> {
   await ensureResourceColumn(client, `expires_at ${intType()}`);
   await ensureResourceColumn(client, "metadata TEXT");
 
+  // Older deployments have 32-bit timestamp columns; on Postgres the
+  // `Date.now()` written on insert/update overflows int4. Widen in place
+  // (no-op once done / on fresh DBs).
+  await widenIntColumnsToBigInt("resources", [
+    "created_at",
+    "updated_at",
+    "expires_at",
+  ]);
+
   // Seed default shared resources if they don't exist (INSERT OR IGNORE to avoid race conditions)
   const now = Date.now();
   const seedSql = isPostgres()

package/corpus/core/src/scripts/runner.ts

@@ -228,11 +228,14 @@ function parsePositionalJsonArg(args: string[]): Record<string, unknown> {
  * resolves `AGENT_USER_EMAIL` / the dev session); we never inject a dev
  * identity here beyond what that wrap already established.
  */
-function cliActionCtx(): import("../action.js").ActionRunContext {
+function cliActionCtx(
+  actionName: string,
+): import("../action.js").ActionRunContext {
   return {
     userEmail: getRequestUserEmail(),
     orgId: getRequestOrgId() ?? null,
     caller: "cli",
+    actionName,
   };
 }
 
@@ -268,7 +271,7 @@ async function dispatchAction(
         typeof handler.run === "function"
       ) {
         const parsed = parseActionArgs(args, { coerceBooleans: true });
-        const result = await handler.run(parsed, cliActionCtx());
+        const result = await handler.run(parsed, cliActionCtx(actionName));
         if (handler.readOnly !== true) {
           await notifyActionChange({ actionName }).catch(() => {});
         }
@@ -298,7 +301,7 @@ async function dispatchAction(
       const parsed = parseActionArgs(args, { coerceBooleans: true });
       const result = await packageAction.run(
         parsed as Record<string, string>,
-        cliActionCtx(),
+        cliActionCtx(actionName),
       );
       if (packageAction.readOnly !== true) {
         await notifyActionChange({ actionName }).catch(() => {});

package/corpus/core/src/server/action-discovery.ts

@@ -580,6 +580,12 @@ export async function mergeCoreSharingActions(
       () => import("../appearance/actions/change-appearance.js"),
     ],
     ["toggle-demo-mode", () => import("../demo/actions/toggle-demo-mode.js")],
+    // Audit log — read surface (who changed what, when, agent vs human).
+    [
+      "list-audit-events",
+      () => import("../audit/actions/list-audit-events.js"),
+    ],
+    ["get-audit-event", () => import("../audit/actions/get-audit-event.js")],
     // Org service tokens (CI credentials, e.g. PLAN_RECAP_TOKEN). Mint/revoke
     // are toolCallable:false — preserved via preserveActionFlags below.
     [

package/corpus/core/src/server/action-routes.ts

@@ -327,6 +327,7 @@ export function mountActionRoutes(
                 userEmail,
                 orgId: orgId ?? null,
                 caller,
+                actionName: name,
               });
 
               // Auto-refresh the UI after a successful mutating action. GET

package/corpus/core/src/server/auth.ts

@@ -70,6 +70,7 @@ import {
   retryOnDdlRace,
   describeDbError,
 } from "../db/client.js";
+import { widenIntColumnsToBigInt } from "../db/widen-columns.js";
 import { getBetterAuth, getBetterAuthSync } from "./better-auth-instance.js";
 import type { BetterAuthConfig } from "./better-auth-instance.js";
 import { resolveGoogleSignInCredentials } from "./google-oauth-credentials.js";
@@ -869,6 +870,10 @@ async function ensureSessionTable(): Promise<void> {
       } catch {
         // Column already exists
       }
+      // Older deployments have a 32-bit `created_at`; on Postgres the
+      // `Date.now()` written on session create overflows int4. Widen in place
+      // (no-op once done / on fresh DBs).
+      await widenIntColumnsToBigInt("sessions", ["created_at"]);
     })().catch((err) => {
       // Don't cache the rejection — let the next caller retry a fresh init.
       _sessionInitPromise = undefined;

package/corpus/core/src/server/core-routes-plugin.ts

@@ -757,6 +757,20 @@ export function createCoreRoutesPlugin(
         // Observability module not available — skip
       }
 
+      // Audit log — durable, append-only record of who mutated what app data,
+      // when, and (for the agent) in which run. Capture is automatic at the
+      // action seam; here we just ensure the table exists and start the
+      // retention purge. Best-effort so a missing DB never crashes boot.
+      try {
+        const { ensureAuditTables } = await import("../audit/store.js");
+        const { startAuditCleanupJob } =
+          await import("../audit/cleanup-job.js");
+        ensureAuditTables().catch(() => {});
+        startAuditCleanupJob();
+      } catch {
+        // Audit module not available — skip
+      }
+
       const P = FRAMEWORK_ROUTE_PREFIX;
 
       // Security response headers — emitted on every framework response.

package/corpus/core/src/server/security-headers.ts

@@ -19,11 +19,14 @@
  *   - `Referrer-Policy: strict-origin-when-cross-origin` — strips path/query
  *     from outbound Referer headers when the request crosses origin, so a
  *     public-share viewer's outbound link clicks never leak the share token.
- *   - `Permissions-Policy: camera=(), microphone=(self), geolocation=(),
- *     screen-wake-lock=()` — allows the app shell to request microphone access
- *     for composer dictation while keeping camera/location/wake-lock blocked
- *     by default. Templates that need broader media capture for recording UI
- *     override this on their own routes.
+ *   - `Permissions-Policy: camera=*, microphone=(self), geolocation=(),
+ *     screen-wake-lock=()` — allows microphone access for composer dictation
+ *     and camera access for media-capture UI (the Clips recorder, and the
+ *     Clips browser extension's camera bubble, which is injected as a
+ *     cross-origin iframe and is therefore blocked outright by `camera=()`).
+ *     Location and wake-lock stay disabled. The browser still gates actual
+ *     camera/mic use behind a per-origin permission prompt, so `camera=*` only
+ *     removes the policy-level block, not the user consent.
  *   - `Cross-Origin-Opener-Policy: same-origin` — isolates window.opener so
  *     a popup-window opener reference can't read or modify our document.
  *   - `Cross-Origin-Embedder-Policy: require-corp` — emitted only for
@@ -69,7 +72,7 @@ export function computeInlineScriptHash(scriptContent: string): string {
 
 const HSTS = "max-age=31536000; includeSubDomains; preload";
 const PERMISSIONS_POLICY =
-  "camera=(), microphone=(self), geolocation=(), screen-wake-lock=()";
+  "camera=*, microphone=(self), geolocation=(), screen-wake-lock=()";
 
 /**
  * Returns true when the request was received over HTTPS. We trust both the

package/corpus/core/src/settings/store.ts

@@ -1,5 +1,6 @@
 import { EventEmitter } from "events";
 import { getDbExec, isPostgres, intType } from "../db/client.js";
+import { widenIntColumnsToBigInt } from "../db/widen-columns.js";
 
 let _initPromise: Promise<void> | undefined;
 
@@ -25,6 +26,11 @@ async function ensureTable(): Promise<void> {
           updated_at ${intType()} NOT NULL
         )
       `);
+      // Older deployments (pre BIGINT-compat) have a 32-bit `updated_at`; on
+      // Postgres the `Date.now()` written on every setSetting overflows int4.
+      // Widen in place (no-op once done / on fresh DBs). Pass the unqualified
+      // name — the helper scopes to the `public` schema.
+      await widenIntColumnsToBigInt("settings", ["updated_at"]);
       // Index for the poll watermark query: `SELECT MAX(updated_at) FROM settings`.
       // MAX on an indexed column avoids a full-table scan on every poll cycle.
       // IF NOT EXISTS makes it idempotent on existing databases.

package/corpus/core/src/templates/workspace-core/.agents/skills/audit-log/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: audit-log
+description: >-
+  Durable, access-scoped, append-only record of who changed what app data,
+  when, and whether it was the agent or a human. Use when adding an activity
+  feed or change history, declaring what a mutating action targets, auditing
+  sensitive reads, or answering "what did the agent change / who edited this".
+scope: dev
+metadata:
+  internal: true
+---
+
+# 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:
+
+```ts
+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.
+
+## Reading the log
+
+Two 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`,
+  `sinceMs`, `limit`.
+- `get-audit-event` — one event by id, with its redacted input payload.
+
+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.
+
+## 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`.

package/corpus/core/src/usage/store.ts

@@ -8,6 +8,7 @@
  * Cost is stored as "centicents" (1/100th of a cent) for integer precision.
  */
 import { getDbExec, intType, isPostgres } from "../db/client.js";
+import { widenIntColumnsToBigInt } from "../db/widen-columns.js";
 
 /**
  * Per-million-token pricing in cents. Cache read is typically ~10% of
@@ -233,6 +234,11 @@ async function ensureUsageTable(): Promise<void> {
         }
       }
 
+      // Older deployments created `created_at` as 32-bit `INTEGER`; on Postgres
+      // the `Date.now()` written per run by recordUsage() overflows int4. Widen
+      // it in place (no-op once done / on fresh BIGINT databases).
+      await widenIntColumnsToBigInt("token_usage", ["created_at"]);
+
       try {
         await client.execute(
           `CREATE INDEX IF NOT EXISTS idx_token_usage_owner_created ON token_usage (owner_email, created_at)`,