@agent-native/core 0.71.0 → 0.72.1

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

@@ -0,0 +1,91 @@
+/**
+ * Pure (no-DB) audit configuration helpers.
+ *
+ * Kept free of any database / store import so `action.ts` can statically
+ * import them without pulling the DB client into every bundle that touches an
+ * action. The DB-touching recorder lives in `record.ts`, which `action.ts`
+ * loads lazily via dynamic import on first audited call.
+ */
+import type {
+  ActionAuditConfig,
+  AuditActorKind,
+  AuditStatus,
+} from "./types.js";
+
+/**
+ * High-frequency / ephemeral framework actions that are not meaningful audit
+ * events. They mutate UI/agent-context state many times per session; auditing
+ * each one would flood the log without recording a real user-facing change.
+ *
+ * An action can still force itself on with `audit: { enabled: true }` —
+ * explicit config always wins over this denylist (see `shouldRecordAudit`).
+ */
+const DEFAULT_SKIP_ACTIONS = new Set<string>([
+  "context-pin",
+  "context-evict",
+  "context-restore",
+  "context-report",
+  "context-manifest-get",
+  "change-appearance",
+  "toggle-demo-mode",
+]);
+
+/** Name patterns for high-frequency state-sync actions, skipped by default. */
+const DEFAULT_SKIP_PATTERN =
+  /(application-state|app-state|set-state|view-screen|navigate|poll)/i;
+
+/** Normalize a raw `audit` option into a config object (or undefined). */
+export function normalizeAuditConfig(
+  raw: unknown,
+): ActionAuditConfig | undefined {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return undefined;
+  return raw as ActionAuditConfig;
+}
+
+/**
+ * Whether to attach the audit wrapper to an action at definition time. Decided
+ * from the action's resolved `readOnly` flag plus its config — the action's
+ * *name* isn't known here (it's the registry key), so name-based skipping
+ * happens later in `shouldRecordAudit`.
+ */
+export function resolveAuditAttach(
+  config: ActionAuditConfig | undefined,
+  readOnly: boolean | undefined,
+): boolean {
+  if (config && typeof config.enabled === "boolean") return config.enabled;
+  // Read-only actions are not audited unless they opt in via `onRead`.
+  if (readOnly === true) return config?.onRead === true;
+  // Everything else mutates — audit by default.
+  return true;
+}
+
+/**
+ * Final, name-aware decision made at record time. Explicit `enabled: true`
+ * overrides the high-frequency denylist; otherwise denylisted names are
+ * dropped.
+ */
+export function shouldRecordAudit(
+  config: ActionAuditConfig | undefined,
+  actionName: string,
+): boolean {
+  if (config && config.enabled === true) return true;
+  if (DEFAULT_SKIP_ACTIONS.has(actionName)) return false;
+  if (DEFAULT_SKIP_PATTERN.test(actionName)) return false;
+  return true;
+}
+
+/** Derive the actor kind from the invocation surface + resolved identity. */
+export function deriveActorKind(
+  caller: string | undefined,
+  actorEmail: string | undefined | null,
+): AuditActorKind {
+  if (caller === "tool") return "agent";
+  return actorEmail ? "human" : "system";
+}
+
+/** Whether the whole subsystem is disabled via env. */
+export function isAuditDisabled(): boolean {
+  return process.env.AGENT_NATIVE_AUDIT_ENABLED === "false";
+}
+
+export type { AuditStatus };

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

@@ -0,0 +1,43 @@
+/**
+ * Framework audit log — a durable, complete, access-scoped, append-only record
+ * of who mutated what app data, when, from where, and (for the agent) in which
+ * run. Distinct from observability (sampled telemetry) and tracking
+ * (fire-and-forget analytics). Capture is automatic at the `defineAction` seam.
+ */
+export type {
+  ActionAuditConfig,
+  AuditActorKind,
+  AuditCallMeta,
+  AuditEvent,
+  AuditQueryFilters,
+  AuditStatus,
+  AuditTarget,
+  AuditVisibility,
+} from "./types.js";
+
+export {
+  deriveActorKind,
+  isAuditDisabled,
+  normalizeAuditConfig,
+  resolveAuditAttach,
+  shouldRecordAudit,
+} from "./config.js";
+
+export { redactArgsToJson } from "./redact.js";
+
+export {
+  ensureAuditTables,
+  insertAuditEvent,
+  queryAuditEvents,
+  getAuditEventById,
+  deleteOldAuditEvents,
+  type AuditReadScope,
+} from "./store.js";
+
+export { recordActionAudit } from "./record.js";
+
+export {
+  runAuditCleanupOnce,
+  startAuditCleanupJob,
+  stopAuditCleanupJob,
+} from "./cleanup-job.js";

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

@@ -0,0 +1,143 @@
+/**
+ * Audit capture entry point, called from the `defineAction` audit wrapper after
+ * an action runs (success or error). Best-effort: any failure here is swallowed
+ * so auditing never breaks the action it observes.
+ *
+ * This module touches the DB (`store.js`), so `action.ts` loads it lazily via
+ * dynamic import on the first audited call — keeping the DB client out of every
+ * bundle that merely defines actions.
+ */
+import {
+  deriveActorKind,
+  isAuditDisabled,
+  shouldRecordAudit,
+} from "./config.js";
+import { redactArgsToJson } from "./redact.js";
+import { insertAuditEvent } from "./store.js";
+import type {
+  ActionAuditConfig,
+  AuditCallMeta,
+  AuditEvent,
+  AuditStatus,
+  AuditTarget,
+} from "./types.js";
+
+/** Minimal view of the action run context the recorder needs. */
+export interface AuditRunContextLike {
+  actionName?: string;
+  caller?: string;
+  userEmail?: string;
+  orgId?: string | null;
+  threadId?: string;
+  turnId?: string;
+}
+
+export interface RecordActionAuditInput {
+  config: ActionAuditConfig | undefined;
+  args: unknown;
+  ctx: AuditRunContextLike | undefined;
+  status: AuditStatus;
+  result?: unknown;
+  error?: unknown;
+}
+
+function errorCode(error: unknown): string | null {
+  if (!error) return null;
+  if (typeof error === "object") {
+    const e = error as { errorCode?: unknown; code?: unknown; name?: unknown };
+    if (typeof e.errorCode === "string") return e.errorCode;
+    if (typeof e.code === "string") return e.code;
+    if (typeof e.name === "string") return e.name;
+  }
+  return "error";
+}
+
+function safeTarget(
+  config: ActionAuditConfig | undefined,
+  args: unknown,
+  result: unknown,
+  meta: AuditCallMeta,
+): AuditTarget | null {
+  if (!config?.target) return null;
+  try {
+    return config.target(args, result, meta) ?? null;
+  } catch {
+    return null;
+  }
+}
+
+function safeSummary(
+  config: ActionAuditConfig | undefined,
+  args: unknown,
+  result: unknown,
+  meta: AuditCallMeta,
+): string | null {
+  if (!config?.summary) return null;
+  try {
+    const s = config.summary(args, result, meta);
+    return typeof s === "string" ? s.slice(0, 500) : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Record one audit event. Resolves the actor, target, ownership (for scoped
+ * reads), and redacted inputs, then appends a row. Never throws.
+ */
+export async function recordActionAudit(
+  input: RecordActionAuditInput,
+): Promise<void> {
+  try {
+    if (isAuditDisabled()) return;
+    const ctx = input.ctx;
+    const actionName = ctx?.actionName;
+    // No name → an internal/programmatic run() with no dispatch context. Skip
+    // rather than write a nameless row.
+    if (!actionName) return;
+    if (!shouldRecordAudit(input.config, actionName)) return;
+
+    const caller = ctx?.caller ?? "http";
+    const actorEmail = ctx?.userEmail ?? null;
+    const meta: AuditCallMeta = {
+      status: input.status,
+      caller,
+      userEmail: ctx?.userEmail,
+      orgId: ctx?.orgId ?? null,
+    };
+
+    const target = safeTarget(input.config, input.args, input.result, meta);
+    const summary = safeSummary(input.config, input.args, input.result, meta);
+
+    const recordInputs = input.config?.recordInputs !== false;
+    const inputJson = recordInputs ? redactArgsToJson(input.args) : null;
+
+    const event: AuditEvent = {
+      id: crypto.randomUUID(),
+      createdAt: Date.now(),
+      action: actionName,
+      caller,
+      actorKind: deriveActorKind(caller, actorEmail),
+      actorEmail,
+      orgId: ctx?.orgId ?? null,
+      threadId: ctx?.threadId ?? null,
+      turnId: ctx?.turnId ?? null,
+      targetType: target?.type ?? null,
+      targetId: target?.id ?? null,
+      status: input.status,
+      summary,
+      input: inputJson,
+      errorCode: input.status === "error" ? errorCode(input.error) : null,
+      // Scope reads to the resource owner when the action declares one,
+      // otherwise to the actor (the common self-mutation case).
+      ownerEmail: target?.ownerEmail ?? actorEmail,
+      visibility: target?.visibility ?? "private",
+    };
+    // org_id used for scoping defaults to the target's, else the actor's org.
+    if (target?.orgId !== undefined) event.orgId = target.orgId;
+
+    await insertAuditEvent(event);
+  } catch {
+    // Best-effort — auditing must never break the audited action.
+  }
+}

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

@@ -0,0 +1,109 @@
+/**
+ * Redaction for audit-captured arguments.
+ *
+ * The audit log must never become a secondary store of secrets. Before any
+ * call arguments are persisted we:
+ *  - drop values under credential-looking keys (token, secret, password, …),
+ *  - redact string values that look like bearer tokens / long opaque keys,
+ *  - truncate oversized strings and cap the serialized payload size.
+ *
+ * This mirrors the framework's standing rule that credential-looking literals
+ * never land in source, logs, or fixtures.
+ */
+
+const SENSITIVE_KEY =
+  /(pass(word|phrase)?|secret|token|api[_-]?key|apikey|authorization|bearer|credential|cookie|session[_-]?(id|token)|private[_-]?key|client[_-]?secret|signing[_-]?secret|access[_-]?key|refresh[_-]?token|webhook[_-]?(url|secret))/i;
+
+const REDACTED = "[redacted]";
+const MAX_STRING = 2000;
+const MAX_DEPTH = 6;
+const MAX_KEYS = 100;
+const MAX_ARRAY = 100;
+const MAX_JSON = 8000;
+
+/** Heuristic: does a bare string value look like a secret? */
+function looksSecret(value: string): boolean {
+  if (/^bearer\s+\S/i.test(value)) return true;
+  // Long, unbroken, high-entropy-ish opaque token (hex/base64url, no spaces).
+  if (value.length >= 32 && /^[A-Za-z0-9_\-+/=.]+$/.test(value)) return true;
+  // Common secret prefixes (Stripe, GitHub, OpenAI, Slack, AWS, …).
+  if (/^(sk|pk|rk|ghp|gho|xox[baprs]|AKIA|AIza|ya29)[-_]/i.test(value)) {
+    return true;
+  }
+  // Webhook URLs carry their secret in the path — redact regardless of the key
+  // they arrive under (e.g. a generic `value` field holding a Slack webhook).
+  if (
+    /^https?:\/\/(hooks\.slack\.com\/|[^/]*\.webhook\.office\.com\/|(canary\.|ptb\.)?discord(app)?\.com\/api\/webhooks\/|hooks\.zapier\.com\/|maker\.ifttt\.com\/|discord\.com\/api\/webhooks\/)/i.test(
+      value,
+    )
+  ) {
+    return true;
+  }
+  return false;
+}
+
+function redactString(value: string): string {
+  if (looksSecret(value)) return REDACTED;
+  if (value.length > MAX_STRING) {
+    return `${value.slice(0, MAX_STRING)}…(${value.length - MAX_STRING} more chars)`;
+  }
+  return value;
+}
+
+function redact(value: unknown, depth: number): unknown {
+  if (value == null) return value;
+  if (typeof value === "string") return redactString(value);
+  if (typeof value === "number" || typeof value === "boolean") return value;
+  if (depth >= MAX_DEPTH) return "[…]";
+  if (Array.isArray(value)) {
+    const out = value.slice(0, MAX_ARRAY).map((v) => redact(v, depth + 1));
+    if (value.length > MAX_ARRAY)
+      out.push(`…(${value.length - MAX_ARRAY} more)`);
+    return out;
+  }
+  if (typeof value === "object") {
+    const out: Record<string, unknown> = {};
+    let n = 0;
+    for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+      if (n >= MAX_KEYS) {
+        out["…"] = "(truncated)";
+        break;
+      }
+      n += 1;
+      out[k] = SENSITIVE_KEY.test(k) ? REDACTED : redact(v, depth + 1);
+    }
+    return out;
+  }
+  // Functions, symbols, bigint, etc. — not serializable / not interesting.
+  return undefined;
+}
+
+/**
+ * Redact and serialize call arguments to a capped JSON string, or `null` when
+ * there is nothing to record. Never throws.
+ */
+export function redactArgsToJson(args: unknown): string | null {
+  try {
+    if (args == null) return null;
+    const redacted = redact(args, 0);
+    if (redacted === undefined) return null;
+    const json = JSON.stringify(redacted);
+    if (json == null) return null;
+    if (json.length > MAX_JSON) {
+      // Slicing the serialized JSON would yield an unparseable string. Wrap a
+      // preview in a valid envelope so `get-audit-event` can always JSON.parse
+      // the stored `input`.
+      return JSON.stringify({
+        _auditTruncated: true,
+        originalBytes: json.length,
+        preview: json.slice(0, MAX_JSON),
+      });
+    }
+    return json;
+  } catch {
+    return null;
+  }
+}
+
+/** Exposed for tests. */
+export const __test = { looksSecret, redact, SENSITIVE_KEY };

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

@@ -0,0 +1,244 @@
+/**
+ * SQL persistence for the framework audit log.
+ *
+ * Follows the same raw-SQL, provider-agnostic pattern as observability/store.ts
+ * and usage/store.ts — framework tables use `getDbExec()` + `intType()` rather
+ * than Drizzle ORM (which is for template-level schemas). One append-only table
+ * `agent_audit_log`; reads are scoped to the caller's identity in SQL (no
+ * shares table — audit rows are never individually shared).
+ */
+import { getDbExec, intType, retryOnDdlRace } from "../db/client.js";
+import type {
+  AuditEvent,
+  AuditQueryFilters,
+  AuditVisibility,
+} from "./types.js";
+
+let _initPromise: Promise<void> | undefined;
+
+export async function ensureAuditTables(): Promise<void> {
+  if (!_initPromise) {
+    _initPromise = (async () => {
+      const client = getDbExec();
+
+      await retryOnDdlRace(() =>
+        client.execute(`
+        CREATE TABLE IF NOT EXISTS agent_audit_log (
+          id TEXT PRIMARY KEY,
+          created_at ${intType()} NOT NULL,
+          action TEXT NOT NULL,
+          caller TEXT NOT NULL,
+          actor_kind TEXT NOT NULL,
+          actor_email TEXT,
+          org_id TEXT,
+          thread_id TEXT,
+          turn_id TEXT,
+          target_type TEXT,
+          target_id TEXT,
+          status TEXT NOT NULL DEFAULT 'success',
+          summary TEXT,
+          input TEXT,
+          error_code TEXT,
+          owner_email TEXT,
+          visibility TEXT NOT NULL DEFAULT 'private'
+        )
+      `),
+      );
+
+      const indexes = [
+        `CREATE INDEX IF NOT EXISTS idx_audit_owner ON agent_audit_log (owner_email, created_at)`,
+        `CREATE INDEX IF NOT EXISTS idx_audit_org ON agent_audit_log (org_id, created_at)`,
+        `CREATE INDEX IF NOT EXISTS idx_audit_target ON agent_audit_log (target_type, target_id, created_at)`,
+        `CREATE INDEX IF NOT EXISTS idx_audit_turn ON agent_audit_log (turn_id)`,
+        `CREATE INDEX IF NOT EXISTS idx_audit_actor ON agent_audit_log (actor_email, created_at)`,
+        `CREATE INDEX IF NOT EXISTS idx_audit_created ON agent_audit_log (created_at)`,
+      ];
+      for (const sql of indexes) {
+        try {
+          await client.execute(sql);
+        } catch {
+          // Index creation is best-effort; a racing boot may have created it.
+        }
+      }
+    })().catch((err) => {
+      // Allow a later call to retry if the first init failed.
+      _initPromise = undefined;
+      throw err;
+    });
+  }
+  return _initPromise;
+}
+
+export async function insertAuditEvent(event: AuditEvent): Promise<void> {
+  await ensureAuditTables();
+  const client = getDbExec();
+  await client.execute({
+    sql: `INSERT INTO agent_audit_log
+      (id, created_at, action, caller, actor_kind, actor_email, org_id,
+       thread_id, turn_id, target_type, target_id, status, summary, input,
+       error_code, owner_email, visibility)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+    args: [
+      event.id,
+      event.createdAt,
+      event.action,
+      event.caller,
+      event.actorKind,
+      event.actorEmail,
+      event.orgId,
+      event.threadId,
+      event.turnId,
+      event.targetType,
+      event.targetId,
+      event.status,
+      event.summary,
+      event.input,
+      event.errorCode,
+      event.ownerEmail,
+      event.visibility,
+    ],
+  });
+}
+
+function mapRow(row: any): AuditEvent {
+  return {
+    id: String(row.id),
+    createdAt: Number(row.created_at),
+    action: String(row.action),
+    caller: String(row.caller),
+    actorKind: row.actor_kind,
+    actorEmail: row.actor_email ?? null,
+    orgId: row.org_id ?? null,
+    threadId: row.thread_id ?? null,
+    turnId: row.turn_id ?? null,
+    targetType: row.target_type ?? null,
+    targetId: row.target_id ?? null,
+    status: row.status,
+    summary: row.summary ?? null,
+    input: row.input ?? null,
+    errorCode: row.error_code ?? null,
+    ownerEmail: row.owner_email ?? null,
+    visibility: (row.visibility ?? "private") as AuditVisibility,
+  };
+}
+
+export interface AuditReadScope {
+  userEmail?: string;
+  orgId?: string | null;
+}
+
+/**
+ * Build the access-scoping WHERE fragment + args. A caller sees audit rows they
+ * own, plus org-visible rows in their org. With no identity, nothing matches —
+ * the audit log never leaks cross-tenant. Mirrors the core ownership clause of
+ * `accessFilter` (minus shares, which audit rows don't have).
+ */
+function scopeClause(scope: AuditReadScope): { sql: string; args: any[] } {
+  const clauses: string[] = [];
+  const args: any[] = [];
+  if (scope.userEmail) {
+    if (scope.orgId) {
+      // Constrain the owner's rows to the active org — plus legacy/solo rows
+      // that predate org-scoping (org_id IS NULL) — mirroring sharing's
+      // `ownerScopeFilter`, so switching orgs doesn't surface another org's
+      // trail.
+      clauses.push("(owner_email = ? AND (org_id = ? OR org_id IS NULL))");
+      args.push(scope.userEmail, scope.orgId);
+    } else {
+      clauses.push("owner_email = ?");
+      args.push(scope.userEmail);
+    }
+  }
+  if (scope.orgId) {
+    clauses.push("(visibility = 'org' AND org_id = ?)");
+    args.push(scope.orgId);
+  }
+  if (clauses.length === 0) return { sql: "1=0", args };
+  return { sql: `(${clauses.join(" OR ")})`, args };
+}
+
+const MAX_LIMIT = 500;
+const DEFAULT_LIMIT = 100;
+
+// Columns returned by the list surface — deliberately EXCLUDES `input` so a
+// timeline query never streams every event's (redacted) request body in bulk.
+// Fetch the full payload one event at a time via `getAuditEventById`.
+const LIST_COLUMNS =
+  "id, created_at, action, caller, actor_kind, actor_email, org_id, " +
+  "thread_id, turn_id, target_type, target_id, status, summary, " +
+  "error_code, owner_email, visibility";
+
+export async function queryAuditEvents(
+  scope: AuditReadScope,
+  filters: AuditQueryFilters = {},
+): Promise<AuditEvent[]> {
+  await ensureAuditTables();
+  if (!scope.userEmail && !scope.orgId) return [];
+  const client = getDbExec();
+
+  const scoped = scopeClause(scope);
+  const where: string[] = [scoped.sql];
+  const args: any[] = [...scoped.args];
+
+  const push = (clause: string, value: any) => {
+    where.push(clause);
+    args.push(value);
+  };
+  if (filters.targetType) push("target_type = ?", filters.targetType);
+  if (filters.targetId) push("target_id = ?", filters.targetId);
+  if (filters.actorKind) push("actor_kind = ?", filters.actorKind);
+  if (filters.actorEmail) push("actor_email = ?", filters.actorEmail);
+  if (filters.status) push("status = ?", filters.status);
+  if (filters.threadId) push("thread_id = ?", filters.threadId);
+  if (filters.turnId) push("turn_id = ?", filters.turnId);
+  if (filters.action) push("action = ?", filters.action);
+  if (typeof filters.sinceMs === "number") {
+    push("created_at >= ?", Math.floor(filters.sinceMs));
+  }
+
+  const limit = Math.min(
+    Math.max(1, Math.floor(filters.limit ?? DEFAULT_LIMIT)),
+    MAX_LIMIT,
+  );
+
+  const result = await client.execute({
+    sql: `SELECT ${LIST_COLUMNS} FROM agent_audit_log
+          WHERE ${where.join(" AND ")}
+          ORDER BY created_at DESC
+          LIMIT ?`,
+    args: [...args, limit],
+  });
+  return (result.rows ?? []).map(mapRow);
+}
+
+export async function getAuditEventById(
+  id: string,
+  scope: AuditReadScope,
+): Promise<AuditEvent | null> {
+  await ensureAuditTables();
+  if (!scope.userEmail && !scope.orgId) return null;
+  const client = getDbExec();
+  const scoped = scopeClause(scope);
+  const result = await client.execute({
+    sql: `SELECT * FROM agent_audit_log WHERE id = ? AND ${scoped.sql} LIMIT 1`,
+    args: [id, ...scoped.args],
+  });
+  const row = (result.rows ?? [])[0];
+  return row ? mapRow(row) : null;
+}
+
+/** Purge audit rows older than `cutoffMs`. Returns the deleted row count. */
+export async function deleteOldAuditEvents(cutoffMs: number): Promise<number> {
+  await ensureAuditTables();
+  const client = getDbExec();
+  const result = await client.execute({
+    sql: `DELETE FROM agent_audit_log WHERE created_at < ?`,
+    args: [Math.floor(cutoffMs)],
+  });
+  return Number(result.rowsAffected ?? 0);
+}
+
+/** Test-only: reset the cached init promise so a fresh DB re-creates tables. */
+export function __resetAuditInitForTests(): void {
+  _initPromise = undefined;
+}