zeitlich 0.2.28 → 0.2.30

package/dist/types-DVdT5ybA.d.cts

@@ -0,0 +1,1212 @@
+import { Duration } from '@temporalio/common';
+import { ActivityFunctionWithOptions, QueryDefinition, ActivityInterfaceFor } from '@temporalio/workflow';
+import { UpdateDefinition } from '@temporalio/common/lib/interfaces';
+import { z } from 'zod';
+import { a as SandboxFileSystem, F as FileStat, D as DirentEntry, g as SandboxOps } from './types-AujBIMMn.cjs';
+
+/**
+ * A tool definition with a name, description, and Zod schema for arguments.
+ * Does not include a handler - use ToolWithHandler for tools with handlers.
+ */
+interface ToolDefinition<TName extends string = string, TSchema extends z.ZodType = z.ZodType> {
+    name: TName;
+    description: string;
+    schema: TSchema;
+    strict?: boolean;
+    max_uses?: number;
+}
+/**
+ * A tool definition with an integrated handler function.
+ * This is the primary type for defining tools in the router.
+ */
+interface ToolWithHandler<TName extends string = string, TSchema extends z.ZodType = z.ZodType, TResult = unknown, TContext extends RouterContext = RouterContext, TToolResponse = JsonValue> {
+    name: TName;
+    description: string;
+    schema: TSchema;
+    handler: ToolHandler<z.infer<TSchema>, TResult, TContext, TToolResponse>;
+    strict?: boolean;
+    max_uses?: number;
+    /** Whether this tool is available to the agent (default: true). Disabled tools are excluded from definitions and rejected at parse time. */
+    enabled?: boolean | (() => boolean);
+    /** Per-tool lifecycle hooks (run in addition to global hooks) */
+    hooks?: ToolHooks<z.infer<TSchema>, TResult>;
+}
+/**
+ * A map of tool keys to tool definitions with handlers.
+ *
+ * Handler uses `any` intentionally — this is a type-system boundary where heterogeneous
+ * tool types are stored together. Type safety for individual tools is enforced by
+ * `defineTool()` at the definition site and generic inference utilities like
+ * `InferToolResults<T>` at the consumption site.
+ */
+type ToolMap = Record<string, {
+    name: string;
+    description: string | (() => string);
+    schema: z.ZodType | (() => z.ZodType);
+    handler: ToolHandler<any, any, any, any>;
+    strict?: boolean;
+    max_uses?: number;
+    enabled?: boolean | (() => boolean);
+    hooks?: ToolHooks<any, any>;
+}>;
+/**
+ * Extract the tool names from a tool map (uses the tool's name property, not the key).
+ */
+type ToolNames<T extends ToolMap> = T[keyof T]["name"];
+/**
+ * A raw tool call as received from the LLM before parsing.
+ */
+interface RawToolCall {
+    id?: string;
+    name: string;
+    args: unknown;
+}
+/**
+ * A parsed tool call with validated arguments for a specific tool.
+ */
+interface ParsedToolCall<TName extends string = string, TArgs = unknown> {
+    id: string;
+    name: TName;
+    args: TArgs;
+}
+/**
+ * Union type of all possible parsed tool calls from a tool map.
+ */
+type ParsedToolCallUnion<T extends ToolMap> = {
+    [K in keyof T]: ParsedToolCall<T[K]["name"], z.infer<T[K]["schema"]>>;
+}[keyof T];
+/**
+ * Function signature for appending tool results to a thread.
+ */
+type AppendToolResultFn = ActivityFunctionWithOptions<(id: string, config: ToolResultConfig) => Promise<void>>;
+/**
+ * The response from a tool handler.
+ * Contains the content for the tool message and the result to return from processToolCalls.
+ *
+ * Tools that don't return additional data should use `data: null` (TResult defaults to null).
+ * Tools that may fail to produce data should type TResult as `SomeType | null`.
+ */
+interface ToolHandlerResponse<TResult = null, TToolResponse = JsonValue> {
+    /** Content sent back to the LLM as the tool call response */
+    toolResponse: TToolResponse;
+    /** Data returned to the workflow and hooks for further processing */
+    data: TResult;
+    /**
+     * When true, the tool result has already been appended to the thread
+     * by the handler itself (e.g. via `withAutoAppend`), so the router
+     * will skip the `appendToolResult` call. This avoids sending large
+     * payloads through Temporal's activity payload limit.
+     */
+    resultAppended?: boolean;
+    /** Token usage from the tool execution (e.g. child agent invocations) */
+    usage?: TokenUsage;
+    /** Thread ID used by the handler (surfaced to the LLM for subagent thread continuation) */
+    threadId?: string;
+    /** Sandbox ID created or used by the handler (e.g. child agent sandbox) */
+    sandboxId?: string;
+    /** Unvalidated metadata passthrough from handler to hooks (e.g. infrastructure state) */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Base context the router always injects into every handler invocation.
+ * Handlers can rely on these fields being present without casting.
+ */
+interface RouterContext {
+    threadId: string;
+    /** Redis key suffix for thread storage. Defaults to 'messages'. */
+    threadKey?: string;
+    toolCallId: string;
+    toolName: string;
+    sandboxId?: string;
+}
+/**
+ * A handler function for a specific tool.
+ * Receives the parsed args and a context that always includes {@link RouterContext}
+ * fields, plus any additional properties when TContext extends RouterContext.
+ */
+type ToolHandler<TArgs, TResult, TContext extends RouterContext = RouterContext, TToolResponse = JsonValue> = (args: TArgs, context: TContext) => ToolHandlerResponse<TResult, TToolResponse> | Promise<ToolHandlerResponse<TResult, TToolResponse>>;
+/**
+ * Activity-compatible tool handler that always returns a Promise.
+ * Use this for tool handlers registered as Temporal activities.
+ *
+ * @example
+ * ```typescript
+ * const readHandler: ActivityToolHandler<
+ *   FileReadArgs,
+ *   ReadResult,
+ *   RouterContext & { scopedNodes: FileNode[]; provider: FileSystemProvider }
+ * > = async (args, context) => {
+ *   // context.threadId, context.sandboxId etc. are always available
+ *   return readHandler(args, context.scopedNodes, context.provider);
+ * };
+ * ```
+ */
+type ActivityToolHandler<TArgs, TResult, TContext extends RouterContext = RouterContext, TToolResponse = JsonValue> = (args: TArgs, context: TContext) => Promise<ToolHandlerResponse<TResult, TToolResponse>>;
+/**
+ * Extract the args type for a specific tool name from a tool map.
+ */
+type ToolArgs<T extends ToolMap, TName extends ToolNames<T>> = z.infer<Extract<T[keyof T], {
+    name: TName;
+}>["schema"]>;
+/**
+ * Extract the result type for a specific tool name from a tool map.
+ */
+type ToolResult<T extends ToolMap, TName extends ToolNames<T>> = Extract<T[keyof T], {
+    name: TName;
+}>["handler"] extends ToolHandler<unknown, infer R, RouterContext, any> ? Awaited<R> : never;
+/**
+ * The result of processing a tool call.
+ */
+interface ToolCallResult<TName extends string = string, TResult = unknown> {
+    toolCallId: string;
+    name: TName;
+    data: TResult;
+    usage?: TokenUsage;
+    /** Unvalidated metadata passthrough from handler to hooks (e.g. infrastructure state) */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Infer result types from a tool map based on handler return types.
+ */
+type InferToolResults<T extends ToolMap> = {
+    [K in keyof T as T[K]["name"]]: T[K]["handler"] extends ToolHandler<any, infer R, any, any> ? Awaited<R> : never;
+};
+/**
+ * Union of all possible tool call results based on handler return types.
+ */
+type ToolCallResultUnion<TResults extends Record<string, unknown>> = {
+    [TName in keyof TResults & string]: ToolCallResult<TName, TResults[TName]>;
+}[keyof TResults & string];
+/**
+ * Context passed to processToolCalls for hook execution and handler invocation
+ */
+interface ProcessToolCallsContext {
+    /** Current turn number (for hooks) */
+    turn?: number;
+    /** Active sandbox ID (when a sandbox is configured for this session) */
+    sandboxId?: string;
+}
+/**
+ * Result from PreToolUse hook - can block or modify execution
+ */
+interface PreToolUseHookResult {
+    /** Skip this tool call entirely */
+    skip?: boolean;
+    /** Modified args to use instead (must match schema) */
+    modifiedArgs?: unknown;
+}
+/**
+ * Result from PostToolUseFailure hook - can recover from errors
+ */
+interface PostToolUseFailureHookResult {
+    /** Provide a fallback result instead of throwing */
+    fallbackContent?: JsonValue;
+    /** Whether to suppress the error (still logs, but continues) */
+    suppress?: boolean;
+}
+/**
+ * Per-tool lifecycle hooks - defined directly on a tool definition.
+ * Runs in addition to global hooks (global pre → tool pre → execute → tool post → global post).
+ */
+interface ToolHooks<TArgs = unknown, TResult = unknown> {
+    /** Called before this tool executes - can skip or modify args */
+    onPreToolUse?: (ctx: {
+        args: TArgs;
+        threadId: string;
+        turn: number;
+    }) => PreToolUseHookResult | Promise<PreToolUseHookResult>;
+    /** Called after this tool executes successfully */
+    onPostToolUse?: (ctx: {
+        args: TArgs;
+        result: TResult;
+        threadId: string;
+        turn: number;
+        durationMs: number;
+        metadata?: Record<string, unknown>;
+    }) => void | Promise<void>;
+    /** Called when this tool execution fails */
+    onPostToolUseFailure?: (ctx: {
+        args: TArgs;
+        error: Error;
+        threadId: string;
+        turn: number;
+    }) => PostToolUseFailureHookResult | Promise<PostToolUseFailureHookResult>;
+}
+/**
+ * Context for PreToolUse hook - called before tool execution
+ */
+interface PreToolUseHookContext<T extends ToolMap> {
+    /** The tool call about to be executed */
+    toolCall: ParsedToolCallUnion<T>;
+    /** Thread identifier */
+    threadId: string;
+    /** Current turn number */
+    turn: number;
+}
+/**
+ * PreToolUse hook - called before tool execution, can block or modify
+ */
+type PreToolUseHook<T extends ToolMap> = (ctx: PreToolUseHookContext<T>) => PreToolUseHookResult | Promise<PreToolUseHookResult>;
+/**
+ * Context for PostToolUse hook - called after successful tool execution
+ */
+interface PostToolUseHookContext<T extends ToolMap, TResult = unknown> {
+    /** The tool call that was executed */
+    toolCall: ParsedToolCallUnion<T>;
+    /** The result from the tool handler */
+    result: TResult;
+    /** Thread identifier */
+    threadId: string;
+    /** Current turn number */
+    turn: number;
+    /** Execution duration in milliseconds */
+    durationMs: number;
+}
+/**
+ * PostToolUse hook - called after successful tool execution
+ */
+type PostToolUseHook<T extends ToolMap, TResult = unknown> = (ctx: PostToolUseHookContext<T, TResult>) => void | Promise<void>;
+/**
+ * Context for PostToolUseFailure hook - called when tool execution fails
+ */
+interface PostToolUseFailureHookContext<T extends ToolMap> {
+    /** The tool call that failed */
+    toolCall: ParsedToolCallUnion<T>;
+    /** The error that occurred */
+    error: Error;
+    /** Thread identifier */
+    threadId: string;
+    /** Current turn number */
+    turn: number;
+}
+/**
+ * PostToolUseFailure hook - called when tool execution fails
+ */
+type PostToolUseFailureHook<T extends ToolMap> = (ctx: PostToolUseFailureHookContext<T>) => PostToolUseFailureHookResult | Promise<PostToolUseFailureHookResult>;
+/**
+ * Tool execution hooks — the subset of hooks consumed by the tool router.
+ * Session/message lifecycle hooks live in lib/hooks/types.ts.
+ */
+interface ToolRouterHooks<T extends ToolMap, TResult = unknown> {
+    /** Called before each tool execution - can block or modify */
+    onPreToolUse?: PreToolUseHook<T>;
+    /** Called after each successful tool execution */
+    onPostToolUse?: PostToolUseHook<T, TResult>;
+    /** Called when tool execution fails */
+    onPostToolUseFailure?: PostToolUseFailureHook<T>;
+}
+/**
+ * Options for creating a tool router.
+ */
+interface ToolRouterOptions<T extends ToolMap> {
+    /** Map of tools with their handlers */
+    tools: T;
+    /** Thread ID for appending tool results */
+    threadId: string;
+    /** Redis key suffix for thread storage. Defaults to 'messages'. */
+    threadKey?: string;
+    /** Function to append tool results to the thread (called automatically after each handler).
+     *  Accepts a Temporal activity proxy with {@link ActivityFunctionWithOptions}. */
+    appendToolResult: AppendToolResultFn;
+    /** Whether to process tools in parallel (default: true) */
+    parallel?: boolean;
+    /** Tool execution lifecycle hooks (pre/post tool use) */
+    hooks?: ToolRouterHooks<T, ToolCallResultUnion<InferToolResults<T>>>;
+    /** Additional tools to auto-register (e.g. subagent, skill tools built by register helpers) */
+    plugins?: ToolMap[string][];
+}
+/**
+ * The tool router interface with full type inference for both args and results.
+ */
+interface ToolRouter<T extends ToolMap> {
+    /** Check if the router has any tools */
+    hasTools(): boolean;
+    /**
+     * Parse and validate a raw tool call against the router's tools.
+     * Returns a typed tool call with validated arguments.
+     */
+    parseToolCall(toolCall: RawToolCall): ParsedToolCallUnion<T>;
+    /**
+     * Check if a tool with the given name exists in the router.
+     */
+    hasTool(name: string): boolean;
+    /**
+     * Get all tool names in the router.
+     */
+    getToolNames(): ToolNames<T>[];
+    /**
+     * Get all tool definitions (without handlers) for passing to LLM.
+     */
+    getToolDefinitions(): ToolDefinition[];
+    /**
+     * Process all tool calls using the registered handlers.
+     * Returns typed results based on handler return types.
+     * @param toolCalls - Array of parsed tool calls to process
+     * @param context - Optional context including turn number for hooks
+     */
+    processToolCalls(toolCalls: ParsedToolCallUnion<T>[], context?: ProcessToolCallsContext): Promise<ToolCallResultUnion<InferToolResults<T>>[]>;
+    /**
+     * Process tool calls matching a specific name with a custom handler.
+     * Useful for overriding the default handler for specific cases.
+     */
+    processToolCallsByName<TName extends ToolNames<T>, TResult>(toolCalls: ParsedToolCallUnion<T>[], toolName: TName, handler: ToolHandler<ToolArgs<T, TName>, TResult>, context?: ProcessToolCallsContext): Promise<ToolCallResult<TName, TResult>[]>;
+    /**
+     * Filter tool calls by name.
+     */
+    filterByName<TName extends ToolNames<T>>(toolCalls: ParsedToolCallUnion<T>[], name: TName): ParsedToolCall<TName, ToolArgs<T, TName>>[];
+    /**
+     * Check if any tool call matches the given name.
+     */
+    hasToolCall(toolCalls: ParsedToolCallUnion<T>[], name: ToolNames<T>): boolean;
+    /**
+     * Filter results by tool name.
+     */
+    getResultsByName<TName extends ToolNames<T>>(results: ToolCallResultUnion<InferToolResults<T>>[], name: TName): ToolCallResult<TName, ToolResult<T, TName>>[];
+}
+
+/**
+ * JSON primitive types that Temporal can serialize
+ */
+type JsonPrimitive = string | number | boolean | null | undefined;
+/**
+ * JSON-serializable value (recursive type for Temporal compatibility)
+ */
+type JsonValue = JsonPrimitive | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+/**
+ * Type constraint ensuring T only contains JSON-serializable values.
+ * Use this for custom state to ensure Temporal workflow compatibility.
+ *
+ * Allows: primitives, arrays, plain objects, and JsonValue
+ * Rejects: functions, symbols, undefined, class instances with methods
+ */
+type JsonSerializable<T> = {
+    [K in keyof T]: T[K] extends JsonValue ? T[K] : T[K] extends JsonPrimitive ? T[K] : T[K] extends (infer U)[] ? U extends JsonValue ? T[K] : JsonSerializable<U>[] : T[K] extends object ? JsonSerializable<T[K]> : never;
+};
+/**
+ * Full state type combining base state with custom state
+ */
+type AgentState<TCustom extends JsonSerializable<TCustom>> = BaseAgentState & TCustom;
+/**
+ * Agent state manager interface
+ * Note: Temporal handlers must be set up in the workflow file due to
+ * Temporal's workflow isolation requirements. This manager provides
+ * the state and helpers needed for those handlers.
+ */
+interface AgentStateManager<TCustom extends JsonSerializable<TCustom>> {
+    /** Typed query definition registered for this agent's state */
+    readonly stateQuery: QueryDefinition<AgentState<TCustom>>;
+    /** Typed update definition registered for waiting on this agent's state change */
+    readonly stateChangeUpdate: UpdateDefinition<AgentState<TCustom>, [number]>;
+    /** Get current status */
+    getStatus(): AgentStatus;
+    /** Check if agent is running */
+    isRunning(): boolean;
+    /** Check if agent is in terminal state */
+    isTerminal(): boolean;
+    /** Get current state version */
+    getVersion(): number;
+    /** Set status to RUNNING */
+    run(): void;
+    /** Set status to WAITING_FOR_INPUT */
+    waitForInput(): void;
+    /** Set status to COMPLETED */
+    complete(): void;
+    /** Set status to FAILED */
+    fail(): void;
+    /** Set status to CANCELLED */
+    cancel(): void;
+    /** Increment state version (call after state changes) */
+    incrementVersion(): void;
+    /** Increment turns (call after each turn) */
+    incrementTurns(): void;
+    /** Get current turns */
+    getTurns(): number;
+    /** Get the system prompt */
+    getSystemPrompt(): string | undefined;
+    /** Set the system prompt */
+    setSystemPrompt(newSystemPrompt: string): void;
+    /** Get a custom state value by key */
+    get<K extends keyof TCustom>(key: K): TCustom[K];
+    /** Set a custom state value by key */
+    set<K extends keyof TCustom>(key: K, value: TCustom[K]): void;
+    /** Bulk-merge a partial update into custom state */
+    mergeUpdate(update: Partial<AgentState<TCustom>>): void;
+    /** Get full state for query handler */
+    getCurrentState(): AgentState<TCustom>;
+    /** Check if should return from waitForStateChange */
+    shouldReturnFromWait(lastKnownVersion: number): boolean;
+    /** Get all tasks */
+    getTasks(): WorkflowTask[];
+    /** Get a task by ID */
+    getTask(id: string): WorkflowTask | undefined;
+    /** Add or update a task */
+    setTask(task: WorkflowTask): void;
+    /** Delete a task by ID */
+    deleteTask(id: string): boolean;
+    /** Set the tools (converts Zod schemas to JSON Schema for serialization) */
+    setTools(newTools: ToolDefinition[]): void;
+    /** Update the usage */
+    updateUsage(usage: TokenUsage): void;
+    /** Get the total usage */
+    getTotalUsage(): {
+        totalInputTokens: number;
+        totalOutputTokens: number;
+        totalCachedWriteTokens: number;
+        totalCachedReadTokens: number;
+        totalReasonTokens: number;
+        turns: number;
+    };
+}
+
+/**
+ * Ephemeral virtual filesystem backed by a {@link FileResolver}.
+ *
+ * Created fresh for each tool invocation from the current workflow file tree.
+ * Directory structure is inferred from file paths. All mutations are tracked
+ * and can be retrieved via {@link getMutations} after the handler completes.
+ */
+declare class VirtualFileSystem<TCtx = unknown, TMeta = FileEntryMetadata> implements SandboxFileSystem {
+    private resolver;
+    private ctx;
+    readonly workspaceBase: string;
+    private entries;
+    private directories;
+    private mutations;
+    constructor(tree: FileEntry<TMeta>[], resolver: FileResolver<TCtx, TMeta>, ctx: TCtx, workspaceBase?: string);
+    /** Return all mutations accumulated during this invocation. */
+    getMutations(): TreeMutation<TMeta>[];
+    /** Look up a file entry by virtual path. */
+    getEntry(path: string): FileEntry<TMeta> | undefined;
+    readFile(path: string): Promise<string>;
+    readFileBuffer(path: string): Promise<Uint8Array>;
+    exists(path: string): Promise<boolean>;
+    stat(path: string): Promise<FileStat>;
+    readdir(path: string): Promise<string[]>;
+    readdirWithFileTypes(path: string): Promise<DirentEntry[]>;
+    writeFile(path: string, content: string | Uint8Array): Promise<void>;
+    appendFile(path: string, content: string | Uint8Array): Promise<void>;
+    mkdir(_path: string, _options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    rm(path: string, options?: {
+        recursive?: boolean;
+        force?: boolean;
+    }): Promise<void>;
+    cp(src: string, dest: string, _options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    mv(src: string, dest: string): Promise<void>;
+    readlink(_path: string): Promise<string>;
+    resolvePath(base: string, path: string): string;
+    private addParentDirectories;
+}
+
+/** Allowed value types for file-entry metadata. */
+type FileEntryMetadata = Record<string, string | number | boolean | null>;
+/** JSON-serializable metadata for a single file in the virtual tree. */
+interface FileEntry<TMeta = FileEntryMetadata> {
+    id: string;
+    /** Virtual path, e.g. "/src/index.ts" */
+    path: string;
+    size: number;
+    /** ISO-8601 date string (JSON-safe) */
+    mtime: string;
+    metadata: TMeta;
+}
+/**
+ * Flat list of file entries.
+ * Directories are inferred from file paths at runtime.
+ */
+type VirtualFileTree<TMeta = FileEntryMetadata> = FileEntry<TMeta>[];
+type TreeMutation<TMeta = FileEntryMetadata> = {
+    type: "add";
+    entry: FileEntry<TMeta>;
+} | {
+    type: "remove";
+    path: string;
+} | {
+    type: "update";
+    path: string;
+    entry: Partial<FileEntry<TMeta>>;
+};
+/**
+ * Consumer-provided bridge to the existing DB / S3 / CRUD layer.
+ *
+ * Generic over `TCtx` so every call receives workflow-level context
+ * (e.g. `{ projectId: string }`) without the resolver holding state.
+ *
+ * Generic over `TMeta` so resolved entries carry typed metadata.
+ */
+interface FileResolver<TCtx = unknown, TMeta = FileEntryMetadata> {
+    resolveEntries(ctx: TCtx): Promise<FileEntry<TMeta>[]>;
+    readFile(id: string, ctx: TCtx, metadata: TMeta): Promise<string>;
+    readFileBuffer(id: string, ctx: TCtx, metadata: TMeta): Promise<Uint8Array>;
+    writeFile(id: string, content: string | Uint8Array, ctx: TCtx, metadata: TMeta): Promise<void>;
+    createFile(path: string, content: string | Uint8Array, ctx: TCtx): Promise<FileEntry<TMeta>>;
+    deleteFile(id: string, ctx: TCtx, metadata: TMeta): Promise<void>;
+}
+/**
+ * Workflow-side operations for the virtual filesystem.
+ *
+ * Unlike {@link SandboxOps}, this only exposes what is actually needed:
+ * resolving the initial file tree from the consumer's data layer.
+ */
+interface VirtualFsOps<TCtx = unknown, TMeta = FileEntryMetadata> {
+    resolveFileTree(ctx: TCtx): Promise<{
+        fileTree: FileEntry<TMeta>[];
+    }>;
+}
+/**
+ * Maps generic {@link VirtualFsOps} method names to scope-prefixed names.
+ *
+ * @example
+ * ```typescript
+ * type Ops = PrefixedVirtualFsOps<"codingAgent">;
+ * // → { codingAgentResolveFileTree: ... }
+ * ```
+ */
+type PrefixedVirtualFsOps<TPrefix extends string, TCtx = unknown, TMeta = FileEntryMetadata> = {
+    [K in keyof VirtualFsOps<TCtx, TMeta> as `${TPrefix}${Capitalize<K & string>}`]: VirtualFsOps<TCtx, TMeta>[K];
+};
+/**
+ * The portion of workflow `AgentState` that the virtual filesystem reads via
+ * {@link queryParentWorkflowState}. Populated automatically by the session
+ * when `virtualFs` config is provided.
+ */
+interface VirtualFsState<TCtx = unknown, TMeta = FileEntryMetadata> {
+    fileTree: FileEntry<TMeta>[];
+    ctx: TCtx;
+    workspaceBase?: string;
+}
+/**
+ * Extended router context injected by {@link withVirtualFs}.
+ * Guarantees a live (ephemeral) virtual filesystem built from the workflow
+ * file tree.
+ */
+interface VirtualFsContext<TCtx = unknown, TMeta = FileEntryMetadata> extends RouterContext {
+    virtualFs: VirtualFileSystem<TCtx, TMeta>;
+}
+
+/**
+ * Agent execution status
+ */
+type AgentStatus = "RUNNING" | "WAITING_FOR_INPUT" | "COMPLETED" | "FAILED" | "CANCELLED";
+/**
+ * Base state that all agents must have
+ */
+interface BaseAgentState {
+    tools: SerializableToolDefinition[];
+    status: AgentStatus;
+    version: number;
+    turns: number;
+    tasks: Map<string, WorkflowTask>;
+    fileTree: FileEntry[];
+    systemPrompt?: string;
+    totalInputTokens: number;
+    totalOutputTokens: number;
+    cachedWriteTokens: number;
+    cachedReadTokens: number;
+}
+/**
+ * File representation for agent workflows
+ */
+interface AgentFile {
+    /** Database/S3 file ID */
+    id: string;
+    /** Virtual path for agent (e.g., "evidence/invoice.pdf") */
+    path: string;
+    /** Original filename */
+    filename: string;
+    /** Generic description for prompt */
+    description?: string;
+    /** MIME type of the file */
+    mimeType?: string;
+}
+interface TokenUsage {
+    inputTokens?: number;
+    outputTokens?: number;
+    cachedWriteTokens?: number;
+    cachedReadTokens?: number;
+    reasonTokens?: number;
+}
+/**
+ * Configuration for a Zeitlich agent
+ */
+interface AgentConfig {
+    /** The name of the agent, should be unique within the workflows, ideally Pascal Case */
+    agentName: string;
+    /** Description, used for sub agents */
+    description?: string;
+}
+/**
+ * A JSON-serializable tool definition for state storage.
+ * Uses a plain JSON Schema object instead of a live Zod instance,
+ * so it survives Temporal serialization without losing constraints (min, max, etc.).
+ */
+interface SerializableToolDefinition {
+    name: string;
+    description: string;
+    schema: Record<string, unknown>;
+    strict?: boolean;
+    max_uses?: number;
+}
+/**
+ * Configuration passed to runAgent activity
+ */
+interface RunAgentConfig extends AgentConfig {
+    /** The thread ID to use for the session */
+    threadId: string;
+    /** Redis key suffix for thread storage. Defaults to 'messages'. */
+    threadKey?: string;
+    /** Metadata for the session */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Configuration for appending a tool result
+ */
+interface ToolResultConfig {
+    threadId: string;
+    /** Redis key suffix for thread storage. Defaults to 'messages'. */
+    threadKey?: string;
+    toolCallId: string;
+    /** The name of the tool that produced this result */
+    toolName: string;
+    /** Content for the tool result — string, object, or array. The adapter converts to its SDK-native format. */
+    content: JsonValue;
+}
+/**
+ * Status of a workflow task
+ */
+type TaskStatus = "pending" | "in_progress" | "completed";
+/**
+ * A task managed within a workflow for tracking work items
+ */
+interface WorkflowTask {
+    /** Unique task identifier */
+    id: string;
+    /** Brief, actionable title in imperative form */
+    subject: string;
+    /** Detailed description of what needs to be done */
+    description: string;
+    /** Present continuous form shown in spinner when in_progress */
+    activeForm: string;
+    /** Current status of the task */
+    status: TaskStatus;
+    /** Arbitrary key-value pairs for tracking */
+    metadata: Record<string, string>;
+    /** IDs of tasks that must complete before this one can start */
+    blockedBy: string[];
+    /** IDs of tasks that are waiting for this one to complete */
+    blocks: string[];
+}
+/**
+ * Exit reasons for session termination
+ */
+type SessionExitReason = "completed" | "max_turns" | "waiting_for_input" | "failed" | "cancelled";
+/**
+ * Helper to check if status is terminal
+ */
+declare function isTerminalStatus(status: AgentStatus): boolean;
+
+/**
+ * Context for SessionStart hook - called when session begins
+ */
+interface SessionStartHookContext {
+    threadId: string;
+    agentName: string;
+    metadata: Record<string, unknown>;
+}
+/**
+ * SessionStart hook - called when session begins
+ */
+type SessionStartHook = (ctx: SessionStartHookContext) => void | Promise<void>;
+/**
+ * Context for SessionEnd hook - called when session ends
+ */
+interface SessionEndHookContext {
+    threadId: string;
+    agentName: string;
+    exitReason: SessionExitReason;
+    turns: number;
+    metadata: Record<string, unknown>;
+}
+/**
+ * SessionEnd hook - called when session ends
+ */
+type SessionEndHook = (ctx: SessionEndHookContext) => void | Promise<void>;
+/**
+ * Context for PreHumanMessageAppend hook - called before each human message is appended to the thread
+ */
+interface PreHumanMessageAppendHookContext<TContent = unknown> {
+    message: TContent;
+    threadId: string;
+}
+/**
+ * PreHumanMessageAppend hook - called before each human message is appended to the thread
+ */
+type PreHumanMessageAppendHook<TContent = unknown> = (ctx: PreHumanMessageAppendHookContext<TContent>) => void | Promise<void>;
+/**
+ * Context for PostHumanMessageAppend hook - called after each human message is appended to the thread
+ */
+interface PostHumanMessageAppendHookContext<TContent = unknown> {
+    message: TContent;
+    threadId: string;
+}
+/**
+ * PostHumanMessageAppend hook - called after each human message is appended to the thread
+ */
+type PostHumanMessageAppendHook<TContent = unknown> = (ctx: PostHumanMessageAppendHookContext<TContent>) => void | Promise<void>;
+/**
+ * Full hooks interface for a session — combines tool execution hooks
+ * (consumed by the router) with session/message lifecycle hooks
+ * (consumed directly by the session).
+ */
+interface Hooks<T extends ToolMap, TResult = unknown, TContent = unknown> extends ToolRouterHooks<T, TResult> {
+    /** Called before each human message is appended to the thread */
+    onPreHumanMessageAppend?: PreHumanMessageAppendHook<TContent>;
+    /** Called after each human message is appended to the thread */
+    onPostHumanMessageAppend?: PostHumanMessageAppendHook<TContent>;
+    /** Called when session starts */
+    onSessionStart?: SessionStartHook;
+    /** Called when session ends */
+    onSessionEnd?: SessionEndHook;
+}
+
+/**
+ * Thread initialization strategy.
+ *
+ * - `"new"` — start a fresh thread (optionally specify its ID).
+ * - `"continue"` — append directly to an existing thread in-place.
+ * - `"fork"` — copy all messages from an existing thread into a new one and
+ *   continue there.
+ */
+type ThreadInit = {
+    mode: "new";
+    threadId?: string;
+} | {
+    mode: "continue";
+    threadId: string;
+} | {
+    mode: "fork";
+    threadId: string;
+};
+/**
+ * Sandbox initialization strategy.
+ *
+ * - `"new"` — create a fresh sandbox. Optionally pass `ctx` to
+ *   have the {@link SandboxManager}'s resolver produce creation options
+ *   (e.g. initial files) from workflow arguments.
+ * - `"continue"` — resume a previously-paused sandbox (this session takes
+ *   ownership and the shutdown policy applies on exit).
+ * - `"fork"` — fork from an existing (or paused) sandbox; a new sandbox is
+ *   created and owned by this session.
+ * - `"inherit"` — use a sandbox owned by someone else (e.g. a parent agent).
+ *   The session will **not** manage its lifecycle on exit.
+ */
+type SandboxInit = {
+    mode: "new";
+    ctx?: unknown;
+} | {
+    mode: "continue";
+    sandboxId: string;
+} | {
+    mode: "fork";
+    sandboxId: string;
+} | {
+    mode: "inherit";
+    sandboxId: string;
+};
+/**
+ * What to do with the sandbox when the session exits.
+ *
+ * - `"destroy"` — tear down the sandbox entirely.
+ * - `"pause"` — pause the sandbox so it can be resumed later.
+ * - `"keep"` — leave the sandbox running (no-op on exit).
+ */
+type SandboxShutdown = "destroy" | "pause" | "keep";
+/**
+ * Extended shutdown options available to subagent workflows.
+ *
+ * Includes all base {@link SandboxShutdown} values plus:
+ * - `"pause-until-parent-close"` — pause the sandbox on exit, then wait for
+ *   the parent workflow to signal when to destroy it.
+ */
+type SubagentSandboxShutdown = SandboxShutdown | "pause-until-parent-close";
+
+/** ToolHandlerResponse with threadId required (subagents must always surface their thread) */
+type SubagentHandlerResponse<TResult = null, TToolResponse = JsonValue> = ToolHandlerResponse<TResult, TToolResponse> & {
+    threadId: string;
+    sandboxId?: string;
+};
+/**
+ * Raw workflow input fields passed from parent to child workflow.
+ * `defineSubagentWorkflow` maps this into `SubagentSessionInput`.
+ */
+interface SubagentWorkflowInput {
+    /** Thread initialization strategy forwarded from the parent */
+    thread?: ThreadInit;
+    /** Sandbox initialization strategy forwarded from the parent */
+    sandbox?: SandboxInit;
+    /** Sandbox shutdown override from the parent (takes precedence over workflow default) */
+    sandboxShutdown?: SubagentSandboxShutdown;
+}
+type SubagentWorkflow<TResult extends z.ZodType = z.ZodType> = (prompt: string, workflowInput: SubagentWorkflowInput, context?: Record<string, unknown>) => Promise<SubagentHandlerResponse<z.infer<TResult> | null>>;
+/**
+ * A subagent workflow with embedded metadata (name, description, resultSchema).
+ * Created by `defineSubagentWorkflow` — pass directly to `defineSubagent`.
+ */
+type SubagentDefinition<TResult extends z.ZodType = z.ZodType, TContext extends Record<string, unknown> = Record<string, unknown>> = ((prompt: string, workflowInput: SubagentWorkflowInput, context?: TContext) => Promise<SubagentHandlerResponse<z.infer<TResult> | null>>) & {
+    readonly agentName: string;
+    readonly description: string;
+    readonly resultSchema?: TResult;
+};
+/** Context value or factory — resolved at invocation time when a function is provided */
+type SubagentContext = Record<string, unknown> | (() => Record<string, unknown>);
+/**
+ * Sandbox configuration for a subagent.
+ *
+ * String shorthands:
+ * - `"none"` — no sandbox (default).
+ * - `"inherit"` — reuse the parent's sandbox (shared filesystem/exec).
+ * - `"own"` — the child creates and owns its own sandbox (shutdown defaults to `"destroy"`).
+ *
+ * Object form (only for `source: "own"`):
+ * - `{ source: "own", shutdown?: SubagentSandboxShutdown }` — own sandbox with explicit shutdown policy.
+ */
+type SubagentSandboxConfig = "none" | "inherit" | "own" | {
+    source: "own";
+    shutdown?: SubagentSandboxShutdown;
+};
+/**
+ * Configuration for a subagent that can be spawned by the parent workflow.
+ *
+ * @template TResult - Zod schema type for validating the child workflow's result
+ */
+interface SubagentConfig<TResult extends z.ZodType = z.ZodType> {
+    /** Identifier used in Task tool's subagent parameter */
+    agentName: string;
+    /** Description shown to the parent agent explaining what this subagent does */
+    description: string;
+    /** Whether this subagent is available (default: true). Disabled subagents are excluded from the Subagent tool. */
+    enabled?: boolean | (() => boolean);
+    /** Temporal workflow function or type name (used with executeChild) */
+    workflow: SubagentWorkflow<TResult>;
+    /** Optional task queue - defaults to parent's queue if not specified */
+    taskQueue?: string;
+    /** Optional Zod schema to validate the child workflow's result. If omitted, result is passed through as-is. */
+    resultSchema?: TResult;
+    /** Optional context passed to the subagent — a static object or a function evaluated at invocation time */
+    context?: SubagentContext;
+    /** Per-subagent lifecycle hooks */
+    hooks?: SubagentHooks;
+    /**
+     * Thread mode for this subagent.
+     *
+     * - `"new"` (default) — always start a fresh thread.
+     * - `"fork"` — the parent can pass a `threadId`; messages are copied into
+     *   a new thread and the subagent continues there.
+     * - `"continue"` — the parent can pass a `threadId`; the subagent appends
+     *   directly to the existing thread in-place.
+     */
+    thread?: "new" | "fork" | "continue";
+    /**
+     * Sandbox strategy for this subagent.
+     *
+     * String shorthands: `"none"` (default) | `"inherit"` | `"own"`.
+     * Object form: `{ source: "own", shutdown?: SubagentSandboxShutdown }`.
+     *
+     * @see {@link SubagentSandboxConfig}
+     */
+    sandbox?: SubagentSandboxConfig;
+}
+/**
+ * Per-subagent lifecycle hooks - defined on a SubagentConfig.
+ * Runs in addition to global hooks (global pre → subagent pre → execute → subagent post → global post).
+ */
+interface SubagentHooks<TArgs = unknown, TResult = unknown> {
+    /** Called before this subagent executes - can skip or modify args */
+    onPreExecution?: (ctx: {
+        args: TArgs;
+        threadId: string;
+        turn: number;
+    }) => PreToolUseHookResult | Promise<PreToolUseHookResult>;
+    /** Called after this subagent executes successfully */
+    onPostExecution?: (ctx: {
+        args: TArgs;
+        result: TResult;
+        threadId: string;
+        turn: number;
+        durationMs: number;
+        /** Unvalidated metadata from the child workflow (e.g. infrastructure state) */
+        metadata?: Record<string, unknown>;
+    }) => void | Promise<void>;
+    /** Called when this subagent execution fails */
+    onExecutionFailure?: (ctx: {
+        args: TArgs;
+        error: Error;
+        threadId: string;
+        turn: number;
+    }) => PostToolUseFailureHookResult | Promise<PostToolUseFailureHookResult>;
+}
+/**
+ * Extended response from the subagent `fn` — includes optional cleanup callbacks
+ * stripped before signaling the parent.
+ *
+ * When `TSandboxShutdown` is `"pause-until-parent-close"`, both `destroySandbox`
+ * and `sandboxId` become required so the parent can coordinate cleanup.
+ */
+type SubagentFnResult<TResult = null, TSandboxShutdown extends SubagentSandboxShutdown = SubagentSandboxShutdown> = SubagentHandlerResponse<TResult> & (TSandboxShutdown extends "pause-until-parent-close" ? {
+    destroySandbox: () => Promise<void>;
+    sandboxId: string;
+} : {
+    destroySandbox?: () => Promise<void>;
+});
+/**
+ * Session config fields passed from parent to child workflow.
+ */
+interface SubagentSessionInput {
+    /** Agent name — spread directly into `createSession` */
+    agentName: string;
+    /** Thread initialization strategy */
+    thread?: ThreadInit;
+    /** Sandbox initialization strategy */
+    sandbox?: SandboxInit;
+    /** Sandbox shutdown policy (default: "destroy") */
+    sandboxShutdown?: SubagentSandboxShutdown;
+}
+
+/**
+ * Skill metadata — the lightweight subset loaded at startup for all skills.
+ * Follows the agentskills.io specification frontmatter fields.
+ */
+interface SkillMetadata {
+    /** Lowercase alphanumeric + hyphens, max 64 chars, must match directory name */
+    name: string;
+    /** What the skill does and when to use it (max 1024 chars) */
+    description: string;
+    /** License name or reference to a bundled license file */
+    license?: string;
+    /** Environment requirements (intended product, system packages, network access) */
+    compatibility?: string;
+    /** Arbitrary key-value pairs for additional metadata */
+    metadata?: Record<string, string>;
+    /** Space-delimited list of pre-approved tools the skill may use */
+    allowedTools?: string[];
+    /** Absolute path to the skill directory (parent of SKILL.md) */
+    location?: string;
+}
+/**
+ * A fully-loaded skill including the SKILL.md instruction body.
+ * Progressive disclosure: metadata is always available, instructions
+ * are loaded on-demand via the ReadSkill tool.
+ */
+interface Skill extends SkillMetadata {
+    /** The markdown body of SKILL.md (everything after the frontmatter) */
+    instructions: string;
+    /** Resource file contents keyed by relative path (e.g. `references/overview.md` → content) */
+    resourceContents?: Record<string, string>;
+}
+/**
+ * Abstraction for discovering and loading skills.
+ *
+ * Implement this interface to provide skills from any source
+ * (filesystem, database, API, in-memory, etc.).
+ */
+interface SkillProvider {
+    /** Return lightweight metadata for all available skills */
+    listSkills(): Promise<SkillMetadata[]>;
+    /** Load a single skill with full instructions by name */
+    getSkill(name: string): Promise<Skill>;
+    /** Load all skills with full instructions */
+    loadAll(): Promise<Skill[]>;
+}
+
+/**
+ * Agent response from LLM invocation
+ */
+interface AgentResponse<M = unknown> {
+    message: M;
+    rawToolCalls: RawToolCall[];
+    usage?: TokenUsage;
+}
+/**
+ * Type signature for workflow-specific runAgent activity
+ */
+type RunAgentActivity<M = unknown> = (config: RunAgentConfig) => Promise<AgentResponse<M>>;
+/**
+ * Configuration passed to a ModelInvoker.
+ * Includes the full agent state so adapters can read tools, system prompt,
+ * token usage, or any custom state fields for model configuration.
+ */
+interface ModelInvokerConfig {
+    threadId: string;
+    /** Redis key suffix for thread storage. Defaults to 'messages'. */
+    threadKey?: string;
+    agentName: string;
+    state: BaseAgentState;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Generic model invocation contract.
+ * Implementations load the thread, call the LLM, append the response,
+ * and return a normalised AgentResponse.
+ *
+ * Framework adapters (e.g. `zeitlich/langchain`) provide concrete
+ * implementations of this type.
+ */
+type ModelInvoker<M = unknown> = (config: ModelInvokerConfig) => Promise<AgentResponse<M>>;
+
+/**
+ * Thread operations required by a session.
+ * Consumers provide these — typically by wrapping Temporal activities.
+ *
+ * `TContent` is the SDK-native content type for human messages.
+ * Each adapter supplies its own type (e.g. Anthropic ContentBlockParam[],
+ * Google GenAI Part[], LangChain MessageContent). Defaults to `string`.
+ */
+interface ThreadOps<TContent = string> {
+    /** Initialize an empty thread */
+    initializeThread(threadId: string, threadKey?: string): Promise<void>;
+    /** Append a human message to the thread */
+    appendHumanMessage(threadId: string, id: string, content: TContent, threadKey?: string): Promise<void>;
+    /** Append a tool result to the thread */
+    appendToolResult(id: string, config: ToolResultConfig): Promise<void>;
+    /** Append a system message to the thread */
+    appendSystemMessage(threadId: string, id: string, content: string, threadKey?: string): Promise<void>;
+    /** Copy all messages from sourceThreadId into a new thread at targetThreadId */
+    forkThread(sourceThreadId: string, targetThreadId: string, threadKey?: string): Promise<void>;
+}
+/**
+ * Composes an adapter prefix + workflow scope for activity naming.
+ *
+ * The adapter prefix stays first (camelCase); the workflow scope is
+ * capitalised and appended. When `TScope` is empty the adapter prefix
+ * is used as-is.
+ *
+ * @example
+ * ```typescript
+ * ScopedPrefix<"codingAgent", "googleGenAI"> // "googleGenAICodingAgent"
+ * ScopedPrefix<"", "googleGenAI">            // "googleGenAI"
+ * ```
+ */
+type ScopedPrefix<TScope extends string, TAdapter extends string> = TScope extends "" ? TAdapter : `${TAdapter}${Capitalize<TScope>}`;
+/**
+ * Maps generic {@link ThreadOps} method names to adapter-prefixed names.
+ *
+ * @example
+ * ```typescript
+ * type GoogleOps = PrefixedThreadOps<"googleGenAI">;
+ * // → { googleGenAIInitializeThread, googleGenAIAppendHumanMessage, … }
+ * ```
+ */
+type PrefixedThreadOps<TPrefix extends string, TContent = string> = {
+    [K in keyof ThreadOps<TContent> as `${TPrefix}${Capitalize<K & string>}`]: ThreadOps<TContent>[K];
+};
+/**
+ * Configuration for a Zeitlich agent session.
+ *
+ * @typeParam T - Tool map
+ * @typeParam M - SDK-native message type returned by the model invoker
+ * @typeParam TContent - SDK-native content type for human messages (defaults to `string`)
+ */
+interface SessionConfig<T extends ToolMap, M = unknown, TContent = string> {
+    /** The name of the agent, should be unique within the workflows */
+    agentName: string;
+    /** Metadata for the session */
+    metadata?: Record<string, unknown>;
+    /** Whether to append the system prompt as message to the thread */
+    appendSystemPrompt?: boolean;
+    /** How many turns to run the session for */
+    maxTurns?: number;
+    /** Workflow-specific runAgent activity (with tools pre-bound) */
+    runAgent: RunAgentActivity<M>;
+    /** Thread operations (initialize, append messages, parse tool calls) */
+    threadOps: ActivityInterfaceFor<ThreadOps<TContent>>;
+    /** Tool router for processing tool calls (optional if agent has no tools) */
+    tools?: T;
+    /** Subagent configurations */
+    subagents?: SubagentConfig[];
+    /** Skills available to this agent (metadata + instructions, loaded before session creation) */
+    skills?: Skill[];
+    /** Session lifecycle hooks */
+    hooks?: Hooks<T, ToolCallResultUnion<InferToolResults<T>>, TContent>;
+    /** Whether to process tools in parallel */
+    processToolsInParallel?: boolean;
+    /**
+     * Build context message content from agent-specific context.
+     * Returns SDK-native content for the initial human message.
+     */
+    buildContextMessage: () => TContent | Promise<TContent>;
+    /** How long to wait for input before cancelling the workflow */
+    waitForInputTimeout?: Duration;
+    /**
+     * Thread initialization strategy (default: `{ mode: "new" }`).
+     *
+     * - `{ mode: "new" }` — start a fresh thread.
+     * - `{ mode: "new", threadId: "..." }` — start a fresh thread with a specific ID.
+     * - `{ mode: "continue", threadId: "..." }` — append to an existing thread in-place.
+     * - `{ mode: "fork", threadId: "..." }` — fork an existing thread and continue in the copy.
+     */
+    thread?: ThreadInit;
+    /**
+     * Redis key suffix for thread storage. Defaults to `"messages"`.
+     *
+     * Controls the Redis key layout: `thread:${threadId}:${threadKey}`.
+     * Use different keys to isolate storage across sessions sharing the
+     * same adapter instance.
+     */
+    threadKey?: string;
+    /** Sandbox lifecycle operations (optional — omit for agents that don't need a sandbox) */
+    sandboxOps?: SandboxOps;
+    /**
+     * Sandbox initialization strategy.
+     *
+     * - `{ mode: "new" }` — create a fresh sandbox.
+     * - `{ mode: "continue", sandboxId: "..." }` — resume a paused sandbox (session owns it).
+     * - `{ mode: "fork", sandboxId: "..." }` — fork from an existing sandbox.
+     * - `{ mode: "inherit", sandboxId: "..." }` — use a parent's sandbox without ownership.
+     *
+     * When omitted and `sandboxOps` is provided, defaults to `{ mode: "new" }`.
+     */
+    sandbox?: SandboxInit;
+    /**
+     * What to do with the sandbox when this session exits.
+     *
+     * Defaults to `"destroy"` when omitted.
+     * Has no effect when the sandbox is inherited (`sandbox.mode === "inherit"`).
+     */
+    sandboxShutdown?: SubagentSandboxShutdown;
+    virtualFsOps?: VirtualFsOps;
+    /**
+     * Virtual filesystem configuration (optional — independent of sandbox).
+     *
+     * When provided, the session resolves the file tree on start and merges
+     * `fileTree`, `ctx`, and `workspaceBase` into `AgentState`.
+     * Tool handlers wrapped with `withVirtualFs` can then read this state.
+     *
+     * Can be used alongside `sandboxOps` for agents that need both a real
+     * sandbox (e.g. for execution) and a virtual filesystem.
+     */
+    virtualFs?: {
+        ctx: unknown;
+    };
+}
+type SessionResult<M, TState extends JsonSerializable<TState>, HasSandbox extends boolean = boolean> = {
+    threadId: string;
+    finalMessage: M | null;
+    exitReason: SessionExitReason;
+    usage: ReturnType<AgentStateManager<TState>["getTotalUsage"]>;
+} & (HasSandbox extends true ? {
+    sandboxId: string;
+} : {
+    sandboxId?: undefined;
+});
+interface ZeitlichSession<M = unknown, HasSandbox extends boolean = boolean> {
+    runSession<T extends JsonSerializable<T>>(args: {
+        stateManager: AgentStateManager<T>;
+    }): Promise<SessionResult<M, T, HasSandbox>>;
+}
+
+export { type SessionEndHook as $, type AgentResponse as A, type BaseAgentState as B, type PostToolUseFailureHookResult as C, type PostToolUseHook as D, type PostToolUseHookContext as E, type FileEntryMetadata as F, type PreHumanMessageAppendHook as G, type Hooks as H, type InferToolResults as I, type JsonValue as J, type PreHumanMessageAppendHookContext as K, type PreToolUseHook as L, type ModelInvokerConfig as M, type PreToolUseHookContext as N, type PreToolUseHookResult as O, type PrefixedThreadOps as P, type ProcessToolCallsContext as Q, type RouterContext as R, type ScopedPrefix as S, type ThreadOps as T, type RawToolCall as U, type VirtualFsContext as V, type RunAgentActivity as W, type SandboxInit as X, type SandboxShutdown as Y, type SerializableToolDefinition as Z, type SessionConfig as _, type ModelInvoker as a, type SessionEndHookContext as a0, type SessionExitReason as a1, type SessionResult as a2, type SessionStartHook as a3, type SessionStartHookContext as a4, type SubagentConfig as a5, type SubagentDefinition as a6, type SubagentFnResult as a7, type SubagentHandlerResponse as a8, type SubagentHooks as a9, isTerminalStatus as aA, type ToolRouterOptions as aB, type SubagentSandboxConfig as aa, type SubagentSandboxShutdown as ab, type SubagentSessionInput as ac, type SubagentWorkflow as ad, type SubagentWorkflowInput as ae, type TaskStatus as af, type ThreadInit as ag, type TokenUsage as ah, type ToolArgs as ai, type ToolCallResult as aj, type ToolCallResultUnion as ak, type ToolDefinition as al, type ToolHandler as am, type ToolHooks as an, type ToolMap as ao, type ToolNames as ap, type ToolResult as aq, type ToolRouter as ar, type ToolRouterHooks as as, type ToolWithHandler as at, VirtualFileSystem as au, type VirtualFileTree as av, type VirtualFsOps as aw, type VirtualFsState as ax, type WorkflowTask as ay, type ZeitlichSession as az, type ToolHandlerResponse as b, type ActivityToolHandler as c, type ToolResultConfig as d, type RunAgentConfig as e, type SkillProvider as f, type SkillMetadata as g, type Skill as h, type FileResolver as i, type TreeMutation as j, type PrefixedVirtualFsOps as k, type AgentConfig as l, type AgentFile as m, type AgentState as n, type AgentStateManager as o, type AgentStatus as p, type AppendToolResultFn as q, type FileEntry as r, type JsonPrimitive as s, type JsonSerializable as t, type ParsedToolCall as u, type ParsedToolCallUnion as v, type PostHumanMessageAppendHook as w, type PostHumanMessageAppendHookContext as x, type PostToolUseFailureHook as y, type PostToolUseFailureHookContext as z };