agent-accelerator 0.4.0 → 0.5.0

package/src/tools/executor.ts

@@ -6,6 +6,9 @@ import type {
 } from "../types/tool.ts";
 import { toJsonSafe } from "../utils/serialization.ts";
 import { ConfigError } from "../types/errors.ts";
+import { isSubagentResult } from "./subagent-result.ts";
+import { isTruncatedArguments } from "../types/tool.ts";
+import { telemetryBus } from "../telemetry.ts";
 
 export interface ExecuteToolsOptions {
   tools: Record<string, ToolDefinition>;
@@ -56,22 +59,16 @@ export const DEFAULT_MAX_RESULT_CHARS = 20000;
 export const REPEAT_BLOCK_THRESHOLD = 3;
 
 /**
- * True when a tool call carries only `{ raw: string }` arguments — the marker
- * shape produced by `parseStreamedToolArguments` when streamed JSON chunks
- * never parsed to an object (truncated/incomplete arguments). Such calls must
- * NOT execute: the model must retry with complete JSON.
+ * True when a tool call carries only the `{ __truncated_raw: string }` marker
+ * produced by `parseStreamedToolArguments` when streamed JSON chunks never
+ * parsed to an object (truncated/incomplete arguments). Such calls must NOT
+ * execute: the model must retry with complete JSON. The marker key is not a
+ * plausible parameter name, so tools with a real `raw` parameter are unaffected.
  *
  * @example `if (isTruncatedToolCall(call)) return truncatedError(call);`
  */
 export function isTruncatedToolCall(call: ToolCallRecord): boolean {
-  const args = call?.arguments;
-  if (!args || typeof args !== "object" || Array.isArray(args)) return false;
-  const keys = Object.keys(args);
-  return (
-    keys.length === 1 &&
-    keys[0] === "raw" &&
-    typeof (args as Record<string, unknown>).raw === "string"
-  );
+  return isTruncatedArguments(call?.arguments);
 }
 
 /**
@@ -99,6 +96,11 @@ export function assertNoToolCollisions(
   }
 }
 
+/** Redacts `scheme://user:pass@` credentials. The only scrub applied to telemetry-bus error detail. */
+function redactUrlCredentials(message: string): string {
+  return message.replace(/([A-Za-z][A-Za-z0-9+.-]*:\/\/)[^\s"'`@]+@/g, "$1[redacted]@");
+}
+
 /**
  * Redacts secrets and machine-local details from an error message before it
  * is sent back to the model: credentials in URLs/connection strings
@@ -106,11 +108,7 @@ export function assertNoToolCollisions(
  * (`/home/...`, `/Users/...`, `C:\...` → `[redacted-path]`).
  */
 export function sanitizeErrorMessage(message: string): string {
-  let out = message;
-  out = out.replace(
-    /([A-Za-z][A-Za-z0-9+.-]*:\/\/)[^\s"'`@]+@/g,
-    "$1[redacted]@"
-  );
+  let out = redactUrlCredentials(message);
   out = out.replace(/\/home\/[^\s"'`:;,)]*/g, "[redacted-path]");
   out = out.replace(/\/Users\/[^\s"'`:;,)]*/g, "[redacted-path]");
   out = out.replace(/[A-Za-z]:\\[^\s"'`:;,)]*/g, "[redacted-path]");
@@ -128,21 +126,26 @@ function truncateResultString(value: string, limit: number): string {
 }
 
 /**
- * Drops `stack` from an Error-shaped sanitized result for model context.
- * Keeps `{ name, message }` plus any custom keys; nested values untouched.
+ * Scrubs Error-shaped values ANYWHERE in a JSON-safe tool result before it
+ * reaches model context: `stack` is dropped (stack frames carry absolute
+ * server paths) and `message` is passed through {@link sanitizeErrorMessage}
+ * (credentials in URLs, absolute paths). Non-error data is untouched.
  */
-function stripTopLevelErrorStack(value: unknown): unknown {
-  if (!value || typeof value !== "object" || Array.isArray(value)) return value;
+function scrubErrors(value: unknown, depth = 0): unknown {
+  if (!value || typeof value !== "object" || depth > 32) return value;
+  if (Array.isArray(value)) return value.map((v) => scrubErrors(v, depth + 1));
   const record = value as Record<string, unknown>;
-  if (
-    typeof record.name === "string" &&
-    typeof record.message === "string" &&
-    "stack" in record
-  ) {
-    const { stack: _dropped, ...rest } = record;
-    return rest;
+  const errorShaped = typeof record.name === "string" && typeof record.message === "string" && "stack" in record;
+  const out: Record<string, unknown> = {};
+  for (const [key, v] of Object.entries(record)) {
+    if (errorShaped && key === "stack") continue;
+    if (errorShaped && key === "message" && typeof v === "string") {
+      out[key] = sanitizeErrorMessage(v);
+      continue;
+    }
+    out[key] = scrubErrors(v, depth + 1);
   }
-  return value;
+  return out;
 }
 
 /** Stable serialization for repeat-guard fingerprints (key order independent). */
@@ -223,6 +226,48 @@ export function makeRepeatBlockedResult(call: ToolCallRecord): ToolResultRecord
   };
 }
 
+/** Error detail for the telemetry bus (developer channel): full message, code, status, stack and cause chain; only URL credentials are redacted. */
+function describeError(err: unknown, depth = 0): Record<string, unknown> {
+  const e = (err ?? {}) as Record<string, unknown>;
+  const text = (v: unknown): string | undefined => (typeof v === "string" ? redactUrlCredentials(v) : undefined);
+  return {
+    name: typeof e.name === "string" ? e.name : typeof err,
+    message: text(e.message) ?? text(String(err)),
+    ...(e.code !== undefined ? { code: e.code } : {}),
+    ...(e.status !== undefined || e.statusCode !== undefined ? { status: e.status ?? e.statusCode } : {}),
+    ...(e.retryable === true || e.transient === true ? { retryable: true } : {}),
+    ...(text(e.stack) ? { stack: text(e.stack) } : {}),
+    ...(e.cause !== undefined && depth < 4 ? { cause: describeError(e.cause, depth + 1) } : {}),
+  };
+}
+
+/**
+ * Emits one tool lifecycle event on the telemetry bus (`tool.<phase>`). The bus
+ * delivers synchronously, so a developer sink that appends to disk leaves a
+ * crash-proof trace: a `call_started` with no ending event means "in flight at
+ * the crash", and the last `progress` shows how far it got.
+ */
+export function traceToolEvent(
+  phase: string,
+  level: "info" | "warn" | "error",
+  call: { id: string; name: string },
+  scope: { agentName?: string; sessionId?: string },
+  data: Record<string, unknown> = {}
+): void {
+  telemetryBus.emit({
+    code: `tool.${phase}`,
+    message: `[Agent Accelerator] tool ${call.name} (${call.id}): ${phase}`,
+    level,
+    data: { toolCallId: call.id, toolName: call.name, agentName: scope.agentName, sessionId: scope.sessionId, ...data },
+  });
+}
+
+function capJson(value: unknown, max = 2000): unknown {
+  const safe = scrubErrors(toJsonSafe(value));
+  const json = JSON.stringify(safe);
+  return typeof json === "string" && json.length > max ? `${json.slice(0, max)}…[truncated]` : safe;
+}
+
 function levenshtein(a: string, b: string): number {
   const row = Array.from({ length: b.length + 1 }, (_, i) => i);
   for (let i = 1; i <= a.length; i++) {
@@ -271,6 +316,14 @@ function resolveTool(tools: Record<string, ToolDefinition>, requestedName: strin
   };
 }
 
+/** Finds a tool definition by exact or case/format-insensitive name (no suggestion logic). */
+export function findToolDefinition(
+  tools: Record<string, ToolDefinition>,
+  name: string
+): ToolDefinition | undefined {
+  return resolveTool(tools, name).definition;
+}
+
 class Semaphore {
   private active = 0;
   private readonly waiters: Array<{
@@ -376,6 +429,7 @@ async function executeAttempt(
     const error: any = new Error(`Tool execution timed out after ${timeoutMs}ms`);
     error.code = "ETIMEDOUT";
     error.transient = true;
+    error.toolTimeout = true;
     return error;
   };
   try {
@@ -430,14 +484,20 @@ export async function executeToolCalls(
     return semaphore;
   };
 
+  const scope = { agentName, sessionId };
   const runSingle = async (call: ToolCallRecord): Promise<ToolResultRecord> => {
     const startTime = nowMs();
+    // Latest `ctx.emit({ type: "progress", ... })` snapshot: what the tool had finished before any failure.
+    let progress: unknown;
+    let attempts = 0;
+    let timedOut = false;
 
-    // Truncated streamed arguments (Q-12): the `{ raw }` marker means the
+    // Truncated streamed arguments (Q-12): the `__truncated_raw` marker means the
     // provider's partial JSON never parsed. Never execute or overwrite wire
     // finishReason here — return a synthetic error so the model retries with
     // complete JSON.
     if (isTruncatedToolCall(call)) {
+      traceToolEvent("call_blocked", "warn", call, scope, { reason: "truncated_arguments" });
       return {
         id: call.id,
         name: call.name,
@@ -453,6 +513,7 @@ export async function executeToolCalls(
     const toolDef = resolved.definition;
 
     if (!toolDef) {
+      traceToolEvent("call_blocked", "warn", call, scope, { reason: "tool_not_found", suggestion: resolved.suggestion });
       const suffix = resolved.suggestion ? ` Did you mean '${resolved.suggestion}'?` : "";
       return {
         id: call.id,
@@ -481,6 +542,10 @@ export async function executeToolCalls(
         signal,
         sessionId,
         onSubagentEvent,
+        emit: (event) => {
+          if (event?.type === "progress") progress = event;
+          traceToolEvent(event?.type === "progress" ? "progress" : "event", "info", call, scope, { event: capJson(event) });
+        },
       };
 
       // Validate input if Zod schema is provided
@@ -500,6 +565,7 @@ export async function executeToolCalls(
           const hint = expectedParams
             ? ` Expected parameters: ${expectedParams}.`
             : "";
+          traceToolEvent("call_blocked", "warn", call, scope, { reason: "schema_validation", detail: parseRes.error.message });
           return {
             id: call.id,
             name: call.name,
@@ -531,13 +597,20 @@ export async function executeToolCalls(
       executionStartTime = nowMs();
       let rawResult: unknown;
       let attempt = 0;
+      traceToolEvent("call_started", "info", call, scope, { maxAttempts, timeoutMs });
       while (true) {
         attempt++;
+        attempts = attempt;
+        traceToolEvent("attempt_started", "info", call, scope, { attempt, maxAttempts });
         try {
           rawResult = await executeAttempt(toolDef, parsedInput, context, timeoutMs);
           break;
         } catch (err: any) {
           if (signal?.aborted) throw new Error("Tool execution aborted");
+          timedOut = err?.toolTimeout === true;
+          const willRetry =
+            isTransientError(err) && attempt < maxAttempts && !(err?.code === "ETIMEDOUT" && (!configuredTries || configuredTries <= 0));
+          traceToolEvent("attempt_failed", "warn", call, scope, { attempt, maxAttempts, willRetry, error: describeError(err), progress: capJson(progress) });
           if (!isTransientError(err) || attempt >= maxAttempts) throw err;
           // A timeout is a deliberate per-attempt deadline, not a parent
           // cancellation (which rejects via the abort signal instead and is
@@ -546,13 +619,18 @@ export async function executeToolCalls(
           // maxTries. Note ctx.signal is cooperative: the timeout races the
           // tool body, but a tool that ignores the signal still resolves.
           if (err?.code === "ETIMEDOUT" && (!configuredTries || configuredTries <= 0)) throw err;
-          await waitForRetry(Math.min(30_000, 250 * 2 ** Math.min(attempt - 1, 7)), signal);
+          const delayMs = Math.min(30_000, 250 * 2 ** Math.min(attempt - 1, 7));
+          traceToolEvent("retry_scheduled", "info", call, scope, { attempt, nextAttempt: attempt + 1, delayMs });
+          await waitForRetry(delayMs, signal);
         }
       }
 
       // Undefined means "no value", serialized null-safe as "null" (changed
       // from the legacy "Success" marker so model context stays valid JSON).
+      const finishOk = (resultChars: number): void =>
+        traceToolEvent("call_succeeded", "info", call, scope, { attempts: attempt, durationMs: elapsedMs(executionStartTime), resultChars });
       if (rawResult === undefined) {
+        finishOk(4);
         return {
           id: call.id,
           name: resolved.name,
@@ -561,12 +639,31 @@ export async function executeToolCalls(
           durationMs: elapsedMs(executionStartTime),
         };
       }
-      // Stack traces stay in server logs, not model context: keep
-      // { name, message } plus custom keys, drop stack.
-      let safeResult = stripTopLevelErrorStack(toJsonSafe(rawResult));
+      // Branded delegation envelopes pass through untouched: JSON-safing would
+      // strip the (symbol) brand the loop needs to trust their metadata.
+      if (isSubagentResult(rawResult)) {
+        finishOk(rawResult.xml.length);
+        return {
+          id: call.id,
+          name: resolved.name,
+          result: rawResult,
+          isError: false,
+          durationMs: elapsedMs(executionStartTime),
+        };
+      }
+      // Nested error stacks / absolute paths never reach model context.
+      let safeResult = scrubErrors(toJsonSafe(rawResult));
+      const charLimit = resultCharLimit(toolDef);
       if (typeof safeResult === "string") {
-        safeResult = truncateResultString(safeResult, resultCharLimit(toolDef));
+        safeResult = truncateResultString(safeResult, charLimit);
+      } else {
+        // Structured results are capped by their serialized size too: a tool
+        // returning 50k rows must not blow the context window (or the bill).
+        // Oversized ones become a truncated JSON string with the usual marker.
+        const json = JSON.stringify(safeResult);
+        if (typeof json === "string" && json.length > charLimit) safeResult = truncateResultString(json, charLimit);
       }
+      finishOk(typeof safeResult === "string" ? safeResult.length : (JSON.stringify(safeResult)?.length ?? 0));
       return {
         id: call.id,
         name: resolved.name,
@@ -575,8 +672,17 @@ export async function executeToolCalls(
         durationMs: elapsedMs(executionStartTime),
       };
     } catch (err: any) {
-      // Never leak secrets/paths to the model. A per-tool redactError hook
-      // wins; otherwise sanitize the message (credentials, file paths).
+      // The developer channel (telemetry bus) gets the full error; the model gets a
+      // scrubbed message plus what the tool finished before failing, so it repairs
+      // only the remainder instead of repeating completed side effects.
+      const aborted = signal?.aborted === true;
+      const done = err?.context?.progress ?? progress;
+      traceToolEvent(aborted ? "call_aborted" : timedOut ? "call_timed_out" : "call_failed", "error", call, scope, {
+        attempts,
+        durationMs: elapsedMs(executionStartTime),
+        error: describeError(err),
+        progress: capJson(done),
+      });
       let message: string;
       const redactError = (toolDef as any)?.redactError;
       if (typeof redactError === "function") {
@@ -588,10 +694,29 @@ export async function executeToolCalls(
       } else {
         message = sanitizeErrorMessage(err?.message || String(err));
       }
+      const details = {
+        ...(typeof redactError === "function"
+          ? {}
+          : {
+              error: {
+                name: err?.name,
+                ...(err?.code !== undefined ? { code: err.code } : {}),
+                ...(err?.status !== undefined || err?.statusCode !== undefined ? { status: err.status ?? err.statusCode } : {}),
+              },
+            }),
+        attempts,
+        ...(timedOut ? { timedOut: true } : {}),
+        ...(aborted ? { aborted: true } : {}),
+        ...(done !== undefined ? { progress: capJson(done) } : {}),
+        hint:
+          done !== undefined
+            ? "The tool failed part-way. Work reported in progress was NOT undone: do not repeat it, retry or fix only what remains."
+            : "The tool failed and may have partially executed. Check before retrying side-effecting work.",
+      };
       return {
         id: call.id,
         name: call.name,
-        result: `Error executing ${call.name}: ${message}`,
+        result: `Error executing ${call.name}: ${message}\n${JSON.stringify(details)}`,
         isError: true,
         durationMs: elapsedMs(executionStartTime),
       };

package/src/tools/subagent-result.ts

@@ -0,0 +1,60 @@
+import type { SubAgentExecutionMetadata } from "../types/response.ts";
+
+/**
+ * Module-private brand proving a tool result was produced by the SDK's own
+ * delegation tools (`agentToTool` / `spawn_subagents`). Symbols cannot be
+ * forged by JSON a tool fetched from the web, so only branded results get
+ * their `_subagentMetadata` trusted (usage/cost rolled up, XML shown to the
+ * model).
+ */
+const SUBAGENT_RESULT_BRAND: unique symbol = Symbol("agent-accelerator.subagent-result") as never;
+
+/** Branded envelope returned by delegation tools. */
+export interface SubagentResult {
+  xml: string;
+  _subagentMetadata: SubAgentExecutionMetadata[];
+  toString(): string;
+  readonly [SUBAGENT_RESULT_BRAND]: true;
+}
+
+/** Wraps worker output + metadata in the branded envelope. */
+export function makeSubagentResult(xml: string, metas: SubAgentExecutionMetadata[]): SubagentResult {
+  return {
+    xml,
+    _subagentMetadata: metas,
+    toString() {
+      return xml;
+    },
+    [SUBAGENT_RESULT_BRAND]: true,
+  };
+}
+
+/** True only for envelopes created by {@link makeSubagentResult}. */
+export function isSubagentResult(value: unknown): value is SubagentResult {
+  return !!value && typeof value === "object" && (value as Record<symbol, unknown>)[SUBAGENT_RESULT_BRAND] === true;
+}
+
+const num = (v: unknown): number => (typeof v === "number" && Number.isFinite(v) && v >= 0 ? v : 0);
+
+/**
+ * Defensive copy of worker metadata: guarantees the fields the loop reads
+ * (`usage` numbers, string `provider`/`model`) exist, so one malformed entry
+ * can never crash a run.
+ */
+export function normalizeSubagentMetadata(metas: unknown): SubAgentExecutionMetadata[] {
+  if (!Array.isArray(metas)) return [];
+  const out: SubAgentExecutionMetadata[] = [];
+  for (const raw of metas) {
+    if (!raw || typeof raw !== "object") continue;
+    const m = raw as Record<string, unknown>;
+    const u = (m.usage && typeof m.usage === "object" ? m.usage : {}) as Record<string, unknown>;
+    const usage = { ...u, inputTokens: num(u.inputTokens), outputTokens: num(u.outputTokens), totalTokens: num(u.totalTokens) };
+    out.push({
+      ...(m as unknown as SubAgentExecutionMetadata),
+      model: typeof m.model === "string" ? m.model : "unknown",
+      provider: typeof m.provider === "string" ? m.provider : "unknown",
+      usage,
+    });
+  }
+  return out;
+}

package/src/types/agent.ts

@@ -7,6 +7,7 @@ import type {
 } from "./core.ts";
 import type { ModelProviderInstance } from "../providers/registry.ts";
 import type { Agent } from "../agent/agent.ts";
+import type { z } from "zod";
 
 // ---------------------------------------------------------------------------
 // Q-52/Q-53/Q-54 canonical option types (all additive; nothing renamed).
@@ -29,12 +30,6 @@ export type ModelRef = string | ModelSpec | ModelProviderInstance;
 /** Canonical reasoning option (Q-52): bare level, or level + explicit token budget. */
 export type ThinkingOption = ThinkingLevel | { level?: ThinkingLevel; budgetTokens?: number };
 
-/** Canonical sampling knobs (Q-54). Read by the loop via `(config as any).sampling`. */
-export interface SamplingConfig {
-  temperature?: number;
-  topP?: number;
-}
-
 /** Canonical retry policy (Q-54). Read by the loop via `(config as any).retry`. */
 export interface RetryPolicyConfig {
   maxRetries?: number;
@@ -61,6 +56,17 @@ export type ToolChoiceOption =
 /** Canonical stop control (Q-54): sequence(s) halting generation. */
 export type StopOption = string | string[];
 
+/** Canonical structured-output input (Q-61). Zod, JSON Schema, or explicit form. */
+export type StructuredOutputOption =
+  | z.ZodType
+  | Record<string, unknown>
+  | {
+      name?: string;
+      description?: string;
+      schema: z.ZodType | Record<string, unknown>;
+      strict?: boolean;
+    };
+
 /** Configuration used to construct an {@link Agent}. */
 export interface AgentConfig {
   /** Display name used in tool and sub-agent metadata. */
@@ -127,24 +133,39 @@ export interface AgentConfig {
    * after every step (user turn, assistant turn, tool batch, sub-agent
    * step) so a crash loses at most the in-flight step. Pass `{ dir }` for
    * `sessions/<sessionId>/session.json` layout or `{ file }` for a single
-   * pretty `.session.json` file. Writes are atomic and never fail a turn.
+   * pretty `.session.json` file. `persist: {}` (neither) uses `<home>/sessions`.
+   * Writes are atomic and never fail a turn.
    */
   persist?: { dir?: string; file?: string };
+  /**
+   * Folder for everything Agent Accelerator writes to disk (`sessions/`,
+   * `scheduled_actions/`, `telemetry/`). Defaults to `setHome()`, then the `AGENT_ACCEL_HOME` env var, then `.agent-accel/` in the working directory.
+   * An explicit `persist.dir` / `persist.file` still wins for sessions.
+   */
+  home?: string;
   // Q-54 missing knobs (all optional, additive; loop reads via `(config as any).*`).
-  /** Canonical tool-selection control (`"auto"` default). */
+  /**
+   * Canonical tool-selection control (`"auto"` default). `"none"` applies to
+   * every turn of a run; `"required"` and a pinned tool (`{ tool: "name" }`)
+   * apply to the FIRST model turn only, since forcing a tool call on every
+   * turn would make a run unable to finish.
+   */
   toolChoice?: ToolChoiceOption;
+  /** Google Interactions storage tier for the chain-TTL gate: `"free"` (23h, default) or `"paid"` (54d). */
+  googleTier?: "free" | "paid";
   /** Maximum output tokens for one model call. */
   maxOutputTokens?: number;
-  /** Sampling knobs. */
-  sampling?: SamplingConfig;
   /** Stop sequence(s). */
   stop?: StopOption;
   /** Deterministic seed, when the provider supports it. */
   seed?: number;
   /**
-   * Optional output schema (Zod or JSON Schema, stored as `unknown` so `zod`
+   * Optional output schema (Zod, JSON Schema, or `{ name, schema, strict }`,
+   * see `StructuredOutputOption`, stored as `unknown` so `zod`
    * stays optional for type-only consumers). Agent-level only; per-run
-   * overrides are intentionally unsupported.
+   * overrides are intentionally unsupported. When set, the model answer is
+   * constrained to the schema on all providers and `AgentResponse.parsed`
+   * carries the validated value.
    */
   output?: unknown;
   /** Retry policy for provider calls. */
@@ -153,19 +174,46 @@ export interface AgentConfig {
   fetch?: typeof fetch;
   /** Provider/env overrides forwarded to key resolution. */
   env?: Record<string, string>;
-  /** Structured logger for loop telemetry (defaults to no-op). */
+  /** @deprecated Not implemented yet; subscribe with `telemetryBus.onEvent` instead. Passing it emits a `config.unsupported_option` warning. */
   logger?: AgentLogger;
-  /** Control hooks (Q-59). All optional, fail-open by default. */
+  /** @deprecated Not implemented yet (accepted for forward compatibility; passing it emits a `config.unsupported_option` warning). */
   hooks?: unknown;
-  /** Threshold compaction policy (Q-60a). Fully configurable/replaceable. */
+  /** @deprecated Not implemented yet (accepted for forward compatibility; passing it emits a `config.unsupported_option` warning). */
   contextManagement?: unknown;
-  /** Telemetry bus (Q-41). Default no-op; pretty logger lives in /cli. */
-  telemetry?: { onEvent?: (e: any) => void } | unknown;
-  /** Local file access roots (Q-08). Default deny; `path` sources must resolve inside roots. */
+  /**
+   * Telemetry options. `persist: true` appends every `telemetryBus` event (except full reasoning
+   * text) to `<home>/telemetry/<date>.ndjson`. Off by default: the SDK writes nothing unless asked.
+   */
+  telemetry?: { persist?: boolean };
+  /**
+   * Local file policy. With `roots` set, every local-path media part and the
+   * built-in `convert_document_to_markdown` tool must resolve inside them
+   * (`[]` denies all local paths). Without it, developer-supplied parts are
+   * unrestricted and the model-callable tool is limited to `process.cwd()`.
+   */
   fileAccess?: { roots?: string[] };
-  /** Raw capture policy (Q-11). Default "redacted": no bodies. */
+  /**
+   * Conversation handling when a run FAILS (aborts always keep partial
+   * history). `"auto"` (default) restores the pre-run state unless a tool
+   * already ran, since rolling back would erase the record of real side
+   * effects and a retry would repeat them. `"rollback"` always restores;
+   * `"keep"` never does.
+   */
+  onFailure?: "auto" | "rollback" | "keep";
+  /**
+   * What `AgentResponse.raw` keeps of the wire exchange. `"redacted"` (default):
+   * URL, method, redacted headers and HTTP status, with request/response BODIES
+   * replaced by a content-free summary so prompts, files and model output never
+   * leak into logs via `toJSON()`. `true`: full bodies (debugging). `false`:
+   * URL, method and status only.
+   */
   captureRaw?: false | "redacted" | true;
-  /** Opt-in run budgets (Q-39). All fields default unlimited. */
+  /**
+   * Opt-in budgets, enforced PER RUN (counters restart with every `run`/`stream`)
+   * and including sub-agent usage. Exceeding a cap throws `BudgetExceededError`
+   * with the partial usage attached. `maxCostUsd` counts only priced usage:
+   * models with unknown pricing contribute $0, never a guess.
+   */
   budget?: Budget;
   /** Run + network limits (Q-22). Turn/budget caps unlimited by default; network timeouts finite. */
   limits?: AgentRunLimits;
@@ -211,6 +259,12 @@ export interface MidSessionConfig {
 export interface DynamicSubagentsConfig {
   /** Enables the automatic `spawn_subagents` tool. Defaults to true when the object is present. */
   enabled?: boolean;
+  /**
+   * Lets the Main Agent schedule dynamic sub-agents to run later (once or on
+   * repeat) via the `scheduled_actions` and `get_datetime` tools. Off by
+   * default: without it no tool, clock or timer exists. Needs a worker model.
+   */
+  allowScheduledActions?: boolean;
   /** Developer-only worker model override. Never choosable by the Main Agent LLM. Falls back to top-level `subagentModel`, then `SUB_AGENT_MODEL` env, then the parent model. */
   model?: string | ModelSpec | ModelProviderInstance;
   /** Max workers the Main Agent may spawn in a single `spawn_subagents` call. Extras are trimmed safely. Defaults to 4. */
@@ -278,8 +332,6 @@ export interface AgentRunOptions {
   toolChoice?: ToolChoiceOption;
   /** Per-run output-token cap. */
   maxOutputTokens?: number;
-  /** Per-run sampling override. */
-  sampling?: SamplingConfig;
   /** Per-run stop sequence(s). */
   stop?: StopOption;
   /** Per-run seed. */

package/src/types/model.ts

@@ -87,6 +87,7 @@ export interface ModelCapabilities {
   supportsLongCacheRetention?: boolean;
   supportsParallelToolCalls?: boolean;
   supportsStreaming?: boolean;
+  supportsStructuredOutput?: boolean;
   modalities?: ("text" | "image" | "audio" | "video" | "pdf")[];
   // derived
   supportsReasoningToggle?: boolean;
@@ -138,6 +139,24 @@ export interface ModelSpec {
   raw?: RawModelData;
 }
 
+// ---------------------------------------------------------------------------
+// Structured outputs — normalized, provider-agnostic spec.
+// Canonical input is `AgentConfig.output` (Zod, JSON Schema, or explicit
+// `{ name, schema, strict }`); `normalizeStructuredOutput` in
+// `src/providers.ts` produces this shape for adapters.
+// ---------------------------------------------------------------------------
+/** Normalized structured-output request passed from Agent to providers. */
+export interface StructuredOutputSpec {
+  /** Format name (1-64 chars, `[a-zA-Z0-9_-]`). Defaults to `structured_output`. */
+  name: string;
+  /** JSON Schema for the final answer (already converted from Zod when needed). */
+  schema: Record<string, unknown>;
+  /** Strict schema adherence (OpenAI/OpenRouter only; ignored by Google). Defaults to true. */
+  strict?: boolean;
+  /** Optional description of what the format is for. */
+  description?: string;
+}
+
 // ---------------------------------------------------------------------------
 // Provider plumbing — unchanged API
 // ---------------------------------------------------------------------------
@@ -156,6 +175,26 @@ export interface ProviderRequestOptions {
   env?: Record<string, string>;
   maxRetries?: number;
   maxRetryDelayMs?: number;
+  /** Normalized structured-output spec (see `normalizeStructuredOutput`). */
+  output?: StructuredOutputSpec;
+  /**
+   * Google Interactions storage tier for the proactive chain-TTL gate
+   * (free: 23h local gate; paid: 54d). Default `free` (safe). Display-only
+   * cache behavior is unaffected; unknown values fall back to `free`.
+   */
+  googleTier?: "free" | "paid";
+  /** Upper bound on generated tokens for one model call. */
+  maxOutputTokens?: number;
+  /** Stop sequence(s). Chat Completions only; other wires warn+drop. */
+  stop?: string[];
+  /** Deterministic-sampling seed. Chat Completions only; other wires warn+drop. */
+  seed?: number;
+  /** `fetch` implementation used for the provider request (defaults to global `fetch`). */
+  fetch?: typeof fetch;
+  /** Base backoff delay in ms for provider retries (default 250). */
+  retryBaseDelayMs?: number;
+  /** Total time budget in ms for provider retries (default 30000). */
+  retryBudgetMs?: number;
 }
 
 /** Auditable request/response wire payload captured in AgentResponse. */