@agent-native/core 0.70.3 → 0.72.0

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

@@ -64,9 +64,42 @@ export const DEFAULT_HOSTED_RUN_SOFT_TIMEOUT_MS = 40_000;
  * env value just guarantees the cutoff is a hard error instead of a graceful
  * hand-off. Any resolved value above this is clamped down when hosted. Local
  * dev (non-hosted) is left alone so long-running local turns aren't chunked.
+ *
+ * IMPORTANT: this clamp is for the INTERACTIVE / foreground path and must NOT
+ * be raised. The foreground POST still rides a synchronous serverless function
+ * (~60-65s wall), so 40s remains correct there. The only sanctioned exception
+ * is the opt-in `backgroundFunction` mode (see
+ * `BACKGROUND_SOFT_TIMEOUT_CEILING_MS`), which runs inside a Netlify background
+ * function (no ~60s wall, 15-min budget) and therefore can safely outlast 40s.
  */
 export const HOSTED_SOFT_TIMEOUT_CEILING_MS = 40_000;
 
+/**
+ * Hard ceiling for the soft timeout when a run executes inside a Netlify
+ * background function (any deployed function whose name ends in `-background`).
+ * Background functions return 202 immediately and run detached for up to 15
+ * minutes, so the ~60s synchronous function wall that 40s defends against does
+ * NOT apply. 13 minutes leaves ~2 min of headroom under Netlify's 15-min hard
+ * kill to abort, persist the partial turn, write the terminal event, and (for
+ * the rare >13-min turn) self-fire another background continuation.
+ *
+ * This ceiling is used ONLY when a caller explicitly opts in with
+ * `backgroundFunction: true`. It does not change the foreground/interactive
+ * ceiling and does not fire unless the durable-background path dispatched the
+ * run into a background function. Per the design doc Guardrail, the 40s
+ * interactive clamp stays correct for every non-background run.
+ */
+export const BACKGROUND_SOFT_TIMEOUT_CEILING_MS = 13 * 60_000; // 780_000
+
+/**
+ * Default soft-timeout budget for a background-function run when the caller
+ * does not pass an explicit `softTimeoutMs`. Same value as the ceiling — we
+ * want a background turn to use nearly its whole 15-min budget before handing
+ * off to a chained background continuation.
+ */
+export const DEFAULT_BACKGROUND_RUN_SOFT_TIMEOUT_MS =
+  BACKGROUND_SOFT_TIMEOUT_CEILING_MS;
+
 /** Default SQL retention for completed run event logs (24 hours). */
 export const DEFAULT_COMPLETED_RUN_RETENTION_MS = 24 * 60 * 60 * 1000;
 
@@ -137,10 +170,28 @@ export interface StartRunOptions {
    * share one `turnId` so the durable assistant message can be folded across
    * them instead of dropped per-run. Defaults to the runId (turn == run). */
   turnId?: string;
+  /**
+   * Opt into the durable-background-function soft-timeout regime for THIS run
+   * only. When true, `resolveRunSoftTimeoutMs` lifts the hosted ceiling from
+   * 40s to ~13min (`BACKGROUND_SOFT_TIMEOUT_CEILING_MS`) because the run is
+   * executing inside a Netlify background function (no ~60s wall). Off by
+   * default — the foreground/interactive path never sets this, so its 40s
+   * clamp is unchanged. See the design doc + the durable-background dispatch
+   * decision in production-agent.ts.
+   */
+  backgroundFunction?: boolean;
 }
 
 export interface ResolveRunSoftTimeoutOptions {
   useHostedDefault?: boolean;
+  /**
+   * Resolve the soft timeout for a run executing inside a Netlify background
+   * function. Lifts the hosted clamp to `BACKGROUND_SOFT_TIMEOUT_CEILING_MS`
+   * (~13min) for this invocation only and, when no override/env is supplied,
+   * defaults to `DEFAULT_BACKGROUND_RUN_SOFT_TIMEOUT_MS`. Does NOT change the
+   * foreground ceiling. Off by default.
+   */
+  backgroundFunction?: boolean;
 }
 
 function isHostedRuntime(): boolean {
@@ -172,15 +223,21 @@ export function resolveRunSoftTimeoutMs(
   options?: ResolveRunSoftTimeoutOptions,
 ): number {
   const hosted = isHostedRuntime();
+  const background = options?.backgroundFunction === true;
+  // The interactive/foreground ceiling is 40s — the synchronous serverless
+  // function wall. A background-function run (opt-in only) has no ~60s wall, so
+  // it is allowed to outlast that and is clamped to the larger 13-min ceiling
+  // instead. The 40s clamp for non-background hosted runs is unchanged.
+  const ceiling = background
+    ? BACKGROUND_SOFT_TIMEOUT_CEILING_MS
+    : HOSTED_SOFT_TIMEOUT_CEILING_MS;
   // A configured/env soft timeout that exceeds the upstream walls can never
   // actually fire (the gateway/function kills the run first), so clamp it down
   // on hosted runtimes. This is what makes auto_continue reach the client
   // instead of the run dying as builder_gateway_timeout / stale_run. `0` means
   // "disabled" and is never clamped up.
   const clampHosted = (ms: number): number =>
-    hosted && ms > HOSTED_SOFT_TIMEOUT_CEILING_MS
-      ? HOSTED_SOFT_TIMEOUT_CEILING_MS
-      : ms;
+    hosted && ms > ceiling ? ceiling : ms;
 
   if (typeof overrideMs === "number" && Number.isFinite(overrideMs)) {
     return clampHosted(Math.max(0, overrideMs));
@@ -190,6 +247,11 @@ export function resolveRunSoftTimeoutMs(
     const raw = Number(envValue);
     if (Number.isFinite(raw) && raw >= 0) return clampHosted(raw);
   }
+  // A background-function run uses the full background budget by default; the
+  // foreground default (40s) is unchanged.
+  if (background) {
+    return hosted ? DEFAULT_BACKGROUND_RUN_SOFT_TIMEOUT_MS : 0;
+  }
   return options?.useHostedDefault && hosted
     ? DEFAULT_HOSTED_RUN_SOFT_TIMEOUT_MS
     : 0;
@@ -343,6 +405,7 @@ export function startRun(
   }, 1500);
   const softTimeoutMs = resolveRunSoftTimeoutMs(options?.softTimeoutMs, {
     useHostedDefault: options?.useHostedSoftTimeoutDefault === true,
+    backgroundFunction: options?.backgroundFunction === true,
   });
   const softTimeoutTimer =
     softTimeoutMs > 0

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";
 
@@ -18,6 +19,21 @@ let _initPromise: Promise<void> | undefined;
  */
 export const RUN_STALE_MS = 15_000;
 
+/**
+ * Stale window for runs dispatched into a Netlify background function
+ * (`dispatch_mode = 'background'`). The design doc flags the 15s reaper vs a
+ * background cold-start as the #1 false-failure risk: the foreground POST
+ * inserts the `running` row, then `fireInternalDispatch` returns 202 and the
+ * background function may take >15s to cold-start and emit its first heartbeat.
+ * With the normal 15s window the reaper would falsely kill that freshly-
+ * inserted-but-not-yet-heartbeaten row. 90s tolerates a slow background
+ * cold-start while still reaping a genuinely dead background worker promptly.
+ *
+ * Only applied to rows explicitly marked background-dispatched; ordinary
+ * foreground runs keep the tight 15s window unchanged.
+ */
+export const BACKGROUND_RUN_STALE_MS = 90_000;
+
 export const STALE_RUN_ERROR_EVENT = {
   type: "error",
   error:
@@ -44,7 +60,8 @@ async function ensureRunTables(): Promise<void> {
           last_progress_at ${intType()},
           turn_id TEXT,
           error_code TEXT,
-          error_detail TEXT
+          error_detail TEXT,
+          dispatch_mode TEXT
         )
       `);
       // Backfill heartbeat_at on older deployments.
@@ -97,7 +114,16 @@ async function ensureRunTables(): Promise<void> {
       //   error_code / error_detail = terminal failure classification captured
       //                at completion so errored/cut-off runs are queryable for
       //                pattern analysis (see listErroredRuns).
-      for (const col of ["turn_id", "error_code", "error_detail"] as const) {
+      // dispatch_mode marks how a run was started: NULL/"foreground" for the
+      // normal synchronous path, "background" for a run dispatched into a
+      // Netlify background function. The reaper/claim widen the stale window
+      // for background rows so a slow cold-start isn't falsely reaped.
+      for (const col of [
+        "turn_id",
+        "error_code",
+        "error_detail",
+        "dispatch_mode",
+      ] as const) {
         try {
           if (isPostgres()) {
             await client.execute(
@@ -134,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;
@@ -234,16 +273,68 @@ export async function insertRun(
   id: string,
   threadId: string,
   turnId?: string,
+  options?: { dispatchMode?: "foreground" | "background" },
 ): Promise<void> {
   await ensureRunTables();
   const client = getDbExec();
   const now = Date.now();
   await client.execute({
-    sql: `INSERT INTO agent_runs (id, thread_id, status, started_at, heartbeat_at, last_progress_at, turn_id) VALUES (?, ?, 'running', ?, ?, ?, ?)`,
-    args: [id, threadId, now, now, now, turnId ?? id],
+    sql: `INSERT INTO agent_runs (id, thread_id, status, started_at, heartbeat_at, last_progress_at, turn_id, dispatch_mode) VALUES (?, ?, 'running', ?, ?, ?, ?, ?)`,
+    args: [
+      id,
+      threadId,
+      now,
+      now,
+      now,
+      turnId ?? id,
+      options?.dispatchMode ?? null,
+    ],
   });
 }
 
+/**
+ * SQL fragment that resolves the per-row stale cutoff. Background-dispatched
+ * runs (`dispatch_mode` starting with `background`) tolerate a much longer gap
+ * without a heartbeat (slow Netlify background-function cold-start) before being
+ * reaped; every other run keeps the tight 15s window. The bound `now` is
+ * subtracted by the resolved window so the comparison is
+ * `COALESCE(heartbeat_at, started_at) < (now - window)`.
+ *
+ * `dispatch_mode` is one of NULL/"foreground" (normal sync path), "background"
+ * (foreground inserted the row for a background dispatch), or
+ * "background-processing" (the background worker claimed it). Both background
+ * 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)`;
+}
+
+/**
+ * Atomically claim a background-dispatched run for processing. The foreground
+ * POST inserts the run row with `dispatch_mode = 'background'`; the FIRST
+ * delivery of the background dispatch flips it to `background-processing` and
+ * wins the claim. A duplicate Netlify delivery (background functions can be
+ * retried) sees `background-processing` and loses, so it no-ops — mirroring
+ * `claimAgentTeamRun` returning null. Returns true when this caller won.
+ *
+ * Idempotent and conditional: the WHERE clause only matches the unclaimed
+ * `background` state AND a still-running row, so a reaped/terminal row can't be
+ * re-claimed.
+ */
+export async function claimBackgroundRun(runId: string): Promise<boolean> {
+  await ensureRunTables();
+  const client = getDbExec();
+  const { rowsAffected } = await client.execute({
+    sql: `UPDATE agent_runs
+          SET dispatch_mode = 'background-processing'
+          WHERE id = ?
+            AND status = 'running'
+            AND dispatch_mode = 'background'`,
+    args: [runId],
+  });
+  return (rowsAffected ?? 0) > 0;
+}
+
 /**
  * Atomically acquire a run lease for a thread. Succeeds (returns true) only
  * when no other run for the same thread is currently status='running' with a
@@ -256,18 +347,37 @@ export async function insertRun(
  */
 export async function tryClaimRunSlot(
   threadId: string,
-  maxStaleMs: number = RUN_STALE_MS,
+  maxStaleMs?: number,
 ): Promise<{ claimed: boolean; activeRunId: string | null }> {
   await ensureRunTables();
   const client = getDbExec();
-  const heartbeatCutoff = Date.now() - maxStaleMs;
+  const now = Date.now();
+  // Default: per-row background-aware window so a live background run (which can
+  // legitimately go >15s between heartbeats during a cold-start) isn't seen as
+  // "free" and double-claimed by a racing foreground POST. An explicit
+  // `maxStaleMs` override keeps a flat window for callers that want one.
+  if (typeof maxStaleMs === "number") {
+    const heartbeatCutoff = now - maxStaleMs;
+    const { rows } = await client.execute({
+      sql: `SELECT id FROM agent_runs
+            WHERE thread_id = ?
+              AND status = 'running'
+              AND COALESCE(heartbeat_at, started_at) >= ?
+            ORDER BY started_at DESC LIMIT 1`,
+      args: [threadId, heartbeatCutoff],
+    });
+    if (rows.length > 0) {
+      return { claimed: false, activeRunId: (rows[0] as { id: string }).id };
+    }
+    return { claimed: true, activeRunId: null };
+  }
   const { rows } = await client.execute({
     sql: `SELECT id FROM agent_runs
           WHERE thread_id = ?
             AND status = 'running'
-            AND COALESCE(heartbeat_at, started_at) >= ?
+            AND COALESCE(heartbeat_at, started_at) >= ${backgroundAwareStaleCutoffSql()}
           ORDER BY started_at DESC LIMIT 1`,
-    args: [threadId, heartbeatCutoff],
+    args: [threadId, now],
   });
   if (rows.length > 0) {
     const row = rows[0] as { id: string };
@@ -335,12 +445,20 @@ export async function bumpRunProgress(runId: string): Promise<void> {
  */
 export async function reapIfStale(
   runId: string,
-  maxStaleMs: number = RUN_STALE_MS,
+  maxStaleMs?: number,
 ): Promise<boolean> {
   await ensureRunTables();
   const client = getDbExec();
   const completedAt = Date.now();
-  const cutoff = completedAt - maxStaleMs;
+  // Background-dispatched runs get the wider stale window so a slow cold-start
+  // isn't reaped; foreground runs keep the tight 15s window. An explicit
+  // override forces a flat window for callers that want one.
+  const staleClause =
+    typeof maxStaleMs === "number"
+      ? `COALESCE(heartbeat_at, started_at) < ?`
+      : `COALESCE(heartbeat_at, started_at) < ${backgroundAwareStaleCutoffSql()}`;
+  const staleArgs =
+    typeof maxStaleMs === "number" ? [completedAt - maxStaleMs] : [completedAt];
   const { rowsAffected } = await client.execute({
     sql: `UPDATE agent_runs
           SET status = 'errored',
@@ -349,13 +467,13 @@ export async function reapIfStale(
               error_detail = ?
           WHERE id = ?
             AND status = 'running'
-            AND COALESCE(heartbeat_at, started_at) < ?`,
+            AND ${staleClause}`,
     args: [
       completedAt,
       STALE_RUN_ERROR_EVENT.errorCode,
       STALE_RUN_ERROR_EVENT.details,
       runId,
-      cutoff,
+      ...staleArgs,
     ],
   });
   const reaped = (rowsAffected ?? 0) > 0;
@@ -675,12 +793,13 @@ export async function getCurrentTurnEventsForThread(
 export async function reapAllStaleRuns(): Promise<number> {
   await ensureRunTables();
   const client = getDbExec();
-  const heartbeatCutoff = Date.now() - RUN_STALE_MS;
+  const now = Date.now();
+  // Background-dispatched runs use the wider window; everything else 15s.
   const stale = await client.execute({
     sql: `SELECT id FROM agent_runs
           WHERE status = 'running'
-            AND COALESCE(heartbeat_at, started_at) < ?`,
-    args: [heartbeatCutoff],
+            AND COALESCE(heartbeat_at, started_at) < ${backgroundAwareStaleCutoffSql()}`,
+    args: [now],
   });
   const completedAt = Date.now();
   const { rowsAffected } = await client.execute({
@@ -690,12 +809,12 @@ export async function reapAllStaleRuns(): Promise<number> {
               error_code = ?,
               error_detail = ?
           WHERE status = 'running'
-            AND COALESCE(heartbeat_at, started_at) < ?`,
+            AND COALESCE(heartbeat_at, started_at) < ${backgroundAwareStaleCutoffSql()}`,
     args: [
       completedAt,
       STALE_RUN_ERROR_EVENT.errorCode,
       STALE_RUN_ERROR_EVENT.details,
-      heartbeatCutoff,
+      completedAt,
     ],
   });
   for (const row of stale.rows) {
@@ -730,15 +849,15 @@ export async function cleanupOldRuns(
   // SELECT covers BOTH UPDATE conditions so the terminal-event-append loop
   // below catches every row we're about to flip — a 24h-old row with a
   // somehow-fresh heartbeat would slip past a heartbeat-only SELECT.
-  const heartbeatCutoff = Date.now() - RUN_STALE_MS;
+  const now = Date.now();
   const stale = await client.execute({
     sql: `SELECT id FROM agent_runs
           WHERE status = 'running'
             AND (
-              COALESCE(heartbeat_at, started_at) < ?
+              COALESCE(heartbeat_at, started_at) < ${backgroundAwareStaleCutoffSql()}
               OR started_at < ?
     )`,
-    args: [heartbeatCutoff, cutoff],
+    args: [now, cutoff],
   });
   const completedAt = Date.now();
   await client.execute({
@@ -755,7 +874,8 @@ export async function cleanupOldRuns(
       cutoff,
     ],
   });
-  // Also expire runs whose heartbeat is stale — producer has died.
+  // Also expire runs whose heartbeat is stale — producer has died. Uses the
+  // background-aware window so a slow background cold-start isn't reaped early.
   await client.execute({
     sql: `UPDATE agent_runs
           SET status = 'errored',
@@ -763,12 +883,12 @@ export async function cleanupOldRuns(
               error_code = ?,
               error_detail = ?
           WHERE status = 'running'
-            AND COALESCE(heartbeat_at, started_at) < ?`,
+            AND COALESCE(heartbeat_at, started_at) < ${backgroundAwareStaleCutoffSql()}`,
     args: [
       completedAt,
       STALE_RUN_ERROR_EVENT.errorCode,
       STALE_RUN_ERROR_EVENT.details,
-      heartbeatCutoff,
+      completedAt,
     ],
   });
   for (const row of stale.rows) {

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

@@ -129,6 +129,26 @@ export interface AgentChatRequest {
   attachments?: AgentChatAttachment[];
   /** Internal retry/continuation requests should not create visible user turns. */
   internalContinuation?: boolean;
+  /**
+   * Internal marker set ONLY by the durable-background self-dispatch (see
+   * `AGENT_CHAT_BACKGROUND_RUN_FIELD`). Present when the agent-chat handler is
+   * re-entered as the background worker: it carries the pre-claimed `runId` and
+   * logical `turnId` so the worker runs the loop inline with the background
+   * soft-timeout instead of re-claiming the slot or re-dispatching. Untrusted
+   * on its own — the `_process-run` route HMAC-verifies the dispatch before
+   * invoking the handler. Absent on every normal client request.
+   */
+  __backgroundRun?: {
+    runId: string;
+    turnId?: string;
+    /**
+     * Number of server-driven background→background continuations already
+     * chained into this logical turn (0 on the first chunk). The worker
+     * increments this when it re-fires `_process-run` at a soft-timeout
+     * boundary and refuses to chain past `MAX_BACKGROUND_RUN_CONTINUATIONS`.
+     */
+    continuationCount?: number;
+  };
   /**
    * Stable identity for the logical assistant turn this request belongs to.
    * The client sends the SAME turnId for the initial POST and every

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;
+  }
+}