@agent-native/core 0.131.9 → 0.132.1

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

@@ -1,7 +1,8 @@
 /**
  * Durable background agent-chat runs (Netlify background functions).
  *
- * Off by default. When enabled, a long in-app agent-chat turn is dispatched
+ * Enabled by default on deployed Netlify apps. When enabled, a long in-app
+ * agent-chat turn is dispatched
  * into a Netlify *background* function (15-min budget) instead of completing
  * synchronously under the ~40s soft-timeout. The foreground POST claims the
  * run slot, inserts the run row, fires an HMAC-signed self-dispatch to
@@ -18,18 +19,17 @@
  * GUARDRAIL: when `isAgentChatDurableBackgroundEnabled()` returns false, the
  * agent-chat handler must behave byte-for-byte like the current synchronous
  * path. The gate is true only when ALL of these hold:
- *   1. `AGENT_CHAT_DURABLE_BACKGROUND` env is explicitly enabled, or a
- *      workspace app's agent-chat plugin opts in with `durableBackgroundRuns`
- *      where the workspace deploy emits a per-app background function by
- *      default. Single-template Netlify deploys must set the env flag because
- *      that same flag controls whether `server-agent-background` is emitted.
+ *   1. The runtime is a deployed Netlify app and
+ *      `AGENT_CHAT_DURABLE_BACKGROUND` is not explicitly disabled, or the
+ *      existing env/app opt-in path is used on another hosted platform. Netlify
+ *      deploys emit the background function by default; `false`, `0`, `no`, or
+ *      `off` disables it.
  *   2. The runtime is hosted/serverless (local dev keeps the inline path so SSE
  *      stays a single live stream and no second function is needed).
  *   3. `A2A_SECRET` is configured (the HMAC handoff is required to authenticate
  *      the background dispatch; without it the dispatch can't be trusted).
  *
- * Opt-in keeps the blast radius small while the worker path is still being
- * proven. And even when enabled, a *dispatch failure degrades to an inline run*:
+ * Even when enabled, a *dispatch failure degrades to an inline run*:
  * if the self-dispatch self-POST can't be delivered (fast connection error or
  * fast non-2xx), the foreground handler runs the turn synchronously instead of
  * erroring (see `production-agent.ts` — the inline fallback claims the run row
@@ -120,7 +120,7 @@ function isNetlifyHostedRuntimeForDispatch(): boolean {
   // exposes AWS runtime variables, so keep the function-name fallback for older
   // deploys. Without either check a modern Netlify Function silently selects the
   // portable framework route even though the emitted background function exists.
-  if (process.env.SITE_ID) return true; // guard:allow-env-credential -- Netlify's read-only public site identifier is a runtime host marker, not a user credential.
+  if (process.env.SITE_ID) return true; // guard:allow-env-credential - Netlify's read-only public site identifier is a runtime host marker, not a user credential.
   // Non-Netlify AWS falls back inline if the /.netlify/functions dispatch
   // fast-fails.
   return Boolean(process.env.AWS_LAMBDA_FUNCTION_NAME);
@@ -186,8 +186,9 @@ export function dispatchPathTargetsNetlifyBackgroundFunction(
 }
 
 /**
- * Env flag for durable background runs. DEFAULT-OFF (opt-in): unset means
- * disabled; an app opts IN with an explicit truthy value (`true`/`1`/`yes`/`on`).
+ * Env flag for durable background runs. On Netlify, unset means enabled and an
+ * explicit falsy value opts out. On other hosted platforms, apps still opt in
+ * with an explicit truthy value (`true`/`1`/`yes`/`on`).
  */
 export const AGENT_CHAT_DURABLE_BACKGROUND_ENV =
   "AGENT_CHAT_DURABLE_BACKGROUND";
@@ -233,6 +234,20 @@ export function isHostedRuntimeForDurableBackground(): boolean {
   );
 }
 
+/**
+ * Netlify is the only host with the emitted 15-minute background function.
+ * Keep the framework-wide default scoped to deployed Netlify rather than
+ * silently enabling it on other hosted runtimes that may not have that worker.
+ */
+export function isNetlifyHostedRuntimeForDurableBackground(): boolean {
+  if (process.env.NETLIFY_LOCAL === "true") return false;
+  if (process.env.NETLIFY === "false") return false;
+  return Boolean(
+    (process.env.NETLIFY && process.env.NETLIFY !== "false") ||
+    process.env.SITE_ID, // guard:allow-env-credential - Netlify's read-only public site identifier is a runtime host marker, not a user credential.
+  );
+}
+
 /**
  * True when THIS process is actually executing inside a Netlify *background*
  * function (the long, 15-min-budget async function whose deployed name ends in
@@ -353,16 +368,10 @@ export function isDurableBackgroundFlagEnabled(): boolean {
   // can statically verify it against the allowlisted `AGENT_*` prefix. Keep this
   // in sync with AGENT_CHAT_DURABLE_BACKGROUND_ENV.
   //
-  // DEFAULT-OFF (opt-in): durable background runs are still being hardened. A
-  // premature fleet-wide default-on caused real-user incidents (Assets/Analytics
-  // hit "Failed to dispatch" + stalls, 2026-06-24) because the async background
-  // worker path is not yet proven end-to-end and the deploy-time env opt-out is
-  // not reliably baked into a given deploy. So an unset/empty/unknown flag means
-  // OFF; an app opts IN only with an explicit truthy value
-  // (AGENT_CHAT_DURABLE_BACKGROUND=true). This still composes with the hosted +
-  // A2A_SECRET gates below. Flip back to default-on only after the 15-min
-  // background-function worker is verified live in production (see the
-  // project_durable_bg_prod_verified memory).
+  // This parses only the explicit opt-in signal. Netlify's default-on behavior
+  // is composed separately in isAgentChatDurableBackgroundEnabled, while other
+  // hosted runtimes still require this truthy value. Empty and unknown values
+  // remain false so an explicit host opt-in cannot be inferred accidentally.
   const raw = process.env.AGENT_CHAT_DURABLE_BACKGROUND;
   if (raw == null) return false;
   const normalized = raw.trim().toLowerCase();
@@ -387,12 +396,10 @@ export function isDurableBackgroundFlagExplicitlyDisabled(): boolean {
 }
 
 /**
- * The single gate. True when the env flag is explicitly enabled, or a workspace
- * app opted in and has a per-app background-function target, AND the runtime is
- * hosted AND A2A_SECRET is configured. False otherwise — and false means the
- * current synchronous behavior is used unchanged. Single-template Netlify app
- * opt-ins deliberately require the env flag too because that flag controls
- * whether the `server-agent-background` function exists in the deploy output.
+ * The single gate. On deployed Netlify, durable runs are enabled unless the env
+ * flag is explicitly falsy. Other hosted runtimes retain the explicit env/app
+ * opt-in path. In every case the runtime must be hosted and have A2A_SECRET.
+ * False means the current synchronous behavior is used unchanged.
  */
 export function isAgentChatDurableBackgroundEnabled(options?: {
   appOptIn?: boolean;
@@ -404,12 +411,15 @@ export function isAgentChatDurableBackgroundEnabled(options?: {
   // prevent.
   if (options?.appOptIn === false) return false;
   const envOptIn = isDurableBackgroundFlagEnabled();
+  const netlifyDefaultOptIn =
+    isNetlifyHostedRuntimeForDurableBackground() &&
+    !isDurableBackgroundFlagExplicitlyDisabled();
   const workspaceAppOptIn =
     options?.appOptIn === true &&
     !isDurableBackgroundFlagExplicitlyDisabled() &&
     resolveWorkspaceBackgroundFunctionUrlPath() !== null;
   return (
-    (envOptIn || workspaceAppOptIn) &&
+    (envOptIn || netlifyDefaultOptIn || workspaceAppOptIn) &&
     isHostedRuntimeForDurableBackground() &&
     hasConfiguredA2ASecret()
   );

package/corpus/core/src/agent/harness/background.ts

@@ -1,3 +1,4 @@
+import { redactArgsToValue, redactTextToSummary } from "../../audit/redact.js";
 import type {
   BackgroundAgentControlInput,
   BackgroundAgentControlResult,
@@ -233,13 +234,22 @@ function summarizeAgentChatEvent(event: AgentChatEvent): {
       return {
         kind: "status",
         message: `Running ${event.tool}`,
-        metadata: { type: "tool_start", tool: event.tool, input: event.input },
+        metadata: {
+          type: "tool_start",
+          tool: event.tool,
+          input: redactArgsToValue(event.input),
+        },
       };
     case "tool_done":
       return {
         kind: "artifact",
         message: event.result,
-        metadata: { type: "tool_done", tool: event.tool },
+        metadata: {
+          type: "tool_done",
+          tool: event.tool,
+          input: redactArgsToValue(event.input),
+          result: redactTextToSummary(event.result),
+        },
       };
     case "error":
       return {

package/corpus/core/src/agent/production-agent.ts

@@ -1,6 +1,6 @@
 import { randomUUID } from "node:crypto";
 
-import Ajv, { type ValidateFunction } from "ajv";
+import Ajv, { type ErrorObject, type ValidateFunction } from "ajv";
 import {
   defineEventHandler,
   getHeader,
@@ -3596,6 +3596,9 @@ const rawToolInputAjv = new Ajv({
   coerceTypes: true,
   useDefaults: false,
   removeAdditional: false,
+  // `parentSchema`/`data` on each error are what let us drop the branches of a
+  // `oneOf` the caller never meant to match.
+  verbose: true,
 });
 
 const rawToolInputValidatorCache = new WeakMap<object, ValidateFunction>();
@@ -3636,17 +3639,83 @@ function isStructurallyEmptyToolValue(value: unknown): boolean {
   );
 }
 
+function compileToolValueValidator(schema: object): ValidateFunction | null {
+  const cached = optionalPlaceholderValidatorCache.get(schema);
+  if (cached) return cached;
+  try {
+    const validator = optionalPlaceholderAjv.compile(schema);
+    optionalPlaceholderValidatorCache.set(schema, validator);
+    return validator;
+  } catch {
+    return null;
+  }
+}
+
 function schemaAcceptsToolValue(schema: object, value: unknown): boolean {
-  let validator = optionalPlaceholderValidatorCache.get(schema);
-  if (!validator) {
-    try {
-      validator = optionalPlaceholderAjv.compile(schema);
-      optionalPlaceholderValidatorCache.set(schema, validator);
-    } catch {
-      return false;
-    }
+  const validator = compileToolValueValidator(schema);
+  return validator ? Boolean(validator(value)) : false;
+}
+
+/**
+ * True only when the sub-schema compiled AND rejected the value. A sub-schema
+ * that cannot be compiled standalone — a `$ref` into the root `$defs`, say — is
+ * unknown, not invalid; counting it as invalid would let one unreadable
+ * sub-schema delete the caller's intentional empty values everywhere else in
+ * the same object.
+ */
+function schemaRejectsToolValue(schema: object, value: unknown): boolean {
+  const validator = compileToolValueValidator(schema);
+  return validator ? !validator(value) : false;
+}
+
+/** The `const`/single-value-`enum` a discriminated-union branch pins a key to. */
+function schemaDiscriminatorValue(
+  schema: AgentNativeJsonSchema | undefined,
+): unknown {
+  if (!schema) return undefined;
+  if (schema.const !== undefined) return schema.const;
+  if (Array.isArray(schema.enum) && schema.enum.length === 1) {
+    return schema.enum[0];
   }
-  return Boolean(validator(value));
+  return undefined;
+}
+
+/**
+ * Index of the `oneOf`/`anyOf` branch whose discriminator constants all match
+ * `value`, or -1 when the union is not discriminated or nothing matches.
+ */
+function discriminatedBranchIndex(
+  branches: readonly AgentNativeJsonSchema[],
+  value: unknown,
+): number {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return -1;
+  const record = value as Record<string, unknown>;
+  return branches.findIndex((branch) => {
+    const properties = branch.properties;
+    if (!properties) return false;
+    const discriminators = Object.entries(properties).filter(
+      ([, spec]) => schemaDiscriminatorValue(spec) !== undefined,
+    );
+    if (discriminators.length === 0) return false;
+    return discriminators.every(
+      ([key, spec]) => record[key] === schemaDiscriminatorValue(spec),
+    );
+  });
+}
+
+/**
+ * The object schema that actually governs `value` — the union branch its
+ * discriminator selects, or the schema itself. Undefined when a union cannot be
+ * resolved, since guessing a branch would strip the wrong keys.
+ */
+function resolveObjectSchemaBranch(
+  schema: RawJsonSchema,
+  value: unknown,
+): RawJsonSchema | undefined {
+  const branches = schema.oneOf ?? schema.anyOf;
+  if (!branches?.length) return schema;
+  const index = discriminatedBranchIndex(branches, value);
+  return index >= 0 ? branches[index] : undefined;
 }
 
 /**
@@ -3654,35 +3723,82 @@ function schemaAcceptsToolValue(schema: object, value: unknown): boolean {
  * instead of omitting it. One schema-invalid empty value proves that pattern;
  * only then strip the other optional empty/default sentinels from the call.
  * Calls whose empty values are all schema-valid keep their intentional clears.
+ *
+ * The proof is evaluated per object, and the walk descends through array items
+ * and discriminated-union branches: gateways pre-fill the leaf object they are
+ * building (`operations[0].fields`), which a top-level-only sweep never reaches.
  */
-function normalizeOptionalToolPlaceholders(
+function stripOptionalToolPlaceholders(
   schema: RawJsonSchema | undefined,
-  input: unknown,
-): { input: unknown; changed: boolean } {
-  if (!schema?.properties || !input || typeof input !== "object") {
-    return { input, changed: false };
+  value: unknown,
+): { value: unknown; changed: boolean } {
+  if (!schema) return { value, changed: false };
+
+  if (Array.isArray(value)) {
+    const itemSchema = schema.items;
+    if (!itemSchema) return { value, changed: false };
+    let changed = false;
+    const items = value.map((item) => {
+      const result = stripOptionalToolPlaceholders(itemSchema, item);
+      if (result.changed) changed = true;
+      return result.value;
+    });
+    return changed
+      ? { value: items, changed: true }
+      : { value, changed: false };
   }
-  if (Array.isArray(input)) return { input, changed: false };
+
+  if (!value || typeof value !== "object") return { value, changed: false };
+
+  const objectSchema = resolveObjectSchemaBranch(schema, value);
+  const properties = objectSchema?.properties;
+  if (!properties) return { value, changed: false };
 
   const required = new Set(
-    Array.isArray(schema.required) ? schema.required : [],
+    Array.isArray(objectSchema.required) ? objectSchema.required : [],
   );
+  const record = value as Record<string, unknown>;
   const placeholders: string[] = [];
   let hasSchemaInvalidPlaceholder = false;
-  for (const [key, value] of Object.entries(input as Record<string, unknown>)) {
-    if (required.has(key) || !isStructurallyEmptyToolValue(value)) continue;
-    const propertySchema = schema.properties[key];
+  let normalized: Record<string, unknown> | null = null;
+
+  for (const [key, entry] of Object.entries(record)) {
+    const propertySchema = properties[key];
     if (!propertySchema || typeof propertySchema !== "object") continue;
-    placeholders.push(key);
-    if (!schemaAcceptsToolValue(propertySchema, value)) {
-      hasSchemaInvalidPlaceholder = true;
+    if (!required.has(key) && isStructurallyEmptyToolValue(entry)) {
+      placeholders.push(key);
+      if (schemaRejectsToolValue(propertySchema, entry)) {
+        hasSchemaInvalidPlaceholder = true;
+      }
+      continue;
     }
+    const nested = stripOptionalToolPlaceholders(propertySchema, entry);
+    if (nested.changed) {
+      normalized ??= { ...record };
+      normalized[key] = nested.value;
+    }
+  }
+
+  if (hasSchemaInvalidPlaceholder) {
+    normalized ??= { ...record };
+    for (const key of placeholders) delete normalized[key];
   }
-  if (!hasSchemaInvalidPlaceholder) return { input, changed: false };
 
-  const normalized = { ...(input as Record<string, unknown>) };
-  for (const key of placeholders) delete normalized[key];
-  return { input: normalized, changed: true };
+  return normalized
+    ? { value: normalized, changed: true }
+    : { value, changed: false };
+}
+
+function normalizeOptionalToolPlaceholders(
+  schema: RawJsonSchema | undefined,
+  input: unknown,
+): { input: unknown; changed: boolean } {
+  if (!schema?.properties || !input || typeof input !== "object") {
+    return { input, changed: false };
+  }
+  if (Array.isArray(input)) return { input, changed: false };
+  const result = stripOptionalToolPlaceholders(schema, input);
+  return { input: result.value, changed: result.changed };
 }
 
 /**
@@ -3754,6 +3870,54 @@ function shouldValidateRawToolParameters(entry: ActionEntry): boolean {
   return !maybeSchema?.["~standard"] && Boolean(entry.tool.parameters);
 }
 
+/**
+ * With `allErrors`, a failing union reports every branch, so a five-branch
+ * union answers "your `patch-deck-fields` op has a bad enum" with eight
+ * complaints about `slideId`/`orderedIds` from the four branches the caller
+ * never meant. The model reads the loudest, wrong advice and re-sends the same
+ * arguments until the identical-error breaker ends the turn. When the
+ * discriminator names a branch, report only that branch's errors.
+ *
+ * Both union keywords are load-bearing for the same Zod schema: Zod v4's own
+ * `toJSONSchema` emits `oneOf` for a discriminated union, while the manual
+ * fallback converter in `action.ts` emits `anyOf`.
+ *
+ * Scoped by `instancePath` as well as `schemaPath`: every element of an array
+ * shares one `items` schema, so `operations[0]` and `operations[1]` produce
+ * branch errors under the same `schemaPath` and only the instance path says
+ * which element they belong to.
+ */
+function isWithinInstancePath(candidate: string, root: string): boolean {
+  return candidate === root || candidate.startsWith(`${root}/`);
+}
+
+function narrowUnionBranchErrors(
+  errors: ErrorObject[] | null | undefined,
+): ErrorObject[] | null | undefined {
+  if (!errors?.length) return errors;
+  let kept = errors;
+  for (const error of errors) {
+    const keyword = error.keyword;
+    if (keyword !== "oneOf" && keyword !== "anyOf") continue;
+    const branches = (error.parentSchema as RawJsonSchema | undefined)?.[
+      keyword
+    ];
+    if (!branches?.length) continue;
+    const index = discriminatedBranchIndex(branches, error.data);
+    if (index < 0) continue;
+    const branchPrefix = `${error.schemaPath}/`;
+    kept = kept.filter((candidate) => {
+      if (candidate === error) return false;
+      if (!isWithinInstancePath(candidate.instancePath, error.instancePath)) {
+        return true;
+      }
+      if (!candidate.schemaPath.startsWith(branchPrefix)) return true;
+      return candidate.schemaPath.startsWith(`${branchPrefix}${index}/`);
+    });
+  }
+  return kept.length ? kept : errors;
+}
+
 function validateRawToolInput(
   entry: ActionEntry,
   input: unknown,
@@ -3768,7 +3932,7 @@ function validateRawToolInput(
     return `tool schema is invalid: ${sanitizeToolErrorValue(err)}`;
   }
   if (validator(input === undefined ? {} : input)) return null;
-  return rawToolInputAjv.errorsText(validator.errors, {
+  return rawToolInputAjv.errorsText(narrowUnionBranchErrors(validator.errors), {
     separator: "; ",
     dataVar: "input",
   });
@@ -5673,23 +5837,26 @@ export async function runAgentLoop(opts: {
         result = `${result}\n\n${formatAgentWarningsForToolResult(agentWarnings)}`;
       }
 
-      // Auto-refresh the UI after a successful mutating tool call. Any action
-      // that isn't explicitly read-only is assumed to mutate. The client's
-      // useDbSync listener sees a change event with source:"action" and
-      // invalidates ["action"] queries so list-* / get-* refetch. This makes
-      // refresh after agent writes reliable without the model needing to
-      // remember to call `refresh-screen` itself.
-      if (!isError && actionEntry.readOnly !== true) {
+      // Auto-refresh the UI after a successful mutating tool call. Any call
+      // that isn't read-only — by its own per-call Plan-mode effect, else the
+      // action's readOnly flag — is assumed to mutate. The client's useDbSync
+      // listener sees a change event with source:"action" and invalidates
+      // ["action"] queries so list-* / get-* refetch. This makes refresh after
+      // agent writes reliable without the model needing to remember to call
+      // `refresh-screen` itself.
+      if (!isError) {
         try {
-          const { notifyActionChange } =
+          const { actionCallIsReadOnly, notifyActionChange } =
             await import("../server/action-change.js");
-          const owner = opts.ownerEmail ?? getRequestUserEmail() ?? undefined;
-          const orgId = opts.orgId ?? getRequestOrgId() ?? undefined;
-          await notifyActionChange({
-            actionName: toolCall.name,
-            ...(owner ? { owner } : {}),
-            ...(orgId ? { orgId } : {}),
-          });
+          if (!actionCallIsReadOnly(actionEntry, toolCall.input, false)) {
+            const owner = opts.ownerEmail ?? getRequestUserEmail() ?? undefined;
+            const orgId = opts.orgId ?? getRequestOrgId() ?? undefined;
+            await notifyActionChange({
+              actionName: toolCall.name,
+              ...(owner ? { owner } : {}),
+              ...(orgId ? { orgId } : {}),
+            });
+          }
         } catch {
           // poll module may be unavailable in non-server contexts — ignore
         }

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

@@ -163,6 +163,46 @@ export const UNCLAIMED_BACKGROUND_RUN_REDISPATCH_BOUND_MS = 5 * 60_000;
  */
 export const UNCLAIMED_BACKGROUND_RUN_FAST_SWEEP_MS = 20_000;
 
+/**
+ * How long a negative `status='running'` probe stays trusted.
+ *
+ * MUST stay well below the tightest staleness window any sweep enforces
+ * (`RUN_STALE_MS`, 15s): the probe sees running rows of EVERY age, so a
+ * negative result proves there were zero running rows that instant, and a row
+ * inserted since — by this process or another one — cannot yet be old enough
+ * for a sweep to act on it. Widen this past a staleness window and a genuinely
+ * dead run becomes invisible for a whole extra tick.
+ */
+const NO_RUNNING_RUNS_CACHE_MS = 5_000;
+
+let _noRunningRunsUntil = 0;
+
+/** Test seam — the probe cache is module state, so suites must clear it. */
+export function __resetNoRunningRunsProbeForTests(): void {
+  _noRunningRunsUntil = 0;
+}
+
+/**
+ * `status = 'running'` is a strict superset of every sweep predicate in this
+ * file, so one probe answers all of them. The fast sweep runs `reapAllStaleRuns`
+ * and `listUnclaimedBackgroundRunRows` back to back every 20s; on an idle app
+ * both scan for rows that do not exist, which on a remote database is two
+ * round trips per tick per app, forever. The probe collapses that pair to one.
+ */
+async function hasRunningRuns(): Promise<boolean> {
+  if (Date.now() < _noRunningRunsUntil) return false;
+  const { rows } = await getDbExec().execute({
+    sql: `SELECT id FROM agent_runs WHERE status = 'running' LIMIT 1`,
+    args: [],
+  });
+  if ((rows?.length ?? 0) > 0) {
+    _noRunningRunsUntil = 0;
+    return true;
+  }
+  _noRunningRunsUntil = Date.now() + NO_RUNNING_RUNS_CACHE_MS;
+  return false;
+}
+
 /**
  * FIX 3 (durable-background incident) per-turn run-count ceiling for
  * stale-run recovery — mirrors `chainServerDrivenContinuation`'s own ledger
@@ -920,6 +960,7 @@ export async function listUnclaimedBackgroundRunRows(): Promise<
   UnclaimedBackgroundRunRow[]
 > {
   await ensureRunTables();
+  if (!(await hasRunningRuns())) return [];
   const client = getDbExec();
   const { rows } = await client.execute({
     // CAST keeps the ms-epoch param 64-bit on Postgres (see
@@ -2538,6 +2579,7 @@ export async function getCurrentTurnEventsForThread(
  */
 export async function reapAllStaleRuns(): Promise<number> {
   await ensureRunTables();
+  if (!(await hasRunningRuns())) return 0;
   const client = getDbExec();
   const now = Date.now();
   // Background-dispatched runs use the wider window; everything else 15s. The
@@ -2570,9 +2612,9 @@ export async function reapAllStaleRuns(): Promise<number> {
   // `reapSingleStaleRun` re-applies the identical staleness clause per row
   // (same as the bulk UPDATE previously did), so a row whose heartbeat
   // landed between the SELECT above and this loop is still correctly
-  // excluded. This function only runs once, at process startup (see
-  // agent-chat-plugin.ts) — the extra per-row round trips are
-  // inconsequential.
+  // excluded. The per-row round trips only ever run for rows the SELECT above
+  // already found stale; on an idle app `hasRunningRuns` returns before any of
+  // this, so the 20s fast sweep (agent-chat-plugin.ts) costs one probe.
   let reapedCount = 0;
   for (const row of stale.rows) {
     const id = (row as { id?: unknown }).id;

package/corpus/core/src/application-state/handlers.ts

@@ -3,6 +3,7 @@ import {
   defineEventHandler,
   getRouterParam,
   getHeader,
+  getQuery,
   setResponseStatus,
   type H3Event,
 } from "h3";
@@ -11,6 +12,7 @@ import { getSession } from "../server/auth.js";
 import { readBody } from "../server/h3-helpers.js";
 import {
   appStateGet,
+  appStateGetManyEntries,
   appStatePut,
   appStateDelete,
   appStateList,
@@ -45,6 +47,49 @@ export const getState = defineEventHandler(async (event: H3Event) => {
   return value ?? null;
 });
 
+/** Upper bound on one batched read, so a crafted URL can't fan out unbounded. */
+export const MAX_APP_STATE_BATCH_KEYS = 100;
+
+/**
+ * `GET /_agent-native/application-state?keys=a,b,c` — read many keys for the
+ * caller's session in one round trip.
+ *
+ * `values` carries only the keys that have a stored row; every other requested
+ * key is listed in `missing`. A key whose stored value is `null` therefore
+ * appears in `values` with a `null` value and NOT in `missing`, which is what
+ * keeps "no row" distinguishable from "row holding an empty value".
+ */
+export const getStateMany = defineEventHandler(async (event: H3Event) => {
+  const sessionId = await getSessionId(event);
+  const raw = getQuery(event).keys;
+  const requested = (Array.isArray(raw) ? raw : [raw])
+    .flatMap((entry) => String(entry ?? "").split(","))
+    .map((key) => safeKey(key.trim()))
+    .filter((key) => key.length > 0);
+  const keys = [...new Set(requested)];
+
+  if (keys.length === 0) {
+    throw createError({
+      statusCode: 400,
+      statusMessage: "Query parameter `keys` is required",
+    });
+  }
+  if (keys.length > MAX_APP_STATE_BATCH_KEYS) {
+    throw createError({
+      statusCode: 400,
+      statusMessage: `At most ${MAX_APP_STATE_BATCH_KEYS} keys may be read at once`,
+    });
+  }
+
+  const entries = await appStateGetManyEntries(sessionId, keys);
+  const values: Record<string, unknown> = {};
+  for (const entry of entries) values[entry.key] = entry.value;
+  return {
+    values,
+    missing: keys.filter((key) => !(key in values)),
+  };
+});
+
 export const putState = defineEventHandler(async (event: H3Event) => {
   const sessionId = await getSessionId(event);
   const key = safeKey(String(getRouterParam(event, "key")));

package/corpus/core/src/application-state/index.ts

@@ -2,6 +2,7 @@
 export {
   appStateGet,
   appStateGetMany,
+  appStateGetManyEntries,
   appStatePut,
   appStateDelete,
   appStateCompareAndSet,
@@ -22,6 +23,8 @@ export {
 // H3 route handlers (for templates)
 export {
   getState,
+  getStateMany,
+  MAX_APP_STATE_BATCH_KEYS,
   putState,
   deleteState,
   listComposeDrafts,