zeitlich 0.1.0

package/dist/workflow-DeVGEXSc.d.ts

@@ -0,0 +1,1201 @@
+import { $InferMessageContent, MessageStructure, StoredMessage, MessageContent, ContentBlock } from '@langchain/core/messages';
+import z$1, { z } from 'zod';
+import Redis from 'ioredis';
+
+/**
+ * Content for a tool message response.
+ * Can be a simple string or complex content parts (text, images, cache points, etc.)
+ */
+type ToolMessageContent = $InferMessageContent<MessageStructure, "tool">;
+
+/**
+ * A tool definition with a name, description, and Zod schema for arguments.
+ */
+interface ToolDefinition<TName extends string = string, TSchema extends z.ZodType = z.ZodType> {
+    name: TName;
+    description: string;
+    schema: TSchema;
+    strict?: boolean;
+    max_uses?: number;
+}
+/**
+ * A map of tool keys to tool definitions.
+ */
+type ToolMap = Record<string, ToolDefinition>;
+/**
+ * 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];
+/**
+ * The tool registry interface with full type inference.
+ */
+interface ToolRegistry<T extends ToolMap> {
+    /**
+     * Parse and validate a raw tool call against the registry.
+     * Returns a typed tool call with validated arguments.
+     */
+    parseToolCall(toolCall: RawToolCall): ParsedToolCallUnion<T>;
+    /**
+     * Get the list of all tools in the registry.
+     */
+    getToolList(): T[keyof T][];
+    /**
+     * Get a specific tool by its key in the registry.
+     */
+    getTool<K extends keyof T>(name: K): T[K];
+    /**
+     * Check if a tool with the given name exists in the registry.
+     */
+    hasTool(name: string): boolean;
+    /**
+     * Get all tool names in the registry.
+     */
+    getToolNames(): ToolNames<T>[];
+}
+/**
+ * Creates a type-safe tool registry for parsing and managing tool definitions.
+ *
+ * @example
+ * const registry = createToolRegistry({
+ *   AssessAttribute: assessAttributeTool,
+ *   AskUserQuestion: userInteractionTool,
+ * });
+ *
+ * const toolCalls = message.tool_calls.map(tc => registry.parseToolCall(tc));
+ * const tools = registry.getToolList();
+ */
+declare function createToolRegistry<T extends ToolMap>(tools: T): ToolRegistry<T>;
+
+/**
+ * Agent execution status
+ */
+type AgentStatus = "RUNNING" | "WAITING_FOR_INPUT" | "COMPLETED" | "FAILED" | "CANCELLED";
+/**
+ * Base state that all agents must have
+ */
+interface BaseAgentState {
+    status: AgentStatus;
+    version: number;
+    turns: 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;
+}
+/**
+ * Agent response from LLM invocation
+ */
+interface AgentResponse {
+    message: StoredMessage;
+    stopReason: string | null;
+    usage?: {
+        input_tokens?: number;
+        output_tokens?: number;
+        total_tokens?: number;
+    };
+}
+/**
+ * Configuration for a Zeitlich agent session
+ */
+interface ZeitlichAgentConfig {
+    threadId: string;
+    agentName: string;
+    metadata?: Record<string, unknown>;
+    maxTurns?: number;
+}
+/**
+ * Configuration passed to runAgent activity
+ */
+interface RunAgentConfig {
+    threadId: string;
+    agentName: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Type signature for workflow-specific runAgent activity
+ */
+type RunAgentActivity = (config: RunAgentConfig, invocationConfig: InvocationConfig) => Promise<AgentResponse>;
+/**
+ * Per-invocation configuration passed to runAgent
+ */
+interface InvocationConfig {
+    systemPrompt: string;
+}
+/**
+ * Configuration for appending a tool result
+ */
+interface ToolResultConfig {
+    threadId: string;
+    toolCallId: string;
+    /** Content for the tool message (string or complex content parts) */
+    content: ToolMessageContent;
+}
+/**
+ * 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 */
+    name: string;
+    /** Description shown to the parent agent explaining what this subagent does */
+    description: string;
+    /** Temporal workflow type name (used with executeChild) */
+    workflowType: string;
+    /** 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;
+}
+/**
+ * Input passed to child workflows when spawned as subagents
+ */
+interface SubagentInput {
+    /** The prompt/task from the parent agent */
+    prompt: string;
+}
+/**
+ * Exit reasons for session termination
+ */
+type SessionExitReason = "completed" | "max_turns" | "waiting_for_input" | "failed" | "cancelled";
+/**
+ * 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;
+}
+/**
+ * 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;
+}
+/**
+ * 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;
+}
+/**
+ * Result from PostToolUseFailure hook - can recover from errors
+ */
+interface PostToolUseFailureHookResult {
+    /** Provide a fallback result instead of throwing */
+    fallbackContent?: ToolMessageContent;
+    /** Whether to suppress the error (still logs, but continues) */
+    suppress?: boolean;
+}
+/**
+ * PostToolUseFailure hook - called when tool execution fails
+ */
+type PostToolUseFailureHook<T extends ToolMap> = (ctx: PostToolUseFailureHookContext<T>) => PostToolUseFailureHookResult | Promise<PostToolUseFailureHookResult>;
+/**
+ * Context for SessionStart hook - called when session begins
+ */
+interface SessionStartHookContext {
+    /** Thread identifier */
+    threadId: string;
+    /** Name of the agent */
+    agentName: string;
+    /** Session metadata */
+    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 {
+    /** Thread identifier */
+    threadId: string;
+    /** Name of the agent */
+    agentName: string;
+    /** Reason the session ended */
+    exitReason: SessionExitReason;
+    /** Total turns executed */
+    turns: number;
+    /** Session metadata */
+    metadata: Record<string, unknown>;
+}
+/**
+ * SessionEnd hook - called when session ends
+ */
+type SessionEndHook = (ctx: SessionEndHookContext) => void | Promise<void>;
+/**
+ * Combined hooks interface for session lifecycle
+ */
+interface SessionHooks<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>;
+    /** Called when session starts */
+    onSessionStart?: SessionStartHook;
+    /** Called when session ends */
+    onSessionEnd?: SessionEndHook;
+}
+/**
+ * Helper to check if status is terminal
+ */
+declare function isTerminalStatus(status: AgentStatus): boolean;
+
+/**
+ * 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;
+};
+/**
+ * Configuration for creating an agent state manager
+ */
+interface AgentStateManagerConfig<TCustom extends JsonSerializable<TCustom>> {
+    /** Initial values for custom state keys */
+    initialState: TCustom;
+}
+/**
+ * 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>> {
+    /** 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 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;
+    /** Get full state for query handler */
+    getCurrentState(): AgentState<TCustom>;
+    /** Check if should return from waitForStateChange */
+    shouldReturnFromWait(lastKnownVersion: number): boolean;
+}
+/**
+ * Creates an agent state manager for tracking workflow state.
+ *
+ * The manager owns all state internally:
+ * - Default state: status, version (from BaseAgentState)
+ * - Custom state: provided via initialState config
+ *
+ * Note: Due to Temporal's workflow isolation, handlers must be set up
+ * in the workflow file using defineQuery/defineUpdate and setHandler.
+ * This manager provides the state and logic needed for those handlers.
+ */
+declare function createAgentStateManager<TCustom extends JsonSerializable<TCustom> = Record<string, never>>(config?: AgentStateManagerConfig<TCustom>): AgentStateManager<TCustom>;
+/**
+ * Handler names used across agents
+ */
+declare const AGENT_HANDLER_NAMES: {
+    readonly getAgentState: "getAgentState";
+    readonly waitForStateChange: "waitForStateChange";
+    readonly addMessage: "addMessage";
+};
+
+/**
+ * Configuration for creating a prompt manager
+ */
+interface PromptManagerConfig<TContext = unknown> {
+    /**
+     * Base system prompt (e.g., Auditron identity).
+     * Can be a static string or async function.
+     */
+    baseSystemPrompt: string | (() => string | Promise<string>);
+    /**
+     * Agent-specific instructions prompt.
+     * Can be a static string or async function.
+     */
+    instructionsPrompt: string | (() => string | Promise<string>);
+    /**
+     * Build context message content from agent-specific context.
+     * Returns MessageContent array for the initial HumanMessage.
+     */
+    buildContextMessage: (context: TContext) => MessageContent | Promise<MessageContent>;
+}
+/**
+ * Prompt manager interface
+ */
+interface PromptManager<TContext = unknown> {
+    /**
+     * Get the full system prompt (base + instructions combined).
+     */
+    getSystemPrompt(): Promise<string>;
+    /**
+     * Build the initial context message content.
+     */
+    buildContextMessage(context: TContext): Promise<MessageContent>;
+}
+/**
+ * Creates a prompt manager for handling system prompts and context messages.
+ *
+ */
+declare function createPromptManager<TContext = unknown>(config: PromptManagerConfig<TContext>): PromptManager<TContext>;
+
+/**
+ * Function signature for appending tool results to a thread.
+ */
+type AppendToolResultFn = (config: ToolResultConfig) => Promise<void>;
+/**
+ * The response from a tool handler.
+ * Contains the content for the tool message and the result to return from processToolCalls.
+ */
+interface ToolHandlerResponse<TResult> {
+    /** Content for the tool message added to the thread */
+    content: ToolMessageContent;
+    /** Result returned from processToolCalls */
+    result: TResult;
+}
+/**
+ * A handler function for a specific tool.
+ * Receives the parsed args and tool call ID, returns a response with content and result.
+ */
+type ToolHandler<TArgs, TResult> = (args: TArgs, toolCallId: string) => ToolHandlerResponse<TResult> | Promise<ToolHandlerResponse<TResult>>;
+/**
+ * Activity-compatible tool handler that always returns a Promise.
+ * Use this for tool handlers registered as Temporal activities.
+ */
+type ActivityToolHandler<TArgs, TResult> = (args: TArgs, toolCallId: string) => Promise<ToolHandlerResponse<TResult>>;
+/**
+ * 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"]>;
+/**
+ * A map of tool handlers keyed by tool name with typed results.
+ * Each handler receives the properly typed args for that tool.
+ */
+type ToolHandlerMap<T extends ToolMap, TResults extends Record<ToolNames<T>, unknown>> = {
+    [TName in ToolNames<T>]: ToolHandler<ToolArgs<T, TName>, TResults[TName]>;
+};
+/**
+ * The result of processing a tool call.
+ */
+interface ToolCallResult<TName extends string = string, TResult = unknown> {
+    toolCallId: string;
+    name: TName;
+    result: TResult;
+}
+/**
+ * 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];
+/**
+ * Tool-specific hooks for the router
+ */
+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 tool router.
+ */
+interface ToolRouterOptions<T extends ToolMap, TResult = unknown> {
+    /** Tool registry - used for type inference */
+    registry: ToolRegistry<T>;
+    /** Thread ID for appending tool results */
+    threadId: string;
+    /** Function to append tool results to the thread (called automatically after each handler) */
+    appendToolResult: AppendToolResultFn;
+    /** Whether to process tools in parallel (default: true) */
+    parallel?: boolean;
+    /** Lifecycle hooks for tool execution */
+    hooks?: ToolRouterHooks<T, TResult>;
+}
+/**
+ * Context passed to processToolCalls for hook execution
+ */
+interface ProcessToolCallsContext {
+    /** Current turn number (for hooks) */
+    turn?: number;
+}
+/**
+ * The tool router interface with full type inference for both args and results.
+ */
+interface ToolRouter<T extends ToolMap, TResults extends Record<string, unknown>> {
+    /**
+     * 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<TResults>[]>;
+    /**
+     * Process tool calls matching a specific name with a custom handler.
+     */
+    processToolCallsByName<TName extends ToolNames<T>, TResult>(toolCalls: ParsedToolCallUnion<T>[], toolName: TName, handler: ToolHandler<ToolArgs<T, TName>, TResult>): 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> & keyof TResults>(results: ToolCallResultUnion<TResults>[], name: TName): ToolCallResult<TName, TResults[TName]>[];
+}
+/**
+ * Infer result types from a handler map.
+ * Uses `any` for args due to function contravariance - handlers with specific
+ * args types won't extend ToolHandler<unknown, R>.
+ */
+type InferHandlerResults<H> = {
+    [K in keyof H & string]: H[K] extends ToolHandler<any, infer R> ? Awaited<R> : never;
+};
+/**
+ * Creates a tool router for declarative tool call processing.
+ * ToolMap type is inferred from options.registry, result types from handlers.
+ *
+ * @example
+ * const router = createToolRouter(
+ *   {
+ *     registry: controlTestToolRegistry,
+ *     threadId,
+ *     appendToolResult,
+ *     hooks: {
+ *       onPreToolUse: (ctx) => { console.log('Before:', ctx.toolCall.name); },
+ *       onPostToolUse: (ctx) => { console.log('After:', ctx.toolCall.name, ctx.durationMs); },
+ *     },
+ *   },
+ *   {
+ *     AskUserQuestion: async (args, toolCallId) => ({ content: '...', result: {...} }),
+ *     // ... other handlers
+ *   },
+ * );
+ *
+ * const results = await router.processToolCalls(toolCalls, { turn: 1 });
+ * // results[0].result is typed based on handler return types
+ */
+declare function createToolRouter<T extends ToolMap, THandlers extends {
+    [TName in ToolNames<T>]: ToolHandler<ToolArgs<T, TName>, unknown>;
+}>(options: ToolRouterOptions<T, ToolCallResultUnion<InferHandlerResults<THandlers>>>, handlers: THandlers): ToolRouter<T, InferHandlerResults<THandlers>>;
+/**
+ * Utility to check if there were no tool calls besides a specific one
+ */
+declare function hasNoOtherToolCalls<T extends ToolMap>(toolCalls: ParsedToolCallUnion<T>[], excludeName: ToolNames<T>): boolean;
+
+declare const TASK_TOOL: "Task";
+/**
+ * Creates a Task tool configured with the available subagents.
+ *
+ * @param subagents - Array of subagent configurations (must have at least one)
+ * @returns A tool definition with dynamic schema based on available subagents
+ *
+ * @example
+ * const taskTool = createTaskTool([
+ *   {
+ *     name: "researcher",
+ *     description: "Researches topics and gathers information",
+ *     workflowType: "researcherWorkflow",
+ *     resultSchema: z.object({ findings: z.string() }),
+ *   },
+ * ]);
+ */
+declare function createTaskTool<T extends SubagentConfig[]>(subagents: T): {
+    name: typeof TASK_TOOL;
+    description: string;
+    schema: z$1.ZodObject<{
+        subagent: z$1.ZodEnum<Record<string, string>>;
+        description: z$1.ZodString;
+        prompt: z$1.ZodString;
+    }>;
+};
+/**
+ * Infer the schema type for a task tool created with specific subagents
+ */
+type TaskToolSchemaType<T extends SubagentConfig[]> = z$1.infer<ReturnType<typeof createTaskTool<T>>["schema"]>;
+/**
+ * Generic task tool schema type (when subagent names are not known at compile time)
+ */
+type GenericTaskToolSchemaType = {
+    subagent: string;
+    description: string;
+    prompt: string;
+};
+
+/**
+ * Result from a task handler execution
+ */
+interface TaskHandlerResult<TResult = unknown> {
+    /** The validated result from the child workflow */
+    result: TResult;
+    /** The child workflow ID (for reference/debugging) */
+    childWorkflowId: string;
+}
+/**
+ * Creates a Task tool handler that spawns child workflows for configured subagents.
+ *
+ * @param subagents - Array of subagent configurations
+ * @returns A tool handler function that can be used with the tool router
+ *
+ * @example
+ * const taskHandler = createTaskHandler([
+ *   {
+ *     name: "researcher",
+ *     description: "Researches topics",
+ *     workflowType: "researcherWorkflow",
+ *     resultSchema: z.object({ findings: z.string() }),
+ *   },
+ * ]);
+ */
+declare function createTaskHandler(subagents: SubagentConfig[]): (args: GenericTaskToolSchemaType, _toolCallId: string) => Promise<ToolHandlerResponse<TaskHandlerResult>>;
+
+/**
+ * Configuration for subagent support
+ */
+interface SubagentSupportConfig {
+    /** Array of subagent configurations */
+    subagents: SubagentConfig[];
+}
+/**
+ * Result from withSubagentSupport - contains enhanced tools and the task handler
+ */
+interface SubagentSupportResult<T extends ToolMap> {
+    /** Combined tools (user tools + Task tool) */
+    tools: T & {
+        Task: ReturnType<typeof createTaskTool>;
+    };
+    /** Task handler to be added to the tool router handlers */
+    taskHandler: ToolHandler<GenericTaskToolSchemaType, TaskHandlerResult>;
+}
+/**
+ * Adds subagent support to a tool map by including the Task tool and handler.
+ *
+ * Use this when you want to enable subagent spawning in your workflow.
+ * The returned tools should be passed to createToolRegistry, and the
+ * taskHandler should be included in your tool router handlers.
+ *
+ * @param userTools - Your workflow's existing tools
+ * @param config - Subagent configuration
+ * @returns Combined tools and the task handler
+ *
+ * @example
+ * const { tools, taskHandler } = withSubagentSupport(
+ *   { AskUserQuestion: askUserQuestionTool },
+ *   {
+ *     subagents: [
+ *       {
+ *         name: "researcher",
+ *         description: "Researches and gathers information",
+ *         workflowType: "researcherWorkflow",
+ *         resultSchema: z.object({ findings: z.string() }),
+ *       },
+ *     ],
+ *   }
+ * );
+ *
+ * const toolRegistry = createToolRegistry(tools);
+ * const toolRouter = createToolRouter(
+ *   { registry: toolRegistry, threadId, appendToolResult },
+ *   {
+ *     AskUserQuestion: handleAskUserQuestion,
+ *     Task: taskHandler,
+ *   }
+ * );
+ */
+declare function withSubagentSupport<T extends ToolMap>(userTools: T, config: SubagentSupportConfig): SubagentSupportResult<T>;
+/**
+ * Type guard to check if a tool map includes the Task tool
+ */
+declare function hasTaskTool(tools: ToolMap): tools is ToolMap & {
+    Task: ToolDefinition;
+};
+
+interface ZeitlichSession {
+    runSession<T extends JsonSerializable<T>>(prompt: string, stateManager: AgentStateManager<T>): Promise<StoredMessage | null>;
+}
+/**
+ * Session-level hooks for lifecycle events
+ */
+interface SessionLifecycleHooks {
+    /** Called when session starts */
+    onSessionStart?: SessionStartHook;
+    /** Called when session ends */
+    onSessionEnd?: SessionEndHook;
+}
+declare const createSession: <T extends ToolMap, TResults extends Record<string, unknown>>({ threadId, agentName, maxTurns, metadata }: ZeitlichAgentConfig, { runAgent, promptManager, toolRouter, toolRegistry, hooks, }: {
+    /** Workflow-specific runAgent activity (with tools pre-bound) */
+    runAgent: RunAgentActivity;
+    promptManager: PromptManager;
+    toolRouter: ToolRouter<T, TResults>;
+    toolRegistry: ToolRegistry<T>;
+    /** Session lifecycle hooks */
+    hooks?: SessionLifecycleHooks;
+}) => Promise<ZeitlichSession>;
+
+/**
+ * Shared Zeitlich activities - thread management and message handling
+ * Note: runAgent is workflow-specific and should be created per-workflow
+ */
+interface ZeitlichSharedActivities {
+    /**
+     * Append a tool result to the thread.
+     * Handles JSON serialization and optional cache points.
+     */
+    appendToolResult(config: ToolResultConfig): Promise<void>;
+    /**
+     * Initialize an empty thread.
+     */
+    initializeThread(threadId: string): Promise<void>;
+    /**
+     * Append messages to a thread.
+     */
+    appendThreadMessages(threadId: string, messages: StoredMessage[]): Promise<void>;
+    /**
+     * Append a human message to a thread.
+     */
+    appendHumanMessage(threadId: string, content: string | MessageContent): Promise<void>;
+    /**
+     * Extract raw tool calls from a stored message.
+     * Returns unvalidated tool calls - use toolRegistry.parseToolCall() to validate.
+     */
+    parseToolCalls(storedMessage: StoredMessage): Promise<RawToolCall[]>;
+}
+/**
+ * Creates shared Temporal activities for thread management
+ *
+ * @returns An object containing the shared activity functions
+ *
+ * @experimental The Zeitlich integration is an experimental feature; APIs may change without notice.
+ */
+declare function createSharedActivities(redis: Redis): ZeitlichSharedActivities;
+
+declare const askUserQuestionTool: {
+    name: "AskUserQuestion";
+    description: string;
+    schema: z$1.ZodObject<{
+        questions: z$1.ZodArray<z$1.ZodObject<{
+            question: z$1.ZodString;
+            header: z$1.ZodString;
+            options: z$1.ZodArray<z$1.ZodObject<{
+                label: z$1.ZodString;
+                description: z$1.ZodString;
+            }, z$1.core.$strip>>;
+            multiSelect: z$1.ZodBoolean;
+        }, z$1.core.$strip>>;
+    }, z$1.core.$strip>;
+    strict: boolean;
+};
+type AskUserQuestionToolSchemaType = z$1.infer<typeof askUserQuestionTool.schema>;
+
+declare const globTool: {
+    name: "Glob";
+    description: string;
+    schema: z.ZodObject<{
+        pattern: z.ZodString;
+        root: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    strict: boolean;
+};
+type GlobToolSchemaType = z.infer<typeof globTool.schema>;
+
+declare const grepTool: {
+    name: "Grep";
+    description: string;
+    schema: z.ZodObject<{
+        pattern: z.ZodString;
+        ignoreCase: z.ZodOptional<z.ZodBoolean>;
+        maxMatches: z.ZodOptional<z.ZodNumber>;
+        includePatterns: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        excludePatterns: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        contextLines: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>;
+    strict: boolean;
+};
+type GrepToolSchemaType = z.infer<typeof grepTool.schema>;
+
+declare const readTool: {
+    name: "FileRead";
+    description: string;
+    schema: z.ZodObject<{
+        path: z.ZodString;
+        offset: z.ZodOptional<z.ZodNumber>;
+        limit: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>;
+    strict: boolean;
+};
+type ReadToolSchemaType = z.infer<typeof readTool.schema>;
+
+declare const writeTool: {
+    name: "FileWrite";
+    description: string;
+    schema: z.ZodObject<{
+        file_path: z.ZodString;
+        content: z.ZodString;
+    }, z.core.$strip>;
+    strict: boolean;
+};
+type WriteToolSchemaType = z.infer<typeof writeTool.schema>;
+
+declare const editTool: {
+    name: "FileEdit";
+    description: string;
+    schema: z.ZodObject<{
+        file_path: z.ZodString;
+        old_string: z.ZodString;
+        new_string: z.ZodString;
+        replace_all: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>;
+    strict: boolean;
+};
+type EditToolSchemaType = z.infer<typeof editTool.schema>;
+
+/**
+ * File node in the tree structure provided to the agent.
+ * Represents both files and directories in a virtual file system.
+ */
+interface FileNode {
+    /** Virtual path (e.g., "docs/readme.md") */
+    path: string;
+    /** Whether this is a file or directory */
+    type: "file" | "directory";
+    /** Optional description shown in the prompt */
+    description?: string;
+    /** MIME type for multimodal content (e.g., "image/png", "application/pdf") */
+    mimeType?: string;
+    /** Provider-specific metadata (S3 key, database ID, etc.) */
+    metadata?: Record<string, unknown>;
+    /** Child nodes for directories */
+    children?: FileNode[];
+}
+/**
+ * Options for rendering the file tree in the prompt
+ */
+interface FileTreeRenderOptions {
+    /** Maximum depth to render (default: unlimited) */
+    maxDepth?: number;
+    /** Include file descriptions (default: true) */
+    showDescriptions?: boolean;
+    /** Show MIME types next to files (default: false) */
+    showMimeTypes?: boolean;
+    /** Glob patterns to exclude from display */
+    excludePatterns?: string[];
+    /** Custom header text (default: "Available files and directories:") */
+    headerText?: string;
+    /** Custom description text (default: "You have access to the following files. Use the Read, Glob, and Grep tools to explore them.") */
+    descriptionText?: string;
+}
+/**
+ * Text file content
+ */
+interface TextFileContent {
+    type: "text";
+    content: string;
+}
+/**
+ * Image file content (base64 encoded)
+ */
+interface ImageFileContent {
+    type: "image";
+    mimeType: string;
+    /** Base64-encoded image data */
+    data: string;
+}
+/**
+ * PDF file content (extracted text)
+ */
+interface PdfFileContent {
+    type: "pdf";
+    /** Extracted text content */
+    content: string;
+}
+/**
+ * Union type for all file content types
+ */
+type FileContent = TextFileContent | ImageFileContent | PdfFileContent;
+/**
+ * Options for grep operations
+ */
+interface GrepOptions {
+    /** Case-insensitive search */
+    ignoreCase?: boolean;
+    /** Maximum number of matches to return */
+    maxMatches?: number;
+    /** File patterns to include (glob) */
+    includePatterns?: string[];
+    /** File patterns to exclude (glob) */
+    excludePatterns?: string[];
+    /** Include N lines of context around matches */
+    contextLines?: number;
+}
+/**
+ * A single grep match result
+ */
+interface GrepMatch {
+    /** Path to the file containing the match */
+    path: string;
+    /** Line number (1-indexed) */
+    lineNumber: number;
+    /** The matching line content */
+    line: string;
+    /** Context lines before the match */
+    contextBefore?: string[];
+    /** Context lines after the match */
+    contextAfter?: string[];
+}
+/**
+ * Provider interface for file system operations.
+ * Implement this interface to support different backends (local FS, S3, Redis, etc.)
+ */
+interface FileSystemProvider {
+    /**
+     * Find files matching a glob pattern
+     * @param pattern Glob pattern to match
+     * @param root Optional root path to search from
+     * @returns Array of matching file nodes
+     */
+    glob(pattern: string, root?: string): Promise<FileNode[]>;
+    /**
+     * Search file contents for a pattern
+     * @param pattern Regex pattern to search for
+     * @param options Search options
+     * @returns Array of matches
+     */
+    grep(pattern: string, options?: GrepOptions): Promise<GrepMatch[]>;
+    /**
+     * Read file content
+     * @param path Virtual path to the file
+     * @returns File content in appropriate format
+     */
+    read(path: string): Promise<FileContent>;
+    /**
+     * Write content to a file
+     * @param path Virtual path to the file
+     * @param content Text content to write
+     * @returns void
+     * @optional - Providers may not support write operations
+     */
+    write?(path: string, content: string): Promise<void>;
+    /**
+     * Check if a file or directory exists
+     * @param path Virtual path to check
+     */
+    exists(path: string): Promise<boolean>;
+}
+/**
+ * Configuration for creating file system tools
+ */
+interface FileSystemToolsConfig {
+    /** The file system provider implementation */
+    provider: FileSystemProvider;
+    /** The scoped file nodes the agent can access */
+    scopedNodes: FileNode[];
+}
+/**
+ * Convert FileContent to LangChain MessageContent format
+ */
+declare function fileContentToMessageContent(content: FileContent): ContentBlock[];
+
+/**
+ * Build a text representation of the file tree for injection into the agent's prompt.
+ *
+ * @param nodes Array of root-level file nodes
+ * @param options Rendering options
+ * @returns Formatted file tree string wrapped in <file_system> tags
+ *
+ * @example
+ * ```typescript
+ * const tree = buildFileTreePrompt([
+ *   {
+ *     path: "docs",
+ *     type: "directory",
+ *     children: [
+ *       { path: "docs/readme.md", type: "file", description: "Project docs" }
+ *     ]
+ *   },
+ *   { path: "src/index.ts", type: "file", description: "Entry point" }
+ * ], { maxDepth: 2 });
+ *
+ * // Output:
+ * // <file_system>
+ * // Available files and directories:
+ * //
+ * // docs/
+ * //   readme.md - Project docs
+ * // src/index.ts - Entry point
+ * // </file_system>
+ * ```
+ */
+declare function buildFileTreePrompt(nodes: FileNode[], options?: FileTreeRenderOptions): string;
+/**
+ * Flatten a file tree into a list of all file paths.
+ * Useful for scope validation.
+ *
+ * @param nodes Array of file nodes
+ * @returns Array of all file paths (files only, not directories)
+ */
+declare function flattenFileTree(nodes: FileNode[]): string[];
+/**
+ * Check if a path is within the scoped file tree.
+ *
+ * @param path Path to check
+ * @param scopedNodes The file nodes that define the allowed scope
+ * @returns true if the path is within scope
+ */
+declare function isPathInScope(path: string, scopedNodes: FileNode[]): boolean;
+/**
+ * Find a node by path in the file tree.
+ *
+ * @param path Path to find
+ * @param nodes Array of file nodes to search
+ * @returns The matching node or undefined
+ */
+declare function findNodeByPath(path: string, nodes: FileNode[]): FileNode | undefined;
+
+/**
+ * Abstract base class for filesystem providers.
+ * Implements scope validation and common utilities.
+ * Subclasses only need to implement the actual I/O operations.
+ */
+declare abstract class BaseFileSystemProvider implements FileSystemProvider {
+    protected scopedNodes: FileNode[];
+    protected allowedPaths: Set<string>;
+    constructor(scopedNodes: FileNode[]);
+    /**
+     * Validate that a path is within the allowed scope.
+     * Throws an error if the path is not allowed.
+     */
+    protected validatePath(path: string): void;
+    /**
+     * Filter paths by glob pattern.
+     */
+    protected filterByPattern(paths: string[], pattern: string, root?: string): string[];
+    /**
+     * Get all file paths in scope
+     */
+    protected getAllPaths(): string[];
+    /**
+     * Find FileNode by path
+     */
+    protected findNode(path: string): FileNode | undefined;
+    /**
+     * Read raw file content from the backend.
+     * This is called after scope validation.
+     */
+    protected abstract readFile(node: FileNode): Promise<FileContent>;
+    /**
+     * Read file as text for grep operations.
+     * Default implementation uses readFile, but can be overridden for efficiency.
+     */
+    protected readFileAsText(node: FileNode): Promise<string | null>;
+    glob(pattern: string, root?: string): Promise<FileNode[]>;
+    grep(pattern: string, options?: GrepOptions): Promise<GrepMatch[]>;
+    read(path: string): Promise<FileContent>;
+    exists(path: string): Promise<boolean>;
+}
+/**
+ * A simple in-memory filesystem provider for testing.
+ * Files are stored as a map of path -> content.
+ */
+declare class InMemoryFileSystemProvider extends BaseFileSystemProvider {
+    private files;
+    constructor(scopedNodes: FileNode[], files: Map<string, FileContent>);
+    protected readFile(node: FileNode): Promise<FileContent>;
+    /**
+     * Add or update a file in the in-memory storage
+     */
+    setFile(path: string, content: FileContent): void;
+    /**
+     * Write text content to a file
+     */
+    write(path: string, content: string): Promise<void>;
+    /**
+     * Create an InMemoryFileSystemProvider from a simple object map
+     */
+    static fromTextFiles(scopedNodes: FileNode[], files: Record<string, string>): InMemoryFileSystemProvider;
+}
+/**
+ * A resolver function that reads file content given a FileNode.
+ * Use this for simple cases where you just need to provide a read function.
+ */
+type FileResolver = (node: FileNode) => Promise<FileContent>;
+/**
+ * Configuration for a backend in the CompositeFileSystemProvider
+ */
+interface BackendConfig {
+    /** The resolver function or provider for this backend */
+    resolver: FileResolver | FileSystemProvider;
+}
+/**
+ * A composite filesystem provider that routes to different backends based on file metadata.
+ *
+ * Files are routed based on `node.metadata.backend` field. If no backend is specified,
+ * the default backend is used.
+ *
+ * @example
+ * ```typescript
+ * const files: FileNode[] = [
+ *   { path: "invoices/2024.pdf", type: "file", metadata: { backend: "s3", s3Key: "..." } },
+ *   { path: "cache/summary.txt", type: "file", metadata: { backend: "redis" } },
+ *   { path: "local/config.json", type: "file" }, // uses default backend
+ * ];
+ *
+ * const provider = new CompositeFileSystemProvider(files, {
+ *   backends: {
+ *     s3: { resolver: async (node) => s3Client.getObject(node.metadata.s3Key) },
+ *     redis: { resolver: async (node) => redis.get(node.path) },
+ *   },
+ *   defaultBackend: "local",
+ *   defaultResolver: async (node) => fs.readFile(node.path),
+ * });
+ * ```
+ */
+declare class CompositeFileSystemProvider extends BaseFileSystemProvider {
+    private backends;
+    private defaultBackend?;
+    private defaultResolver?;
+    constructor(scopedNodes: FileNode[], config: {
+        /** Map of backend name to configuration */
+        backends: Record<string, BackendConfig>;
+        /** Default backend name for files without metadata.backend */
+        defaultBackend?: string;
+        /** Fallback resolver if no backend matches (alternative to defaultBackend) */
+        defaultResolver?: FileResolver;
+    });
+    /**
+     * Get the backend name for a file node
+     */
+    private getBackendName;
+    /**
+     * Resolve content using a resolver (function or provider)
+     */
+    private resolveContent;
+    protected readFile(node: FileNode): Promise<FileContent>;
+    /**
+     * Add or update a backend configuration
+     */
+    setBackend(name: string, config: BackendConfig): void;
+    /**
+     * Remove a backend
+     */
+    removeBackend(name: string): boolean;
+    /**
+     * Check if a backend exists
+     */
+    hasBackend(name: string): boolean;
+}
+
+export { type SessionHooks as $, type AgentResponse as A, type BackendConfig as B, CompositeFileSystemProvider as C, type PostToolUseFailureHookResult as D, type EditToolSchemaType as E, type FileSystemProvider as F, type GlobToolSchemaType as G, type PostToolUseHook as H, type InvocationConfig as I, type JsonPrimitive as J, type PostToolUseHookContext as K, type PreToolUseHook as L, type PreToolUseHookContext as M, type PreToolUseHookResult as N, type ProcessToolCallsContext as O, type ParsedToolCall as P, type PromptManager as Q, type ReadToolSchemaType as R, type PromptManagerConfig as S, type ToolDefinition as T, type RawToolCall as U, type RunAgentActivity as V, type WriteToolSchemaType as W, type RunAgentConfig as X, type SessionEndHook as Y, type SessionEndHookContext as Z, type SessionExitReason as _, type ActivityToolHandler as a, type SessionLifecycleHooks as a0, type SessionStartHook as a1, type SessionStartHookContext as a2, type SubagentConfig as a3, type SubagentInput as a4, type SubagentSupportConfig as a5, type SubagentSupportResult as a6, type TaskHandlerResult as a7, type TaskToolSchemaType as a8, type ToolCallResult as a9, fileContentToMessageContent as aA, findNodeByPath as aB, flattenFileTree as aC, globTool as aD, grepTool as aE, hasNoOtherToolCalls as aF, hasTaskTool as aG, isPathInScope as aH, isTerminalStatus as aI, readTool as aJ, withSubagentSupport as aK, writeTool as aL, type ToolCallResultUnion as aa, type ToolHandler as ab, type ToolHandlerMap as ac, type ToolHandlerResponse as ad, type ToolMap as ae, type ToolMessageContent as af, type ToolNames as ag, type ToolRegistry as ah, type ToolResultConfig as ai, type ToolRouter as aj, type ToolRouterHooks as ak, type ToolRouterOptions as al, type ZeitlichAgentConfig as am, type ZeitlichSession as an, type ZeitlichSharedActivities as ao, askUserQuestionTool as ap, buildFileTreePrompt as aq, createAgentStateManager as ar, createPromptManager as as, createSession as at, createSharedActivities as au, createTaskHandler as av, createTaskTool as aw, createToolRegistry as ax, createToolRouter as ay, editTool as az, type AskUserQuestionToolSchemaType as b, type FileNode as c, type GrepToolSchemaType as d, type GrepMatch as e, type FileContent as f, AGENT_HANDLER_NAMES as g, type AgentFile as h, type AgentState as i, type AgentStateManager as j, type AgentStateManagerConfig as k, type AgentStatus as l, type AppendToolResultFn as m, type BaseAgentState as n, BaseFileSystemProvider as o, type FileResolver as p, type FileSystemToolsConfig as q, type FileTreeRenderOptions as r, type GenericTaskToolSchemaType as s, type GrepOptions as t, InMemoryFileSystemProvider as u, type JsonSerializable as v, type JsonValue as w, type ParsedToolCallUnion as x, type PostToolUseFailureHook as y, type PostToolUseFailureHookContext as z };