@agent-native/core 0.131.9 → 0.132.1

package/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/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/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/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,

package/src/application-state/store.ts

@@ -112,19 +112,18 @@ export async function appStateGet(
 }
 
 /**
- * Read several application-state keys for one session in a single SQL query.
- * Missing keys are returned as `null` so callers can preserve the requested
- * shape without issuing one fallback query per key.
+ * Read several application-state keys for one session in a single SQL query,
+ * returning ONLY the rows that exist. A key absent from the result has no row;
+ * a key present with a `null` value has a row that stores `null`. Callers that
+ * must not conflate the two (the batched HTTP read) depend on that difference,
+ * so this deliberately does not pad missing keys.
  */
-export async function appStateGetMany(
+export async function appStateGetManyEntries(
   sessionId: string,
   keys: readonly string[],
-): Promise<Record<string, Record<string, unknown> | null>> {
+): Promise<Array<{ key: string; value: Record<string, unknown> | null }>> {
   const uniqueKeys = [...new Set(keys)];
-  const values: Record<string, Record<string, unknown> | null> = {};
-  for (const key of uniqueKeys) values[key] = null;
-  if (uniqueKeys.length === 0) return values;
-
+  if (uniqueKeys.length === 0) return [];
   await ensureTable();
   const client = getDbExec();
   const placeholders = uniqueKeys.map(() => "?").join(", ");
@@ -132,8 +131,26 @@ export async function appStateGetMany(
     sql: `SELECT key, value FROM application_state WHERE session_id = ? AND key IN (${placeholders})`,
     args: [sessionId, ...uniqueKeys],
   });
-  for (const row of rows) {
-    values[row.key as string] = JSON.parse(row.value as string);
+  return rows.map((row) => ({
+    key: row.key as string,
+    value: JSON.parse(row.value as string),
+  }));
+}
+
+/**
+ * Read several application-state keys for one session in a single SQL query.
+ * Missing keys are returned as `null` so callers can preserve the requested
+ * shape without issuing one fallback query per key.
+ */
+export async function appStateGetMany(
+  sessionId: string,
+  keys: readonly string[],
+): Promise<Record<string, Record<string, unknown> | null>> {
+  const values: Record<string, Record<string, unknown> | null> = {};
+  for (const key of new Set(keys)) values[key] = null;
+
+  for (const entry of await appStateGetManyEntries(sessionId, keys)) {
+    values[entry.key] = entry.value;
   }
   return values;
 }