zeitlich 0.1.1 → 0.2.0

package/dist/workflow-uVNF7zoe.d.ts

@@ -0,0 +1,941 @@
+import { $InferMessageContent, MessageStructure, StoredMessage, MessageContent } from '@langchain/core/messages';
+import z, { z as z$1 } from 'zod';
+import { IFileSystem } from 'just-bash';
+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">;
+
+/**
+ * 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>> {
+    /** 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;
+    /** 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 */
+    setTools(newTools: ToolDefinition[]): void;
+}
+/**
+ * Creates an agent state manager for tracking workflow state.
+ *
+ * @param initialState - Optional initial values for base and custom state
+ *   Base state defaults: status="RUNNING", version=0, turns=0, tasks=empty, fileTree=[]
+ *
+ * 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>>(initialState?: Partial<BaseAgentState> & TCustom): AgentStateManager<TCustom>;
+/**
+ * Handler names used across agents
+ */
+declare const AGENT_HANDLER_NAMES: {
+    readonly getAgentState: "getAgentState";
+    readonly waitForStateChange: "waitForStateChange";
+    readonly addMessage: "addMessage";
+};
+
+declare const taskCreateTool: {
+    name: "TaskCreate";
+    description: string;
+    schema: z.ZodObject<{
+        subject: z.ZodString;
+        description: z.ZodString;
+        activeForm: z.ZodString;
+        metadata: z.ZodRecord<z.ZodString, z.ZodString>;
+    }, z.core.$strip>;
+};
+type TaskCreateToolSchemaType = z.infer<typeof taskCreateTool.schema>;
+
+/**
+ * Creates a TaskCreate handler that adds tasks to the workflow state.
+ *
+ * @param stateManager - State manager containing tasks state
+ * @param idGenerator - Function to generate unique task IDs (e.g., uuid4 from Temporal)
+ * @returns A tool handler function
+ *
+ * @example
+ * const handler = createTaskCreateHandler(stateManager, uuid4);
+ */
+declare function createTaskCreateHandler<TCustom extends JsonSerializable<TCustom>>({ stateManager, idGenerator, }: {
+    stateManager: AgentStateManager<TCustom>;
+    idGenerator: () => string;
+}): (args: TaskCreateToolSchemaType) => ToolHandlerResponse<WorkflowTask>;
+
+declare const bashTool: {
+    name: "Bash";
+    description: string;
+    schema: z.ZodObject<{
+        command: z.ZodString;
+    }, z.core.$strip>;
+    strict: boolean;
+};
+type bashToolSchemaType = z.infer<typeof bashTool.schema>;
+
+type BashExecOut = {
+    exitCode: number;
+    stderr: string;
+    stdout: string;
+};
+declare const handleBashTool: (fs: IFileSystem) => ActivityToolHandler<bashToolSchemaType, BashExecOut | null>;
+
+/**
+ * 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$1.ZodType = z$1.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$1.ZodType = z$1.ZodType, TResult = unknown, TContext = ToolHandlerContext> {
+    name: TName;
+    description: string;
+    schema: TSchema;
+    handler: ToolHandler<z$1.infer<TSchema>, TResult, TContext>;
+    strict?: boolean;
+    max_uses?: number;
+}
+/**
+ * A map of tool keys to tool definitions with handlers.
+ */
+type ToolMap = Record<string, {
+    name: string;
+    description: string;
+    schema: z$1.ZodType;
+    handler: (args: any, context: any) => ToolHandlerResponse<any> | Promise<ToolHandlerResponse<any>>;
+    strict?: boolean;
+    max_uses?: number;
+}>;
+/**
+ * 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$1.infer<T[K]["schema"]>>;
+}[keyof T];
+/**
+ * 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;
+}
+/**
+ * Context passed to tool handlers for additional data beyond tool args.
+ * Use this to pass workflow state like file trees, user context, etc.
+ */
+interface ToolHandlerContext {
+    /** Additional context data - define your own shape */
+    [key: string]: unknown;
+}
+interface BuildInToolDefinitions {
+    [bashTool.name]: typeof bashTool & {
+        handler: ReturnType<typeof handleBashTool>;
+    };
+    [taskCreateTool.name]: typeof taskCreateTool & {
+        handler: ReturnType<typeof createTaskCreateHandler>;
+    };
+}
+/**
+ * A handler function for a specific tool.
+ * Receives the parsed args and context, returns a response with content and result.
+ * Context always has a value (defaults to empty object if not provided).
+ */
+type ToolHandler<TArgs, TResult, TContext = ToolHandlerContext> = (args: TArgs, context: TContext) => ToolHandlerResponse<TResult> | Promise<ToolHandlerResponse<TResult>>;
+/**
+ * Activity-compatible tool handler that always returns a Promise.
+ * Use this for tool handlers registered as Temporal activities.
+ * Context always has a value (defaults to empty object if not provided).
+ *
+ * @example
+ * ```typescript
+ * // Filesystem handler with context
+ * const readHandler: ActivityToolHandler<
+ *   ReadToolSchemaType,
+ *   ReadResult,
+ *   { scopedNodes: FileNode[]; provider: FileSystemProvider }
+ * > = async (args, context) => {
+ *   return readHandler(args, context.scopedNodes, context.provider);
+ * };
+ * ```
+ */
+type ActivityToolHandler<TArgs, TResult, TContext = ToolHandlerContext> = (args: TArgs, context: TContext) => 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$1.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, unknown> ? Awaited<R> : never;
+/**
+ * The result of processing a tool call.
+ */
+interface ToolCallResult<TName extends string = string, TResult = unknown> {
+    toolCallId: string;
+    name: TName;
+    result: TResult;
+}
+/**
+ * Options for creating a tool router.
+ */
+interface ToolRouterOptions<T extends ToolMap> {
+    /** File tree for the agent */
+    fileTree: string;
+    /** Map of tools with their handlers */
+    tools: 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?: Hooks<T, ToolCallResultUnion<InferToolResults<T>>>;
+    /** Subagent configurations */
+    subagents?: SubagentConfig[];
+    /** Build in tools - accepts raw handlers or proxied activities */
+    buildInTools?: {
+        [K in keyof BuildInToolDefinitions]?: BuildInToolDefinitions[K]["handler"];
+    };
+}
+/**
+ * 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> ? 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<THandlerContext = ToolHandlerContext> {
+    /** Current turn number (for hooks) */
+    turn?: number;
+    /** Context passed to each tool handler (scopedNodes, provider, etc.) */
+    handlerContext?: THandlerContext;
+}
+/**
+ * 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, TContext = ToolHandlerContext>(toolCalls: ParsedToolCallUnion<T>[], toolName: TName, handler: ToolHandler<ToolArgs<T, TName>, TResult, TContext>, context?: ProcessToolCallsContext<TContext>): 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>>[];
+}
+/**
+ * Creates a tool router for declarative tool call processing.
+ * Combines tool definitions with handlers in a single API.
+ *
+ * @example
+ * ```typescript
+ * const router = createToolRouter({
+ *   threadId,
+ *   tools: {
+ *     Read: {
+ *       name: "FileRead",
+ *       description: "Read file contents",
+ *       schema: z.object({ path: z.string() }),
+ *       handler: async (args, ctx) => ({
+ *         content: `Read ${args.path}`,
+ *         result: { path: args.path, content: "..." },
+ *       }),
+ *     },
+ *   },
+ *   hooks: { onPreToolUse, onPostToolUse },
+ * });
+ *
+ * // Parse raw tool calls from LLM
+ * const parsed = router.parseToolCall(rawToolCall);
+ *
+ * // Process tool calls
+ * const results = await router.processToolCalls([parsed]);
+ * ```
+ */
+declare function createToolRouter<T extends ToolMap>(options: ToolRouterOptions<T>): ToolRouter<T>;
+/**
+ * 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;
+
+/**
+ * Agent execution status
+ */
+type AgentStatus = "RUNNING" | "WAITING_FOR_INPUT" | "COMPLETED" | "FAILED" | "CANCELLED";
+/**
+ * Base state that all agents must have
+ */
+interface BaseAgentState {
+    tools: ToolDefinition[];
+    status: AgentStatus;
+    version: number;
+    turns: number;
+    tasks: Map<string, WorkflowTask>;
+}
+/**
+ * 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<T extends ToolMap> {
+    buildFileTree?: () => Promise<string>;
+    threadId: string;
+    agentName: string;
+    metadata?: Record<string, unknown>;
+    maxTurns?: number;
+    /** Workflow-specific runAgent activity (with tools pre-bound) */
+    runAgent: RunAgentActivity;
+    /** Tool router for processing tool calls (optional if agent has no tools) */
+    tools?: T;
+    /** Subagent configurations */
+    subagents?: SubagentConfig[];
+    /** Session lifecycle hooks */
+    hooks?: Hooks<T, ToolCallResultUnion<InferToolResults<T>>>;
+    /** Whether to process tools in parallel */
+    processToolsInParallel?: boolean;
+    /**
+     * 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: () => MessageContent | Promise<MessageContent>;
+    /**
+     * Build in tools - accepts raw handlers or proxied activities
+     */
+    buildInTools?: {
+        [K in keyof BuildInToolDefinitions]?: BuildInToolDefinitions[K]["handler"];
+    };
+}
+/**
+ * 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) => Promise<AgentResponse>;
+/**
+ * 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$1.ZodType = z$1.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;
+}
+/**
+ * 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";
+/**
+ * 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 Hooks<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;
+
+interface ZeitlichSession {
+    runSession<T extends JsonSerializable<T>>(args: {
+        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>({ threadId, agentName, maxTurns, metadata, runAgent, baseSystemPrompt, instructionsPrompt, buildContextMessage, buildFileTree, subagents, tools, processToolsInParallel, buildInTools, hooks, }: ZeitlichAgentConfig<T>) => Promise<ZeitlichSession>;
+
+/**
+ * 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: string;
+    description: string;
+    schema: z.ZodObject<{
+        subagent: z.ZodEnum<Record<string, string>>;
+        description: z.ZodString;
+        prompt: z.ZodString;
+    }>;
+};
+/**
+ * Infer the schema type for a task tool created with specific subagents
+ */
+type TaskToolSchemaType<T extends SubagentConfig[]> = z.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;
+}
+
+/**
+ * Shared Zeitlich activities - thread management and message handling
+ * Note: runAgent is workflow-specific and should be created per-workflow
+ */
+interface ZeitlichSharedActivities {
+    appendSystemMessage(threadId: string, content: string): Promise<void>;
+    /**
+     * 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 a system message to a thread.
+     */
+    appendSystemMessage(threadId: string, content: 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.ZodObject<{
+        questions: z.ZodArray<z.ZodObject<{
+            question: z.ZodString;
+            header: z.ZodString;
+            options: z.ZodArray<z.ZodObject<{
+                label: z.ZodString;
+                description: z.ZodString;
+            }, z.core.$strip>>;
+            multiSelect: z.ZodBoolean;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    strict: boolean;
+};
+type AskUserQuestionToolSchemaType = z.infer<typeof askUserQuestionTool.schema>;
+
+declare const globTool: {
+    name: "Glob";
+    description: string;
+    schema: z$1.ZodObject<{
+        pattern: z$1.ZodString;
+        root: z$1.ZodOptional<z$1.ZodString>;
+    }, z$1.core.$strip>;
+    strict: boolean;
+};
+type GlobToolSchemaType = z$1.infer<typeof globTool.schema>;
+
+declare const grepTool: {
+    name: "Grep";
+    description: string;
+    schema: z$1.ZodObject<{
+        pattern: z$1.ZodString;
+        ignoreCase: z$1.ZodOptional<z$1.ZodBoolean>;
+        maxMatches: z$1.ZodOptional<z$1.ZodNumber>;
+        includePatterns: z$1.ZodOptional<z$1.ZodArray<z$1.ZodString>>;
+        excludePatterns: z$1.ZodOptional<z$1.ZodArray<z$1.ZodString>>;
+        contextLines: z$1.ZodOptional<z$1.ZodNumber>;
+    }, z$1.core.$strip>;
+    strict: boolean;
+};
+type GrepToolSchemaType = z$1.infer<typeof grepTool.schema>;
+
+declare const readTool: {
+    name: "FileRead";
+    description: string;
+    schema: z$1.ZodObject<{
+        path: z$1.ZodString;
+        offset: z$1.ZodOptional<z$1.ZodNumber>;
+        limit: z$1.ZodOptional<z$1.ZodNumber>;
+    }, z$1.core.$strip>;
+    strict: boolean;
+};
+type ReadToolSchemaType = z$1.infer<typeof readTool.schema>;
+
+declare const writeTool: {
+    name: "FileWrite";
+    description: string;
+    schema: z$1.ZodObject<{
+        file_path: z$1.ZodString;
+        content: z$1.ZodString;
+    }, z$1.core.$strip>;
+    strict: boolean;
+};
+type WriteToolSchemaType = z$1.infer<typeof writeTool.schema>;
+
+declare const editTool: {
+    name: "FileEdit";
+    description: string;
+    schema: z$1.ZodObject<{
+        file_path: z$1.ZodString;
+        old_string: z$1.ZodString;
+        new_string: z$1.ZodString;
+        replace_all: z$1.ZodOptional<z$1.ZodBoolean>;
+    }, z$1.core.$strip>;
+    strict: boolean;
+};
+type EditToolSchemaType = z$1.infer<typeof editTool.schema>;
+
+declare const taskGetTool: {
+    name: "TaskGet";
+    description: string;
+    schema: z.ZodObject<{
+        taskId: z.ZodString;
+    }, z.core.$strip>;
+};
+type TaskGetToolSchemaType = z.infer<typeof taskGetTool.schema>;
+
+/**
+ * Creates a TaskGet handler that retrieves a task by ID.
+ *
+ * @param stateManager - State manager containing tasks state
+ * @returns A tool handler function
+ *
+ * @example
+ * const handler = createTaskGetHandler(stateManager);
+ */
+declare function createTaskGetHandler<TCustom extends JsonSerializable<TCustom>>(stateManager: AgentStateManager<TCustom>): (args: TaskGetToolSchemaType) => ToolHandlerResponse<WorkflowTask | null>;
+
+declare const taskListTool: {
+    name: "TaskList";
+    description: string;
+    schema: z.ZodObject<{}, z.core.$strip>;
+};
+type TaskListToolSchemaType = z.infer<typeof taskListTool.schema>;
+
+/**
+ * Creates a TaskList handler that returns all tasks.
+ *
+ * @param stateManager - State manager containing tasks state
+ * @returns A tool handler function
+ *
+ * @example
+ * const handler = createTaskListHandler(stateManager);
+ */
+declare function createTaskListHandler<TCustom extends JsonSerializable<TCustom>>(stateManager: AgentStateManager<TCustom>): (args: TaskListToolSchemaType) => ToolHandlerResponse<WorkflowTask[]>;
+
+declare const taskUpdateTool: {
+    name: "TaskUpdate";
+    description: string;
+    schema: z.ZodObject<{
+        taskId: z.ZodString;
+        status: z.ZodEnum<{
+            pending: "pending";
+            in_progress: "in_progress";
+            completed: "completed";
+        }>;
+        addBlockedBy: z.ZodArray<z.ZodString>;
+        addBlocks: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>;
+};
+type TaskUpdateToolSchemaType = z.infer<typeof taskUpdateTool.schema>;
+
+/**
+ * Creates a TaskUpdate handler that modifies task status and dependencies.
+ *
+ * @param stateManager - State manager containing tasks state
+ * @returns A tool handler function
+ *
+ * @example
+ * const handler = createTaskUpdateHandler(stateManager);
+ */
+declare function createTaskUpdateHandler<TCustom extends JsonSerializable<TCustom>>(stateManager: AgentStateManager<TCustom>): (args: TaskUpdateToolSchemaType) => ToolHandlerResponse<WorkflowTask | null>;
+
+export { type ToolHandlerResponse as $, type AgentResponse as A, type BaseAgentState as B, type SessionExitReason as C, type SessionLifecycleHooks as D, type EditToolSchemaType as E, type SessionStartHook as F, type GlobToolSchemaType as G, type SessionStartHookContext as H, type InferToolResults as I, type JsonPrimitive as J, type SubagentConfig as K, type SubagentInput as L, type TaskGetToolSchemaType as M, type TaskHandlerResult as N, type TaskStatus as O, type ParsedToolCall as P, type TaskToolSchemaType as Q, type RawToolCall as R, type SessionEndHook as S, type TaskCreateToolSchemaType as T, type TaskUpdateToolSchemaType as U, type ToolArgs as V, type ToolCallResult as W, type ToolCallResultUnion as X, type ToolDefinition as Y, type ToolHandler as Z, type ToolHandlerContext as _, type ActivityToolHandler as a, type ToolMap as a0, type ToolMessageContent as a1, type ToolNames as a2, type ToolResult as a3, type ToolResultConfig as a4, type ToolRouter as a5, type ToolWithHandler as a6, type WorkflowTask as a7, type WriteToolSchemaType as a8, type ZeitlichAgentConfig as a9, type ZeitlichSession as aa, type ZeitlichSharedActivities as ab, askUserQuestionTool as ac, bashTool as ad, type bashToolSchemaType as ae, createAgentStateManager as af, createSession as ag, createSharedActivities as ah, createTaskCreateHandler as ai, createTaskGetHandler as aj, createTaskListHandler as ak, createTaskTool as al, createTaskUpdateHandler as am, createToolRouter as an, editTool as ao, globTool as ap, grepTool as aq, handleBashTool as ar, hasNoOtherToolCalls as as, isTerminalStatus as at, readTool as au, taskCreateTool as av, taskGetTool as aw, taskListTool as ax, taskUpdateTool as ay, writeTool as az, type AskUserQuestionToolSchemaType as b, AGENT_HANDLER_NAMES as c, type AgentFile as d, type AgentState as e, type AgentStateManager as f, type AgentStatus as g, type AppendToolResultFn as h, type GenericTaskToolSchemaType as i, type GrepToolSchemaType as j, type JsonSerializable as k, type JsonValue as l, type ParsedToolCallUnion as m, type PostToolUseFailureHook as n, type PostToolUseFailureHookContext as o, type PostToolUseFailureHookResult as p, type PostToolUseHook as q, type PostToolUseHookContext as r, type PreToolUseHook as s, type PreToolUseHookContext as t, type PreToolUseHookResult as u, type ProcessToolCallsContext as v, type ReadToolSchemaType as w, type RunAgentActivity as x, type RunAgentConfig as y, type SessionEndHookContext as z };