@agent-native/core 0.96.0 → 0.97.0

package/corpus/core/docs/content/locales/zh-TW/security.mdx

@@ -415,3 +415,11 @@ AGENT_NATIVE_KEYS_WORKSPACE_FALLBACK=1
 ```
 
 無論此標誌如何，工作空間範圍的秘密寫入仍然需要組織所有者/管理員角色。
+
+## 下一步
+
+- [**Authentication**](/docs/authentication) — 本頁所依賴的驗證模式、cookie realm 和工作階段細節
+- [**Multi-Tenancy**](/docs/multi-tenancy) — `org_id` 範圍界定背後的組織成員模型
+- [**Sharing**](/docs/sharing) — 應用於可共用資源的 `ownableColumns()` 和存取守衛模式
+- [**Messaging**](/docs/messaging#env-vars) — 上方清單中提到的每個整合的 webhook 簽名金鑰
+- [**Deployment**](/docs/deployment) — 此清單假定已設定的正式環境變數

package/corpus/core/docs/content/package-lifecycle.mdx

@@ -0,0 +1,51 @@
+---
+title: Package Lifecycle
+description: Inspect, add, and eject manifest-driven Agent Native packages safely.
+---
+
+# Package lifecycle
+
+Reusable Agent Native packages can publish a versioned static
+`agent-native.package.json`. The CLI reads that JSON without executing package
+code and reports the package's actions, schema entry point, skills, secret key
+names, and peer providers.
+
+```bash
+agent-native package inspect @agent-native/scheduling
+agent-native package inspect @agent-native/scheduling --json
+agent-native package add @agent-native/scheduling
+agent-native package add @agent-native/scheduling --apply
+agent-native package eject @agent-native/scheduling --apply
+```
+
+`add` and `eject` are dry-run by default. `--apply` is required before the CLI
+writes files or runs the detected package manager. Use `--root` for a different
+project root; at a workspace root, pass `--app <name>` to select the target app.
+
+## Safety and idempotency
+
+Before writing, the CLI resolves every contribution and refuses missing or
+ambiguous layouts, existing files with different content, escaping manifest
+paths, and eject targets that already exist. It stages the complete write set,
+uses atomic renames, snapshots package and lock files, and rolls back if the
+package-manager install fails. A provenance record under
+`.agent-native/packages/` makes a repeated add a no-op when generated files are
+unchanged.
+
+Inspection and registry staging use static package metadata only. The CLI never
+imports a package's JavaScript manifest and passes `--ignore-scripts` while
+downloading an uninstalled package archive. Reports show credential key names,
+never credential values.
+
+## Scheduling pilot
+
+`@agent-native/scheduling` is the first package with the generic manifest. Add
+creates action re-export stubs, adds the schema export, copies its agent skills,
+records the dependency, and reports required secret names and providers.
+Eject copies the published Scheduling source to `packages/scheduling`, switches
+the dependency to `workspace:*`, and preserves canonical
+`@agent-native/scheduling` imports so workspace resolution selects the local
+copy.
+
+Ejecting other packages, including Pinpoint, is intentionally refused until the
+Scheduling pilot has proven the contract.

package/corpus/core/docs/content/sandbox-adapters.mdx

@@ -106,6 +106,10 @@ The seam lives in core at `packages/core/src/coding-tools/sandbox/` — `adapter
       path: "index.ts",
       note: "selection: getSandboxAdapter() / registerSandboxAdapter()",
     },
+    {
+      path: "background.ts",
+      note: "durable queue marker and background execution lifecycle",
+    },
     {
       path: "local-child-process-adapter.ts",
       note: "the default backend — locked-down Node child process",
@@ -189,12 +193,17 @@ registerSandboxAdapter(adapter)  →  AGENT_NATIVE_SANDBOX  →  local default
 
 #### `AGENT_NATIVE_SANDBOX` env var {#env}
 
-Selects a built-in adapter by id. Currently only `local` (the default) is wired; unknown values fall back to local rather than failing the run.
+Selects a built-in adapter by id. Both `local` (the default) and `background` are wired; unknown values fall back to local rather than failing the run.
 
 ```bash
-AGENT_NATIVE_SANDBOX=local   # the default — explicit
+AGENT_NATIVE_SANDBOX=local        # the default — explicit
+AGENT_NATIVE_SANDBOX=background   # enqueue every run-code call durably
 ```
 
+`background` stores the raw code in `sandbox_executions` and returns an `executionId` with `status: "queued"` immediately. A signed self-dispatch starts a fresh serverless invocation; long-lived Node starts detached in-process work; status polling and the periodic sweep redrive lost dispatches or expired leases. Poll the execution later for its persisted result.
+
+`BackgroundQueueAdapter` is a durable queue marker, not the executor. Queued work uses a registered non-queued execution adapter when one is available; otherwise it falls back to the local child process. Selecting `background` alone does not provide remote or container isolation, and it does not make an edge runtime compatible with `node:child_process`.
+
 #### `registerSandboxAdapter()` {#register}
 
 A host process overrides the backend for all subsequent `run-code` invocations through the seam's `index.ts` — for example, to run every call in a remote container:
@@ -219,13 +228,15 @@ registerSandboxAdapter(new RemoteSandboxAdapter());
 
 ### The seam for a durable runner {#durable}
 
-This interface is deliberately the seam for a future remote/durable sandbox. A remote or durable adapter (Docker, a Vercel-Sandbox-style runner, or a queued background worker) would:
+The built-in `background` adapter already provides durable queuing and a fresh execution budget, while actual execution still uses a non-queued adapter or the local child-process fallback. A separately registered remote or isolated adapter (Docker or a Vercel-Sandbox-style runner) can provide a different execution boundary and can also execute per-call background work.
+
+Such an adapter would:
 
 1. Implement `SandboxAdapter.run` against an out-of-process runtime.
 2. Tunnel the loopback bridge (or proxy bridge calls back to the parent).
-3. Let large data jobs run to completion independently of the request lifecycle — exceeding the hosted ~40s code-exec ceiling that bounds the local child-process adapter.
+3. Supply remote or container isolation independently of the shipped durable queue lifecycle.
 
-Register it under a new `AGENT_NATIVE_SANDBOX` value (e.g. `remote`) and/or via `registerSandboxAdapter()`. The agent loop and `run-code.ts` never change.
+Register it programmatically via `registerSandboxAdapter()`. The agent loop and `run-code.ts` do not need to change.
 
 <Callout id="doc-block-adap1tip" tone="info">
 

package/corpus/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.96.0",
+  "version": "0.97.0",
   "description": "Framework for agent-native application development — where AI agents and UI share SQL state, actions, and context",
   "homepage": "https://github.com/BuilderIO/agent-native#readme",
   "bugs": {
@@ -101,6 +101,10 @@
     "./shared": "./dist/shared/index.js",
     "./voice": "./dist/voice/index.js",
     "./scripts": "./dist/scripts/index.js",
+    "./guards": {
+      "types": "./dist/guards/index.d.ts",
+      "default": "./dist/guards/index.js"
+    },
     "./application-state": "./dist/application-state/index.js",
     "./settings": "./dist/settings/index.js",
     "./localization": "./dist/localization/index.js",
@@ -207,6 +211,10 @@
       "default": "./dist/local-artifacts/index.js"
     },
     "./workspace-files": "./dist/workspace-files/index.js",
+    "./package-lifecycle": {
+      "types": "./dist/package-lifecycle/index.d.ts",
+      "default": "./dist/package-lifecycle/index.js"
+    },
     "./code-agents": "./dist/code-agents/index.js",
     "./code-agents/transcript-normalizer": "./dist/code-agents/transcript-normalizer.js",
     "./workspace-connections": "./dist/workspace-connections/index.js",
@@ -373,7 +381,6 @@
     "react-dom": "^19.2.7",
     "react-router": "^8.1.0",
     "tailwindcss": "catalog:",
-    "typescript": "catalog:",
     "typescript-7": "catalog:",
     "vite": "catalog:",
     "vitest": "^4.1.5",

package/corpus/core/src/a2a/auth-policy.ts

@@ -31,3 +31,36 @@ export function hasConfiguredA2ASecret(): boolean {
 export function shouldAdvertiseJwtA2AAuth(): boolean {
   return hasConfiguredA2ASecret() || isA2AProductionRuntime();
 }
+
+/**
+ * True only when unsigned internal self-dispatch is acceptable: no A2A_SECRET
+ * is configured AND we can positively identify a local/dev runtime. Everything
+ * else — production, or any UNRECOGNIZED deployed/networked host — must fail
+ * closed and require A2A_SECRET. `loopback` should be whether the inbound
+ * request arrived over the loopback interface (127.0.0.1/::1); callers that
+ * cannot determine the peer address pass `false`.
+ *
+ * NODE_ENV alone is deliberately NOT a trust grant: a self-hosted deployment
+ * that doesn't set NODE_ENV=production and isn't recognized by
+ * `isA2AProductionRuntime()` (a bare Docker/VPS/K8s pod) must still fail
+ * closed unless the request actually came from loopback or the explicit
+ * opt-in flag is set.
+ */
+export function isTrustedLocalRuntime(opts: { loopback: boolean }): boolean {
+  if (isA2AProductionRuntime()) return false;
+  if (process.env.A2A_ALLOW_UNSIGNED_INTERNAL === "1") return true;
+  return opts.loopback === true;
+}
+
+/** True if a socket peer address is a loopback/local address. */
+export function isLoopbackAddress(addr: string | undefined | null): boolean {
+  if (!addr) return false;
+  const a = addr.trim();
+  return (
+    a === "127.0.0.1" ||
+    a === "::1" ||
+    a === "::ffff:127.0.0.1" ||
+    a.startsWith("127.") ||
+    a === "localhost"
+  );
+}

package/corpus/core/src/agent/durable-background.ts

@@ -39,7 +39,7 @@
  */
 import {
   hasConfiguredA2ASecret,
-  isA2AProductionRuntime,
+  isTrustedLocalRuntime,
 } from "../a2a/auth-policy.js";
 import {
   extractBearerToken,
@@ -469,10 +469,13 @@ export function extractProcessRunId(body: unknown): string | null {
  *
  * Auth policy mirrors the agent-teams processor exactly:
  *   - `A2A_SECRET` set → require a valid `verifyInternalToken(runId, token)`.
- *   - no secret but a production runtime → refuse (503) — never run unsigned in
- *     prod.
- *   - no secret + non-prod (local dev) → allow unsigned; the SQL atomic claim
- *     in the worker still prevents double-processing.
+ *   - no secret → require `isTrustedLocalRuntime({ loopback })` (see
+ *     auth-policy.ts): refuse (503) unless `A2A_ALLOW_UNSIGNED_INTERNAL=1` is
+ *     set. This function has no h3 `event` of its own, so callers that CAN
+ *     see the inbound socket peer (the route handler, which has the event)
+ *     should compute `loopback` from it and pass it through; callers that
+ *     can't determine the peer address should omit it (defaults to `false`
+ *     — never trust unsigned dispatch without an explicit opt-in).
  *
  * Extracted from the route handler so the auth + marker-prep decision is unit
  * testable without booting the whole Nitro plugin. The route only adds body
@@ -481,6 +484,7 @@ export function extractProcessRunId(body: unknown): string | null {
 export function prepareProcessRunRequest(
   body: unknown,
   authHeader: string | undefined,
+  loopback: boolean = false,
 ): ProcessRunPreparation {
   if (!body || typeof body !== "object") {
     return {
@@ -514,12 +518,16 @@ export function prepareProcessRunRequest(
         runId,
       };
     }
-  } else if (isA2AProductionRuntime()) {
+  } else if (!isTrustedLocalRuntime({ loopback })) {
+    // Callers that can see the h3 `event` (the route handler) pass the real
+    // loopback signal; callers without one default to non-loopback. Unsigned
+    // dispatch is still allowed via A2A_ALLOW_UNSIGNED_INTERNAL=1 for trusted
+    // local/dev setups; see auth-policy.ts `isTrustedLocalRuntime`.
     return {
       ok: false,
       status: 503,
       error:
-        "Agent chat background processor not configured — set A2A_SECRET on this deployment.",
+        "Agent chat background processor not configured — set A2A_SECRET on this deployment (or A2A_ALLOW_UNSIGNED_INTERNAL=1 for trusted local dev).",
       runId,
     };
   }

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

@@ -1759,7 +1759,7 @@ export async function listRunsForThread(
           LIMIT ?`,
     args: [threadId, limit],
   });
-  let repairedTerminalRow = false;
+  const reconcileCandidateIds: string[] = [];
   for (const r of rows) {
     const row = r as {
       id?: string;
@@ -1773,10 +1773,19 @@ export async function listRunsForThread(
       (row.status === "errored" &&
         row.error_code === STALE_RUN_ERROR_EVENT.errorCode);
     if (!canReconcileFromEvents) continue;
-    repairedTerminalRow =
-      (await reconcileTerminalRunFromEvents(runId).catch(() => false)) ||
-      repairedTerminalRow;
+    reconcileCandidateIds.push(runId);
   }
+  // Each candidate's reconciliation is independently fenced by the UPDATE's
+  // WHERE clause (status = 'running' OR errored-with-stale-code) inside
+  // reconcileTerminalRunFromEvents, keyed on that run's own id — reconciling
+  // several stale runs in parallel is safe and avoids N sequential
+  // SELECT+UPDATE round-trip pairs on a shared-thread page load.
+  const reconcileResults = await Promise.all(
+    reconcileCandidateIds.map((runId) =>
+      reconcileTerminalRunFromEvents(runId).catch(() => false),
+    ),
+  );
+  const repairedTerminalRow = reconcileResults.some(Boolean);
   if (repairedTerminalRow) {
     const refreshed = await client.execute({
       sql: `SELECT id, thread_id, turn_id, status, started_at, heartbeat_at, completed_at, last_progress_at, error_code, abort_reason, dispatch_mode, terminal_reason, diag_stage

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

@@ -0,0 +1,162 @@
+import { z } from "zod";
+
+import { defineAction } from "../../action.js";
+import { MAX_LIMIT, queryAuditEvents } from "../store.js";
+import type { AuditEvent } from "../types.js";
+
+const DEFAULT_MAX_ROWS = 5000;
+const HARD_CAP_ROWS = 10000;
+
+// Deterministic column order for CSV — mirrors the store's list projection
+// (`LIST_COLUMNS`), which deliberately excludes `input` so a bulk export
+// never streams every event's (redacted) request body at once. Future
+// columns added to the audit store must be reflected here too.
+const CSV_COLUMNS: Array<[key: keyof AuditEvent, header: string]> = [
+  ["id", "id"],
+  ["createdAt", "created_at"],
+  ["action", "action"],
+  ["caller", "caller"],
+  ["actorKind", "actor_kind"],
+  ["actorEmail", "actor_email"],
+  ["orgId", "org_id"],
+  ["threadId", "thread_id"],
+  ["turnId", "turn_id"],
+  ["targetType", "target_type"],
+  ["targetId", "target_id"],
+  ["status", "status"],
+  ["summary", "summary"],
+  ["errorCode", "error_code"],
+  ["ownerEmail", "owner_email"],
+  ["visibility", "visibility"],
+];
+
+/** Hand-rolled CSV field escaper — quotes a field when it contains a comma,
+ *  quote, or newline, doubling any embedded quotes. No dependency needed for
+ *  ~10 lines of RFC 4180 escaping. */
+function csvField(value: unknown): string {
+  if (value === null || value === undefined) return "";
+  const raw = String(value);
+  if (/[",\n\r]/.test(raw)) {
+    return `"${raw.replace(/"/g, '""')}"`;
+  }
+  return raw;
+}
+
+function toCsv(events: AuditEvent[]): string {
+  const header = CSV_COLUMNS.map(([, label]) => label).join(",");
+  const rows = events.map((event) =>
+    CSV_COLUMNS.map(([key]) => csvField(event[key])).join(","),
+  );
+  return [header, ...rows].join("\n");
+}
+
+function toNdjson(events: AuditEvent[]): string {
+  return events.map((event) => JSON.stringify(event)).join("\n");
+}
+
+/**
+ * Bulk-export audit-log events as CSV or NDJSON — the "bulk export" sensitive
+ * read the audit doc itself names. Pages past the per-call row clamp
+ * (`queryAuditEvents`'s `MAX_LIMIT`) up to `maxRows`, scoped in SQL to the
+ * caller's identity exactly like `list-audit-events`. Read-only; never
+ * exposes other tenants' rows.
+ */
+export default defineAction({
+  description:
+    "Export audit-log events as a CSV or NDJSON document for offline/compliance pulls (up to maxRows, default 5000, hard cap 10000). Use this instead of hand-paging list-audit-events when you need a bulk download of the trail; use list-audit-events instead for browsing recent activity or answering 'what changed'.",
+  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)."),
+    format: z
+      .enum(["csv", "ndjson"])
+      .default("csv")
+      .describe(
+        "Export format — CSV with a header row, or one JSON event per line.",
+      ),
+    maxRows: z
+      .number()
+      .optional()
+      .describe("Max rows to export (default 5000, hard cap 10000)."),
+  }),
+  http: { method: "GET" },
+  audit: {
+    // Read-only actions are skipped by default — this is exactly the
+    // "bulk export" sensitive read the framework's own audit doc calls out.
+    onRead: true,
+    summary: (args) =>
+      `Bulk export of audit events (${(args as { format?: string }).format ?? "csv"})`,
+  },
+  run: async (args, ctx) => {
+    const scope = { userEmail: ctx?.userEmail, orgId: ctx?.orgId ?? null };
+    const cap = Math.min(
+      Math.max(1, Math.floor(args.maxRows ?? DEFAULT_MAX_ROWS)),
+      HARD_CAP_ROWS,
+    );
+
+    const filters = {
+      ...(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 } : {}),
+    };
+
+    const events: AuditEvent[] = [];
+    let offset = 0;
+    while (events.length < cap) {
+      const pageLimit = Math.min(MAX_LIMIT, cap - events.length);
+      const page = await queryAuditEvents(scope, {
+        ...filters,
+        limit: pageLimit,
+        offset,
+      });
+      events.push(...page);
+      offset += page.length;
+      if (page.length < pageLimit) break; // exhausted — no more matching rows
+    }
+
+    // We stopped because we hit the cap, not because we ran out of rows —
+    // probe one more row to know whether the export was actually truncated.
+    let truncated = false;
+    if (events.length >= cap) {
+      const probe = await queryAuditEvents(scope, {
+        ...filters,
+        limit: 1,
+        offset,
+      });
+      truncated = probe.length > 0;
+    }
+
+    const content = args.format === "ndjson" ? toNdjson(events) : toCsv(events);
+    return { content, rowCount: events.length, truncated, format: args.format };
+  },
+});

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

@@ -250,7 +250,9 @@ function scopeClause(scope: AuditReadScope): { sql: string; args: any[] } {
   return { sql: `(${clauses.join(" OR ")})`, args };
 }
 
-const MAX_LIMIT = 500;
+// Exported so callers that must page past a single call (e.g.
+// `export-audit-events`) can mirror the clamp instead of guessing it.
+export const MAX_LIMIT = 500;
 const DEFAULT_LIMIT = 100;
 
 // Columns returned by the list surface — deliberately EXCLUDES `input` so a
@@ -297,13 +299,16 @@ export async function queryAuditEvents(
     Math.max(1, Math.floor(filters.limit ?? DEFAULT_LIMIT)),
     MAX_LIMIT,
   );
+  // 0-based, default-compatible: existing callers that never pass `offset`
+  // keep selecting from the top of the ordered result set.
+  const offset = Math.max(0, Math.floor(filters.offset ?? 0));
 
   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],
+          LIMIT ? OFFSET ?`,
+    args: [...args, limit, offset],
   });
   return (result.rows ?? []).map(mapRow);
 }

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

@@ -135,4 +135,7 @@ export interface AuditQueryFilters {
   sourcePlatform?: string;
   sinceMs?: number;
   limit?: number;
+  /** Skip this many matching rows before applying `limit` (0-based). Used by
+   *  `export-audit-events` to page past the per-call `MAX_LIMIT` clamp. */
+  offset?: number;
 }