@standardagents/spec 0.14.1 → 0.15.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { z, ZodString, ZodNumber, ZodBoolean, ZodNull, ZodLiteral, ZodEnum, ZodOptional, ZodNullable, ZodDefault, ZodArray, ZodObject, ZodRecord, ZodUnion, ZodTypeAny } from 'zod';
+import { z, ZodString, ZodNumber, ZodBoolean, ZodNull, ZodLiteral, ZodUnknown, ZodEnum, ZodOptional, ZodNullable, ZodDefault, ZodArray, ZodObject, ZodRecord, ZodUnion, ZodTypeAny } from 'zod';
 
 /**
  * Global namespace for Standard Agent Specification types.
@@ -97,11 +97,21 @@ declare global {
          * Union of all tool names, or string when registry is empty.
          */
         type Tools = keyof ToolRegistry extends never ? string : keyof ToolRegistry;
+        /**
+         * Provider-executed tool reference stored by AgentBuilder prompts.
+         */
+        type ProviderCallable = `provider:${string}`;
+        /**
+         * MCP tool reference stored by AgentBuilder prompts.
+         */
+        type McpCallable = `mcp:${string}`;
         /**
          * Union of all callable names, or string when registry is empty.
          * Callables include prompts, agents, and tools that can be used as tools.
+         * Provider and MCP tool references use reserved prefixes and remain valid
+         * even when generated project registries are populated.
          */
-        type Callables = keyof CallableRegistry extends never ? string : keyof CallableRegistry;
+        type Callables = keyof CallableRegistry extends never ? string : keyof CallableRegistry | ProviderCallable | McpCallable;
         /**
          * Union of all hook IDs, or string when registry is empty.
          * Hook IDs are the unique identifiers defined in agents/hooks/ files.
@@ -115,7 +125,7 @@ declare global {
  *
  * Effects are scheduled operations that run outside the tool execution context.
  * They enable implementation-specific side effects with optional delay support,
- * leveraging the runtime's scheduling mechanism (e.g., Cloudflare Durable Object alarms).
+ * leveraging whichever scheduling mechanism the runtime provides.
  *
  * Unlike tools, effects:
  * - Do not return results to the LLM
@@ -462,6 +472,221 @@ interface FileChunk {
     /** Whether this is the final chunk */
     isLast: boolean;
 }
+/**
+ * Options passed to {@link ThreadState.runCode}.
+ *
+ * Code execution is strictly capability-based: the sandbox starts with no
+ * ambient capabilities (no `fs`, no `fetch`, no `console`, no host globals).
+ * Every capability the sandbox needs must be bridged in explicitly through
+ * `imports` or `globals`.
+ *
+ * Deadlines are **not** an option. Callers impose their own by calling
+ * `handle.terminate()` on the returned {@link CodeExecution}.
+ *
+ * See the [Code Execution specification](https://standardagentspec.com/0.1.0/specification/threads/code-execution)
+ * for the full contract.
+ */
+interface CodeExecutionOptions {
+    /**
+     * Export to execute from the evaluated module and arguments to pass.
+     *
+     * By default, runtimes execute the module's `default` export with no
+     * arguments. If the selected export is a function, it is called with
+     * `args` and the returned value or promise is used as the run result. If the
+     * selected export is not a function, `args` MUST be omitted or empty and the
+     * export value itself becomes the result.
+     *
+     * @default { fn: 'default', args: [] }
+     *
+     * @example
+     * ```ts
+     * execute: { fn: 'increment', args: [100] }
+     * ```
+     */
+    execute?: {
+        /** Export name to execute. Use `'default'` for the default export. */
+        fn?: string;
+        /** Arguments passed to the selected export when it is a function. */
+        args?: unknown[];
+    };
+    /**
+     * Map of bare module specifier → named exports exposed to the sandbox.
+     *
+     * Only bare specifiers resolve from `imports` (e.g., `'fs'`,
+     * `'@scope/pkg'`). Relative specifiers resolve only from `modules`; URL
+     * (`'https://…'`) imports MUST fail at link time.
+     *
+     * The key `default` within a namespace becomes that module's default export.
+     *
+     * @example
+     * ```ts
+     * imports: {
+     *   fs: { readFile: (path) => state.readFile(path) },
+     *   supervisor: { report: (payload) => telemetry.push(payload) },
+     * }
+     * ```
+     */
+    imports?: Record<string, Record<string, unknown>>;
+    /**
+     * Additional relative ES modules available to the sandbox.
+     *
+     * Keys are relative module specifiers from the module graph root, such as
+     * `'./helpers.js'` or `'./lib/math.js'`. Entry source imports resolve from
+     * `filename` when one is supplied. Entry and module source may import sibling
+     * or parent modules with `./` and `../` specifiers when those imports resolve
+     * within the supplied module graph. Values are JavaScript or TypeScript module
+     * source. Use this when a caller wants the entry source to import local files
+     * while still keeping all modules inside the sandbox.
+     */
+    modules?: Record<string, string>;
+    /**
+     * Map of identifier → value installed on the sandbox's module scope.
+     *
+     * These identifiers are resolvable as free variables inside the sandbox
+     * but MUST NOT appear on `globalThis`.
+     *
+     * @example
+     * ```ts
+     * globals: {
+     *   console: { log: (...args) => logger.info(...args) },
+     *   getMessage: async () => '...',
+     * }
+     * ```
+     */
+    globals?: Record<string, unknown>;
+    /**
+     * Source language. TypeScript source has its types erased before evaluation;
+     * no type checking is performed.
+     *
+     * @default 'typescript'
+     */
+    language?: 'javascript' | 'typescript';
+    /**
+     * Maximum sandbox heap in bytes. Exceeding this settles the handle with
+     * `status: 'memory'`. Runtime default is implementation-defined and
+     * documented per runtime.
+     */
+    memoryLimitBytes?: number;
+    /**
+     * Label used in stack traces and error `specifier` fields.
+     *
+     * @default '<runCode>'
+     */
+    filename?: string;
+    /**
+     * Optional host-side sink for the built-in `report` bridge.
+     *
+     * When provided, the runtime installs a `report` global that forwards values
+     * to this callback. Reported values are also appended to the live
+     * {@link CodeExecution.reports} view and to the final
+     * {@link CodeExecutionResult.reports}.
+     */
+    report?: (value: unknown) => void;
+}
+/**
+ * Handle returned by {@link ThreadState.runCode}.
+ *
+ * `CodeExecution` is a `PromiseLike<CodeExecutionResult>` — `await` the handle
+ * to get the final result. The handle also exposes controls that only make
+ * sense while the run is in flight: caller-initiated termination and a live
+ * view of values emitted via the `report` bridge.
+ */
+interface CodeExecution extends PromiseLike<CodeExecutionResult> {
+    /**
+     * Stop the run. Idempotent: subsequent calls are no-ops.
+     *
+     * Settles the handle with `status: 'terminated'` at the next ECMAScript
+     * yield point (microtask boundary, async operation, or runtime interrupt).
+     * Typically a few milliseconds and SHOULD be ≤ 50 ms under normal host load;
+     * a pure-synchronous tight loop may run until the runtime's own safety cap
+     * fires. When `reason` is provided, it surfaces in `error.message`.
+     */
+    terminate(reason?: string): void;
+    /** `true` until the handle settles. */
+    readonly running: boolean;
+    /**
+     * Snapshot of values emitted via the `report` bridge so far, in call order.
+     * The same values appear in {@link CodeExecutionResult.reports} once the
+     * run ends.
+     */
+    readonly reports: readonly unknown[];
+}
+/**
+ * Outcome classification for {@link CodeExecutionResult.status}.
+ *
+ * - `success` — Module evaluated and the configured export resolved.
+ * - `error` — Uncaught runtime error inside the sandbox.
+ * - `memory` — `memoryLimitBytes` exceeded.
+ * - `terminated` — Caller called `handle.terminate()`, or the runtime's own
+ *   safety cap fired. `error.message` distinguishes the two (including any
+ *   `reason` the caller passed).
+ * - `link_error` — Module graph failed to link (unknown specifier, missing
+ *   named export, parse error).
+ */
+type CodeExecutionStatus = 'success' | 'error' | 'memory' | 'terminated' | 'link_error';
+/**
+ * A single captured `console.*` call from inside the sandbox.
+ *
+ * Only populated when the runtime installs a capturing `console` (typically
+ * when the caller does not provide one via `options.globals`).
+ */
+interface CodeExecutionLog {
+    level: 'log' | 'info' | 'warn' | 'error' | 'debug';
+    /** Marshaled argument values, deep-cloned from the sandbox. */
+    args: unknown[];
+    /** Millisecond timestamp when the call occurred. */
+    timestamp: number;
+}
+/**
+ * Error surfaced when a {@link CodeExecutionResult} does not have
+ * `status: 'success'`.
+ *
+ * Host-side stack frames MUST NOT leak into this object — only sandbox
+ * frames are included.
+ */
+interface CodeExecutionError {
+    name: string;
+    message: string;
+    stack?: string;
+    /** Module specifier that failed to link (for `link_error`). */
+    specifier?: string;
+    /** Source filename associated with `line` and `column`, when available. */
+    filename?: string;
+    /** 1-based line number in source, when available. */
+    line?: number;
+    /** 1-based column number in source, when available. */
+    column?: number;
+}
+/**
+ * Result of a {@link ThreadState.runCode} call.
+ *
+ * The sandbox has two result channels and both may be used in the same run:
+ * - **Configured export** → marshaled into `result` on success.
+ * - **Bridge reports** → appended to `reports` in call order as they are emitted.
+ */
+interface CodeExecutionResult {
+    /** Outcome classification — see {@link CodeExecutionStatus}. */
+    status: CodeExecutionStatus;
+    /**
+     * Resolved configured export (after awaiting top-level promises).
+     * Omitted when `status !== 'success'`. `undefined` is a valid success result
+     * when the configured export resolves to `undefined`.
+     */
+    result?: unknown;
+    /**
+     * Values emitted through the built-in `report` bridge when
+     * `options.report` is supplied, in call order. Empty when unused.
+     */
+    reports: unknown[];
+    /** Captured `console.*` calls (see {@link CodeExecutionLog}). Empty when the caller supplies its own `console`. */
+    logs: CodeExecutionLog[];
+    /** Error detail. Present iff `status` is not `'success'`. */
+    error?: CodeExecutionError;
+    /** Wall-clock execution time in milliseconds. */
+    durationMs: number;
+    /** Peak sandbox heap in bytes, when the engine can measure it. */
+    memoryUsedBytes?: number;
+}
 /**
  * Execution-specific state available during agent execution.
  *
@@ -520,6 +745,24 @@ interface ExecutionState {
      */
     readonly promptPath: string[];
 }
+/**
+ * Display/redaction classification for thread-scoped environment values.
+ *
+ * `secret` values should be redacted from tool output and logs. `text` values
+ * may be displayed.
+ */
+type EnvValueType = 'text' | 'secret';
+/**
+ * Options for {@link ThreadState.setEnv}.
+ */
+interface SetEnvOptions {
+    /**
+     * Display/redaction classification for this value.
+     *
+     * Defaults to the existing type for that key, or `secret` for new keys.
+     */
+    type?: EnvValueType;
+}
 /**
  * The unified interface for all thread operations.
  *
@@ -554,10 +797,10 @@ interface ExecutionState {
  * @example
  * ```typescript
  * // In an endpoint
- * export default defineThreadEndpoint(async (req, state) => {
+ * export default defineThreadEndpoint(async (req, state, params) => {
  *   // state.execution is null (not executing)
  *   const { messages } = await state.getMessages({ limit: 50 });
- *   return Response.json({ messages });
+ *   return Response.json({ messages, params });
  * });
  * ```
  */
@@ -698,6 +941,13 @@ interface ThreadState {
      * @throws If the variable is not defined in any source
      */
     env(propertyName: string): Promise<string>;
+    /**
+     * Resolve the display/redaction type for an environment value.
+     *
+     * Values marked `secret` should be redacted from tool output and logs.
+     * Values marked `text` may be shown. Unknown values default to `secret`.
+     */
+    envType(propertyName: string): Promise<EnvValueType>;
     /**
      * Set a thread-scoped environment variable.
      *
@@ -707,8 +957,9 @@ interface ThreadState {
      *
      * @param propertyName - Environment variable name
      * @param value - Environment variable value
+     * @param options - Optional display/redaction classification for this value
      */
-    setEnv(propertyName: string, value: string): Promise<void>;
+    setEnv(propertyName: string, value: string, options?: SetEnvOptions): Promise<void>;
     /**
      * Queue a silent message to this thread's parent, if one exists.
      *
@@ -787,13 +1038,14 @@ interface ThreadState {
      */
     getScheduledEffects(name?: string): Promise<ScheduledEffect[]>;
     /**
-     * Remove a scheduled effect.
+     * Cancel a scheduled effect.
      *
-     * Cancels a pending effect before it executes. Has no effect if the
-     * effect has already executed or doesn't exist.
+     * Cancels a pending effect before it executes. Has no effect if the effect
+     * has already executed, was already canceled, or doesn't exist. Runtimes may
+     * retain canceled effects in inspection history.
      *
      * @param id - The effect ID returned by scheduleEffect
-     * @returns true if the effect was found and removed, false otherwise
+     * @returns true if the effect was found and canceled, false otherwise
      */
     removeScheduledEffect(id: string): Promise<boolean>;
     /**
@@ -837,10 +1089,47 @@ interface ThreadState {
      * Key-value storage for custom data scoped to this thread.
      *
      * Context data persists across tool calls within a single execution.
-     * For persistent storage across executions, use messages or external
-     * storage.
+     * For persistent storage across executions, use {@link ThreadState.getValue}
+     * and {@link ThreadState.setValue}, the file system, or external storage.
      */
     context: Record<string, unknown>;
+    /**
+     * Read a value from the thread's durable key-value store.
+     *
+     * Values written with {@link ThreadState.setValue} persist across executions,
+     * tool calls, hook invocations, and endpoint requests for the lifetime of
+     * the thread. The key-value store is one of two ways to store persistent
+     * data on a thread, alongside the file system.
+     *
+     * Returns `null` when no value has been set for the given key. Values are
+     * returned exactly as they were stored; runtimes MUST preserve JSON-equivalent
+     * structure (objects, arrays, strings, numbers, booleans, `null`).
+     *
+     * @param key - The key to read
+     * @returns The stored value, or `null` if the key has no value
+     *
+     * @example
+     * ```typescript
+     * const count = (await state.getValue<number>('invocation_count')) ?? 0;
+     * await state.setValue('invocation_count', count + 1);
+     * ```
+     */
+    getValue<T = unknown>(key: string): Promise<T | null>;
+    /**
+     * Write a value to the thread's durable key-value store.
+     *
+     * The value persists across executions for the lifetime of the thread.
+     * Passing `null` or `undefined` deletes the key. Values MUST be
+     * JSON-serializable; implementations MAY reject non-serializable values.
+     *
+     * Durable values are **not** automatically copied between threads when
+     * subagents are spawned — each thread maintains its own key-value store.
+     *
+     * @param key - The key to write
+     * @param value - The value to store (JSON-serializable), or `null`/`undefined`
+     *   to delete the key
+     */
+    setValue(key: string, value: unknown): Promise<void>;
     /**
      * Write a file to the thread's file system.
      *
@@ -954,11 +1243,79 @@ interface ThreadState {
      * Use this to access step counts, force turns, or stop execution.
      */
     execution: ExecutionState | null;
+    /**
+     * Execute JavaScript or TypeScript source in an isolated sandbox.
+     *
+     * The sandbox has **no ambient capabilities**: no filesystem, no network,
+     * no timers, no host globals, no access to `state` itself. Every capability
+     * the sandbox needs must be bridged in explicitly via `options.imports`,
+     * `options.modules`, or `options.globals`.
+     *
+     * Returns a {@link CodeExecution} handle that is a
+     * `PromiseLike<CodeExecutionResult>` — `await` it for the final result — and
+     * also exposes `terminate()` for caller-initiated cancellation. The spec
+     * does not impose a wall-clock timeout; callers layer their own deadline
+     * using a timer plus `handle.terminate()`.
+     *
+     * Results flow back through either:
+     * - the module export selected by `options.execute` (marshaled into
+     *   `result.result`; defaults to the `default` export with no arguments; if
+     *   the selected export is a function, it is called with `execute.args` and
+     *   any returned promise is awaited before marshaling), or
+     * - the built-in `report` bridge (accumulated into `result.reports` and
+     *   visible live on `handle.reports`), or
+     * - caller-installed bridge callbacks that the caller owns.
+     *
+     * See the [Code Execution specification](https://standardagentspec.com/0.1.0/specification/threads/code-execution)
+     * for isolation guarantees, module resolution rules, value marshaling, and
+     * conformance requirements.
+     *
+     * @param source - JavaScript or TypeScript source, evaluated as an ES module.
+     * @param options - Export selection, imports, globals, memory cap, and language hints.
+     * @returns A handle that settles with the execution result and can be
+     *   terminated at any time before settlement.
+     *
+     * @example
+     * ```typescript
+     * const run = state.runCode(
+     *   `
+     *     import { readFile } from 'fs';
+     *     import { report } from 'supervisor';
+     *
+     *     const message = await getMessage();
+     *     if (/username/.test(message)) {
+     *       report({ topic: 'username', message });
+     *     }
+     *     export default async () => ({ scanned: true });
+     *   `,
+     *   {
+     *     imports: {
+     *       fs: { readFile: (p) => state.readFile(p) },
+     *       supervisor: { report: (payload) => flagged.push(payload) },
+     *     },
+     *     globals: {
+     *       console: { log: (...a) => {} },
+     *       getMessage: async () => 'latest user message',
+     *     },
+     *   },
+     * );
+     *
+     * const deadline = setTimeout(() => run.terminate('5s budget'), 5_000);
+     * const result = await run;
+     * clearTimeout(deadline);
+     *
+     * if (result.status === 'success') {
+     *   // result.result === { scanned: true }
+     * }
+     * ```
+     */
+    runCode(source: string, options?: CodeExecutionOptions): CodeExecution;
     /**
      * Runtime-specific context that cannot be packed or shared.
      *
-     * This property allows runtime implementations to inject non-portable
-     * context (e.g., Cloudflare env bindings, database connections).
+     * This property lets runtime implementations inject non-portable context —
+     * typically host bindings, database connections, or other
+     * platform-specific handles the runtime chooses to expose.
      *
      * WARNING: Tools using this property cannot be packed, shared, or
      * published as they depend on runtime-specific context.
@@ -1089,10 +1446,12 @@ type Dec<N extends number> = N extends 10 ? 9 : N extends 9 ? 8 : N extends 8 ?
  * This is the single source of truth for which Zod types can be used
  * in tool argument schemas. The depth parameter limits recursion to
  * prevent infinite type expansion.
+ * Use ZodUnknown for arbitrary JSON slots, such as array items that can
+ * be strings, numbers, booleans, null, arrays, or objects.
  *
  * @template D - Maximum nesting depth (default: 7)
  */
-type ToolArgsNode<D extends number = 7> = ZodString | ZodNumber | ZodBoolean | ZodNull | ZodLiteral<string | number | boolean | null> | ZodEnum<Readonly<Record<string, string>>> | (D extends 0 ? never : ZodOptional<ToolArgsNode<Dec<D>>>) | (D extends 0 ? never : ZodNullable<ToolArgsNode<Dec<D>>>) | (D extends 0 ? never : ZodDefault<ToolArgsNode<Dec<D>>>) | (D extends 0 ? never : ZodArray<ToolArgsNode<Dec<D>>>) | (D extends 0 ? never : ZodObject<Record<string, ToolArgsNode<Dec<D>>>>) | (D extends 0 ? never : ZodRecord<ZodString, ToolArgsNode<Dec<D>>>) | (D extends 0 ? never : ZodUnion<[
+type ToolArgsNode<D extends number = 7> = ZodString | ZodNumber | ZodBoolean | ZodNull | ZodLiteral<string | number | boolean | null> | ZodUnknown | ZodEnum<Readonly<Record<string, string>>> | (D extends 0 ? never : ZodOptional<ToolArgsNode<Dec<D>>>) | (D extends 0 ? never : ZodNullable<ToolArgsNode<Dec<D>>>) | (D extends 0 ? never : ZodDefault<ToolArgsNode<Dec<D>>>) | (D extends 0 ? never : ZodArray<ToolArgsNode<Dec<D>>>) | (D extends 0 ? never : ZodObject<Record<string, ToolArgsNode<Dec<D>>>>) | (D extends 0 ? never : ZodRecord<ZodString, ToolArgsNode<Dec<D>>>) | (D extends 0 ? never : ZodUnion<readonly [
     ToolArgsNode<Dec<D>>,
     ToolArgsNode<Dec<D>>,
     ...ToolArgsNode<Dec<D>>[]
@@ -1477,6 +1836,16 @@ interface ProviderModelInfo {
     iconId?: string;
     /** Optional slug for additional lookups (e.g., OpenRouter endpoint queries) */
     slug?: string;
+    /**
+     * Optional capability hints surfaced from the provider's listing
+     * payload. Populated when the provider can derive support flags
+     * (vision / tool calls / streaming / JSON mode) without an
+     * additional per-model probe — lets UIs render the capability
+     * matrix on every row in the picker. Omit when the provider
+     * doesn't expose enough metadata; consumers must tolerate
+     * undefined.
+     */
+    capabilities?: ModelCapabilities;
 }
 /**
  * Query params for provider-backed model discovery.
@@ -1546,7 +1915,11 @@ interface LLMProviderInterface {
     /**
      * Get tools embedded in this provider.
      * Optional - providers may implement this to expose built-in tools
-     * (e.g., OpenAI's web_search, file_search, code_interpreter).
+     * (e.g., OpenAI's web_search or xAI's x_search).
+     *
+     * Tool names are provider-defined capability names. Standard Agents defines
+     * discovery, selection, execution ownership, and result reporting; providers
+     * define their own native request mapping.
      *
      * These tools are defined using defineTool() with optional variable requirements.
      * Tools returned here can be referenced by name in model/prompt definitions.
@@ -1753,6 +2126,12 @@ interface ProviderToolCallPart {
     id: string;
     name: string;
     arguments: Record<string, unknown>;
+    /**
+     * Provider-specific metadata that must round-trip with the tool call.
+     * For example, Gemini tool calls can include a thought signature that must
+     * be echoed back on the next turn for tool calling to continue working.
+     */
+    extraContent?: Record<string, unknown>;
 }
 type ProviderToolResultContent = string | {
     type: 'text';
@@ -1767,6 +2146,14 @@ interface ProviderResponse {
     reasoningDetails?: ProviderReasoningDetail[];
     toolCalls?: ProviderToolCallPart[];
     images?: ProviderGeneratedImage[];
+    /**
+     * Provider-executed tool calls surfaced for logging and inspection.
+     *
+     * Providers should populate this when the upstream provider executed a
+     * built-in/native tool server-side. These entries are informational for
+     * Standard Agents and must not be re-executed locally.
+     */
+    providerTools?: ProviderExecutedToolResult[];
     finishReason: ProviderFinishReason;
     usage: ProviderUsage;
     metadata?: Record<string, unknown>;
@@ -1821,6 +2208,57 @@ interface ProviderWebSearchResult {
         }>;
     }>;
 }
+/**
+ * Provider-executed tool call surfaced for logging.
+ *
+ * Providers use this when the upstream model provider executes a native tool
+ * server-side and Standard Agents should record the call without attempting to
+ * execute it locally.
+ */
+interface ProviderExecutedToolResult {
+    /** Provider-facing tool name, such as "web_search" or "x_search" */
+    name: string;
+    /**
+     * Legacy alias for `name`, retained for persisted log compatibility.
+     * New provider implementations should set `name`; runtimes may mirror it
+     * into `type` when serializing logs for older UIs.
+     */
+    type?: string;
+    /** Provider that executed the tool, such as "openai" or "xai" */
+    provider?: string;
+    /** Unique ID of the provider tool call */
+    id: string;
+    /** Execution status */
+    status: 'completed' | 'failed' | 'in_progress';
+    /** Optional provider-specific result or argument summary */
+    result?: {
+        actions?: Array<{
+            type: string;
+            query?: string;
+            url?: string;
+            pattern?: string;
+            sources?: Array<{
+                type?: string;
+                url: string;
+                title?: string;
+            }>;
+        }>;
+        input?: Record<string, unknown>;
+        output?: string;
+        results?: unknown[];
+        artifacts?: Array<{
+            type: string;
+            id?: string;
+            mediaType?: string;
+            url?: string;
+            path?: string;
+            title?: string;
+            metadata?: Record<string, unknown>;
+        }>;
+    };
+    /** Provider-specific structured details that should stay JSON-serializable */
+    metadata?: Record<string, unknown>;
+}
 type ProviderStreamChunk = {
     type: 'content-delta';
     delta: string;
@@ -1835,6 +2273,7 @@ type ProviderStreamChunk = {
     type: 'tool-call-start';
     id: string;
     name: string;
+    extraContent?: Record<string, unknown>;
 } | {
     type: 'tool-call-delta';
     id: string;
@@ -1843,6 +2282,7 @@ type ProviderStreamChunk = {
     type: 'tool-call-done';
     id: string;
     arguments: Record<string, unknown>;
+    extraContent?: Record<string, unknown>;
 } | {
     type: 'image-delta';
     index: number;
@@ -1854,6 +2294,9 @@ type ProviderStreamChunk = {
 } | {
     type: 'web-search-done';
     result: ProviderWebSearchResult;
+} | {
+    type: 'provider-tool-done';
+    tool: ProviderExecutedToolResult;
 } | {
     type: 'finish';
     finishReason: ProviderFinishReason;
@@ -1916,7 +2359,7 @@ interface ProviderInstance {
     getModelsPage?(query?: ProviderModelsQuery): Promise<ProviderModelsPage>;
     /** Fetch capabilities for a specific model */
     getModelCapabilities?(modelId: string): Promise<ModelCapabilities | null>;
-    /** Get provider-specific tools available for a model */
+    /** Get provider-defined built-in tools available for a model */
     getTools?(modelId?: string): Record<string, ToolDefinition<unknown, ToolArgs | null, ToolTenvs | null>> | Promise<Record<string, ToolDefinition<unknown, ToolArgs | null, ToolTenvs | null>>>;
     /** Get the icon URL for this provider or a specific model */
     getIcon?(modelId?: string): string | undefined;
@@ -2190,9 +2633,10 @@ interface ModelDefinition<N extends string = string, P extends ProviderFactoryWi
      * Provider tools available for this model.
      * References tool names from provider.getTools().
      *
-     * Provider tools are built-in tools offered by the provider (e.g., OpenAI's
-     * web_search, file_search, code_interpreter, image_generation). These tools
-     * can be used in prompts alongside custom tools.
+     * Provider tools are built-in tools offered by the provider. Tool names are
+     * provider-defined capability names, not Standard Agents global names. These
+     * tools can be used in prompts alongside custom tools and are executed by
+     * the upstream provider.
      *
      * @example
      * ```typescript
@@ -2432,7 +2876,9 @@ interface PromptToolConfig {
  * Non-resumable subagents behave like normal tool calls.
  * Resumable subagents are created/messaged through runtime-injected lifecycle
  * tools (for example `subagent_create` and `subagent_message`) and tracked in
- * the parent thread registry.
+ * the parent thread registry. The injected `subagent_create` tool MUST require
+ * a non-empty human-readable `name` argument and runtimes SHOULD persist it as
+ * a child thread display name.
  *
  * @example
  * ```typescript
@@ -2816,12 +3262,16 @@ declare function definePrompt<N extends string, S extends ToolArgs = never>(opti
  *
  * @example
  * ```typescript
- * const hook = defineHook('filter_messages', async (state, messages) => {
- *   console.log(`Thread: ${state.threadId}`);
- *   if (state.execution) {
- *     console.log(`Turn: ${state.execution.turnCount}`);
- *   }
- *   return messages.slice(-10);
+ * const hook = defineHook({
+ *   hook: 'filter_messages',
+ *   id: 'keep_recent',
+ *   execute: async (state, messages) => {
+ *     console.log(`Thread: ${state.threadId}`);
+ *     if (state.execution) {
+ *       console.log(`Step: ${state.execution.stepCount}`);
+ *     }
+ *     return messages.slice(-10);
+ *   },
  * });
  * ```
  */
@@ -2908,6 +3358,38 @@ interface LLMMessage {
  * @template ToolResult - The tool result type (defaults to HookToolResult)
  */
 interface HookSignatures<State = ThreadState, Msg = HookMessage, ToolCall = HookToolCall, ToolResult = HookToolResult> {
+    /**
+     * Called after a thread is created, before initial message processing or LLM
+     * requests for that thread.
+     *
+     * Only ThreadState is passed. Use for initializing durable thread values,
+     * env placeholders, files, or side-effect instrumentation.
+     *
+     * @param state - Created thread state
+     */
+    after_thread_created: (state: State) => Promise<void>;
+    /**
+     * Called on the parent thread immediately after a subagent child thread is
+     * created.
+     *
+     * Receives parent ThreadState and child ThreadState. Use for copying or
+     * linking metadata, bookkeeping, or side-effect instrumentation.
+     *
+     * @param state - Parent thread state
+     * @param childState - Created child thread state
+     */
+    after_subagent_created: (state: State, childState: State) => Promise<void>;
+    /**
+     * Called after the prompt system message is rendered for a model request.
+     *
+     * Return a string to replace the rendered system message. Return null or
+     * undefined to keep the original message.
+     *
+     * @param state - Thread state
+     * @param systemMessage - Rendered system message for this request
+     * @returns Replacement system message, or null/undefined for no change
+     */
+    after_system_message: (state: State, systemMessage: string) => string | Promise<string | null | undefined> | null | undefined;
     /**
      * Called before messages are filtered and sent to the LLM.
      *
@@ -2920,9 +3402,10 @@ interface HookSignatures<State = ThreadState, Msg = HookMessage, ToolCall = Hook
      *
      * @example
      * ```typescript
-     * defineHook('filter_messages', async (state, messages) => {
-     *   // Only include messages from last 10 turns
-     *   return messages.slice(-10);
+     * defineHook({
+     *   hook: 'filter_messages',
+     *   id: 'limit_to_10',
+     *   execute: async (state, messages) => messages.slice(-10),
      * });
      * ```
      */
@@ -2939,9 +3422,10 @@ interface HookSignatures<State = ThreadState, Msg = HookMessage, ToolCall = Hook
      *
      * @example
      * ```typescript
-     * defineHook('prefilter_llm_history', async (state, messages) => {
-     *   // Add a reminder to the last user message
-     *   return messages;
+     * defineHook({
+     *   hook: 'prefilter_llm_history',
+     *   id: 'add_reminder',
+     *   execute: async (state, messages) => messages,
      * });
      * ```
      */
@@ -3006,8 +3490,13 @@ interface HookSignatures<State = ThreadState, Msg = HookMessage, ToolCall = Hook
      *
      * @example
      * ```typescript
-     * defineHook('before_update_message', async (state, messageId, updates) => {
-     *   return { ...updates, updated_at: Date.now() };
+     * defineHook({
+     *   hook: 'before_update_message',
+     *   id: 'stamp_updated_at',
+     *   execute: async (state, messageId, updates) => ({
+     *     ...updates,
+     *     updated_at: Date.now(),
+     *   }),
      * });
      * ```
      */
@@ -3023,8 +3512,12 @@ interface HookSignatures<State = ThreadState, Msg = HookMessage, ToolCall = Hook
      *
      * @example
      * ```typescript
-     * defineHook('after_update_message', async (state, message) => {
-     *   console.log(`Message updated: ${message.id}`);
+     * defineHook({
+     *   hook: 'after_update_message',
+     *   id: 'log_update',
+     *   execute: async (state, message) => {
+     *     console.log(`Message updated: ${message.id}`);
+     *   },
      * });
      * ```
      */
@@ -3071,9 +3564,13 @@ interface HookSignatures<State = ThreadState, Msg = HookMessage, ToolCall = Hook
      *
      * @example
      * ```typescript
-     * defineHook('after_tool_call_success', async (state, toolCall, toolResult) => {
-     *   console.log(`Tool ${toolCall.function.name} succeeded`);
-     *   return null; // Use original result
+     * defineHook({
+     *   hook: 'after_tool_call_success',
+     *   id: 'log_success',
+     *   execute: async (state, toolCall, toolResult) => {
+     *     console.log(`Tool ${toolCall.function.name} succeeded`);
+     *     return null; // use original result
+     *   },
      * });
      * ```
      */
@@ -3092,9 +3589,13 @@ interface HookSignatures<State = ThreadState, Msg = HookMessage, ToolCall = Hook
      *
      * @example
      * ```typescript
-     * defineHook('after_tool_call_failure', async (state, toolCall, toolResult) => {
-     *   console.error(`Tool ${toolCall.function.name} failed: ${toolResult.error}`);
-     *   return null; // Use original error
+     * defineHook({
+     *   hook: 'after_tool_call_failure',
+     *   id: 'log_failure',
+     *   execute: async (state, toolCall, toolResult) => {
+     *     console.error(`Tool ${toolCall.function.name} failed: ${toolResult.error}`);
+     *     return null; // use original error
+     *   },
      * });
      * ```
      */
@@ -3602,8 +4103,9 @@ type VirtualModuleRegistry<T> = Record<string, VirtualModuleLoader<T>>;
  * and optionally the virtual module registries injected at runtime.
  *
  * Note: The `env` property contains implementation-specific bindings.
- * Cloudflare implementations may include Durable Object namespaces,
- * KV namespaces, etc. Other implementations may provide different bindings.
+ * Its shape is defined by the runtime — typical surfaces include handles
+ * to storage, queues, key-value stores, or other platform resources the
+ * runtime chooses to expose.
  */
 interface ControllerContext {
     /** The incoming HTTP request */
@@ -3615,7 +4117,8 @@ interface ControllerContext {
     /**
      * Environment bindings (implementation-specific).
      *
-     * Contains platform-specific bindings like Durable Objects, KV, etc.
+     * Contains platform-specific bindings — handles to storage,
+     * queues, key-value stores, or other resources the runtime exposes.
      * The exact contents depend on the runtime implementation.
      */
     env: Record<string, unknown>;
@@ -3663,9 +4166,19 @@ type Controller = (context: ControllerContext) => ControllerReturn;
  * Thread endpoint handler function.
  *
  * Receives the HTTP request and the ThreadState for the requested thread.
- * The thread is automatically looked up by ID from URL parameters.
+ * The supplied ThreadState includes the standard thread surface, including
+ * `runCode`. The thread is automatically looked up by ID from URL parameters. Route
+ * parameters are derived from the endpoint file path. For a dynamic segment
+ * such as `[id].ts`, `params.id` contains the matched segment. For a catch-all
+ * segment `[*].ts`, `params['*']` contains the unmatched path suffix,
+ * including `/` separators when the match spans multiple segments.
+ *
+ * Thread endpoint routes are scoped beneath the runtime's thread ID prefix.
+ * A request under that prefix that does not match any local or packed thread
+ * endpoint route MUST return HTTP 404.
  */
-type ThreadEndpointHandler = (req: Request, state: ThreadState) => Response | Promise<Response>;
+type ThreadEndpointRouteParams = Record<string, string>;
+type ThreadEndpointHandler = (req: Request, state: ThreadState, params: ThreadEndpointRouteParams) => Response | Promise<Response>;
 /**
  * Define a standard HTTP controller.
  *
@@ -3704,12 +4217,15 @@ declare function defineController(controller: Controller): Controller;
  * ThreadState with messages, logs, resource loading, event emission,
  * and (when executing) execution state.
  *
- * @param handler - The handler function receiving request and ThreadState
+ * Runtimes MUST return HTTP 404 for requests beneath the thread endpoint
+ * prefix that do not match any local or packed thread endpoint route.
+ *
+ * @param handler - The handler function receiving request, ThreadState, and route params
  * @returns A Controller that can be used with the router
  *
  * @example
  * ```typescript
- * // agents/api/threads/[id]/status.get.ts
+ * // agents/api/status.ts
  * import { defineThreadEndpoint } from '@standardagents/spec';
  *
  * export default defineThreadEndpoint(async (req, state) => {
@@ -3724,7 +4240,7 @@ declare function defineController(controller: Controller): Controller;
  *
  * @example
  * ```typescript
- * // agents/api/threads/[id]/export.get.ts
+ * // agents/api/export.ts
  * import { defineThreadEndpoint } from '@standardagents/spec';
  *
  * export default defineThreadEndpoint(async (req, state) => {
@@ -3743,7 +4259,7 @@ declare function defineController(controller: Controller): Controller;
  *
  * @example
  * ```typescript
- * // agents/api/threads/[id]/invoke.post.ts
+ * // agents/api/invoke.post.ts
  * import { defineThreadEndpoint } from '@standardagents/spec';
  *
  * export default defineThreadEndpoint(async (req, state) => {
@@ -3755,6 +4271,17 @@ declare function defineController(controller: Controller): Controller;
  *   return Response.json({ queued: true });
  * });
  * ```
+ *
+ * @example
+ * ```typescript
+ * // agents/api/files/[id].ts
+ * import { defineThreadEndpoint } from '@standardagents/spec';
+ *
+ * export default defineThreadEndpoint(async (req, state, params) => {
+ *   const file = await state.readFile(`/files/${params.id}.json`);
+ *   return Response.json({ exists: !!file });
+ * });
+ * ```
  */
 declare function defineThreadEndpoint(handler: ThreadEndpointHandler): MarkedThreadEndpoint;
 
@@ -3952,8 +4479,10 @@ interface PackedExports {
     /**
      * Thread endpoint handlers, keyed by packed route key (for example, `status.get`).
      *
-     * Runtimes typically mount these under a package namespace (for example:
-     * `/api/packages/:packageId/threads/:id/...`) to avoid collisions.
+     * Runtimes mount these beneath the same thread ID prefix as local thread
+     * endpoints, using the packed route key to derive the endpoint path.
+     * Requests beneath that prefix that do not match any local or packed thread
+     * endpoint route MUST return HTTP 404.
      *
      * Optional for backward compatibility with previously packed packages.
      */
@@ -3962,4 +4491,4 @@ interface PackedExports {
     __meta: PackedMeta;
 }
 
-export { type AgentDefinition, type AgentType, type AttachmentRef, type ContentPart, type Controller, type ControllerContext, type ControllerReturn, type DefineToolOptions, type DefinitionLoader, type Effect, type EffectDefinition, type EmptyUsesState, type ExecutionState, type FileChunk, type FilePart, type FileRecord, type FileStats, type FileStorage, type FindResult, type GetMessagesOptions, type GlobalNamespaceContext, type GrepResult, type HookContext, type HookDefinition, type HookDefinitionOptions, type HookDefinitionResult, type HookMessage, type HookName, type HookSignatures, type HookToolCall, type HookToolResult, type ImageContent, type ImagePart, type ImageUrlPart, type InferProviderOptions, type InjectMessageInput, type InspectedRequest, type LLMMessage, type LLMProviderInterface, type MarkedThreadEndpoint, type Message, type MessageUpdates, type MessagesResult, type ModelCapabilities, type ModelDefinition, type ModelProvider, type NamespaceContext, type PackageSignature, type PackedExports, type PackedMeta, type PackedMetadata, type PackedNamespaceContext, type PromptContent, type PromptDefinition, type PromptEnvPart, type PromptIncludePart, type PromptInput, type PromptPart, type PromptTextPart, type PromptToolConfig, type ProviderAssistantMessage, type ProviderAttachment, ProviderError, type ProviderErrorCode, type ProviderFactory, type ProviderFactoryConfig, type ProviderFactoryWithOptions, type ProviderFinishReason, type ProviderGeneratedImage, type ProviderInstance, type ProviderMessage, type ProviderMessageContent, type ProviderModelInfo, type ProviderModelsPage, type ProviderModelsQuery, type ProviderReasoningDetail, type ProviderRequest, type ProviderResponse, type ProviderStreamChunk, type ProviderSystemMessage, type ProviderTool, type ProviderToolCallPart, type ProviderToolMessage, type ProviderToolResultContent, type ProviderUsage, type ProviderUserMessage, type ProviderWebSearchResult, type QueueMessageInput, type ReadFileStreamOptions, type ReaddirResult, type ReasoningConfig, type ResolveUsesState, type ResponseSummary, type ScheduledEffect, type SessionToolBinding, type SessionToolConfig, type SideConfig, type StructuredPrompt, type SubagentRegistryEntry, type SubagentToolConfig, type SubpromptConfig, THREAD_ENDPOINT_SYMBOL, type TenvRawShape, type TextContent, type TextPart, type ThreadEndpointHandler, type ThreadMetadata, type ThreadState, type Tool, type ToolArgs, type ToolArgsNode, type ToolArgsRawShape, type ToolAttachment, type ToolConfig, type ToolContent, type ToolDefinition, type ToolResult, type ToolTenvs, type ToolVariables, type UsesAwareExecute, type UsesConstrainedState, type VariableDefinition, type VariableType, type VirtualModuleLoader, type VirtualModuleRegistry, type WriteFileOptions, belongsToPackage, defineAgent, defineController, defineEffect, defineHook, defineModel, definePrompt, defineThreadEndpoint, defineTool, isPacked, isThreadEndpoint, isVisibleInNamespace, mapReasoningLevel, validateToolName };
+export { type AgentDefinition, type AgentType, type AttachmentRef, type CodeExecution, type CodeExecutionError, type CodeExecutionLog, type CodeExecutionOptions, type CodeExecutionResult, type CodeExecutionStatus, type ContentPart, type Controller, type ControllerContext, type ControllerReturn, type DefineToolOptions, type DefinitionLoader, type Effect, type EffectDefinition, type EmptyUsesState, type EnvValueType, type ExecutionState, type FileChunk, type FilePart, type FileRecord, type FileStats, type FileStorage, type FindResult, type GetMessagesOptions, type GlobalNamespaceContext, type GrepResult, type HookContext, type HookDefinition, type HookDefinitionOptions, type HookDefinitionResult, type HookMessage, type HookName, type HookSignatures, type HookToolCall, type HookToolResult, type ImageContent, type ImagePart, type ImageUrlPart, type InferProviderOptions, type InjectMessageInput, type InspectedRequest, type LLMMessage, type LLMProviderInterface, type MarkedThreadEndpoint, type Message, type MessageUpdates, type MessagesResult, type ModelCapabilities, type ModelDefinition, type ModelProvider, type NamespaceContext, type PackageSignature, type PackedExports, type PackedMeta, type PackedMetadata, type PackedNamespaceContext, type PromptContent, type PromptDefinition, type PromptEnvPart, type PromptIncludePart, type PromptInput, type PromptPart, type PromptTextPart, type PromptToolConfig, type ProviderAssistantMessage, type ProviderAttachment, ProviderError, type ProviderErrorCode, type ProviderExecutedToolResult, type ProviderFactory, type ProviderFactoryConfig, type ProviderFactoryWithOptions, type ProviderFinishReason, type ProviderGeneratedImage, type ProviderInstance, type ProviderMessage, type ProviderMessageContent, type ProviderModelInfo, type ProviderModelsPage, type ProviderModelsQuery, type ProviderReasoningDetail, type ProviderRequest, type ProviderResponse, type ProviderStreamChunk, type ProviderSystemMessage, type ProviderTool, type ProviderToolCallPart, type ProviderToolMessage, type ProviderToolResultContent, type ProviderUsage, type ProviderUserMessage, type ProviderWebSearchResult, type QueueMessageInput, type ReadFileStreamOptions, type ReaddirResult, type ReasoningConfig, type ResolveUsesState, type ResponseSummary, type ScheduledEffect, type SessionToolBinding, type SessionToolConfig, type SetEnvOptions, type SideConfig, type StructuredPrompt, type SubagentRegistryEntry, type SubagentToolConfig, type SubpromptConfig, THREAD_ENDPOINT_SYMBOL, type TenvRawShape, type TextContent, type TextPart, type ThreadEndpointHandler, type ThreadEndpointRouteParams, type ThreadMetadata, type ThreadState, type Tool, type ToolArgs, type ToolArgsNode, type ToolArgsRawShape, type ToolAttachment, type ToolConfig, type ToolContent, type ToolDefinition, type ToolResult, type ToolTenvs, type ToolVariables, type UsesAwareExecute, type UsesConstrainedState, type VariableDefinition, type VariableType, type VirtualModuleLoader, type VirtualModuleRegistry, type WriteFileOptions, belongsToPackage, defineAgent, defineController, defineEffect, defineHook, defineModel, definePrompt, defineThreadEndpoint, defineTool, isPacked, isThreadEndpoint, isVisibleInNamespace, mapReasoningLevel, validateToolName };