@standardagents/spec 0.27.13 → 0.28.0

package/dist/index.d.ts

@@ -121,2073 +121,2024 @@ declare global {
 }
 
 /**
- * Effect definition types for Standard Agents.
- *
- * Effects are scheduled operations that run outside the tool execution context.
- * They enable implementation-specific side effects with optional delay support,
- * leveraging whichever scheduling mechanism the runtime provides.
+ * Tool definition types for Standard Agents.
  *
- * Unlike tools, effects:
- * - Do not return results to the LLM
- * - Can be delayed for future execution
- * - Run independently of the conversation flow
- * - Are ideal for notifications, cleanup, and async operations
+ * Tools are callable functions that agents can invoke during execution.
+ * They receive the current ThreadState and validated arguments,
+ * and return results that are included in the conversation.
  *
  * @module
  */
 
 /**
- * Effect function signature.
- *
- * Effects are async functions that receive a ThreadState and
- * optionally validated arguments. Unlike tools, they return void
- * since results are not included in the conversation.
- *
- * @template State - The state type (defaults to ThreadState)
- * @template Args - The Zod schema for effect arguments, or null for no args
- */
-type Effect<State = ThreadState, Args extends ToolArgs | null = null> = Args extends ToolArgs ? (state: State, args: z.infer<Args>) => Promise<void> | void : (state: State) => Promise<void> | void;
-/**
- * Return type of defineEffect function.
- *
- * A tuple containing:
- * - Effect description string
- * - Argument schema (or null)
- * - Effect implementation function
- */
-type EffectDefinition<State = ThreadState, Args extends ToolArgs | null = null> = [string, Args, Effect<State, Args>];
-/**
- * Record of a scheduled effect.
- *
- * Returned by getScheduledEffects() to inspect pending effects.
+ * Text content item returned by tools.
  */
-interface ScheduledEffect {
-    /** Unique identifier for this scheduled effect. */
-    id: string;
-    /** Name of the effect to execute. */
-    name: string;
-    /** Arguments to pass to the effect handler. */
-    args: Record<string, unknown>;
-    /** When the effect is scheduled to run (microseconds since epoch). */
-    scheduledAt: number;
-    /** When the effect was created (microseconds since epoch). */
-    createdAt: number;
+interface TextContent {
+    type: 'text';
+    text: string;
 }
 /**
- * Define an effect with arguments.
- *
- * @param description - Description of what the effect does
- * @param args - Zod schema for validating effect arguments
- * @param handler - The effect implementation function
- * @returns A tuple containing the effect definition
+ * Image content item returned by tools.
  */
-declare function defineEffect<State = ThreadState, Args extends ToolArgs = ToolArgs>(description: string, args: Args, handler: Effect<State, Args>): EffectDefinition<State, Args>;
+interface ImageContent {
+    type: 'image';
+    /** Base64-encoded image data. */
+    data: string;
+    /** MIME type of the image (e.g., 'image/png', 'image/jpeg'). */
+    mimeType: string;
+}
 /**
- * Define an effect without arguments.
- *
- * @param description - Description of what the effect does
- * @param handler - The effect implementation function
- * @returns A tuple containing the effect definition
+ * Content types that can be returned by tools.
  */
-declare function defineEffect<State = ThreadState>(description: string, handler: Effect<State, null>): EffectDefinition<State, null>;
-
+type ToolContent = TextContent | ImageContent;
 /**
- * Agent Skills — instance-global skill store types.
- *
- * Skills follow the Agent Skills standard (https://agentskills.io): a folder
- * whose root SKILL.md opens with YAML frontmatter carrying a required `name`
- * (lowercase kebab, ≤64 chars) and `description` (≤1024 chars), optionally
- * accompanied by scripts, references, and assets.
+ * File attachment generated by a tool.
  *
- * Runtimes store skills server-side as a GLOBAL, instance-wide library:
- * installed once, visible to every thread, nothing persisted on a client
- * machine. Progressive disclosure is the contract — agents see only each
- * skill's name + description until a skill is judged applicable, at which
- * point they load its SKILL.md body (and, when needed, read or execute its
- * bundled files).
+ * Attachments are stored in the thread's file system and linked to
+ * the tool result message. Unlike user uploads, tool attachments are
+ * not subject to image downsampling.
  */
-/** Registry view of an installed skill (metadata only — no file contents). */
-interface SkillMetadata {
-    /** Kebab-case identifier from SKILL.md frontmatter. */
+interface ToolAttachment {
+    /** File name for the attachment. */
     name: string;
-    /** What the skill does and when to use it (from frontmatter). */
-    description: string;
-    /** Optional version string from frontmatter. */
-    version?: string;
-    /** Disabled skills stay installed but are hidden from agents. */
-    enabled: boolean;
-    /** Relative paths of the skill's files (always includes SKILL.md). */
-    files: string[];
-    /** Unix seconds of the last install/update. */
-    updatedAt?: number;
+    /** MIME type of the attachment. */
+    mimeType: string;
+    /** Base64-encoded file data. */
+    data: string;
+    /** Width in pixels (for images). */
+    width?: number;
+    /** Height in pixels (for images). */
+    height?: number;
 }
-/** A file being installed into a skill (relative path + full text). */
-interface SkillFileInput {
+/**
+ * Reference to a pre-existing attachment in the thread file system.
+ */
+interface AttachmentRef {
+    /** Unique identifier for the attachment. */
+    id: string;
+    /** Attachment type. */
+    type: 'file';
+    /** Path in the thread file system. */
     path: string;
-    content: string;
+    /** File name. */
+    name: string;
+    /** MIME type. */
+    mimeType: string;
+    /** File size in bytes. */
+    size: number;
+    /** Width in pixels (for images). */
+    width?: number;
+    /** Height in pixels (for images). */
+    height?: number;
+    /** AI-generated description. */
+    description?: string;
 }
 /**
- * ThreadState surface for the global skill library. All operations hit the
- * instance-wide store — there is no per-thread skill state beyond what a
- * thread chooses to keep in its own key-value store.
+ * Result returned by a tool execution.
  */
-interface SkillsNamespace {
-    /** Installed skills (enabled only, unless includeDisabled). */
-    list(options?: {
-        includeDisabled?: boolean;
-    }): Promise<SkillMetadata[]>;
-    /** A skill's metadata plus its SKILL.md source (null when not installed). */
-    get(name: string): Promise<{
-        metadata: SkillMetadata;
-        skillMd: string;
-    } | null>;
-    /** Read one bundled file's text (null when the skill or file is missing). */
-    readFile(name: string, path: string): Promise<string | null>;
+interface ToolResult {
+    /** Status of the tool execution. */
+    status: 'success' | 'error';
     /**
-     * Install (or replace) a skill from its file set. The file set must include
-     * a root SKILL.md with valid frontmatter; the skill's identity comes from
-     * that frontmatter, never from a caller-supplied name.
+     * Text representation of the tool output.
+     *
+     * For tools that return structured content, this is derived by
+     * concatenating all text parts. For simple tools, this is the
+     * direct result string.
      */
-    install(files: SkillFileInput[]): Promise<SkillMetadata>;
-    /** Enable/disable an installed skill. Returns false when not installed. */
-    setEnabled(name: string, enabled: boolean): Promise<boolean>;
-    /** Uninstall a skill entirely. Returns false when not installed. */
-    remove(name: string): Promise<boolean>;
+    result?: string;
+    /** Error message if status is 'error'. */
+    error?: string;
+    /**
+     * Machine-readable error code for structured handling.
+     *
+     * Example: `subagent_env_required` indicates the client must provide
+     * scoped subagent env values before execution can continue.
+     */
+    error_code?: string;
+    /**
+     * Structured error payload for machine handling.
+     *
+     * Implementations should keep this JSON-serializable.
+     */
+    error_data?: Record<string, unknown>;
+    /** Stack trace for error debugging. */
+    stack?: string;
+    /**
+     * File attachments returned by the tool.
+     *
+     * Can contain either:
+     * - ToolAttachment: New files with base64 data to be stored
+     * - AttachmentRef: References to existing files in the thread filesystem
+     *
+     * Implementations MUST store new attachments under /attachments/ directory.
+     */
+    attachments?: Array<ToolAttachment | AttachmentRef>;
 }
-
+/** Decrement helper to limit recursion depth. */
+type Dec<N extends number> = N extends 10 ? 9 : N extends 9 ? 8 : N extends 8 ? 7 : N extends 7 ? 6 : N extends 6 ? 5 : N extends 5 ? 4 : N extends 4 ? 3 : N extends 3 ? 2 : N extends 2 ? 1 : N extends 1 ? 0 : 0;
 /**
- * Thread state types for Standard Agents.
+ * Allowed Zod types for tool argument nodes.
  *
- * ThreadState is the unified interface for all thread operations.
- * It provides access to thread identity, messages, logs, resource loading,
- * tool invocation, event emission, and execution state.
+ * 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.
  *
- * @module
+ * @template D - Maximum nesting depth (default: 7)
  */
-
+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>>[]
+]>);
 /**
- * Metadata about a thread.
+ * Raw shape for a Zod object schema containing tool argument nodes.
  *
- * This represents the core identity of a thread, separate from its
- * operational state. Thread metadata is immutable after creation.
+ * @template D - Maximum nesting depth (default: 7)
  */
+type ToolArgsRawShape<D extends number = 7> = Record<string, ToolArgsNode<D>>;
 /**
- * The profile of the user a thread belongs to, as exposed by
- * {@link ThreadState.user}. Identity fields only — never credentials.
+ * Top-level tool argument schema.
+ *
+ * Tool arguments MUST be defined as a Zod object schema.
+ * This is required for compatibility with OpenAI's function calling API.
+ *
+ * @template D - Maximum nesting depth (default: 7)
  */
-interface ThreadUser {
-    id: string;
-    username: string;
-    /** 'admin' | 'user' | 'api' in the reference runtime. */
-    role: string;
-    /** Explicit permission grants (runtime-defined strings), if any. */
-    permissions?: string[] | null;
-    email?: string | null;
-    display_name?: string | null;
-    avatar_url?: string | null;
-}
-interface ThreadMetadata {
-    /** Unique identifier for the thread */
-    id: string;
-    /** Agent that owns this thread */
-    agent_id: string;
-    /** User associated with this thread (if any) */
-    user_id: string | null;
-    /** Creation timestamp (microseconds since epoch) */
-    created_at: number;
-}
+type ToolArgs<D extends number = 7> = z.ZodObject<ToolArgsRawShape<D>>;
 /**
- * Registry entry for a subagent child thread.
- */
-interface SubagentRegistryEntry {
-    /** Child thread UUID used as stable reference address */
-    reference: string;
-    /** Child agent name */
-    name: string;
-    /** Child agent title (human-readable) */
-    title?: string;
-    /** Tool description shown to the parent LLM */
-    description: string;
-    /** Whether this subagent instance is resumable */
-    resumable?: boolean;
-    /** Whether parent execution blocks on this subagent */
-    blocking?: boolean;
-    /** Optional human-readable thread name (for example from `name:` tag) */
-    threadName?: string;
-    /**
-     * Initial argument values supplied when the child was created.
-     *
-     * For resumable subagents, these values persist for the lifetime of the
-     * child thread and are visible to both child sides. Runtimes SHOULD source
-     * this object from the receiving side's prompt argument schema. The registry
-     * copy is parent-visible metadata; the durable child-side source SHOULD live
-     * with the child thread metadata/properties and be restored into
-     * `ThreadState.arguments` during execution and endpoint access. Top-level
-     * keys SHOULD also be exposed to prompt variable interpolation for whichever
-     * child side is currently rendering.
-     */
-    initialArguments?: Record<string, unknown>;
-    /** Spawn group identifier used for grouping instances created together */
-    spawnGroupId?: string;
-    /** Instance creation timestamp (microseconds) */
-    createdAt?: number;
-    /** Current status (`running`, `idle`, `terminated`, or custom text) */
-    status: string;
-    /** How this child reports information back to its parent thread */
-    parentCommunication?: 'implicit' | 'explicit';
-}
-/**
- * Options for retrieving messages.
- */
-interface GetMessagesOptions {
-    /** Maximum number of messages to return */
-    limit?: number;
-    /** Number of messages to skip */
-    offset?: number;
-    /** Sort order ('asc' for oldest first, 'desc' for newest first) */
-    order?: 'asc' | 'desc';
-    /** Include silent messages (not shown in UI) */
-    includeSilent?: boolean;
-    /** Maximum nesting depth for sub-prompt messages */
-    maxDepth?: number;
-}
-/**
- * Result of a message query.
+ * Variable declaration type.
+ *
+ * - `text`: Plain string configuration value
+ * - `secret`: Sensitive value that should be encrypted at rest
  */
-interface MessagesResult {
-    /** Array of messages */
-    messages: Message[];
-    /** Total number of messages matching the query */
-    total: number;
-    /** Whether there are more messages available */
-    hasMore: boolean;
-}
+type VariableType = 'text' | 'secret';
 /**
- * A message in the thread conversation.
+ * Declares a variable required or optionally consumed by a tool or prompt.
  */
-interface Message {
-    /** Unique message identifier */
-    id: string;
-    /** Message role */
-    role: 'system' | 'user' | 'assistant' | 'tool';
-    /** Message content (null for tool calls without text) */
-    content: string | null;
-    /** Tool name (for tool result messages) */
-    name?: string | null;
-    /** JSON-encoded array of tool calls (for assistant messages) */
-    tool_calls?: string | null;
-    /** Tool call ID (for tool result messages) */
-    tool_call_id?: string | null;
-    /** Creation timestamp (microseconds since epoch) */
-    created_at: number;
-    /** Parent message ID (for sub-prompt messages) */
-    parent_id?: string | null;
-    /** Nesting depth (0 for top-level messages) */
-    depth?: number;
-    /** Whether this message is silent (not shown in UI) */
-    silent?: boolean;
+interface VariableDefinition {
+    /** Environment variable/property name */
+    name: string;
+    /** Value type */
+    type: VariableType;
+    /** Whether this variable is required to execute */
+    required: boolean;
     /**
-     * Custom metadata.
+     * Whether this variable is scoped to the declarer subtree.
      *
-     * Runtimes may attach lifecycle metadata for synthesized status messages
-     * (for example: `status_kind`, `subagent_event`). Message APIs may also
-     * mark send-message and durable queue entries with `queued: true` until
-     * they are injected into stored history.
+     * Scoped variables do not inherit parent thread env values. Descendants of
+     * the declarer still inherit scoped values from that declarer thread.
+     *
+     * @default false
      */
-    metadata?: Record<string, unknown>;
-    /** Message processing status */
-    status?: 'pending' | 'completed' | 'failed' | null;
-    /** Tool execution status (for tool result messages) */
-    tool_status?: 'success' | 'error' | null;
-    /** Subagent reference UUID associated with this message */
-    subagent_id?: string | null;
-    /** Subagent agent name projected from runtime registry (when available) */
-    subagent_name?: string | null;
-    /** Subagent agent title projected from runtime registry (when available) */
-    subagent_title?: string | null;
-    /** Subagent description projected from runtime registry (when available) */
-    subagent_description?: string | null;
-    /** Subagent status projected from runtime registry (when available) */
-    subagent_status?: string | null;
-    /** Whether the associated subagent is resumable (when available) */
-    subagent_resumable?: boolean | null;
-    /** Whether the associated subagent is blocking (when available) */
-    subagent_blocking?: boolean | null;
-    /** Optional subagent instance thread name (when available) */
-    subagent_thread_name?: string | null;
-    /** Spawn group identifier for related subagent instances (when available) */
-    subagent_spawn_group_id?: string | null;
-}
-/**
- * Input for injecting a new message.
- */
-interface InjectMessageInput {
-    /** Message role */
-    role: 'user' | 'assistant' | 'system';
-    /** Message content */
-    content: string;
-    /** Whether to hide from UI */
-    silent?: boolean;
-    /** Custom metadata */
-    metadata?: Record<string, unknown>;
+    scoped?: boolean;
+    /** Human-readable description (empty string when not provided) */
+    description: string;
 }
 /**
- * Input for queueing a message for delivery on the thread's next step.
+ * Legacy raw shape for `tenvs` schema - uses same pattern as ToolArgsRawShape.
+ * Each key is an environment variable name and each value is a Zod schema.
  *
- * Role mapping follows dual_ai conventions:
- * - `assistant` maps to side_a
- * - `user` maps to side_b
+ * @template D - Maximum nesting depth (default: 7)
  */
-interface QueueMessageInput {
-    /** Message role (`user` queues side_b perspective, `assistant` queues side_a perspective) */
-    role: 'user' | 'assistant';
-    /** Message content */
-    content: string;
-    /** Optional file attachments (new files or existing refs) */
-    attachments?: Array<ToolAttachment | AttachmentRef>;
-    /** Whether to hide the queued message from normal UI display */
-    silent?: boolean;
-    /** Optional structured metadata */
-    metadata?: Record<string, unknown>;
-}
+type TenvRawShape<D extends number = 7> = Record<string, ToolArgsNode<D>>;
 /**
- * Updates to apply to an existing message.
+ * Top-level thread environment variable schema.
+ *
+ * Defines which thread environment variables a tool requires.
+ * Required values are non-optional fields, optional values use `.optional()`.
+ *
+ * @example
+ * ```typescript
+ * z.object({
+ *   VECTOR_STORE_ID: z.string().describe('OpenAI Vector Store ID'),  // Required
+ *   USER_LOCATION: z.string().optional().describe('User location'),   // Optional
+ * })
+ * ```
+ *
+ * @template D - Maximum nesting depth (default: 7)
  */
-interface MessageUpdates {
-    /** New content */
-    content?: string;
-    /** Updated metadata (merged with existing) */
-    metadata?: Record<string, unknown>;
-}
+type ToolTenvs<D extends number = 7> = z.ZodObject<TenvRawShape<D>>;
 /**
- * A streamed fragment of an assistant message's *visible content*.
- *
- * Always broadcast (no opt-in). Clients accumulate `chunk`s by `message_id` to
- * render the answer as it generates; the authoritative final content still
- * arrives separately as a persisted message. Clients must not discard an
- * already-painted draft solely because a retry/reconnect exposes another id:
- * retain keyed drafts or treat the id as a reconciliation alias until the
- * terminal message record atomically supersedes it.
+ * @deprecated Use VariableDefinition[] via the `variables` property instead.
  */
-interface ThreadMessageChunkEvent {
-    type: 'message_chunk';
-    /** The assistant message these fragments belong to. */
-    message_id: string;
-    /** Message depth: 0 = top-level thread, 1+ = subagent. */
-    depth: number;
-    /** The next fragment of visible content. */
-    chunk: string;
-}
+type ToolVariables = VariableDefinition[];
 /**
- * A streamed fragment of a model's *internal reasoning* (chain-of-thought).
+ * Tool function signature.
  *
- * OPT-IN. Unlike content, reasoning is private by default: it is only sent to
- * sockets that explicitly subscribe by connecting with the
- * {@link THREAD_STREAM_REASONING_PARAM} query parameter set to a truthy value
- * (e.g. `?reasoning=1`). Standard SDK consumers therefore never receive it
- * unless they opt in.
+ * Tools are async functions that receive a ThreadState and
+ * optionally validated arguments, returning a ToolResult.
  *
- * Reasoning is ephemeral *display* output: it is streamed for live presentation
- * only and is NOT persisted as part of the assistant message content, so it
- * cannot be replayed from message history — a client that wants it must be
- * subscribed while the turn runs.
+ * @template State - The state type (defaults to ThreadState)
+ * @template Args - The Zod schema for tool arguments, or null for no args
  */
-interface ThreadReasoningChunkEvent {
-    type: 'reasoning_chunk';
-    /** The assistant message this reasoning accompanies. */
-    message_id: string;
-    /** Message depth: 0 = top-level thread, 1+ = subagent. */
-    depth: number;
-    /** The next fragment of internal reasoning. */
-    chunk: string;
-}
+type Tool<State = ThreadState, Args extends ToolArgs | null = null> = Args extends ToolArgs ? (state: State, args: z.infer<Args>) => Promise<ToolResult> : (state: State) => Promise<ToolResult>;
 /**
- * Query-parameter name a client sets (truthy) on the thread stream WebSocket to
- * opt into receiving {@link ThreadReasoningChunkEvent}s. Absent/falsey means the
- * server never emits reasoning to that socket.
+ * Helper type to check if Uses is a non-empty const array.
+ * Returns true only if Uses has literal string elements (from `as const`).
  */
-declare const THREAD_STREAM_REASONING_PARAM = "reasoning";
+type IsConstArray<Uses extends readonly string[]> = string extends Uses[number] ? false : true;
 /**
- * Storage location identifier.
- *
- * Implementations define their own storage identifiers (e.g., 'local', 'cloud', 's3').
- * The spec does not mandate specific storage backends.
+ * Helper type to check if Uses array is empty.
  */
-type FileStorage = string;
+type IsEmptyArray<Uses extends readonly string[]> = Uses extends readonly [] ? true : false;
 /**
- * Record representing a file in the thread's file system.
+ * A ThreadState with queueTool and invokeTool constrained to specific tool names.
+ *
+ * When a tool declares `uses: ['a', 'b'] as const`, the state passed to execute
+ * will only allow calling those specific tools.
+ *
+ * @template Uses - Readonly array of allowed tool names
  */
-interface FileRecord {
-    /** File path (relative to thread root) */
-    path: string;
-    /** File name */
-    name: string;
-    /** MIME type */
-    mimeType: string;
-    /** Storage location */
-    storage: FileStorage;
-    /** File size in bytes */
-    size: number;
-    /** Whether this is a directory */
-    isDirectory: boolean;
-    /** Custom metadata */
-    metadata?: Record<string, unknown>;
-    /** Image width in pixels (if applicable) */
-    width?: number;
-    /** Image height in pixels (if applicable) */
-    height?: number;
-    /** Creation timestamp */
-    createdAt?: number;
-    /** Last modified timestamp */
-    updatedAt?: number;
-}
-/**
- * Options for writing a file.
- */
-interface WriteFileOptions {
-    /** Custom metadata to attach to the file */
-    metadata?: Record<string, unknown>;
-    /** Image width in pixels (if applicable) */
-    width?: number;
-    /** Image height in pixels (if applicable) */
-    height?: number;
-}
-/**
- * Result of reading a directory.
- */
-interface ReaddirResult {
-    /** Files and directories in the path */
-    entries: FileRecord[];
-}
-/**
- * Statistics about the thread's file system.
- */
-interface FileStats {
-    /** Total number of files */
-    fileCount: number;
-    /** Total number of directories */
-    directoryCount: number;
-    /** Total size in bytes */
-    totalSize: number;
-}
-/**
- * Result of a grep search.
- */
-interface GrepResult {
-    /** File path */
-    path: string;
-    /** Matching lines */
-    matches: Array<{
-        line: number;
-        content: string;
-    }>;
-}
-/**
- * Result of a find operation.
- */
-interface FindResult {
-    /** Matching file paths */
-    paths: string[];
-}
-/**
- * Options for streaming file reads.
- */
-interface ReadFileStreamOptions {
+type UsesConstrainedState<Uses extends readonly string[]> = Omit<ThreadState, 'queueTool' | 'invokeTool'> & {
     /**
-     * Abort signal for cancellation.
+     * Queue a tool for execution.
      *
-     * When signaled, the stream stops yielding new chunks.
-     * Already-yielded chunks remain valid.
+     * Constrained to only tools declared in `uses` array.
+     *
+     * @param toolName - Name of the tool to invoke (must be in uses array)
+     * @param args - Arguments to pass to the tool
      */
-    signal?: AbortSignal;
-}
+    queueTool(toolName: Uses[number], args?: Record<string, unknown>): void;
+    /**
+     * Invoke a tool directly and wait for the result.
+     *
+     * Constrained to only tools declared in `uses` array.
+     *
+     * @param toolName - Name of the tool to invoke (must be in uses array)
+     * @param args - Arguments to pass to the tool
+     * @returns The tool result
+     */
+    invokeTool(toolName: Uses[number], args?: Record<string, unknown>): Promise<ToolResult>;
+};
 /**
- * A chunk of file data from a streaming read.
+ * A ThreadState where queueTool and invokeTool cannot be called (empty uses).
  */
-interface FileChunk {
-    /** Raw binary data for this chunk */
-    data: Uint8Array;
-    /** 0-based index of this chunk */
-    index: number;
-    /** Total number of chunks (1 for small files) */
-    totalChunks: number;
-    /** Whether this is the final chunk */
-    isLast: boolean;
-}
+type EmptyUsesState = Omit<ThreadState, 'queueTool' | 'invokeTool'>;
 /**
- * Options passed to {@link ThreadState.runCode}.
+ * Determines the correct state type based on the Uses array.
  *
- * 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`.
+ * - Empty `uses: [] as const` → EmptyUsesState (no queueTool/invokeTool)
+ * - Const `uses: ['a', 'b'] as const` → UsesConstrainedState (constrained methods)
+ * - Non-const `uses: ['a']` or no uses → ThreadState (unconstrained, backward compatible)
+ */
+type ResolveUsesState<Uses extends readonly string[]> = IsEmptyArray<Uses> extends true ? EmptyUsesState : IsConstArray<Uses> extends true ? UsesConstrainedState<Uses> : ThreadState;
+/**
+ * Tool execute function with uses-aware state.
  *
- * Deadlines are **not** an option. Callers impose their own by calling
- * `handle.terminate()` on the returned {@link CodeExecution}.
+ * When `uses` is declared with `as const`, the state's queueTool and invokeTool
+ * are constrained to only the declared tools. When `uses` is not declared or
+ * is a regular string[], any tool name is allowed (backward compatible).
  *
- * See the [Code Execution specification](https://standardagentspec.com/0.1.0/specification/threads/code-execution)
- * for the full contract.
+ * @template State - Base state type
+ * @template Args - Tool arguments schema
+ * @template Uses - Readonly array of allowed tool names
  */
-interface CodeExecutionOptions {
+type UsesAwareExecute<State, Args extends ToolArgs | null, Uses extends readonly string[]> = Args extends ToolArgs ? (state: ResolveUsesState<Uses>, args: z.infer<Args>) => Promise<ToolResult> : (state: ResolveUsesState<Uses>) => Promise<ToolResult>;
+/**
+ * Options for defining a tool.
+ *
+ * @template State - The state type (defaults to ThreadState)
+ * @template Args - The Zod schema for tool arguments, or null for no args
+ * @template Tenvs - The Zod schema for thread environment variables, or null
+ * @template Uses - Readonly array of tool names this tool can invoke
+ */
+interface DefineToolOptions<State = ThreadState, Args extends ToolArgs | null = null, Tenvs extends ToolTenvs | null = null, Uses extends readonly string[] = readonly string[]> {
+    /** Description of what the tool does (shown to the LLM). */
+    description: string;
+    /** Zod schema for validating tool arguments. Omit for tools with no args. */
+    args?: Args;
+    /** The tool implementation function. */
+    execute: UsesAwareExecute<State, Args, Uses>;
     /**
-     * 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] }
-     * ```
+     * Variable declarations required/optionally used by this tool.
      */
-    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[];
-    };
+    variables?: VariableDefinition[];
     /**
-     * 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) },
-     * }
-     * ```
+     * @deprecated Use `variables` instead.
+     * Zod schema for thread environment variables the tool requires.
      */
-    imports?: Record<string, Record<string, unknown>>;
+    tenvs?: Tenvs;
     /**
-     * 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.
+     * Where this tool is executed:
+     * - 'local': Execute locally by the execution engine (default)
+     * - 'provider': Executed by the LLM provider, results come in response
      */
-    modules?: Record<string, string>;
+    executionMode?: 'local' | 'provider';
     /**
-     * Map of identifier → value installed on the sandbox's module scope.
+     * Which provider executes this tool (when executionMode='provider').
+     * e.g., 'openai', 'anthropic'
+     */
+    executionProvider?: string;
+    /**
+     * Explicit list of tools, prompts, or agents this tool can call.
      *
-     * These identifiers are resolvable as free variables inside the sandbox
-     * but MUST NOT appear on `globalThis`.
+     * When specified with `as const`, the tool's execute function's state
+     * will have queueTool() and invokeTool() constrained to only the
+     * declared tools (compile-time type safety).
+     *
+     * At runtime, attempts to call unlisted items will throw an error.
+     *
+     * This is required for packed tools to ensure namespace isolation.
+     * For unpacked tools, it's optional but recommended for clarity.
      *
      * @example
-     * ```ts
-     * globals: {
-     *   console: { log: (...args) => logger.info(...args) },
-     *   getMessage: async () => '...',
-     * }
+     * ```typescript
+     * // Type-safe: only 'validate_input' and 'format_output' allowed
+     * defineTool({
+     *   description: 'Process data using helper tools',
+     *   uses: ['validate_input', 'format_output'] as const,
+     *   execute: async (state) => {
+     *     state.queueTool('validate_input', { data: '...' }); // ✓ OK
+     *     state.queueTool('unknown_tool', {}); // ✗ TypeScript error
+     *     // ...
+     *   },
+     * });
+     *
+     * // Without `as const`, any tool name is allowed (backward compatible)
+     * defineTool({
+     *   description: 'Flexible tool',
+     *   uses: ['some_tool'],
+     *   execute: async (state) => {
+     *     state.queueTool('any_tool', {}); // ✓ OK (no type constraint)
+     *   },
+     * });
      * ```
      */
-    globals?: Record<string, unknown>;
+    uses?: Uses;
     /**
-     * Source language. TypeScript source has its types erased before evaluation;
-     * no type checking is performed.
+     * The name of an argument whose value is a short, human-readable description
+     * of what this tool call is doing — for example `"fixing index.html"`.
      *
-     * @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.
+     * When set, the `tool_call_started` hook and the `tool_call_started` thread
+     * event wait until **just this argument** has finished streaming from the
+     * model — not the whole tool call — and include its value as `progress`. This
+     * lets a UI show what a tool is about to do before a large argument (such as
+     * a file's `content`) finishes generating.
      *
-     * @default '<runCode>'
-     */
-    filename?: string;
-    /**
-     * Optional host-side sink for the built-in `report` bridge.
+     * When unset, `tool_call_started` fires as soon as the tool call appears in
+     * the model stream (its name is known, arguments may still be incomplete).
      *
-     * 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}.
+     * Declare the named argument early in the `args` schema and keep it short so
+     * it completes quickly. If the model never emits it, `tool_call_started`
+     * still fires once the tool call finishes, with `progress` undefined.
+     *
+     * @example
+     * ```typescript
+     * defineTool({
+     *   description: 'Write a file to the workspace',
+     *   progressArgument: 'description',
+     *   args: z.object({
+     *     description: z.string().describe('e.g. "writing index.html"'),
+     *     path: z.string(),
+     *     content: z.string(),
+     *   }),
+     *   execute: async (state, args) => { ... },
+     * });
+     * ```
      */
-    report?: (value: unknown) => void;
+    progressArgument?: string;
 }
 /**
- * Handle returned by {@link ThreadState.runCode}.
+ * Tool definition object returned by defineTool().
  *
- * `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.
+ * Contains all the metadata and implementation needed to register
+ * and execute a tool.
+ *
+ * @template State - The state type (defaults to ThreadState)
+ * @template Args - The Zod schema for tool arguments, or null for no args
+ * @template Tenvs - The Zod schema for thread environment variables, or null
+ * @template Uses - Readonly array of tool names this tool can invoke
  */
-interface CodeExecution extends PromiseLike<CodeExecutionResult> {
+interface ToolDefinition<State = ThreadState, Args extends ToolArgs | null = null, Tenvs extends ToolTenvs | null = null, Uses extends readonly string[] = readonly string[]> {
+    /** Description of what the tool does (shown to the LLM). */
+    description: string;
+    /** Zod schema for validating tool arguments, or null for no args. */
+    args: Args;
+    /** The tool implementation function. */
+    execute: UsesAwareExecute<State, Args, Uses>;
+    /** Declared variables for this tool. */
+    variables: VariableDefinition[];
     /**
-     * Stop the run. Idempotent: subsequent calls are no-ops.
+     * @deprecated Use `variables` instead.
+     * Zod schema for thread environment variables, or null if none.
+     */
+    tenvs: Tenvs;
+    /**
+     * Where this tool is executed:
+     * - 'local': Execute locally by the execution engine (default)
+     * - 'provider': Executed by the LLM provider, results come in response
+     */
+    executionMode?: 'local' | 'provider';
+    /**
+     * Which provider executes this tool (when executionMode='provider').
+     */
+    executionProvider?: string;
+    /**
+     * Explicit list of tools, prompts, or agents this tool can call.
      *
-     * 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`.
+     * When specified with `as const`, TypeScript constrains queueTool()
+     * and invokeTool() at compile time. At runtime, attempts to call
+     * unlisted items throw an error.
+     *
+     * This is required for packed tools to ensure namespace isolation.
+     * For unpacked tools, it's optional but recommended for clarity.
+     *
+     * Items can be:
+     * - Simple names: Resolve within current namespace
+     * - Qualified names (e.g., 'other_pkg:agent'): Cross-package entry point
      */
-    terminate(reason?: string): void;
-    /** `true` until the handle settles. */
-    readonly running: boolean;
+    uses?: Uses;
     /**
-     * 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.
+     * The name of an argument carrying a short, human-readable description of what
+     * this tool call is doing (e.g. `"fixing index.html"`). Controls when the
+     * `tool_call_started` hook/event fires — see {@link DefineToolOptions.progressArgument}.
      */
-    readonly reports: readonly unknown[];
+    progressArgument?: string;
 }
 /**
- * Outcome classification for {@link CodeExecutionResult.status}.
+ * Defines a tool that agents can call during execution.
  *
- * - `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).
+ * Tools are the primary way agents interact with external systems.
+ * Each tool has a description (shown to the LLM), optional argument
+ * schema (validated at runtime), an implementation function, and
+ * optional variable requirements.
+ *
+ * @example
+ * ```typescript
+ * import { defineTool } from '@standardagents/spec';
+ * import { z } from 'zod';
+ *
+ * // Tool with arguments
+ * export default defineTool({
+ *   description: 'Search the knowledge base for relevant information',
+ *   args: z.object({
+ *     query: z.string().describe('Search query'),
+ *     limit: z.number().optional().describe('Max results'),
+ *   }),
+ *   execute: async (state, args) => {
+ *     const results = await search(args.query, args.limit);
+ *     return { status: 'success', result: JSON.stringify(results) };
+ *   },
+ * });
+ *
+ * // Tool without arguments
+ * export default defineTool({
+ *   description: 'Get the current server time',
+ *   execute: async (state) => {
+ *     return { status: 'success', result: new Date().toISOString() };
+ *   },
+ * });
+ *
+ * // Tool with declared variables
+ * export default defineTool({
+ *   description: 'Search through uploaded files',
+ *   args: z.object({ query: z.string() }),
+ *   execute: async (state, args) => ({ status: 'success', result: 'done' }),
+ *   variables: [
+ *     {
+ *       name: 'VECTOR_STORE_ID',
+ *       type: 'text',
+ *       required: true,
+ *       description: 'OpenAI Vector Store ID',
+ *     },
+ *   ],
+ * });
+ *
+ * // Provider-executed tool (e.g., OpenAI built-in tools)
+ * export default defineTool({
+ *   description: 'Generate images using DALL-E',
+ *   args: z.object({ prompt: z.string() }),
+ *   execute: async () => ({ status: 'success', result: 'Handled by provider' }),
+ *   executionMode: 'provider',
+ *   executionProvider: 'openai',
+ * });
+ * ```
+ *
+ * @param options - Tool definition options
+ * @returns A tool definition object
  */
-type CodeExecutionStatus = 'success' | 'error' | 'memory' | 'terminated' | 'link_error';
 /**
- * A single captured `console.*` call from inside the sandbox.
+ * Validate a tool name does not contain reserved characters.
+ * Tools are typically defined without a name field (they get the filename),
+ * but this can be called by build tools that assign names.
+ */
+declare function validateToolName(name: string): void;
+declare function defineTool<State = ThreadState, Args extends ToolArgs | null = null, Tenvs extends ToolTenvs | null = null, Uses extends readonly string[] = readonly string[]>(options: DefineToolOptions<State, Args, Tenvs, Uses>): ToolDefinition<State, Args, Tenvs, Uses>;
+
+/**
+ * Effect definition types for Standard Agents.
  *
- * Only populated when the runtime installs a capturing `console` (typically
- * when the caller does not provide one via `options.globals`).
+ * Effects are scheduled operations that run outside the tool execution context.
+ * They enable implementation-specific side effects with optional delay support,
+ * leveraging whichever scheduling mechanism the runtime provides.
+ *
+ * Unlike tools, effects:
+ * - Do not return results to the LLM
+ * - Can be delayed for future execution
+ * - Run independently of the conversation flow
+ * - Are ideal for notifications, cleanup, and async operations
+ *
+ * @module
  */
-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'`.
+ * Effect function signature.
  *
- * Host-side stack frames MUST NOT leak into this object — only sandbox
- * frames are included.
+ * Effects are async functions that receive a ThreadState and
+ * optionally validated arguments. Unlike tools, they return void
+ * since results are not included in the conversation.
+ *
+ * @template State - The state type (defaults to ThreadState)
+ * @template Args - The Zod schema for effect arguments, or null for no args
  */
-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;
-}
+type Effect<State = ThreadState, Args extends ToolArgs | null = null> = Args extends ToolArgs ? (state: State, args: z.infer<Args>) => Promise<void> | void : (state: State) => Promise<void> | void;
 /**
- * Result of a {@link ThreadState.runCode} call.
+ * Return type of defineEffect function.
  *
- * 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.
+ * A tuple containing:
+ * - Effect description string
+ * - Argument schema (or null)
+ * - Effect implementation function
  */
-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;
-}
+type EffectDefinition<State = ThreadState, Args extends ToolArgs | null = null> = [string, Args, Effect<State, Args>];
 /**
- * Execution-specific state available during agent execution.
+ * Record of a scheduled effect.
  *
- * This is present when a thread is actively executing (during tool calls,
- * hook invocations, etc.) and null when accessing a thread at rest
- * (from endpoints, external code, etc.).
+ * Returned by getScheduledEffects() to inspect pending effects.
  */
-interface ExecutionState {
-    /** Current flow ID (unique per execution) */
-    readonly flowId: string;
-    /** Current side in dual_ai agents ('a' or 'b') */
-    readonly currentSide: 'a' | 'b';
-    /** Total steps executed in this flow */
-    readonly stepCount: number;
-    /** Steps executed by side A */
-    readonly sideAStepCount: number;
-    /** Steps executed by side B */
-    readonly sideBStepCount: number;
-    /** Whether execution has been stopped */
-    readonly stopped: boolean;
-    /** Which side initiated the stop (if stopped) */
-    readonly stoppedBy?: 'a' | 'b';
-    /** Message history loaded for current execution */
-    readonly messageHistory: Message[];
-    /**
-     * Force a specific side to play the next turn.
-     *
-     * Only valid for dual_ai agents. Has no effect on ai_human agents.
-     *
-     * @param side - The side to force ('a' or 'b')
-     */
-    forceTurn(side: 'a' | 'b'): void;
-    /**
-     * Stop the current execution.
-     *
-     * Signals the execution loop to terminate after the current operation
-     * completes. Does not abort in-progress LLM calls.
-     */
-    stop(): void;
-    /**
-     * Abort signal for cancellation.
-     *
-     * Can be used to abort fetch requests or other async operations
-     * when the execution is cancelled.
-     */
-    readonly abortSignal: AbortSignal;
-    /**
-     * Path from root prompt to current prompt.
-     *
-     * Tracks the current position in the prompt hierarchy:
-     * - At root level: `['my_prompt']`
-     * - Inside a sub-prompt: `['my_prompt', 'sub_prompt']`
-     * - After handoff: `['new_agent_prompt']`
-     *
-     * This allows tools and hooks to understand their execution context depth.
-     */
-    readonly promptPath: string[];
+interface ScheduledEffect {
+    /** Unique identifier for this scheduled effect. */
+    id: string;
+    /** Name of the effect to execute. */
+    name: string;
+    /** Arguments to pass to the effect handler. */
+    args: Record<string, unknown>;
+    /** When the effect is scheduled to run (microseconds since epoch). */
+    scheduledAt: number;
+    /** When the effect was created (microseconds since epoch). */
+    createdAt: number;
 }
 /**
- * Display/redaction classification for thread-scoped environment values.
+ * Define an effect with arguments.
  *
- * `secret` values should be redacted from tool output and logs. `text` values
- * may be displayed.
+ * @param description - Description of what the effect does
+ * @param args - Zod schema for validating effect arguments
+ * @param handler - The effect implementation function
+ * @returns A tuple containing the effect definition
  */
-type EnvValueType = 'text' | 'secret';
+declare function defineEffect<State = ThreadState, Args extends ToolArgs = ToolArgs>(description: string, args: Args, handler: Effect<State, Args>): EffectDefinition<State, Args>;
 /**
- * Options for {@link ThreadState.setEnv}.
+ * Define an effect without arguments.
+ *
+ * @param description - Description of what the effect does
+ * @param handler - The effect implementation function
+ * @returns A tuple containing the effect definition
  */
-interface SetEnvOptions {
-    /**
-     * Display/redaction classification for this value.
-     *
-     * Defaults to the existing type for that key, or `secret` for new keys.
-     */
-    type?: EnvValueType;
+declare function defineEffect<State = ThreadState>(description: string, handler: Effect<State, null>): EffectDefinition<State, null>;
+
+/**
+ * Agent Skills — instance-global skill store types.
+ *
+ * Skills follow the Agent Skills standard (https://agentskills.io): a folder
+ * whose root SKILL.md opens with YAML frontmatter carrying a required `name`
+ * (lowercase kebab, ≤64 chars) and `description` (≤1024 chars), optionally
+ * accompanied by scripts, references, and assets.
+ *
+ * Runtimes store skills server-side as a GLOBAL, instance-wide library:
+ * installed once, visible to every thread, nothing persisted on a client
+ * machine. Progressive disclosure is the contract — agents see only each
+ * skill's name + description until a skill is judged applicable, at which
+ * point they load its SKILL.md body (and, when needed, read or execute its
+ * bundled files).
+ */
+/** Registry view of an installed skill (metadata only — no file contents). */
+interface SkillMetadata {
+    /** Kebab-case identifier from SKILL.md frontmatter. */
+    name: string;
+    /** What the skill does and when to use it (from frontmatter). */
+    description: string;
+    /** Optional version string from frontmatter. */
+    version?: string;
+    /** Disabled skills stay installed but are hidden from agents. */
+    enabled: boolean;
+    /** Relative paths of the skill's files (always includes SKILL.md). */
+    files: string[];
+    /** Unix seconds of the last install/update. */
+    updatedAt?: number;
+}
+/** A file being installed into a skill (relative path + full text). */
+interface SkillFileInput {
+    path: string;
+    content: string;
 }
 /**
- * Options for {@link ThreadState.stopSession}.
+ * ThreadState surface for the global skill library. All operations hit the
+ * instance-wide store — there is no per-thread skill state beyond what a
+ * thread chooses to keep in its own key-value store.
  */
-interface StopSessionOptions {
-    /**
-     * Result text returned to a blocking parent/subagent caller.
-     *
-     * This does not send a parent message by itself. Use `notifyParent` when the
-     * session stop should also queue an explicit parent notification.
-     */
-    result?: string;
-    /**
-     * Optional silent message to queue to this thread's parent before stopping.
-     *
-     * Omit this for no parent-message side effect.
-     */
-    notifyParent?: string;
+interface SkillsNamespace {
+    /** Installed skills (enabled only, unless includeDisabled). */
+    list(options?: {
+        includeDisabled?: boolean;
+    }): Promise<SkillMetadata[]>;
+    /** A skill's metadata plus its SKILL.md source (null when not installed). */
+    get(name: string): Promise<{
+        metadata: SkillMetadata;
+        skillMd: string;
+    } | null>;
+    /** Read one bundled file's text (null when the skill or file is missing). */
+    readFile(name: string, path: string): Promise<string | null>;
     /**
-     * Optional parent registry status to set before stopping. Runtimes may ignore
-     * this when the thread has no parent registry entry.
-     *
-     * Omit this for no status side effect.
+     * Install (or replace) a skill from its file set. The file set must include
+     * a root SKILL.md with valid frontmatter; the skill's identity comes from
+     * that frontmatter, never from a caller-supplied name.
      */
-    status?: string;
+    install(files: SkillFileInput[]): Promise<SkillMetadata>;
+    /** Enable/disable an installed skill. Returns false when not installed. */
+    setEnabled(name: string, enabled: boolean): Promise<boolean>;
+    /** Uninstall a skill entirely. Returns false when not installed. */
+    remove(name: string): Promise<boolean>;
 }
+
 /**
- * The unified interface for all thread operations.
- *
- * ThreadState provides a consistent API for interacting with threads
- * regardless of context - whether from tools during execution, hooks,
- * or HTTP endpoints. The same interface is used throughout, with
- * execution-specific state available when applicable.
- *
- * @example
- * ```typescript
- * // In a tool
- * export default defineTool(
- *   'Send a greeting',
- *   z.object({ name: z.string() }),
- *   async (state, args) => {
- *     // Access thread identity
- *     console.log(`Thread: ${state.threadId}`);
- *
- *     // Check execution state
- *     if (state.execution?.stepCount > 10) {
- *       state.execution.stop();
- *     }
- *
- *     // Emit custom event
- *     state.emit('greeting', { name: args.name });
+ * Thread state types for Standard Agents.
  *
- *     return { status: 'success', result: `Hello, ${args.name}!` };
- *   }
- * );
- * ```
+ * ThreadState is the unified interface for all thread operations.
+ * It provides access to thread identity, messages, logs, resource loading,
+ * tool invocation, event emission, and execution state.
  *
- * @example
- * ```typescript
- * // In an endpoint
- * export default defineThreadEndpoint(async (req, state, params) => {
- *   // state.execution is null (not executing)
- *   const { messages } = await state.getMessages({ limit: 50 });
- *   return Response.json({ messages, params });
- * });
- * ```
+ * @module
  */
+
 /**
- * A request forwarded from a server-side tool to a connected client (CLI) for
- * local execution. Used by "forwarded" tools where the agent loop runs remotely
- * but the actual operation (read a file, run a command) must happen on the
- * user's own machine.
+ * Metadata about a thread.
+ *
+ * This represents the core identity of a thread, separate from its
+ * operational state. Thread metadata is immutable after creation.
  */
-interface ClientToolRequest {
-    /** Logical operation name the client knows how to perform (e.g. `read_file`). */
-    tool: string;
-    /** Arguments for the operation. */
-    args?: Record<string, unknown>;
-    /**
-     * Human-readable description of what this call will do, shown to the user when
-     * the client needs to ask for permission. Presence signals the operation may
-     * carry side effects.
-     */
-    requestPermission?: string;
-    /** Risk level 1 (safe) – 5 (dangerous). Clients slide auto-accept on this. */
-    risk?: number;
-    /** Milliseconds to wait for the client before failing the call. */
-    timeoutMs?: number;
-}
 /**
- * The result a connected client returns for a {@link ClientToolRequest}.
+ * The profile of the user a thread belongs to, as exposed by
+ * {@link ThreadState.user}. Identity fields only — never credentials.
  */
-interface ClientToolResponse {
-    /** Whether the client successfully performed the operation. */
-    ok: boolean;
-    /** Text result (e.g. file contents, command output). */
-    result?: string;
-    /** Error message when `ok` is false (including a user denial). */
-    error?: string;
-    /** Optional structured payload the tool can inspect. */
-    data?: unknown;
+interface ThreadUser {
+    id: string;
+    username: string;
+    /** 'admin' | 'user' | 'api' in the reference runtime. */
+    role: string;
+    /** Explicit permission grants (runtime-defined strings), if any. */
+    permissions?: string[] | null;
+    email?: string | null;
+    display_name?: string | null;
+    avatar_url?: string | null;
 }
-interface ThreadState {
-    /** Unique thread identifier */
-    readonly threadId: string;
+interface ThreadMetadata {
+    /** Unique identifier for the thread */
+    id: string;
     /** Agent that owns this thread */
-    readonly agentId: string;
+    agent_id: string;
     /** User associated with this thread (if any) */
-    readonly userId: string | null;
-    /** Thread creation timestamp (microseconds since epoch) */
-    readonly createdAt: number;
-    /**
-     * Registry of subagent child instances owned by this thread.
-     *
-     * Includes both resumable and non-resumable instances.
-     */
-    readonly children: SubagentRegistryEntry[];
-    /**
-     * Termination timestamp (microseconds) if this thread has been terminated.
-     * Null when the thread is active.
-     */
-    readonly terminated: number | null;
-    /**
-     * Arguments supplied when this thread was created or invoked.
-     *
-     * For resumable subagent child threads, this is the durable
-     * `subagent_create.arguments` object restored from child thread
-     * metadata/properties. Both child sides see the same object. Runtimes also
-     * expose these keys to prompt variable interpolation, including included
-     * prompts.
-     */
-    readonly arguments: Record<string, unknown>;
-    /**
-     * Get messages from the thread.
-     *
-     * @param options - Query options (limit, offset, order, etc.)
-     * @returns Messages and pagination info
-     */
-    getMessages(options?: GetMessagesOptions): Promise<MessagesResult>;
-    /**
-     * Get a single message by ID.
-     *
-     * @param messageId - The message ID
-     * @returns The message, or null if not found
-     */
-    getMessage(messageId: string): Promise<Message | null>;
-    /**
-     * Inject a message into the thread.
-     *
-     * Creates a new message in the conversation history. This can be used
-     * to add context, simulate user input, or insert assistant responses.
-     *
-     * @param message - The message to inject
-     * @returns The created message
-     */
-    injectMessage(message: InjectMessageInput): Promise<Message>;
-    /**
-     * Update an existing message.
-     *
-     * @param messageId - The message ID
-     * @param updates - The updates to apply
-     * @returns The updated message
-     */
-    updateMessage(messageId: string, updates: MessageUpdates): Promise<Message>;
-    /**
-     * Delete a message from the thread.
-     *
-     * Removes the message and any associated attachments from storage.
-     * Tool call results are cascade-deleted when their parent message is removed.
-     *
-     * @param messageId - The message ID to delete
-     * @returns true if the message was found and deleted, false if not found
-     */
-    deleteMessage(messageId: string): Promise<boolean>;
-    /**
-     * Queue a message for delivery on the thread's next step.
-     *
-     * If the thread is executing, the message is delivered before the next LLM call.
-     * If idle, queueing forces execution by the queued side.
-     */
-    queueMessage(message: QueueMessageInput): Promise<void>;
-    /**
-     * Load a model definition by name.
-     *
-     * @param name - The model name
-     * @returns The model definition
-     * @throws If the model is not found
-     */
-    loadModel<T = unknown>(name: string): Promise<T>;
-    /**
-     * Load a prompt definition by name.
-     *
-     * @param name - The prompt name
-     * @returns The prompt definition
-     * @throws If the prompt is not found
-     */
-    loadPrompt<T = unknown>(name: string): Promise<T>;
-    /**
-     * Load an agent definition by name.
-     *
-     * @param name - The agent name
-     * @returns The agent definition
-     * @throws If the agent is not found
-     */
-    loadAgent<T = unknown>(name: string): Promise<T>;
-    /**
-     * Get available prompt names.
-     *
-     * @returns Array of prompt names that can be loaded
-     */
-    getPromptNames(): string[];
-    /**
-     * Get available agent names.
-     *
-     * @returns Array of agent names that can be loaded
-     */
-    getAgentNames(): string[];
-    /**
-     * Get available model names.
-     *
-     * @returns Array of model names that can be loaded
-     */
-    getModelNames(): string[];
-    /**
-     * Get a child thread by its subagent reference ID.
-     *
-     * @param referenceId - Child thread UUID
-     * @returns Child ThreadState or null if not found
-     */
-    getChildThread(referenceId: string): Promise<ThreadState | null>;
-    /**
-     * Get this thread's parent thread (if any).
-     *
-     * @returns Parent ThreadState, or null for top-level threads
-     */
-    getParentThread(): Promise<ThreadState | null>;
-    /**
-     * Resolve an environment value for this thread by property name.
-     *
-     * Resolution order:
-     * 1. Thread
-     * 2. Agent definition
-     * 3. Prompt definition
-     * 4. User account
-     * 5. AgentBuilder instance
-     *
-     * @throws If the variable is not defined in any source
-     */
-    env(propertyName: string): Promise<string>;
-    /**
-     * Resolve the display/redaction type for an environment value.
-     *
-     * Resolution follows the same order as `env()`:
-     * thread, agent definition, prompt definition, user account, AgentBuilder instance.
-     * User-account and AgentBuilder-instance env stores may persist per-key
-     * `text` / `secret` metadata; agent/prompt defaults remain `secret` unless
-     * overridden by thread state.
-     *
-     * 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.
-     *
-     * This writes to thread env storage and propagates the updated thread env
-     * to all active descendant threads recursively. Terminated descendants are
-     * not modified.
-     *
-     * @param propertyName - Environment variable name
-     * @param value - Environment variable value
-     * @param options - Optional display/redaction classification for this value
-     */
-    setEnv(propertyName: string, value: string, options?: SetEnvOptions): Promise<void>;
+    user_id: string | null;
+    /** Creation timestamp (microseconds since epoch) */
+    created_at: number;
+}
+/**
+ * Registry entry for a subagent child thread.
+ */
+interface SubagentRegistryEntry {
+    /** Child thread UUID used as stable reference address */
+    reference: string;
+    /** Child agent name */
+    name: string;
+    /** Child agent title (human-readable) */
+    title?: string;
+    /** Tool description shown to the parent LLM */
+    description: string;
+    /** Whether this subagent instance is resumable */
+    resumable?: boolean;
+    /** Whether parent execution blocks on this subagent */
+    blocking?: boolean;
+    /** Optional human-readable thread name (for example from `name:` tag) */
+    threadName?: string;
     /**
-     * Queue a silent message to this thread's parent, if one exists.
-     *
-     * This is useful for explicit child-to-parent escalation paths where tools or
-     * hooks decide when the parent should be notified.
-     *
-     * Implementations SHOULD tag the queued message with the current thread's
-     * `subagent_id` metadata so the parent can attribute the notification.
+     * Initial argument values supplied when the child was created.
      *
-     * @throws If content is empty
+     * For resumable subagents, these values persist for the lifetime of the
+     * child thread and are visible to both child sides. Runtimes SHOULD source
+     * this object from the receiving side's prompt argument schema. The registry
+     * copy is parent-visible metadata; the durable child-side source SHOULD live
+     * with the child thread metadata/properties and be restored into
+     * `ThreadState.arguments` during execution and endpoint access. Top-level
+     * keys SHOULD also be exposed to prompt variable interpolation for whichever
+     * child side is currently rendering.
      */
-    notifyParent(content: string): Promise<void>;
+    initialArguments?: Record<string, unknown>;
+    /** Spawn group identifier used for grouping instances created together */
+    spawnGroupId?: string;
+    /** Instance creation timestamp (microseconds) */
+    createdAt?: number;
+    /** Current status (`running`, `idle`, `terminated`, or custom text) */
+    status: string;
+    /** How this child reports information back to its parent thread */
+    parentCommunication?: 'implicit' | 'explicit';
+}
+/**
+ * Options for retrieving messages.
+ */
+interface GetMessagesOptions {
+    /** Maximum number of messages to return */
+    limit?: number;
+    /** Number of messages to skip */
+    offset?: number;
+    /** Sort order ('asc' for oldest first, 'desc' for newest first) */
+    order?: 'asc' | 'desc';
+    /** Include silent messages (not shown in UI) */
+    includeSilent?: boolean;
+    /** Maximum nesting depth for sub-prompt messages */
+    maxDepth?: number;
+}
+/**
+ * Result of a message query.
+ */
+interface MessagesResult {
+    /** Array of messages */
+    messages: Message[];
+    /** Total number of messages matching the query */
+    total: number;
+    /** Whether there are more messages available */
+    hasMore: boolean;
+}
+/**
+ * A message in the thread conversation.
+ */
+interface Message {
+    /** Unique message identifier */
+    id: string;
+    /** Message role */
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    /** Message content (null for tool calls without text) */
+    content: string | null;
+    /** Tool name (for tool result messages) */
+    name?: string | null;
+    /** JSON-encoded array of tool calls (for assistant messages) */
+    tool_calls?: string | null;
+    /** Tool call ID (for tool result messages) */
+    tool_call_id?: string | null;
+    /** Creation timestamp (microseconds since epoch) */
+    created_at: number;
+    /** Parent message ID (for sub-prompt messages) */
+    parent_id?: string | null;
+    /** Nesting depth (0 for top-level messages) */
+    depth?: number;
+    /** Whether this message is silent (not shown in UI) */
+    silent?: boolean;
     /**
-     * Update this thread's status in its parent registry entry.
-     *
-     * Useful for long-lived watcher/observer children that want to expose their
-     * current state without sending a parent message.
-     *
-     * This is a no-op when the thread has no parent registry entry.
+     * Custom metadata.
      *
-     * @throws If status is empty
+     * Runtimes may attach lifecycle metadata for synthesized status messages
+     * (for example: `status_kind`, `subagent_event`). Message APIs may also
+     * mark send-message and durable queue entries with `queued: true` until
+     * they are injected into stored history.
      */
-    setStatus(status: string): Promise<void>;
+    metadata?: Record<string, unknown>;
+    /** Message processing status */
+    status?: 'pending' | 'completed' | 'failed' | null;
+    /** Tool execution status (for tool result messages) */
+    tool_status?: 'success' | 'error' | null;
+    /** Subagent reference UUID associated with this message */
+    subagent_id?: string | null;
+    /** Subagent agent name projected from runtime registry (when available) */
+    subagent_name?: string | null;
+    /** Subagent agent title projected from runtime registry (when available) */
+    subagent_title?: string | null;
+    /** Subagent description projected from runtime registry (when available) */
+    subagent_description?: string | null;
+    /** Subagent status projected from runtime registry (when available) */
+    subagent_status?: string | null;
+    /** Whether the associated subagent is resumable (when available) */
+    subagent_resumable?: boolean | null;
+    /** Whether the associated subagent is blocking (when available) */
+    subagent_blocking?: boolean | null;
+    /** Optional subagent instance thread name (when available) */
+    subagent_thread_name?: string | null;
+    /** Spawn group identifier for related subagent instances (when available) */
+    subagent_spawn_group_id?: string | null;
+}
+/**
+ * Input for injecting a new message.
+ */
+interface InjectMessageInput {
+    /** Message role */
+    role: 'user' | 'assistant' | 'system';
+    /** Message content */
+    content: string;
+    /** Whether to hide from UI */
+    silent?: boolean;
+    /** Custom metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Input for queueing a message for delivery on the thread's next step.
+ *
+ * Role mapping follows dual_ai conventions:
+ * - `assistant` maps to side_a
+ * - `user` maps to side_b
+ */
+interface QueueMessageInput {
+    /** Message role (`user` queues side_b perspective, `assistant` queues side_a perspective) */
+    role: 'user' | 'assistant';
+    /** Message content */
+    content: string;
+    /** Optional file attachments (new files or existing refs) */
+    attachments?: Array<ToolAttachment | AttachmentRef>;
+    /** Whether to hide the queued message from normal UI display */
+    silent?: boolean;
+    /** Optional structured metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Updates to apply to an existing message.
+ */
+interface MessageUpdates {
+    /** New content */
+    content?: string;
+    /** Updated metadata (merged with existing) */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * A streamed fragment of an assistant message's *visible content*.
+ *
+ * Always broadcast (no opt-in). Clients accumulate `chunk`s by `message_id` to
+ * render the answer as it generates; the authoritative final content still
+ * arrives separately as a persisted message. Clients must not discard an
+ * already-painted draft solely because a retry/reconnect exposes another id:
+ * retain keyed drafts or treat the id as a reconciliation alias until the
+ * terminal message record atomically supersedes it.
+ */
+interface ThreadMessageChunkEvent {
+    type: 'message_chunk';
+    /** The assistant message these fragments belong to. */
+    message_id: string;
+    /** Message depth: 0 = top-level thread, 1+ = subagent. */
+    depth: number;
+    /** The next fragment of visible content. */
+    chunk: string;
+}
+/**
+ * A streamed fragment of a model's *internal reasoning* (chain-of-thought).
+ *
+ * OPT-IN. Unlike content, reasoning is private by default: it is only sent to
+ * sockets that explicitly subscribe by connecting with the
+ * {@link THREAD_STREAM_REASONING_PARAM} query parameter set to a truthy value
+ * (e.g. `?reasoning=1`). Standard SDK consumers therefore never receive it
+ * unless they opt in.
+ *
+ * Reasoning is ephemeral *display* output: it is streamed for live presentation
+ * only and is NOT persisted as part of the assistant message content, so it
+ * cannot be replayed from message history — a client that wants it must be
+ * subscribed while the turn runs.
+ */
+interface ThreadReasoningChunkEvent {
+    type: 'reasoning_chunk';
+    /** The assistant message this reasoning accompanies. */
+    message_id: string;
+    /** Message depth: 0 = top-level thread, 1+ = subagent. */
+    depth: number;
+    /** The next fragment of internal reasoning. */
+    chunk: string;
+}
+/**
+ * Query-parameter name a client sets (truthy) on the thread stream WebSocket to
+ * opt into receiving {@link ThreadReasoningChunkEvent}s. Absent/falsey means the
+ * server never emits reasoning to that socket.
+ */
+declare const THREAD_STREAM_REASONING_PARAM = "reasoning";
+/**
+ * Storage location identifier.
+ *
+ * Implementations define their own storage identifiers (e.g., 'local', 'cloud', 's3').
+ * The spec does not mandate specific storage backends.
+ */
+type FileStorage = string;
+/**
+ * Record representing a file in the thread's file system.
+ */
+interface FileRecord {
+    /** File path (relative to thread root) */
+    path: string;
+    /** File name */
+    name: string;
+    /** MIME type */
+    mimeType: string;
+    /** Storage location */
+    storage: FileStorage;
+    /** File size in bytes */
+    size: number;
+    /** Whether this is a directory */
+    isDirectory: boolean;
+    /** Custom metadata */
+    metadata?: Record<string, unknown>;
+    /** Image width in pixels (if applicable) */
+    width?: number;
+    /** Image height in pixels (if applicable) */
+    height?: number;
+    /** Creation timestamp */
+    createdAt?: number;
+    /** Last modified timestamp */
+    updatedAt?: number;
+}
+/**
+ * Options for writing a file.
+ */
+interface WriteFileOptions {
+    /** Custom metadata to attach to the file */
+    metadata?: Record<string, unknown>;
+    /** Image width in pixels (if applicable) */
+    width?: number;
+    /** Image height in pixels (if applicable) */
+    height?: number;
+}
+/**
+ * Result of reading a directory.
+ */
+interface ReaddirResult {
+    /** Files and directories in the path */
+    entries: FileRecord[];
+}
+/**
+ * Statistics about the thread's file system.
+ */
+interface FileStats {
+    /** Total number of files */
+    fileCount: number;
+    /** Total number of directories */
+    directoryCount: number;
+    /** Total size in bytes */
+    totalSize: number;
+}
+/**
+ * Result of a grep search.
+ */
+interface GrepResult {
+    /** File path */
+    path: string;
+    /** Matching lines */
+    matches: Array<{
+        line: number;
+        content: string;
+    }>;
+}
+/**
+ * Result of a find operation.
+ */
+interface FindResult {
+    /** Matching file paths */
+    paths: string[];
+}
+/**
+ * Options for streaming file reads.
+ */
+interface ReadFileStreamOptions {
     /**
-     * Force the current agent session to stop successfully.
-     *
-     * This is stronger than `state.execution.stop()`: it marks the active session
-     * as terminal for subagent/session-boundary purposes, without requiring a
-     * `sessionStop` tool call. By default it has no parent-message or status side
-     * effects. Pass `notifyParent` and/or `status` when those effects are desired.
+     * Abort signal for cancellation.
      *
-     * @throws If called outside an active execution context
+     * When signaled, the stream stops yielding new chunks.
+     * Already-yielded chunks remain valid.
      */
-    stopSession(options?: StopSessionOptions): Promise<void>;
+    signal?: AbortSignal;
+}
+/**
+ * A chunk of file data from a streaming read.
+ */
+interface FileChunk {
+    /** Raw binary data for this chunk */
+    data: Uint8Array;
+    /** 0-based index of this chunk */
+    index: number;
+    /** Total number of chunks (1 for small files) */
+    totalChunks: number;
+    /** 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 {
     /**
-     * Queue a tool for execution.
-     *
-     * If the thread is currently executing, the tool is added to the
-     * execution queue. If not, this starts a new execution with the
-     * tool call.
+     * Export to execute from the evaluated module and arguments to pass.
      *
-     * @param toolName - Name of the tool to invoke
-     * @param args - Arguments to pass to the tool
-     */
-    queueTool(toolName: string, args: Record<string, unknown>): void;
-    /**
-     * Invoke a tool directly and wait for the result.
+     * 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.
      *
-     * If the thread is not currently executing, this creates a minimal
-     * execution context for the tool. Unlike queueTool, this blocks
-     * until the tool completes.
+     * @default { fn: 'default', args: [] }
      *
-     * @param toolName - Name of the tool to invoke
-     * @param args - Arguments to pass to the tool
-     * @returns The tool result
+     * @example
+     * ```ts
+     * execute: { fn: 'increment', args: [100] }
+     * ```
      */
-    invokeTool(toolName: string, args: Record<string, unknown>): Promise<ToolResult>;
+    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[];
+    };
     /**
-     * Schedule an effect for future execution.
+     * Map of bare module specifier → named exports exposed to the sandbox.
      *
-     * Effects are executed outside the current conversation flow, making them
-     * ideal for delayed operations like sending notifications, triggering
-     * webhooks, or running cleanup tasks.
+     * 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.
      *
-     * @param name - Name of the effect to schedule (must exist in agents/effects/)
-     * @param args - Arguments to pass to the effect handler
-     * @param delay - Delay in milliseconds before execution (default: 0 for immediate)
-     * @returns Unique ID of the scheduled effect (UUID)
+     * The key `default` within a namespace becomes that module's default export.
      *
      * @example
-     * ```typescript
-     * // Schedule a reminder email in 30 minutes
-     * const effectId = await state.scheduleEffect(
-     *   'send_reminder_email',
-     *   { to: 'user@example.com', subject: 'Reminder' },
-     *   30 * 60 * 1000
-     * );
+     * ```ts
+     * imports: {
+     *   fs: { readFile: (path) => state.readFile(path) },
+     *   supervisor: { report: (payload) => telemetry.push(payload) },
+     * }
      * ```
      */
-    scheduleEffect(name: string, args: Record<string, unknown>, delay?: number): Promise<string>;
-    /**
-     * Get scheduled effects for this thread.
-     *
-     * Returns effects that are pending execution. Can optionally filter
-     * by effect name.
-     *
-     * @param name - Optional effect name to filter by
-     * @returns Array of scheduled effect records
-     */
-    getScheduledEffects(name?: string): Promise<ScheduledEffect[]>;
+    imports?: Record<string, Record<string, unknown>>;
     /**
-     * Cancel a scheduled effect.
-     *
-     * 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.
+     * Additional relative ES modules available to the sandbox.
      *
-     * @param id - The effect ID returned by scheduleEffect
-     * @returns true if the effect was found and canceled, false otherwise
+     * 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.
      */
-    removeScheduledEffect(id: string): Promise<boolean>;
+    modules?: Record<string, string>;
     /**
-     * Trigger an agent to run on this thread.
-     *
-     * Starts a new agent execution asynchronously. This is useful for effects
-     * that need to trigger background agent work (e.g., running a finalizer
-     * agent after a delay).
-     *
-     * The agent runs in the background - this method returns immediately
-     * after queuing the execution.
+     * Map of identifier → value installed on the sandbox's module scope.
      *
-     * @param agentName - Name of the agent to run (must exist in agents/agents/)
-     * @returns Promise that resolves when the execution is queued
+     * These identifiers are resolvable as free variables inside the sandbox
+     * but MUST NOT appear on `globalThis`.
      *
      * @example
-     * ```typescript
-     * // In an effect handler, trigger a finalizer agent
-     * await state.runAgent('booking_finalizer');
+     * ```ts
+     * globals: {
+     *   console: { log: (...args) => logger.info(...args) },
+     *   getMessage: async () => '...',
+     * }
      * ```
      */
-    runAgent(agentName: string): Promise<void>;
+    globals?: Record<string, unknown>;
     /**
-     * Soft-terminate the thread.
+     * Source language. TypeScript source has its types erased before evaluation;
+     * no type checking is performed.
      *
-     * Implementations should mark the thread as terminated, abort in-flight
-     * execution, and reject subsequent execution/message queue operations.
+     * @default 'typescript'
      */
-    terminate(): Promise<void>;
+    language?: 'javascript' | 'typescript';
     /**
-     * Emit a custom event to connected clients.
-     *
-     * Events are sent via WebSocket to any connected clients. Use this
-     * for real-time updates, progress notifications, or custom data.
+     * 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.
      *
-     * @param event - Event name
-     * @param data - Event data (must be JSON-serializable)
+     * @default '<runCode>'
      */
-    emit(event: string, data: unknown): void;
+    filename?: string;
     /**
-     * Execution-scoped key-value data available while the current agent run is
-     * being assembled and executed.
+     * Optional host-side sink for the built-in `report` bridge.
      *
-     * Runtimes use this bag for values shared between tools/hooks/effects during
-     * one execution. Invocation or creation arguments belong in
-     * {@link ThreadState.arguments}, not in `context`.
+     * 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.
      *
-     * User mutations persist across tool calls within a single execution, but are
-     * not durable after execution ends unless the runtime rehydrates a value from
-     * another durable source. For durable storage, use
-     * {@link ThreadState.getValue} and {@link ThreadState.setValue}, the file
-     * system, or external storage.
+     * 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`.
      */
-    context: Record<string, unknown>;
+    terminate(reason?: string): void;
+    /** `true` until the handle settles. */
+    readonly running: boolean;
     /**
-     * Read a value from the thread's durable key-value store.
+     * 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.
+ *
+ * This is present when a thread is actively executing (during tool calls,
+ * hook invocations, etc.) and null when accessing a thread at rest
+ * (from endpoints, external code, etc.).
+ */
+interface ExecutionState {
+    /** Current flow ID (unique per execution) */
+    readonly flowId: string;
+    /** Current side in dual_ai agents ('a' or 'b') */
+    readonly currentSide: 'a' | 'b';
+    /** Total steps executed in this flow */
+    readonly stepCount: number;
+    /** Steps executed by side A */
+    readonly sideAStepCount: number;
+    /** Steps executed by side B */
+    readonly sideBStepCount: number;
+    /** Whether execution has been stopped */
+    readonly stopped: boolean;
+    /** Which side initiated the stop (if stopped) */
+    readonly stoppedBy?: 'a' | 'b';
+    /** Message history loaded for current execution */
+    readonly messageHistory: Message[];
+    /**
+     * Force a specific side to play the next turn.
      *
-     * 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.
+     * Only valid for dual_ai agents. Has no effect on ai_human agents.
      *
-     * 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 side - The side to force ('a' or 'b')
+     */
+    forceTurn(side: 'a' | 'b'): void;
+    /**
+     * Stop the current execution.
      *
-     * @param key - The key to read
-     * @returns The stored value, or `null` if the key has no value
+     * Signals the execution loop to terminate after the current operation
+     * completes. Does not abort in-progress LLM calls.
+     */
+    stop(): void;
+    /**
+     * Abort signal for cancellation.
      *
-     * @example
-     * ```typescript
-     * const count = (await state.getValue<number>('invocation_count')) ?? 0;
-     * await state.setValue('invocation_count', count + 1);
-     * ```
+     * Can be used to abort fetch requests or other async operations
+     * when the execution is cancelled.
      */
-    getValue<T = unknown>(key: string): Promise<T | null>;
+    readonly abortSignal: AbortSignal;
     /**
-     * Write a value to the thread's durable key-value store.
+     * Path from root prompt to current prompt.
      *
-     * 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.
+     * Tracks the current position in the prompt hierarchy:
+     * - At root level: `['my_prompt']`
+     * - Inside a sub-prompt: `['my_prompt', 'sub_prompt']`
+     * - After handoff: `['new_agent_prompt']`
      *
-     * Durable values are **not** automatically copied between threads when
-     * subagents are spawned — each thread maintains its own key-value store.
+     * This allows tools and hooks to understand their execution context depth.
+     */
+    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.
      *
-     * @param key - The key to write
-     * @param value - The value to store (JSON-serializable), or `null`/`undefined`
-     *   to delete the key
+     * Defaults to the existing type for that key, or `secret` for new keys.
      */
-    setValue(key: string, value: unknown): Promise<void>;
+    type?: EnvValueType;
+}
+/**
+ * Options for {@link ThreadState.stopSession}.
+ */
+interface StopSessionOptions {
     /**
-     * Read a value from the account-wide durable key-value store of the user
-     * this thread belongs to.
-     *
-     * The user store is the account-scoped sibling of the thread store: values
-     * persist across every thread the user owns on the instance (e.g. a coding
-     * client's registry of registered machines and projects). Returns `null`
-     * when the thread has no associated user or the key has no value.
+     * Result text returned to a blocking parent/subagent caller.
      *
-     * @param key - The key to read
+     * This does not send a parent message by itself. Use `notifyParent` when the
+     * session stop should also queue an explicit parent notification.
      */
-    getUserValue<T = unknown>(key: string): Promise<T | null>;
+    result?: string;
     /**
-     * Write a value to the account-wide durable key-value store of the user
-     * this thread belongs to.
-     *
-     * Passing `null` or `undefined` deletes the key. Values MUST be
-     * JSON-serializable. Implementations MUST reject the write when the thread
-     * has no associated user.
+     * Optional silent message to queue to this thread's parent before stopping.
      *
-     * @param key - The key to write
-     * @param value - The value to store (JSON-serializable), or `null`/`undefined`
-     *   to delete the key
+     * Omit this for no parent-message side effect.
      */
-    setUserValue(key: string, value: unknown): Promise<void>;
+    notifyParent?: string;
     /**
-     * List entries in the account-wide durable key-value store of the user this
-     * thread belongs to, optionally filtered by key prefix. Returns an empty
-     * list when the thread has no associated user.
+     * Optional parent registry status to set before stopping. Runtimes may ignore
+     * this when the thread has no parent registry entry.
      *
-     * @param options - Optional `prefix`, `limit` (default 100), and `offset`
+     * Omit this for no status side effect.
      */
-    listUserValues(options?: {
-        prefix?: string | null;
-        limit?: number;
-        offset?: number;
-    }): Promise<{
-        entries: Array<{
-            key: string;
-            value: unknown;
-            updated_at: number;
-        }>;
-        total: number;
-    }>;
+    status?: string;
+}
+/**
+ * The unified interface for all thread operations.
+ *
+ * ThreadState provides a consistent API for interacting with threads
+ * regardless of context - whether from tools during execution, hooks,
+ * or HTTP endpoints. The same interface is used throughout, with
+ * execution-specific state available when applicable.
+ *
+ * @example
+ * ```typescript
+ * // In a tool
+ * export default defineTool(
+ *   'Send a greeting',
+ *   z.object({ name: z.string() }),
+ *   async (state, args) => {
+ *     // Access thread identity
+ *     console.log(`Thread: ${state.threadId}`);
+ *
+ *     // Check execution state
+ *     if (state.execution?.stepCount > 10) {
+ *       state.execution.stop();
+ *     }
+ *
+ *     // Emit custom event
+ *     state.emit('greeting', { name: args.name });
+ *
+ *     return { status: 'success', result: `Hello, ${args.name}!` };
+ *   }
+ * );
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // In an endpoint
+ * export default defineThreadEndpoint(async (req, state, params) => {
+ *   // state.execution is null (not executing)
+ *   const { messages } = await state.getMessages({ limit: 50 });
+ *   return Response.json({ messages, params });
+ * });
+ * ```
+ */
+interface ThreadState {
+    /** Unique thread identifier */
+    readonly threadId: string;
+    /** Agent that owns this thread */
+    readonly agentId: string;
+    /** User associated with this thread (if any) */
+    readonly userId: string | null;
+    /** Thread creation timestamp (microseconds since epoch) */
+    readonly createdAt: number;
     /**
-     * The profile of the user this thread belongs to, or `null` when the thread
-     * has no associated user (e.g. unauthenticated local development).
-     *
-     * Lets tools and hooks personalize or gate behavior per user — e.g. an
-     * entitlement hook enforcing a per-user concurrency limit, or a tool
-     * addressing the user by name. Never includes credentials.
+     * Registry of subagent child instances owned by this thread.
      *
-     * @example
-     * ```typescript
-     * const user = await state.user();
-     * if (user?.email) await notifyBillingService(user.email);
-     * ```
+     * Includes both resumable and non-resumable instances.
      */
-    user(): Promise<ThreadUser | null>;
+    readonly children: SubagentRegistryEntry[];
     /**
-     * The instance-global Agent Skills library (https://agentskills.io format).
-     *
-     * Skills are installed once and visible to every thread; their files live
-     * server-side (never on a client machine). Agents should follow progressive
-     * disclosure: browse metadata via `skills.list()`, and load a skill's
-     * SKILL.md body with `skills.get()` only when it is applicable to the task.
-     *
-     * @example
-     * ```typescript
-     * const available = await state.skills.list();
-     * const skill = await state.skills.get('pdf-processing');
-     * const script = await state.skills.readFile('pdf-processing', 'scripts/extract.py');
-     * ```
+     * Termination timestamp (microseconds) if this thread has been terminated.
+     * Null when the thread is active.
      */
-    skills: SkillsNamespace;
+    readonly terminated: number | null;
     /**
-     * Forward a tool operation to the connected client (e.g. the coding CLI) and
-     * await its result. The agent loop runs remotely, but operations like reading
-     * a file or running a shell command must execute on the user's own machine;
-     * `callClient` bridges that gap over the thread's `bridge` WebSocket.
-     *
-     * Resolves with `{ ok: false, error }` (rather than throwing) when no client
-     * is connected, the request times out, or the user denies permission, so
-     * forwarded tools can surface a normal tool error to the model.
+     * Arguments supplied when this thread was created or invoked.
      *
-     * @param request - The operation, args, and optional permission/risk metadata
-     * @returns The client's response
+     * For resumable subagent child threads, this is the durable
+     * `subagent_create.arguments` object restored from child thread
+     * metadata/properties. Both child sides see the same object. Runtimes also
+     * expose these keys to prompt variable interpolation, including included
+     * prompts.
      */
-    callClient(request: ClientToolRequest): Promise<ClientToolResponse>;
+    readonly arguments: Record<string, unknown>;
     /**
-     * Write a file to the thread's file system.
-     *
-     * Large files (>1.75MB) are automatically chunked for storage.
+     * Get messages from the thread.
      *
-     * @param path - File path (relative to thread root)
-     * @param data - File content as ArrayBuffer or string
-     * @param mimeType - MIME type of the file
-     * @param options - Optional metadata and dimensions
-     * @returns The created file record
+     * @param options - Query options (limit, offset, order, etc.)
+     * @returns Messages and pagination info
      */
-    writeFile(path: string, data: ArrayBuffer | string, mimeType: string, options?: WriteFileOptions): Promise<FileRecord>;
+    getMessages(options?: GetMessagesOptions): Promise<MessagesResult>;
     /**
-     * Read a file from the thread's file system.
+     * Get a single message by ID.
      *
-     * @param path - File path
-     * @returns File content as ArrayBuffer, or null if not found
+     * @param messageId - The message ID
+     * @returns The message, or null if not found
      */
-    readFile(path: string): Promise<ArrayBuffer | null>;
+    getMessage(messageId: string): Promise<Message | null>;
     /**
-     * Stream a file from the thread's file system in chunks.
-     *
-     * For large files (>1.75MB), this yields one chunk at a time, enabling
-     * memory-efficient access without loading the entire file. Small files
-     * are yielded as a single chunk.
-     *
-     * Returns null if the file is not found or stored externally (S3, R2, URL).
+     * Inject a message into the thread.
      *
-     * @param path - File path
-     * @param options - Optional streaming options (abort signal)
-     * @returns Async iterable of file chunks, or null if not found/external
+     * Creates a new message in the conversation history. This can be used
+     * to add context, simulate user input, or insert assistant responses.
      *
-     * @example
-     * ```typescript
-     * const stream = await state.readFileStream('/uploads/video.mp4');
-     * if (stream) {
-     *   for await (const chunk of stream) {
-     *     console.log(`Chunk ${chunk.index + 1}/${chunk.totalChunks}`);
-     *     // Process chunk.data (Uint8Array)
-     *   }
-     * }
-     * ```
+     * @param message - The message to inject
+     * @returns The created message
      */
-    readFileStream(path: string, options?: ReadFileStreamOptions): Promise<AsyncIterable<FileChunk> | null>;
+    injectMessage(message: InjectMessageInput): Promise<Message>;
     /**
-     * Get metadata about a file.
+     * Update an existing message.
      *
-     * @param path - File path
-     * @returns File record, or null if not found
+     * @param messageId - The message ID
+     * @param updates - The updates to apply
+     * @returns The updated message
      */
-    statFile(path: string): Promise<FileRecord | null>;
+    updateMessage(messageId: string, updates: MessageUpdates): Promise<Message>;
     /**
-     * List contents of a directory.
+     * Delete a message from the thread.
      *
-     * @param path - Directory path
-     * @returns Directory entries
+     * Removes the message and any associated attachments from storage.
+     * Tool call results are cascade-deleted when their parent message is removed.
+     *
+     * @param messageId - The message ID to delete
+     * @returns true if the message was found and deleted, false if not found
      */
-    readdirFile(path: string): Promise<ReaddirResult>;
+    deleteMessage(messageId: string): Promise<boolean>;
     /**
-     * Delete a file.
+     * Queue a message for delivery on the thread's next step.
      *
-     * @param path - File path
+     * If the thread is executing, the message is delivered before the next LLM call.
+     * If idle, queueing forces execution by the queued side.
      */
-    unlinkFile(path: string): Promise<void>;
+    queueMessage(message: QueueMessageInput): Promise<void>;
     /**
-     * Create a directory.
+     * Load a model definition by name.
      *
-     * @param path - Directory path
-     * @returns The created directory record
+     * @param name - The model name
+     * @returns The model definition
+     * @throws If the model is not found
      */
-    mkdirFile(path: string): Promise<FileRecord>;
+    loadModel<T = unknown>(name: string): Promise<T>;
     /**
-     * Remove a directory.
+     * Load a prompt definition by name.
      *
-     * @param path - Directory path (must be empty)
+     * @param name - The prompt name
+     * @returns The prompt definition
+     * @throws If the prompt is not found
      */
-    rmdirFile(path: string): Promise<void>;
+    loadPrompt<T = unknown>(name: string): Promise<T>;
     /**
-     * Move or rename a file or directory.
-     *
-     * Relocates the entry at `sourcePath` to `destinationPath`. Works for
-     * files and directories; moving a directory relocates its entire subtree,
-     * preserving the relative layout of its contents. The destination must not
-     * already exist, and a directory cannot be moved into itself or one of its
-     * own descendants.
+     * Load an agent definition by name.
      *
-     * @param sourcePath - Existing file or directory path
-     * @param destinationPath - New path (must not already exist)
-     * @returns The moved entry's record at its new path
+     * @param name - The agent name
+     * @returns The agent definition
+     * @throws If the agent is not found
      */
-    moveFile(sourcePath: string, destinationPath: string): Promise<FileRecord>;
+    loadAgent<T = unknown>(name: string): Promise<T>;
     /**
-     * Rename a file or directory in place.
-     *
-     * Keeps the entry in its current parent directory and changes only its
-     * final path segment. `newName` must be a bare file name with no path
-     * separators. To relocate an entry to a different directory, use
-     * {@link ThreadState.moveFile} instead.
+     * Get available prompt names.
      *
-     * @param path - Existing file or directory path
-     * @param newName - New name (no path separators)
-     * @returns The renamed entry's record at its new path
+     * @returns Array of prompt names that can be loaded
      */
-    renameFile(path: string, newName: string): Promise<FileRecord>;
+    getPromptNames(): string[];
     /**
-     * Get overall file system statistics.
+     * Get available agent names.
      *
-     * @returns File count, directory count, and total size
+     * @returns Array of agent names that can be loaded
      */
-    getFileStats(): Promise<FileStats>;
+    getAgentNames(): string[];
     /**
-     * Search file contents for a pattern.
+     * Get available model names.
      *
-     * @param pattern - Search pattern (regular expression)
-     * @returns Matching files and lines
+     * @returns Array of model names that can be loaded
      */
-    grepFiles(pattern: string): Promise<GrepResult[]>;
+    getModelNames(): string[];
     /**
-     * Find files matching a glob pattern.
+     * Get a child thread by its subagent reference ID.
      *
-     * @param pattern - Glob pattern (e.g., "*.txt", "**\/*.json")
-     * @returns Matching file paths
+     * @param referenceId - Child thread UUID
+     * @returns Child ThreadState or null if not found
      */
-    findFiles(pattern: string): Promise<FindResult>;
+    getChildThread(referenceId: string): Promise<ThreadState | null>;
     /**
-     * Get a thumbnail for an image file.
+     * Get this thread's parent thread (if any).
      *
-     * @param path - Path to the image file
-     * @returns Thumbnail data as ArrayBuffer, or null if not available
+     * @returns Parent ThreadState, or null for top-level threads
      */
-    getFileThumbnail(path: string): Promise<ArrayBuffer | null>;
+    getParentThread(): Promise<ThreadState | null>;
     /**
-     * Execution-specific state.
+     * Resolve an environment value for this thread by property name.
      *
-     * This is present when the thread is actively executing (tools, hooks)
-     * and null when accessing a thread at rest (endpoints, external code).
+     * Resolution order:
+     * 1. Thread
+     * 2. Agent definition
+     * 3. Prompt definition
+     * 4. User account
+     * 5. AgentBuilder instance
      *
-     * Use this to access step counts, force turns, or stop execution.
+     * @throws If the variable is not defined in any source
      */
-    execution: ExecutionState | null;
+    env(propertyName: string): Promise<string>;
     /**
-     * Execute JavaScript or TypeScript source in an isolated sandbox.
+     * Resolve the display/redaction type for an environment value.
      *
-     * 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`.
+     * Resolution follows the same order as `env()`:
+     * thread, agent definition, prompt definition, user account, AgentBuilder instance.
+     * User-account and AgentBuilder-instance env stores may persist per-key
+     * `text` / `secret` metadata; agent/prompt defaults remain `secret` unless
+     * overridden by thread state.
      *
-     * 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()`.
+     * 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.
      *
-     * 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.
+     * This writes to thread env storage and propagates the updated thread env
+     * to all active descendant threads recursively. Terminated descendants are
+     * not modified.
      *
-     * 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 propertyName - Environment variable name
+     * @param value - Environment variable value
+     * @param options - Optional display/redaction classification for this value
+     */
+    setEnv(propertyName: string, value: string, options?: SetEnvOptions): Promise<void>;
+    /**
+     * Queue a silent message to this thread's parent, if one exists.
      *
-     * @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.
+     * This is useful for explicit child-to-parent escalation paths where tools or
+     * hooks decide when the parent should be notified.
      *
-     * @example
-     * ```typescript
-     * const run = state.runCode(
-     *   `
-     *     import { readFile } from 'fs';
-     *     import { report } from 'supervisor';
+     * Implementations SHOULD tag the queued message with the current thread's
+     * `subagent_id` metadata so the parent can attribute the notification.
      *
-     *     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',
-     *     },
-     *   },
-     * );
+     * @throws If content is empty
+     */
+    notifyParent(content: string): Promise<void>;
+    /**
+     * Update this thread's status in its parent registry entry.
      *
-     * const deadline = setTimeout(() => run.terminate('5s budget'), 5_000);
-     * const result = await run;
-     * clearTimeout(deadline);
+     * Useful for long-lived watcher/observer children that want to expose their
+     * current state without sending a parent message.
      *
-     * if (result.status === 'success') {
-     *   // result.result === { scanned: true }
-     * }
-     * ```
+     * This is a no-op when the thread has no parent registry entry.
+     *
+     * @throws If status is empty
      */
-    runCode(source: string, options?: CodeExecutionOptions): CodeExecution;
+    setStatus(status: string): Promise<void>;
     /**
-     * Runtime-specific context that cannot be packed or shared.
+     * Force the current agent session to stop successfully.
      *
-     * This property lets runtime implementations inject non-portable context —
-     * typically host bindings, database connections, or other
-     * platform-specific handles the runtime chooses to expose.
+     * This is stronger than `state.execution.stop()`: it marks the active session
+     * as terminal for subagent/session-boundary purposes, without requiring a
+     * `sessionStop` tool call. By default it has no parent-message or status side
+     * effects. Pass `notifyParent` and/or `status` when those effects are desired.
      *
-     * WARNING: Tools using this property cannot be packed, shared, or
-     * published as they depend on runtime-specific context. A packed agent
-     * MUST NOT use this property for required behavior. If a reusable agent
-     * needs a capability that is missing from ThreadState, define that
-     * capability in the Standard Agent Specification and its conformance
-     * surface instead of creating a private runtime dependency.
+     * @throws If called outside an active execution context
      */
-    readonly _notPackableRuntimeContext?: Record<string, unknown>;
-}
-
-/**
- * Tool definition types for Standard Agents.
- *
- * Tools are callable functions that agents can invoke during execution.
- * They receive the current ThreadState and validated arguments,
- * and return results that are included in the conversation.
- *
- * @module
- */
-
-/**
- * Text content item returned by tools.
- */
-interface TextContent {
-    type: 'text';
-    text: string;
-}
-/**
- * Image content item returned by tools.
- */
-interface ImageContent {
-    type: 'image';
-    /** Base64-encoded image data. */
-    data: string;
-    /** MIME type of the image (e.g., 'image/png', 'image/jpeg'). */
-    mimeType: string;
-}
-/**
- * Content types that can be returned by tools.
- */
-type ToolContent = TextContent | ImageContent;
-/**
- * File attachment generated by a tool.
- *
- * Attachments are stored in the thread's file system and linked to
- * the tool result message. Unlike user uploads, tool attachments are
- * not subject to image downsampling.
- */
-interface ToolAttachment {
-    /** File name for the attachment. */
-    name: string;
-    /** MIME type of the attachment. */
-    mimeType: string;
-    /** Base64-encoded file data. */
-    data: string;
-    /** Width in pixels (for images). */
-    width?: number;
-    /** Height in pixels (for images). */
-    height?: number;
-}
-/**
- * Reference to a pre-existing attachment in the thread file system.
- */
-interface AttachmentRef {
-    /** Unique identifier for the attachment. */
-    id: string;
-    /** Attachment type. */
-    type: 'file';
-    /** Path in the thread file system. */
-    path: string;
-    /** File name. */
-    name: string;
-    /** MIME type. */
-    mimeType: string;
-    /** File size in bytes. */
-    size: number;
-    /** Width in pixels (for images). */
-    width?: number;
-    /** Height in pixels (for images). */
-    height?: number;
-    /** AI-generated description. */
-    description?: string;
-}
-/**
- * Result returned by a tool execution.
- */
-interface ToolResult {
-    /** Status of the tool execution. */
-    status: 'success' | 'error';
+    stopSession(options?: StopSessionOptions): Promise<void>;
+    /**
+     * Queue a tool for execution.
+     *
+     * If the thread is currently executing, the tool is added to the
+     * execution queue. If not, this starts a new execution with the
+     * tool call.
+     *
+     * @param toolName - Name of the tool to invoke
+     * @param args - Arguments to pass to the tool
+     */
+    queueTool(toolName: string, args: Record<string, unknown>): void;
     /**
-     * Text representation of the tool output.
+     * Invoke a tool directly and wait for the result.
      *
-     * For tools that return structured content, this is derived by
-     * concatenating all text parts. For simple tools, this is the
-     * direct result string.
+     * If the thread is not currently executing, this creates a minimal
+     * execution context for the tool. Unlike queueTool, this blocks
+     * until the tool completes.
+     *
+     * @param toolName - Name of the tool to invoke
+     * @param args - Arguments to pass to the tool
+     * @returns The tool result
      */
-    result?: string;
-    /** Error message if status is 'error'. */
-    error?: string;
+    invokeTool(toolName: string, args: Record<string, unknown>): Promise<ToolResult>;
     /**
-     * Machine-readable error code for structured handling.
+     * Schedule an effect for future execution.
      *
-     * Example: `subagent_env_required` indicates the client must provide
-     * scoped subagent env values before execution can continue.
+     * Effects are executed outside the current conversation flow, making them
+     * ideal for delayed operations like sending notifications, triggering
+     * webhooks, or running cleanup tasks.
+     *
+     * @param name - Name of the effect to schedule (must exist in agents/effects/)
+     * @param args - Arguments to pass to the effect handler
+     * @param delay - Delay in milliseconds before execution (default: 0 for immediate)
+     * @returns Unique ID of the scheduled effect (UUID)
+     *
+     * @example
+     * ```typescript
+     * // Schedule a reminder email in 30 minutes
+     * const effectId = await state.scheduleEffect(
+     *   'send_reminder_email',
+     *   { to: 'user@example.com', subject: 'Reminder' },
+     *   30 * 60 * 1000
+     * );
+     * ```
      */
-    error_code?: string;
+    scheduleEffect(name: string, args: Record<string, unknown>, delay?: number): Promise<string>;
     /**
-     * Structured error payload for machine handling.
+     * Get scheduled effects for this thread.
      *
-     * Implementations should keep this JSON-serializable.
+     * Returns effects that are pending execution. Can optionally filter
+     * by effect name.
+     *
+     * @param name - Optional effect name to filter by
+     * @returns Array of scheduled effect records
      */
-    error_data?: Record<string, unknown>;
-    /** Stack trace for error debugging. */
-    stack?: string;
+    getScheduledEffects(name?: string): Promise<ScheduledEffect[]>;
     /**
-     * File attachments returned by the tool.
+     * Cancel a scheduled effect.
      *
-     * Can contain either:
-     * - ToolAttachment: New files with base64 data to be stored
-     * - AttachmentRef: References to existing files in the thread filesystem
+     * 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.
      *
-     * Implementations MUST store new attachments under /attachments/ directory.
+     * @param id - The effect ID returned by scheduleEffect
+     * @returns true if the effect was found and canceled, false otherwise
      */
-    attachments?: Array<ToolAttachment | AttachmentRef>;
-}
-/** Decrement helper to limit recursion depth. */
-type Dec<N extends number> = N extends 10 ? 9 : N extends 9 ? 8 : N extends 8 ? 7 : N extends 7 ? 6 : N extends 6 ? 5 : N extends 5 ? 4 : N extends 4 ? 3 : N extends 3 ? 2 : N extends 2 ? 1 : N extends 1 ? 0 : 0;
-/**
- * Allowed Zod types for tool argument nodes.
- *
- * 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> | 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>>[]
-]>);
-/**
- * Raw shape for a Zod object schema containing tool argument nodes.
- *
- * @template D - Maximum nesting depth (default: 7)
- */
-type ToolArgsRawShape<D extends number = 7> = Record<string, ToolArgsNode<D>>;
-/**
- * Top-level tool argument schema.
- *
- * Tool arguments MUST be defined as a Zod object schema.
- * This is required for compatibility with OpenAI's function calling API.
- *
- * @template D - Maximum nesting depth (default: 7)
- */
-type ToolArgs<D extends number = 7> = z.ZodObject<ToolArgsRawShape<D>>;
-/**
- * Variable declaration type.
- *
- * - `text`: Plain string configuration value
- * - `secret`: Sensitive value that should be encrypted at rest
- */
-type VariableType = 'text' | 'secret';
-/**
- * Declares a variable required or optionally consumed by a tool or prompt.
- */
-interface VariableDefinition {
-    /** Environment variable/property name */
-    name: string;
-    /** Value type */
-    type: VariableType;
-    /** Whether this variable is required to execute */
-    required: boolean;
+    removeScheduledEffect(id: string): Promise<boolean>;
     /**
-     * Whether this variable is scoped to the declarer subtree.
+     * Trigger an agent to run on this thread.
      *
-     * Scoped variables do not inherit parent thread env values. Descendants of
-     * the declarer still inherit scoped values from that declarer thread.
+     * Starts a new agent execution asynchronously. This is useful for effects
+     * that need to trigger background agent work (e.g., running a finalizer
+     * agent after a delay).
      *
-     * @default false
+     * The agent runs in the background - this method returns immediately
+     * after queuing the execution.
+     *
+     * @param agentName - Name of the agent to run (must exist in agents/agents/)
+     * @returns Promise that resolves when the execution is queued
+     *
+     * @example
+     * ```typescript
+     * // In an effect handler, trigger a finalizer agent
+     * await state.runAgent('booking_finalizer');
+     * ```
      */
-    scoped?: boolean;
-    /** Human-readable description (empty string when not provided) */
-    description: string;
-}
-/**
- * Legacy raw shape for `tenvs` schema - uses same pattern as ToolArgsRawShape.
- * Each key is an environment variable name and each value is a Zod schema.
- *
- * @template D - Maximum nesting depth (default: 7)
- */
-type TenvRawShape<D extends number = 7> = Record<string, ToolArgsNode<D>>;
-/**
- * Top-level thread environment variable schema.
- *
- * Defines which thread environment variables a tool requires.
- * Required values are non-optional fields, optional values use `.optional()`.
- *
- * @example
- * ```typescript
- * z.object({
- *   VECTOR_STORE_ID: z.string().describe('OpenAI Vector Store ID'),  // Required
- *   USER_LOCATION: z.string().optional().describe('User location'),   // Optional
- * })
- * ```
- *
- * @template D - Maximum nesting depth (default: 7)
- */
-type ToolTenvs<D extends number = 7> = z.ZodObject<TenvRawShape<D>>;
-/**
- * @deprecated Use VariableDefinition[] via the `variables` property instead.
- */
-type ToolVariables = VariableDefinition[];
-/**
- * Tool function signature.
- *
- * Tools are async functions that receive a ThreadState and
- * optionally validated arguments, returning a ToolResult.
- *
- * @template State - The state type (defaults to ThreadState)
- * @template Args - The Zod schema for tool arguments, or null for no args
- */
-type Tool<State = ThreadState, Args extends ToolArgs | null = null> = Args extends ToolArgs ? (state: State, args: z.infer<Args>) => Promise<ToolResult> : (state: State) => Promise<ToolResult>;
-/**
- * Helper type to check if Uses is a non-empty const array.
- * Returns true only if Uses has literal string elements (from `as const`).
- */
-type IsConstArray<Uses extends readonly string[]> = string extends Uses[number] ? false : true;
-/**
- * Helper type to check if Uses array is empty.
- */
-type IsEmptyArray<Uses extends readonly string[]> = Uses extends readonly [] ? true : false;
-/**
- * A ThreadState with queueTool and invokeTool constrained to specific tool names.
- *
- * When a tool declares `uses: ['a', 'b'] as const`, the state passed to execute
- * will only allow calling those specific tools.
- *
- * @template Uses - Readonly array of allowed tool names
- */
-type UsesConstrainedState<Uses extends readonly string[]> = Omit<ThreadState, 'queueTool' | 'invokeTool'> & {
+    runAgent(agentName: string): Promise<void>;
+    /**
+     * Soft-terminate the thread.
+     *
+     * Implementations should mark the thread as terminated, abort in-flight
+     * execution, and reject subsequent execution/message queue operations.
+     */
+    terminate(): Promise<void>;
+    /**
+     * Emit a custom event to connected clients.
+     *
+     * Events are sent via WebSocket to any connected clients. Use this
+     * for real-time updates, progress notifications, or custom data.
+     *
+     * @param event - Event name
+     * @param data - Event data (must be JSON-serializable)
+     */
+    emit(event: string, data: unknown): void;
+    /**
+     * Execution-scoped key-value data available while the current agent run is
+     * being assembled and executed.
+     *
+     * Runtimes use this bag for values shared between tools/hooks/effects during
+     * one execution. Invocation or creation arguments belong in
+     * {@link ThreadState.arguments}, not in `context`.
+     *
+     * User mutations persist across tool calls within a single execution, but are
+     * not durable after execution ends unless the runtime rehydrates a value from
+     * another durable source. For durable storage, 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>;
     /**
-     * Queue a tool for execution.
+     * Read a value from the account-wide durable key-value store of the user
+     * this thread belongs to.
      *
-     * Constrained to only tools declared in `uses` array.
+     * The user store is the account-scoped sibling of the thread store: values
+     * persist across every thread the user owns on the instance (e.g. a coding
+     * client's registry of registered machines and projects). Returns `null`
+     * when the thread has no associated user or the key has no value.
      *
-     * @param toolName - Name of the tool to invoke (must be in uses array)
-     * @param args - Arguments to pass to the tool
+     * @param key - The key to read
      */
-    queueTool(toolName: Uses[number], args?: Record<string, unknown>): void;
+    getUserValue<T = unknown>(key: string): Promise<T | null>;
     /**
-     * Invoke a tool directly and wait for the result.
+     * Write a value to the account-wide durable key-value store of the user
+     * this thread belongs to.
      *
-     * Constrained to only tools declared in `uses` array.
+     * Passing `null` or `undefined` deletes the key. Values MUST be
+     * JSON-serializable. Implementations MUST reject the write when the thread
+     * has no associated user.
      *
-     * @param toolName - Name of the tool to invoke (must be in uses array)
-     * @param args - Arguments to pass to the tool
-     * @returns The tool result
+     * @param key - The key to write
+     * @param value - The value to store (JSON-serializable), or `null`/`undefined`
+     *   to delete the key
      */
-    invokeTool(toolName: Uses[number], args?: Record<string, unknown>): Promise<ToolResult>;
-};
-/**
- * A ThreadState where queueTool and invokeTool cannot be called (empty uses).
- */
-type EmptyUsesState = Omit<ThreadState, 'queueTool' | 'invokeTool'>;
-/**
- * Determines the correct state type based on the Uses array.
- *
- * - Empty `uses: [] as const` → EmptyUsesState (no queueTool/invokeTool)
- * - Const `uses: ['a', 'b'] as const` → UsesConstrainedState (constrained methods)
- * - Non-const `uses: ['a']` or no uses → ThreadState (unconstrained, backward compatible)
- */
-type ResolveUsesState<Uses extends readonly string[]> = IsEmptyArray<Uses> extends true ? EmptyUsesState : IsConstArray<Uses> extends true ? UsesConstrainedState<Uses> : ThreadState;
-/**
- * Tool execute function with uses-aware state.
- *
- * When `uses` is declared with `as const`, the state's queueTool and invokeTool
- * are constrained to only the declared tools. When `uses` is not declared or
- * is a regular string[], any tool name is allowed (backward compatible).
- *
- * @template State - Base state type
- * @template Args - Tool arguments schema
- * @template Uses - Readonly array of allowed tool names
- */
-type UsesAwareExecute<State, Args extends ToolArgs | null, Uses extends readonly string[]> = Args extends ToolArgs ? (state: ResolveUsesState<Uses>, args: z.infer<Args>) => Promise<ToolResult> : (state: ResolveUsesState<Uses>) => Promise<ToolResult>;
-/**
- * Options for defining a tool.
- *
- * @template State - The state type (defaults to ThreadState)
- * @template Args - The Zod schema for tool arguments, or null for no args
- * @template Tenvs - The Zod schema for thread environment variables, or null
- * @template Uses - Readonly array of tool names this tool can invoke
- */
-interface DefineToolOptions<State = ThreadState, Args extends ToolArgs | null = null, Tenvs extends ToolTenvs | null = null, Uses extends readonly string[] = readonly string[]> {
-    /** Description of what the tool does (shown to the LLM). */
-    description: string;
-    /** Zod schema for validating tool arguments. Omit for tools with no args. */
-    args?: Args;
-    /** The tool implementation function. */
-    execute: UsesAwareExecute<State, Args, Uses>;
+    setUserValue(key: string, value: unknown): Promise<void>;
     /**
-     * Variable declarations required/optionally used by this tool.
+     * List entries in the account-wide durable key-value store of the user this
+     * thread belongs to, optionally filtered by key prefix. Returns an empty
+     * list when the thread has no associated user.
+     *
+     * @param options - Optional `prefix`, `limit` (default 100), and `offset`
      */
-    variables?: VariableDefinition[];
+    listUserValues(options?: {
+        prefix?: string | null;
+        limit?: number;
+        offset?: number;
+    }): Promise<{
+        entries: Array<{
+            key: string;
+            value: unknown;
+            updated_at: number;
+        }>;
+        total: number;
+    }>;
     /**
-     * @deprecated Use `variables` instead.
-     * Zod schema for thread environment variables the tool requires.
+     * The profile of the user this thread belongs to, or `null` when the thread
+     * has no associated user (e.g. unauthenticated local development).
+     *
+     * Lets tools and hooks personalize or gate behavior per user — e.g. an
+     * entitlement hook enforcing a per-user concurrency limit, or a tool
+     * addressing the user by name. Never includes credentials.
+     *
+     * @example
+     * ```typescript
+     * const user = await state.user();
+     * if (user?.email) await notifyBillingService(user.email);
+     * ```
      */
-    tenvs?: Tenvs;
+    user(): Promise<ThreadUser | null>;
     /**
-     * Where this tool is executed:
-     * - 'local': Execute locally by the execution engine (default)
-     * - 'provider': Executed by the LLM provider, results come in response
+     * The instance-global Agent Skills library (https://agentskills.io format).
+     *
+     * Skills are installed once and visible to every thread; their files live
+     * server-side (never on a client machine). Agents should follow progressive
+     * disclosure: browse metadata via `skills.list()`, and load a skill's
+     * SKILL.md body with `skills.get()` only when it is applicable to the task.
+     *
+     * @example
+     * ```typescript
+     * const available = await state.skills.list();
+     * const skill = await state.skills.get('pdf-processing');
+     * const script = await state.skills.readFile('pdf-processing', 'scripts/extract.py');
+     * ```
      */
-    executionMode?: 'local' | 'provider';
+    skills: SkillsNamespace;
     /**
-     * Which provider executes this tool (when executionMode='provider').
-     * e.g., 'openai', 'anthropic'
+     * Write a file to the thread's file system.
+     *
+     * Large files (>1.75MB) are automatically chunked for storage.
+     *
+     * @param path - File path (relative to thread root)
+     * @param data - File content as ArrayBuffer or string
+     * @param mimeType - MIME type of the file
+     * @param options - Optional metadata and dimensions
+     * @returns The created file record
      */
-    executionProvider?: string;
+    writeFile(path: string, data: ArrayBuffer | string, mimeType: string, options?: WriteFileOptions): Promise<FileRecord>;
     /**
-     * Explicit list of tools, prompts, or agents this tool can call.
+     * Read a file from the thread's file system.
      *
-     * When specified with `as const`, the tool's execute function's state
-     * will have queueTool() and invokeTool() constrained to only the
-     * declared tools (compile-time type safety).
+     * @param path - File path
+     * @returns File content as ArrayBuffer, or null if not found
+     */
+    readFile(path: string): Promise<ArrayBuffer | null>;
+    /**
+     * Stream a file from the thread's file system in chunks.
      *
-     * At runtime, attempts to call unlisted items will throw an error.
+     * For large files (>1.75MB), this yields one chunk at a time, enabling
+     * memory-efficient access without loading the entire file. Small files
+     * are yielded as a single chunk.
      *
-     * This is required for packed tools to ensure namespace isolation.
-     * For unpacked tools, it's optional but recommended for clarity.
+     * Returns null if the file is not found or stored externally (S3, R2, URL).
+     *
+     * @param path - File path
+     * @param options - Optional streaming options (abort signal)
+     * @returns Async iterable of file chunks, or null if not found/external
      *
      * @example
      * ```typescript
-     * // Type-safe: only 'validate_input' and 'format_output' allowed
-     * defineTool({
-     *   description: 'Process data using helper tools',
-     *   uses: ['validate_input', 'format_output'] as const,
-     *   execute: async (state) => {
-     *     state.queueTool('validate_input', { data: '...' }); // ✓ OK
-     *     state.queueTool('unknown_tool', {}); // ✗ TypeScript error
-     *     // ...
-     *   },
-     * });
-     *
-     * // Without `as const`, any tool name is allowed (backward compatible)
-     * defineTool({
-     *   description: 'Flexible tool',
-     *   uses: ['some_tool'],
-     *   execute: async (state) => {
-     *     state.queueTool('any_tool', {}); // ✓ OK (no type constraint)
-     *   },
-     * });
+     * const stream = await state.readFileStream('/uploads/video.mp4');
+     * if (stream) {
+     *   for await (const chunk of stream) {
+     *     console.log(`Chunk ${chunk.index + 1}/${chunk.totalChunks}`);
+     *     // Process chunk.data (Uint8Array)
+     *   }
+     * }
      * ```
      */
-    uses?: Uses;
+    readFileStream(path: string, options?: ReadFileStreamOptions): Promise<AsyncIterable<FileChunk> | null>;
     /**
-     * The name of an argument whose value is a short, human-readable description
-     * of what this tool call is doing — for example `"fixing index.html"`.
+     * Get metadata about a file.
      *
-     * When set, the `tool_call_started` hook and the `tool_call_started` thread
-     * event wait until **just this argument** has finished streaming from the
-     * model — not the whole tool call — and include its value as `progress`. This
-     * lets a UI show what a tool is about to do before a large argument (such as
-     * a file's `content`) finishes generating.
+     * @param path - File path
+     * @returns File record, or null if not found
+     */
+    statFile(path: string): Promise<FileRecord | null>;
+    /**
+     * List contents of a directory.
+     *
+     * @param path - Directory path
+     * @returns Directory entries
+     */
+    readdirFile(path: string): Promise<ReaddirResult>;
+    /**
+     * Delete a file.
+     *
+     * @param path - File path
+     */
+    unlinkFile(path: string): Promise<void>;
+    /**
+     * Create a directory.
+     *
+     * @param path - Directory path
+     * @returns The created directory record
+     */
+    mkdirFile(path: string): Promise<FileRecord>;
+    /**
+     * Remove a directory.
+     *
+     * @param path - Directory path (must be empty)
+     */
+    rmdirFile(path: string): Promise<void>;
+    /**
+     * Move or rename a file or directory.
+     *
+     * Relocates the entry at `sourcePath` to `destinationPath`. Works for
+     * files and directories; moving a directory relocates its entire subtree,
+     * preserving the relative layout of its contents. The destination must not
+     * already exist, and a directory cannot be moved into itself or one of its
+     * own descendants.
+     *
+     * @param sourcePath - Existing file or directory path
+     * @param destinationPath - New path (must not already exist)
+     * @returns The moved entry's record at its new path
+     */
+    moveFile(sourcePath: string, destinationPath: string): Promise<FileRecord>;
+    /**
+     * Rename a file or directory in place.
+     *
+     * Keeps the entry in its current parent directory and changes only its
+     * final path segment. `newName` must be a bare file name with no path
+     * separators. To relocate an entry to a different directory, use
+     * {@link ThreadState.moveFile} instead.
      *
-     * When unset, `tool_call_started` fires as soon as the tool call appears in
-     * the model stream (its name is known, arguments may still be incomplete).
+     * @param path - Existing file or directory path
+     * @param newName - New name (no path separators)
+     * @returns The renamed entry's record at its new path
+     */
+    renameFile(path: string, newName: string): Promise<FileRecord>;
+    /**
+     * Get overall file system statistics.
      *
-     * Declare the named argument early in the `args` schema and keep it short so
-     * it completes quickly. If the model never emits it, `tool_call_started`
-     * still fires once the tool call finishes, with `progress` undefined.
+     * @returns File count, directory count, and total size
+     */
+    getFileStats(): Promise<FileStats>;
+    /**
+     * Search file contents for a pattern.
      *
-     * @example
-     * ```typescript
-     * defineTool({
-     *   description: 'Write a file to the workspace',
-     *   progressArgument: 'description',
-     *   args: z.object({
-     *     description: z.string().describe('e.g. "writing index.html"'),
-     *     path: z.string(),
-     *     content: z.string(),
-     *   }),
-     *   execute: async (state, args) => { ... },
-     * });
-     * ```
+     * @param pattern - Search pattern (regular expression)
+     * @returns Matching files and lines
      */
-    progressArgument?: string;
-}
-/**
- * Tool definition object returned by defineTool().
- *
- * Contains all the metadata and implementation needed to register
- * and execute a tool.
- *
- * @template State - The state type (defaults to ThreadState)
- * @template Args - The Zod schema for tool arguments, or null for no args
- * @template Tenvs - The Zod schema for thread environment variables, or null
- * @template Uses - Readonly array of tool names this tool can invoke
- */
-interface ToolDefinition<State = ThreadState, Args extends ToolArgs | null = null, Tenvs extends ToolTenvs | null = null, Uses extends readonly string[] = readonly string[]> {
-    /** Description of what the tool does (shown to the LLM). */
-    description: string;
-    /** Zod schema for validating tool arguments, or null for no args. */
-    args: Args;
-    /** The tool implementation function. */
-    execute: UsesAwareExecute<State, Args, Uses>;
-    /** Declared variables for this tool. */
-    variables: VariableDefinition[];
+    grepFiles(pattern: string): Promise<GrepResult[]>;
     /**
-     * @deprecated Use `variables` instead.
-     * Zod schema for thread environment variables, or null if none.
+     * Find files matching a glob pattern.
+     *
+     * @param pattern - Glob pattern (e.g., "*.txt", "**\/*.json")
+     * @returns Matching file paths
      */
-    tenvs: Tenvs;
+    findFiles(pattern: string): Promise<FindResult>;
     /**
-     * Where this tool is executed:
-     * - 'local': Execute locally by the execution engine (default)
-     * - 'provider': Executed by the LLM provider, results come in response
+     * Get a thumbnail for an image file.
+     *
+     * @param path - Path to the image file
+     * @returns Thumbnail data as ArrayBuffer, or null if not available
      */
-    executionMode?: 'local' | 'provider';
+    getFileThumbnail(path: string): Promise<ArrayBuffer | null>;
     /**
-     * Which provider executes this tool (when executionMode='provider').
+     * Execution-specific state.
+     *
+     * This is present when the thread is actively executing (tools, hooks)
+     * and null when accessing a thread at rest (endpoints, external code).
+     *
+     * Use this to access step counts, force turns, or stop execution.
      */
-    executionProvider?: string;
+    execution: ExecutionState | null;
     /**
-     * Explicit list of tools, prompts, or agents this tool can call.
+     * Execute JavaScript or TypeScript source in an isolated sandbox.
      *
-     * When specified with `as const`, TypeScript constrains queueTool()
-     * and invokeTool() at compile time. At runtime, attempts to call
-     * unlisted items throw an error.
+     * 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`.
      *
-     * This is required for packed tools to ensure namespace isolation.
-     * For unpacked tools, it's optional but recommended for clarity.
+     * 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()`.
      *
-     * Items can be:
-     * - Simple names: Resolve within current namespace
-     * - Qualified names (e.g., 'other_pkg:agent'): Cross-package entry point
+     * 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 }
+     * }
+     * ```
      */
-    uses?: Uses;
+    runCode(source: string, options?: CodeExecutionOptions): CodeExecution;
     /**
-     * The name of an argument carrying a short, human-readable description of what
-     * this tool call is doing (e.g. `"fixing index.html"`). Controls when the
-     * `tool_call_started` hook/event fires — see {@link DefineToolOptions.progressArgument}.
+     * Runtime-specific context that cannot be packed or shared.
+     *
+     * 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. A packed agent
+     * MUST NOT use this property for required behavior. If a reusable agent
+     * needs a capability that is missing from ThreadState, define that
+     * capability in the Standard Agent Specification and its conformance
+     * surface instead of creating a private runtime dependency.
      */
-    progressArgument?: string;
+    readonly _notPackableRuntimeContext?: Record<string, unknown>;
 }
-/**
- * Defines a tool that agents can call during execution.
- *
- * Tools are the primary way agents interact with external systems.
- * Each tool has a description (shown to the LLM), optional argument
- * schema (validated at runtime), an implementation function, and
- * optional variable requirements.
- *
- * @example
- * ```typescript
- * import { defineTool } from '@standardagents/spec';
- * import { z } from 'zod';
- *
- * // Tool with arguments
- * export default defineTool({
- *   description: 'Search the knowledge base for relevant information',
- *   args: z.object({
- *     query: z.string().describe('Search query'),
- *     limit: z.number().optional().describe('Max results'),
- *   }),
- *   execute: async (state, args) => {
- *     const results = await search(args.query, args.limit);
- *     return { status: 'success', result: JSON.stringify(results) };
- *   },
- * });
- *
- * // Tool without arguments
- * export default defineTool({
- *   description: 'Get the current server time',
- *   execute: async (state) => {
- *     return { status: 'success', result: new Date().toISOString() };
- *   },
- * });
- *
- * // Tool with declared variables
- * export default defineTool({
- *   description: 'Search through uploaded files',
- *   args: z.object({ query: z.string() }),
- *   execute: async (state, args) => ({ status: 'success', result: 'done' }),
- *   variables: [
- *     {
- *       name: 'VECTOR_STORE_ID',
- *       type: 'text',
- *       required: true,
- *       description: 'OpenAI Vector Store ID',
- *     },
- *   ],
- * });
- *
- * // Provider-executed tool (e.g., OpenAI built-in tools)
- * export default defineTool({
- *   description: 'Generate images using DALL-E',
- *   args: z.object({ prompt: z.string() }),
- *   execute: async () => ({ status: 'success', result: 'Handled by provider' }),
- *   executionMode: 'provider',
- *   executionProvider: 'openai',
- * });
- * ```
- *
- * @param options - Tool definition options
- * @returns A tool definition object
- */
-/**
- * Validate a tool name does not contain reserved characters.
- * Tools are typically defined without a name field (they get the filename),
- * but this can be called by build tools that assign names.
- */
-declare function validateToolName(name: string): void;
-declare function defineTool<State = ThreadState, Args extends ToolArgs | null = null, Tenvs extends ToolTenvs | null = null, Uses extends readonly string[] = readonly string[]>(options: DefineToolOptions<State, Args, Tenvs, Uses>): ToolDefinition<State, Args, Tenvs, Uses>;
 
 /**
  * Provider types for Standard Agents.
@@ -2735,7 +2686,9 @@ declare class ProviderError extends Error {
     code: ProviderErrorCode;
     statusCode?: number | undefined;
     retryAfter?: number | undefined;
-    constructor(message: string, code: ProviderErrorCode, statusCode?: number | undefined, retryAfter?: number | undefined);
+    constructor(message: string, code: ProviderErrorCode, statusCode?: number | undefined, retryAfter?: number | undefined, options?: {
+        cause?: unknown;
+    });
     /**
      * Whether this error is retryable
      */
@@ -2791,6 +2744,13 @@ interface ProviderInstance {
     /** Fetch additional metadata about a completed response */
     getResponseMetadata?(summary: ResponseSummary, signal?: AbortSignal): Promise<Record<string, unknown> | null>;
 }
+/**
+ * A `fetch`-compatible transport function.
+ *
+ * Matches the WHATWG `fetch` call signature so any standard `fetch`
+ * implementation (or a wrapper around one) satisfies it.
+ */
+type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
 /**
  * Configuration passed to provider factory functions.
  */
@@ -2798,6 +2758,16 @@ interface ProviderFactoryConfig {
     apiKey: string;
     baseUrl?: string;
     timeout?: number;
+    /**
+     * Transport override for HTTP-based providers.
+     *
+     * The runtime may inject a custom transport here — for mocking, proxying,
+     * instrumentation, or any other request routing the host environment needs.
+     * Provider packages that speak HTTP MUST honor this override and route every
+     * request to the provider backend through it when present, instead of the
+     * global `fetch`.
+     */
+    fetch?: FetchLike;
     /**
      * Extra HTTP headers sent on every request to the provider backend.
      * Provider packages that build an HTTP client should forward these, so a
@@ -2879,7 +2849,32 @@ interface ProviderOverrideContext {
     config: ProviderFactoryConfig;
     /** Base provider instance before overrides are applied */
     baseProvider: ProviderInstance;
+    /**
+     * The thread this request is executing for, when available.
+     *
+     * Only populated for request-scoped overrides (`generate`, `stream`,
+     * `inspectRequest`, `getResponseMetadata`) — catalog overrides (`getModels`,
+     * `getIcon`, etc.) run without a thread and leave this undefined. Lets a
+     * transport override key off thread state without any product-specific
+     * coupling in the specification.
+     */
+    state?: ThreadState;
 }
+/**
+ * Builds a request transport for a defined provider.
+ *
+ * The runtime calls this per request with the executing thread's `state` and
+ * uses the returned transport as `ProviderFactoryConfig.fetch`. It is a
+ * generic hook — "override the fetch mechanism however you want" — with no
+ * knowledge of what the transport does (proxy, instrument, tunnel, mock).
+ * Because the transport can close over `state`, a provider declaring
+ * `createFetch` is constructed fresh per request rather than cached.
+ */
+type CreateFetch = (context: {
+    providerName: string;
+    config: ProviderFactoryConfig;
+    state?: ThreadState;
+}) => FetchLike;
 type MaybePromise<T> = T | Promise<T>;
 type ProviderOverride<Context, Result> = (context: ProviderOverrideContext & Context, next: () => MaybePromise<Result>) => MaybePromise<Result>;
 type ProviderSyncOverride<Context, Result> = (context: ProviderOverrideContext & Context, next: () => Result) => Result;
@@ -2926,6 +2921,13 @@ interface ProviderDefinition<N extends string = string, Base extends ProviderFac
     baseProvider: Base;
     config?: Partial<Record<keyof ProviderFactoryConfig | string, ProviderConfigEntry>>;
     overrides?: ProviderMethodOverrides;
+    /**
+     * Per-request transport factory. When declared, the runtime builds the
+     * provider fresh for each request with `ProviderFactoryConfig.fetch` set to
+     * this transport (so it can close over the executing thread's state) instead
+     * of using the shared provider cache.
+     */
+    createFetch?: CreateFetch;
 }
 /**
  * Provider factory with optional typed providerOptions schema.
@@ -5155,4 +5157,4 @@ interface PackedExports {
     __meta: PackedMeta;
 }
 
-export { type AgentDefinition, type AgentType, type AttachmentRef, type ClientToolRequest, type ClientToolResponse, 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, type ProviderConfigSlot, type ProviderConfigSlots, type ProviderConfigValueSource, type ProviderDefinition, ProviderError, type ProviderErrorCode, type ProviderExecutedToolResult, type ProviderFactory, type ProviderFactoryConfig, type ProviderFactoryWithOptions, type ProviderFinishReason, type ProviderGeneratedImage, type ProviderInstance, type ProviderMessage, type ProviderMessageContent, type ProviderMethodOverrides, type ProviderModelInfo, type ProviderModelsPage, type ProviderModelsQuery, type ProviderOverride, type ProviderOverrideContext, type ProviderReasoningDetail, type ProviderRequest, type ProviderResponse, type ProviderStreamChunk, type ProviderSyncOverride, type ProviderSystemMessage, type ProviderTool, type ProviderToolCallPart, type ProviderToolMessage, type ProviderToolResultContent, type ProviderUsage, type ProviderUsagePricing, 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 SkillFileInput, type SkillMetadata, type SkillsNamespace, type StopSessionOptions, type StructuredPrompt, type SubagentRegistryEntry, type SubagentToolConfig, type SubpromptConfig, THREAD_ENDPOINT_SYMBOL, THREAD_STREAM_REASONING_PARAM, type TenvRawShape, type TextContent, type TextPart, type ThreadEndpointHandler, type ThreadEndpointRouteParams, type ThreadMessageChunkEvent, type ThreadMetadata, type ThreadReasoningChunkEvent, type ThreadState, type ThreadUser, 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, defineProvider, defineThreadEndpoint, defineTool, isPacked, isThreadEndpoint, isVisibleInNamespace, mapReasoningLevel, providerConst, providerEnv, providerValue, 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 CreateFetch, type DefineToolOptions, type DefinitionLoader, type Effect, type EffectDefinition, type EmptyUsesState, type EnvValueType, type ExecutionState, type FetchLike, 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, type ProviderConfigSlot, type ProviderConfigSlots, type ProviderConfigValueSource, type ProviderDefinition, ProviderError, type ProviderErrorCode, type ProviderExecutedToolResult, type ProviderFactory, type ProviderFactoryConfig, type ProviderFactoryWithOptions, type ProviderFinishReason, type ProviderGeneratedImage, type ProviderInstance, type ProviderMessage, type ProviderMessageContent, type ProviderMethodOverrides, type ProviderModelInfo, type ProviderModelsPage, type ProviderModelsQuery, type ProviderOverride, type ProviderOverrideContext, type ProviderReasoningDetail, type ProviderRequest, type ProviderResponse, type ProviderStreamChunk, type ProviderSyncOverride, type ProviderSystemMessage, type ProviderTool, type ProviderToolCallPart, type ProviderToolMessage, type ProviderToolResultContent, type ProviderUsage, type ProviderUsagePricing, 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 SkillFileInput, type SkillMetadata, type SkillsNamespace, type StopSessionOptions, type StructuredPrompt, type SubagentRegistryEntry, type SubagentToolConfig, type SubpromptConfig, THREAD_ENDPOINT_SYMBOL, THREAD_STREAM_REASONING_PARAM, type TenvRawShape, type TextContent, type TextPart, type ThreadEndpointHandler, type ThreadEndpointRouteParams, type ThreadMessageChunkEvent, type ThreadMetadata, type ThreadReasoningChunkEvent, type ThreadState, type ThreadUser, 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, defineProvider, defineThreadEndpoint, defineTool, isPacked, isThreadEndpoint, isVisibleInNamespace, mapReasoningLevel, providerConst, providerEnv, providerValue, validateToolName };