@agent-native/core 0.131.9 → 0.132.1

package/corpus/README.md

@@ -28,6 +28,6 @@ rg -n "defineAction|useActionQuery" node_modules/@agent-native/core/corpus
 
 ## Generated Counts
 
-- core files: 1644
+- core files: 1645
 - toolkit files: 168
-- template files: 7226
+- template files: 7235

package/corpus/core/CHANGELOG.md

@@ -1,5 +1,110 @@
 # @agent-native/core
 
+## 0.132.1
+
+### Patch Changes
+
+- 548844d: Fix agent tool calls failing against discriminated-union action schemas. Gateway-supplied empty placeholders are now stripped from nested objects and union branches (not just top-level fields), `oneOf` validation errors report only the branch the discriminator selects, and the expected-signature hint expands array items and union branches so nested enums are spelled out.
+
+## 0.132.0
+
+### Minor Changes
+
+- 89e5910: Enable durable agent-chat background runs by default for deployed Netlify apps, with an explicit opt-out.
+
+### Patch Changes
+
+- 89e5910: Batch application-state reads. `GET /_agent-native/application-state?keys=a,b,c`
+  returns many keys in one request, and `readClientAppState` coalesces reads
+  issued in the same tick into that single call, so a page load no longer pays one
+  HTTP round trip and one full identity resolution per key. The response reports
+  absent keys in `missing` rather than as `null` values, keeping "never written"
+  distinguishable from "written as null or empty"; the single-key routes are
+  unchanged.
+- 89e5910: Cut database round trips on the status endpoints a page load hits repeatedly.
+  - Added `prefetchSecrets(keys)`, which warms the per-request secret memo with
+    one batched read per scope instead of one read per key per scope, and used it
+    in `/_agent-native/env-status` (48 single-key `app_secrets` selects per request
+    → 4 batched) and `/_agent-native/voice-providers/status` (19 → 4).
+  - The change marker after an action now honours a per-call Plan-mode `effect`
+    before the action-level `readOnly` flag. A status poll shaped as a mutating
+    action — `manage-agent-engine` with `action: "list"`, polled every few seconds
+    — no longer bumps the `"action"` change version, so queries keyed on it stop
+    refetching on an idle page.
+  - The default database schema health probe runs its table checks in parallel and
+    memoizes a clean result for a few seconds. A probe reporting a missing table or
+    an unreadable database is never memoized.
+
+- 89e5910: Record tool arguments and result summaries in delegated-run traces. The A2A
+  agent-activity snapshot and the agent-team / harness background transcripts now
+  carry each tool call's arguments and a result preview in redacted, size-capped
+  form, so a delegated run that loops on the same tool is diagnosable from what
+  was recorded instead of needing a fresh repro. Captures reuse the audit
+  redaction helper (credential-looking keys and values become `[redacted]`),
+  oversized values keep an explicit `…(N more chars)` / `_auditTruncated` marker,
+  and a shared per-snapshot payload budget keeps the activity part inside its
+  wire limit.
+- 89e5910: Share one Postgres connection pool per URL across the whole process instead of
+  building a separate one for the `getDbExec` singleton, Better Auth, and every
+  `createGetDb` store. Against a remote database that removed five redundant
+  first-connect round trips per process, and it let the pool cap rise so a
+  request's concurrent reads no longer serialize behind a single connection.
+  Secret reads are now memoized per request, keyed on scope and scope id, so the
+  user/org/workspace credential waterfall is not re-walked on every lookup.
+  Onboarding step status, resource inheritance layers, and feature-flag rules now
+  resolve their independent reads concurrently.
+- 89e5910: Give delegated agent turns their app's actions as native tools in dev, so asking
+  a sibling app a question actually returns an answer.
+
+  In dev the interactive surface deliberately omits template actions from the tool
+  registry and lets the agent reach them through `bash`, which sidesteps the
+  degenerate empty-object tool call some models emit for complex schemas. That is
+  a reasonable trade for a person, who sees the bad call and rephrases. It is the
+  wrong trade for a delegated turn. An A2A caller, or an external host calling
+  `ask_app` over MCP, has nobody to intervene: with no native action the receiving
+  agent shells out, the call runs long, and the caller records "Interrupted before
+  this tool returned a result" — after which callers commonly fall back to
+  composing their own queries against a schema they do not own.
+
+  Both delegated surfaces now keep template actions native even in dev. A rejected
+  `{}` call returns a schema error the model can correct on its next step, which
+  is strictly better than a shell loop no caller can see or recover from.
+
+- 89e5910: Stop paying for background sweeps and no-change polls that find nothing.
+
+  A workspace runs one server per app, so every recurring sweep multiplies by app
+  count. Several of them queried unconditionally: the 20-second unclaimed-run
+  sweep issued two `agent_runs` scans back to back, the A2A continuation retry ran
+  two blind `UPDATE`s before ever checking whether anything was due, the MCP config
+  refresh scanned the whole settings table every minute to diff a signature that
+  had not moved since boot, and the Google Docs poller re-read its config every 30
+  seconds even on deployments where the integration was never enabled. On local
+  SQLite that was free; on a remote or metered database each one is a network round
+  trip, forever, per app.
+
+  Each of those now leads with a cheap existence probe or an in-process change
+  signal, so the idle case costs one round trip instead of several and the work
+  still runs the moment there is any. The poll route gets the same treatment: its
+  legacy watermark scan read `application_state` four separate times per check,
+  and now reads `MAX(updated_at)` once and only fans out when that advances — a
+  cost that repeated per app per connected client.
+
+  Detection latency is unchanged: every probe is a strict superset of the predicate
+  it guards, and the negative caches are all narrower than the staleness window
+  they sit in front of.
+
+- 89e5910: Cut one database round trip from every authenticated request. The membership
+  and `active-org-id` reads behind org resolution now overlap instead of queueing,
+  and `resolveOrgIdForEmail` memoizes its `org_members` read per request (keyed on
+  the AsyncLocalStorage request context and the email) so credential lookups,
+  agent runs, A2A, MCP, and adapter-authenticated action calls — none of which
+  carry an h3 event — stop each paying their own lookup.
+- 89e5910: Refresh derived database consumers after pool recycling, redact embedded
+  credentials from captured tool results, preserve multiline A2A previews, and
+  retry MCP configuration refreshes after transient failures.
+- Updated dependencies [89e5910]
+  - @agent-native/toolkit@0.12.1
+
 ## 0.131.9
 
 ### Patch Changes

package/corpus/core/docs/content/durable-background-runs.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Durable Background Runs"
-description: "Long agent-chat turns can run on a separate 15-minute Netlify background function instead of the synchronous request, so multi-step work finishes server-side without the client babysitting continuations. Opt-in per app; a foreground circuit-breaker keeps chat working even if the worker never starts."
+description: "Long agent-chat turns can run on a separate 15-minute Netlify background function instead of the synchronous request, so multi-step work finishes server-side without the client babysitting continuations. Enabled by default on deployed Netlify apps with an explicit opt-out; a foreground circuit-breaker keeps chat working even if the worker never starts."
 ---
 
 # Durable Background Runs
@@ -10,7 +10,8 @@ description: "Long agent-chat turns can run on a separate 15-minute Netlify back
 **Who is this for:** anyone deploying an agent-native app who wants long,
 multi-step agent turns to complete server-side, and anyone wondering what the
 `AGENT_CHAT_DURABLE_BACKGROUND` flag and the second Netlify function do. This
-is opt-in and entirely inside the framework — there is no app code to write.
+is enabled by default on deployed Netlify apps and entirely inside the
+framework — there is no app code to write.
 
 </Callout>
 
@@ -108,14 +109,17 @@ normal API calls always run synchronously on `server`.
 The foreground chat POST decides **per turn**. It dispatches to the background
 function only when all three hold:
 
-- `AGENT_CHAT_DURABLE_BACKGROUND` is truthy (`true` / `1` / `yes` / `on`),
+- the app is deployed on Netlify and `AGENT_CHAT_DURABLE_BACKGROUND` is not
+  explicitly falsy (`false` / `0` / `no` / `off`), or a non-Netlify hosted app
+  explicitly opts in with a truthy value (`true` / `1` / `yes` / `on`),
 - the app is running hosted (on the platform, not local dev), and
 - `A2A_SECRET` is set (the dispatch is an HMAC-signed self-call; without the
   secret it cannot be signed, so the turn stays inline).
 
-If any is missing, the turn runs inline exactly as before. The flag is read at
+If the app is local, `A2A_SECRET` is missing, or the flag is explicitly
+disabled, the turn runs inline exactly as before. The setting is read at
 **both build time** (to decide whether to emit the background function) and
-**runtime** (to decide whether to dispatch), so enabling it requires a redeploy.
+**runtime** (to decide whether to dispatch), so changing it requires a redeploy.
 
 ## The lifecycle and the circuit-breaker {#lifecycle}
 
@@ -190,7 +194,12 @@ one long invocation, not purely additive.
 
 <Callout id="doc-block-gjoj2d" tone="info">
 
-Durable runs are opt-in per app and default OFF. Enable with AGENT_CHAT_DURABLE_BACKGROUND=true (plus A2A_SECRET) and redeploy. Verify a turn actually used the worker by checking that its run reaches dispatch_mode=background-processing rather than falling back to inline recovery.
+Durable runs are enabled by default for deployed Netlify apps. Set
+`AGENT_CHAT_DURABLE_BACKGROUND=false` to opt out, or set it to `true` on another
+host. `A2A_SECRET` is still required. Redeploy after changing the setting, and
+verify a turn actually used the worker by checking that its run reaches
+`dispatch_mode=background-processing` rather than falling back to inline
+recovery.
 
 </Callout>
 

package/corpus/core/docs/design/durable-agent-runs.md

@@ -200,7 +200,8 @@ itself checkpoint).
 
 > Status: **Phase 0 shipped. Phase 1 + Phase 2 implemented** (the host-agnostic
 > durable-background worker and the Netlify 15-min `-background` optimization),
-> behind `AGENT_CHAT_DURABLE_BACKGROUND`, off by default. Internal per-step
+> default-on for deployed Netlify apps with an explicit opt-out via
+> `AGENT_CHAT_DURABLE_BACKGROUND=false`. Internal per-step
 > checkpointing (the Option A core of Phase 1) is recommended-not-yet-built; the
 > worker today gets its durability from the long single invocation plus
 > server-chained continuations rather than per-step idempotent checkpoints. See
@@ -251,13 +252,14 @@ checkpointed and durable runs remove the ceiling itself.
 
 # Final layered architecture
 
-Status: implemented (flagged, off by default)
+Status: implemented (default-on for deployed Netlify, explicit opt-out)
 Owner: core / run-manager + deploy
 
-Durable background runs ship as **two layers**. Both are gated behind
-`AGENT_CHAT_DURABLE_BACKGROUND` and default off; when off, the agent-chat run
-path and the deploy output are byte-for-byte the pre-existing synchronous
-behavior.
+Durable background runs ship as **two layers**. Deployed Netlify apps enable the
+path by default and can opt out with an explicit falsy
+`AGENT_CHAT_DURABLE_BACKGROUND` value. Other hosted platforms retain explicit
+opt-in. When off, the agent-chat run path and deploy output are byte-for-byte
+the pre-existing synchronous behavior.
 
 ### Layer 1 (portable baseline) — host-agnostic durable execution
 
@@ -600,8 +602,9 @@ Already strong; make the new claim match:
 
 > Status: \*\*Slices 0–1 implemented and the Slice-3 background-aware stale window
 >
-> - background→background continuation chaining are implemented\*\*, all behind
->   `AGENT_CHAT_DURABLE_BACKGROUND` (off by default). The host-agnostic baseline
+> - background→background continuation chaining are implemented\*\*, default-on
+>   for deployed Netlify apps with `AGENT_CHAT_DURABLE_BACKGROUND=false` as the
+>   opt-out. The host-agnostic baseline
 >   (Layer 1) carries the run on any host; the Netlify `-background` emit (Layer 2)
 >   is the deploy-time optimization. Slice 2's richer reconnect-first client UX and
 >   the internal per-step checkpointing (Option A) remain follow-ups; Slice 4
@@ -618,9 +621,10 @@ just writes a run event. Dispatch to it from a temporary test route via
 stub writes an event to `agent_run_events` from the background function, visible
 via `GET /runs/:id/events`. This de-risks the only genuinely new infra.
 
-**Slice 1 — route the real chat loop through the background function (flagged).**
-Behind `AGENT_CHAT_DURABLE_BACKGROUND` (off by default; hosted + `A2A_SECRET`
-only): foreground handler inserts the run row, dispatches, returns the SSE
+**Slice 1 — route the real chat loop through the background function.** On
+deployed Netlify it is enabled by default; `AGENT_CHAT_DURABLE_BACKGROUND=false`
+opts out. Other hosted platforms require explicit opt-in, and all hosts require
+`A2A_SECRET`: the foreground handler inserts the run row, dispatches, returns the SSE
 stream from `subscribeToRun`. The background `_process-run` claims the run and
 calls the same `startRun` + `runAgentLoop` the inline path uses, with
 `softTimeoutMs ≈ 13min` (new `backgroundFunction` option in

package/corpus/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.131.9",
+  "version": "0.132.1",
   "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": {

package/corpus/core/src/a2a/activity.ts

@@ -1,16 +1,27 @@
 import { sanitizeToolErrorText } from "../agent/tool-error-redaction.js";
 import type { AgentChatEvent } from "../agent/types.js";
+import { redactArgsToJson, redactTextToSummary } from "../audit/redact.js";
 import type { DataPart, Part } from "./types.js";
 
 export const A2A_AGENT_ACTIVITY_KIND = "agent-native/agent-activity";
 export const A2A_AGENT_ACTIVITY_VERSION = 1;
 export const MAX_A2A_ACTIVITY_REASONING_CHARS = 32_768;
 export const MAX_A2A_ACTIVITY_RESPONSE_CHARS = 32_768;
-export const MAX_A2A_ACTIVITY_TOTAL_CHARS = 98_304;
 export const MAX_A2A_ACTIVITY_REASONING_SEGMENTS = 128;
 export const MAX_A2A_ACTIVITY_TOOL_CALLS = 64;
 export const MAX_A2A_ACTIVITY_TOOL_NAME_CHARS = 96;
 export const MAX_A2A_ACTIVITY_TOOL_ID_CHARS = 128;
+export const MAX_A2A_ACTIVITY_TOOL_INPUT_CHARS = 1024;
+export const MAX_A2A_ACTIVITY_TOOL_RESULT_CHARS = 512;
+/**
+ * Shared ceiling for every recorded tool input/result across the snapshot. The
+ * per-call caps alone allow 64 × 1536 chars, which would push a busy run past
+ * `MAX_A2A_ACTIVITY_TOTAL_CHARS` and make `parseA2AAgentActivityPart` reject
+ * the whole snapshot — trading missing arguments for a missing trace.
+ */
+export const MAX_A2A_ACTIVITY_TOOL_PAYLOAD_CHARS = 16_384;
+export const MAX_A2A_ACTIVITY_TOTAL_CHARS =
+  98_304 + MAX_A2A_ACTIVITY_TOOL_PAYLOAD_CHARS;
 
 export type A2AAgentActivityPhase =
   | "reasoning"
@@ -25,6 +36,13 @@ export interface A2AAgentActivityToolCall {
   name: string;
   id?: string;
   status: A2AAgentActivityToolStatus;
+  /**
+   * Redacted, size-capped JSON of the call's arguments. Absent when the call
+   * had none, or when the snapshot's shared payload budget was already spent.
+   */
+  input?: string;
+  /** Redacted, size-capped head of the tool result (`tool_done` only). */
+  result?: string;
 }
 
 export interface A2AAgentActivitySnapshot extends Record<string, unknown> {
@@ -68,9 +86,11 @@ export function createA2AAgentActivityState(
 }
 
 /**
- * Converts internal loop events into a bounded activity snapshot. It carries
- * only reasoning text already emitted to the local chat, never tool inputs or
- * results.
+ * Converts internal loop events into a bounded activity snapshot. Reasoning
+ * text is carried verbatim (it was already emitted to the local chat); tool
+ * arguments and results are carried only in redacted, size-capped form so the
+ * delegated run stays diagnosable without the snapshot becoming a secondary
+ * store of secrets or payloads.
  */
 export function applyA2AAgentActivityEvent(
   state: A2AAgentActivityState,
@@ -91,14 +111,26 @@ export function applyA2AAgentActivityEvent(
       );
       changed = true;
       break;
-    case "tool_start":
+    case "tool_start": {
       next.activePhase = "tool";
-      next.toolCalls = appendToolCall(next.toolCalls, toolFromEvent(event));
+      const input = captureToolInput(
+        event.input,
+        remainingPayloadBudget(next.toolCalls),
+      );
+      next.toolCalls = appendToolCall(next.toolCalls, {
+        ...toolFromEvent(event),
+        ...(input ? { input } : {}),
+      });
       changed = true;
       break;
+    }
     case "tool_done":
       next.activePhase = "tool";
-      next.toolCalls = settleToolCall(next.toolCalls, toolFromEvent(event));
+      next.toolCalls = settleToolCall(
+        next.toolCalls,
+        toolFromEvent(event),
+        event,
+      );
       changed = true;
       break;
     case "text":
@@ -203,6 +235,49 @@ function toolFromEvent(
   };
 }
 
+function payloadChars(tool: A2AAgentActivityToolCall): number {
+  return (tool.input?.length ?? 0) + (tool.result?.length ?? 0);
+}
+
+function remainingPayloadBudget(
+  current: A2AAgentActivityToolCall[],
+  excludeIndex = -1,
+): number {
+  const used = current.reduce(
+    (total, tool, index) =>
+      index === excludeIndex ? total : total + payloadChars(tool),
+    0,
+  );
+  return Math.max(0, MAX_A2A_ACTIVITY_TOOL_PAYLOAD_CHARS - used);
+}
+
+/**
+ * Redacted, capped JSON of the arguments, or `undefined` when there is nothing
+ * to record or the shared budget cannot fit a whole (still-parseable) capture.
+ * A partial JSON string would be worse than none — the reader could not tell a
+ * clipped object from a different one.
+ */
+function captureToolInput(input: unknown, budget: number): string | undefined {
+  const cap = Math.min(MAX_A2A_ACTIVITY_TOOL_INPUT_CHARS, budget);
+  if (cap < MAX_A2A_ACTIVITY_TOOL_INPUT_CHARS / 8) return undefined;
+  const json = redactArgsToJson(input, { maxJson: cap, maxString: 256 });
+  // JSON.stringify escapes control characters, so the result is already safe
+  // for the snapshot without a `sanitizeText` pass — which would rewrite
+  // `"token":"[redacted]"` into unparseable JSON.
+  if (!json || json === "{}" || json.length > cap) return undefined;
+  return json;
+}
+
+function captureToolResult(
+  result: string | undefined,
+  budget: number,
+): string | undefined {
+  const cap = Math.min(MAX_A2A_ACTIVITY_TOOL_RESULT_CHARS, budget);
+  if (!result || cap <= 0) return undefined;
+  const summary = redactTextToSummary(result, cap);
+  return summary ? sanitizeText(summary, cap) || undefined : undefined;
+}
+
 function appendBoundedSegment(
   current: string[],
   addition: string,
@@ -244,6 +319,7 @@ function appendToolCall(
 function settleToolCall(
   current: A2AAgentActivityToolCall[],
   tool: A2AAgentActivityToolCall,
+  event: Extract<AgentChatEvent, { type: "tool_done" }>,
 ): A2AAgentActivityToolCall[] {
   for (let index = current.length - 1; index >= 0; index -= 1) {
     const existing = current[index];
@@ -251,12 +327,32 @@ function settleToolCall(
       (tool.id && tool.id === existing.id) ||
       (!tool.id && tool.name === existing.name)
     ) {
+      // The matching `tool_start` already paid for its input; reuse it rather
+      // than re-capturing (and re-charging) the same arguments.
+      let budget = remainingPayloadBudget(current, index);
+      const input =
+        existing.input ?? captureToolInput(event.input, budget) ?? undefined;
+      budget -= input?.length ?? 0;
+      const result = captureToolResult(event.result, budget);
+      const settled: A2AAgentActivityToolCall = {
+        ...tool,
+        ...(input ? { input } : {}),
+        ...(result ? { result } : {}),
+      };
       return current.map((value, itemIndex) =>
-        itemIndex === index ? tool : value,
+        itemIndex === index ? settled : value,
       );
     }
   }
-  return appendToolCall(current, tool);
+  let budget = remainingPayloadBudget(current);
+  const input = captureToolInput(event.input, budget);
+  budget -= input?.length ?? 0;
+  const result = captureToolResult(event.result, budget);
+  return appendToolCall(current, {
+    ...tool,
+    ...(input ? { input } : {}),
+    ...(result ? { result } : {}),
+  });
 }
 
 function sanitizeText(value: string, maxChars: number): string {
@@ -320,12 +416,31 @@ function isSafeToolCall(value: unknown): value is A2AAgentActivityToolCall {
   if (!isRecord(value) || !isSafeToolName(value.name)) return false;
   return (
     (value.id === undefined || isSafeToolId(value.id)) &&
+    (value.input === undefined ||
+      isSafeCapturedText(value.input, MAX_A2A_ACTIVITY_TOOL_INPUT_CHARS)) &&
+    (value.result === undefined ||
+      isSafeCapturedText(value.result, MAX_A2A_ACTIVITY_TOOL_RESULT_CHARS)) &&
     (value.status === "running" ||
       value.status === "completed" ||
       value.status === "failed")
   );
 }
 
+/**
+ * Captured input/result are producer-side redacted strings. Unlike reasoning
+ * text they are NOT re-sanitized on read: `sanitizeToolErrorText` rewrites
+ * `"token":"…"` into unparseable JSON, so a round-trip equality check would
+ * reject every legitimate capture. Bound the length and reject raw control
+ * characters instead.
+ */
+function isSafeCapturedText(value: unknown, maxChars: number): value is string {
+  return (
+    typeof value === "string" &&
+    value.length <= maxChars &&
+    !/[\u0000-\u0008\u000b-\u001f\u007f]/.test(value)
+  );
+}
+
 function isSafeText(value: unknown, maxChars: number): value is string {
   return (
     typeof value === "string" &&
@@ -365,7 +480,9 @@ function activityCharacterCount(data: Record<string, unknown>): number {
         return (
           total +
           (typeof tool.name === "string" ? tool.name.length : 0) +
-          (typeof tool.id === "string" ? tool.id.length : 0)
+          (typeof tool.id === "string" ? tool.id.length : 0) +
+          (typeof tool.input === "string" ? tool.input.length : 0) +
+          (typeof tool.result === "string" ? tool.result.length : 0)
         );
       }, 0)
     : 0;

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

@@ -11,7 +11,10 @@ export {
   MAX_A2A_ACTIVITY_TOOL_CALLS,
   MAX_A2A_ACTIVITY_TOTAL_CHARS,
   MAX_A2A_ACTIVITY_TOOL_ID_CHARS,
+  MAX_A2A_ACTIVITY_TOOL_INPUT_CHARS,
   MAX_A2A_ACTIVITY_TOOL_NAME_CHARS,
+  MAX_A2A_ACTIVITY_TOOL_PAYLOAD_CHARS,
+  MAX_A2A_ACTIVITY_TOOL_RESULT_CHARS,
   applyA2AAgentActivityEvent,
   buildA2AAgentActivityPart,
   buildA2AAgentActivitySnapshot,

package/corpus/core/src/action.ts

@@ -8,6 +8,7 @@ import type {
   ActionTool,
   AgentChatAttachment,
   AgentChatEvent,
+  AgentNativeJsonSchema,
 } from "./agent/types.js";
 import { normalizeAuditConfig, resolveAuditAttach } from "./audit/config.js";
 import type { ActionAuditConfig } from "./audit/types.js";
@@ -1445,6 +1446,52 @@ function coerceGatewayStringifiedArgs(
   return out ?? args;
 }
 
+// The enums and required members that actually explain a rejection are usually
+// nested inside `items`/`oneOf` (a discriminated union of operations), not on
+// the top-level property, so rendering only the top level prints `operations*:
+// array` — true and useless. Bounded depth keeps a deep schema from crowding out
+// the validation errors it is meant to explain.
+const MAX_SIGNATURE_DEPTH = 4;
+const MAX_SIGNATURE_LENGTH = 1200;
+
+function describeSchemaType(
+  spec: AgentNativeJsonSchema | undefined,
+  depth: number,
+): string {
+  if (!spec) return "any";
+  if (spec.const !== undefined) return JSON.stringify(spec.const);
+  if (Array.isArray(spec.enum)) {
+    return spec.enum.map((value) => JSON.stringify(value)).join("|");
+  }
+
+  const branches = spec.oneOf ?? spec.anyOf;
+  if (branches?.length) {
+    if (depth >= MAX_SIGNATURE_DEPTH) return "object";
+    return branches
+      .map((branch) => describeSchemaType(branch, depth))
+      .join(" | ");
+  }
+
+  if (spec.properties && Object.keys(spec.properties).length > 0) {
+    if (depth >= MAX_SIGNATURE_DEPTH) return "object";
+    const required = new Set(spec.required ?? []);
+    const members = Object.entries(spec.properties)
+      .map(
+        ([key, value]) =>
+          `${key}${required.has(key) ? "*" : "?"}: ${describeSchemaType(value, depth + 1)}`,
+      )
+      .join(", ");
+    return `{ ${members} }`;
+  }
+
+  if (spec.items) {
+    if (depth >= MAX_SIGNATURE_DEPTH) return "array";
+    return `array<${describeSchemaType(spec.items, depth + 1)}>`;
+  }
+
+  return Array.isArray(spec.type) ? spec.type.join("|") : (spec.type ?? "any");
+}
+
 /**
  * Compact signature of an action's parameters, e.g.
  * `{ deckId*: string, operation*: "edit"|"replace", slideId?: string }` where
@@ -1469,19 +1516,13 @@ export function describeToolParameterSignature(
     (key) => !only?.length || only.includes(key),
   );
   const sig = (keys.length ? keys : Object.keys(properties))
-    .map((key) => {
-      const spec = properties[key];
-      const mark = required.has(key) ? "*" : "?";
-      const type = Array.isArray(spec.enum)
-        ? spec.enum.map((value) => JSON.stringify(value)).join("|")
-        : Array.isArray(spec.type)
-          ? spec.type.join("|")
-          : (spec.type ?? "any");
-      return `${key}${mark}: ${type}`;
-    })
+    .map(
+      (key) =>
+        `${key}${required.has(key) ? "*" : "?"}: ${describeSchemaType(properties[key], 1)}`,
+    )
     .join(", ");
   if (!sig) return null;
-  return `{ ${sig.length > 600 ? `${sig.slice(0, 600)}…` : sig} }`;
+  return `{ ${sig.length > MAX_SIGNATURE_LENGTH ? `${sig.slice(0, MAX_SIGNATURE_LENGTH)}…` : sig} }`;
 }
 
 /**