@agent-native/core 0.95.1 → 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.95.1",
+  "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",
@@ -219,6 +227,8 @@
     "./terminal/server": "./dist/terminal/index.js",
     "./tailwind": "./dist/tailwind.preset.js",
     "./styles/agent-native.css": "./dist/styles/agent-native.css",
+    "./styles/agent-conversation.css": "./dist/styles/agent-conversation.css",
+    "./styles/chat-history-list.css": "./dist/styles/chat-history-list.css",
     "./agent/engine": "./dist/agent/engine/index.js",
     "./agent/harness": "./dist/agent/harness/index.js",
     "./eval": "./dist/eval/index.js",
@@ -371,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/a2a/client.ts

@@ -550,6 +550,13 @@ export async function callAgent(
     timeoutMs?: number;
     /** Poll interval for async calls. Primarily useful for tests/retries. */
     pollIntervalMs?: number;
+    /**
+     * Return receiver-verified artifact text from the last polled task when
+     * the call times out. Defaults to true for backwards compatibility.
+     * Callers that can continue polling the remote task separately should set
+     * this to false so the A2ATaskTimeoutError (and its taskId) is preserved.
+     */
+    returnRecoverableArtifactsOnTimeout?: boolean;
     /**
      * Called with each successfully polled task while an async call is still
      * in flight (see `A2AClient.sendAndWait`). Fires once per real poll
@@ -614,7 +621,10 @@ export async function callAgent(
 
       return "";
     } catch (err) {
-      if (err instanceof A2ATaskTimeoutError) {
+      if (
+        opts?.returnRecoverableArtifactsOnTimeout !== false &&
+        err instanceof A2ATaskTimeoutError
+      ) {
         const recoverableText = extractRecoverableArtifactText(err.lastTask);
         if (recoverableText) return recoverableText;
       }

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/production-agent.ts

@@ -1762,6 +1762,12 @@ export type AgentLoopFinalResponseGuardResult =
   | {
       retryMessage: string;
       fallbackMessage?: string;
+      /**
+       * Number of rejected text-only answers the model may correct before the
+       * fallback is emitted. Defaults to one and is capped to keep a broken
+       * guard/model combination from looping indefinitely.
+       */
+      maxRetries?: number;
     };
 
 export type AgentLoopFinalResponseGuard = (
@@ -3641,7 +3647,11 @@ export async function runAgentLoop(opts: {
           typeof guard === "string" ? guard : guard.retryMessage;
         const fallbackMessage =
           typeof guard === "string" ? guard : guard.fallbackMessage;
-        if (finalGuardRetries < 1) {
+        const maxGuardRetries =
+          typeof guard === "string"
+            ? 1
+            : Math.max(0, Math.min(3, Math.trunc(guard.maxRetries ?? 1)));
+        if (finalGuardRetries < maxGuardRetries) {
           finalGuardRetries += 1;
           send({ type: "clear" });
           messages.push({
@@ -6160,21 +6170,82 @@ export function createProductionAgentHandler(
     // DIAGNOSTIC-ONLY: bracket stored-model resolution (getStoredModelForEngine
     // settings read).
     workerStep("model_start");
+    const storedModel =
+      requestModel == null && configuredModel == null
+        ? await getStoredModelForEngine(engine, { appId: options.appId })
+        : undefined;
     const modelCandidate =
-      requestModel ??
-      configuredModel ??
-      (await getStoredModelForEngine(engine, { appId: options.appId })) ??
-      engine.defaultModel;
+      requestModel ?? configuredModel ?? storedModel ?? engine.defaultModel;
     // DIAGNOSTIC-ONLY: stored-model resolution finished.
     workerStep("model_done");
     const model = normalizeModelForEngine(engine, modelCandidate);
+    let effectiveModel = model;
+    let modelSelectionSource:
+      | "request"
+      | "configured"
+      | "stored"
+      | "default"
+      | "experiment" =
+      requestModel != null
+        ? "request"
+        : configuredModel != null
+          ? "configured"
+          : storedModel != null
+            ? "stored"
+            : "default";
+    let experimentAssignments: Array<{
+      experimentId: string;
+      variantId: string;
+    }> = [];
+
+    // Database-backed experiments remain available to app operators. A
+    // platform-wide hosted rollout is layered in only when no explicit or
+    // persisted model selection exists, and only on the cross-provider Builder
+    // engine. This preserves the model picker's user intent.
+    try {
+      if (ownerEmail) {
+        const { resolveActiveExperimentConfig } =
+          await import("../observability/experiments.js");
+        const expConfig = await resolveActiveExperimentConfig(ownerEmail);
+        if (expConfig) {
+          experimentAssignments = [...expConfig.assignments];
+          if (typeof expConfig.configs.model === "string") {
+            effectiveModel = normalizeModelForEngine(
+              engine,
+              expConfig.configs.model,
+            );
+            modelSelectionSource = "experiment";
+          }
+        }
+
+        if (modelSelectionSource === "default") {
+          const { resolveHostedDefaultModelExperiment } =
+            await import("../observability/hosted-model-experiment.js");
+          const hostedExperiment = resolveHostedDefaultModelExperiment({
+            userId: ownerEmail,
+            engineName: engine.name,
+            isDefaultModelSelection: true,
+            supportedModels: engine.supportedModels,
+          });
+          if (hostedExperiment) {
+            effectiveModel = hostedExperiment.model;
+            experimentAssignments.push(hostedExperiment.assignment);
+            modelSelectionSource = "experiment";
+          }
+        }
+      }
+    } catch {
+      // Experiments are best-effort. Model resolution must keep working if the
+      // observability tables are unavailable during startup or migration.
+    }
+
     const reasoningEffort = resolveAgentRequestReasoningEffort({
-      model,
+      model: effectiveModel,
       requestEffort,
       configuredEffort: options.reasoningEffort,
     });
 
-    options.onEngineResolved?.(engine, model);
+    options.onEngineResolved?.(engine, effectiveModel);
 
     // One-line per-turn resolution log so it's obvious in dev which engine
     // is actually handling the request. `requestEngine` is what the client
@@ -6182,7 +6253,7 @@ export function createProductionAgentHandler(
     // Divergence between them is the usual cause of "status says builder but
     // no [builder-engine] log lines appear" confusion.
     console.log(
-      `[agent-chat] resolved engine=${engine.name} model=${model} requestEngine=${requestEngine ?? "(none)"}`,
+      `[agent-chat] resolved engine=${engine.name} model=${effectiveModel} requestEngine=${requestEngine ?? "(none)"} modelSource=${modelSelectionSource}`,
     );
 
     if (
@@ -7487,25 +7558,6 @@ export function createProductionAgentHandler(
           }
         }
 
-        // Apply experiment variant overrides (A/B testing)
-        let effectiveModel = model;
-        try {
-          const { resolveActiveExperimentConfig } =
-            await import("../observability/experiments.js");
-          if (!ownerEmail) {
-            // Without an authenticated owner we can't resolve user-scoped experiments.
-            throw new Error("no authenticated user");
-          }
-          const expConfig = await resolveActiveExperimentConfig(ownerEmail);
-          if (expConfig) {
-            if (typeof expConfig.configs.model === "string") {
-              effectiveModel = expConfig.configs.model;
-            }
-          }
-        } catch {
-          // Experiments module unavailable — use default model
-        }
-
         // TODO(processor-seam): thread `processors` from ProductionAgentOptions
         // through to runAgentLoop here once the handler exposes a way to
         // configure them (e.g. a `processors` field on ProductionAgentOptions
@@ -7592,6 +7644,14 @@ export function createProductionAgentHandler(
               threadId: threadId ?? null,
               userId: ownerEmail,
               config: obsConfig,
+              metadata: {
+                modelSelectionSource,
+                ...(experimentAssignments.length > 0
+                  ? { experimentAssignments }
+                  : {}),
+              },
+              experimentAssignments,
+              modelSelectionSource,
               classifyError: () => {
                 if (
                   agentLoopOpts.signal.aborted &&

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/agent/thread-data-builder.ts

@@ -1,5 +1,6 @@
 import type { ActionChatUIConfig } from "../action-ui.js";
 import {
+  isCredentialGapCodeAgentEvent,
   normalizeCodeAgentTranscript,
   type CodeAgentTranscriptEvent as CoreCodeAgentTranscriptEvent,
   type NormalizedCodeAgentStatusEvent,
@@ -664,6 +665,7 @@ export interface CodeAgentThreadTranscriptEvent {
   metadata?: Record<string, unknown>;
   artifactPath?: string;
   artifactUrl?: string;
+  signal?: CoreCodeAgentTranscriptEvent["signal"];
 }
 
 export interface BuildRepositoryFromCodeAgentTranscriptOptions {
@@ -1094,6 +1096,7 @@ function toCoreCodeAgentTranscriptEvent(
       ...(event.artifactPath ? { artifactPath: event.artifactPath } : {}),
       ...(event.artifactUrl ? { artifactUrl: event.artifactUrl } : {}),
     },
+    ...(event.signal ? { signal: event.signal } : {}),
   };
 }
 
@@ -1137,6 +1140,9 @@ function toolContentPartForCodeAgentTranscriptItem(
       ? { result: previewCodeAgentTranscriptValue(item.result) ?? "" }
       : {}),
     ...(item.structuredMeta ? { structuredMeta: item.structuredMeta } : {}),
+    ...(item.pendingApprovalKey
+      ? { approval: { approvalKey: item.pendingApprovalKey } }
+      : {}),
   };
 }
 
@@ -1144,7 +1150,7 @@ function statusTextForCodeAgentTranscriptItem(
   item: NormalizedCodeAgentStatusEvent,
   options: BuildRepositoryFromCodeAgentTranscriptOptions,
 ): string | null {
-  if (options.hideCredentialMessages && isCredentialCodeAgentText(item.text)) {
+  if (options.hideCredentialMessages && isCredentialGapCodeAgentEvent(item)) {
     return null;
   }
   if (item.statusKind === "artifact") {
@@ -1219,10 +1225,6 @@ function stringRecordValue(
   return typeof value === "string" && value.trim() ? value.trim() : undefined;
 }
 
-function isCredentialCodeAgentText(value: string): boolean {
-  return /No LLM provider key was found|Missing credentials/i.test(value);
-}
-
 export function upsertUserMessage(repo: any, userMsg: UserMessage): any {
   const nextRepo = normalizeThreadRepository(repo);