zeitlich 0.2.2 → 0.2.4

package/dist/{workflow-BQf5EfNN.d.ts → workflow-PjeURKw4.d.ts}

@@ -1,34 +1,37 @@
+import { Workflow, proxyActivities } from '@temporalio/workflow';
 import Redis from 'ioredis';
 import { $InferMessageContent, MessageStructure, StoredMessage, MessageContent } from '@langchain/core/messages';
 import z, { z as z$1 } from 'zod';
 import * as _temporalio_common from '@temporalio/common';
-import { BashOptions } from 'just-bash';
-import { Workflow } from '@temporalio/workflow';
 
 /**
  * 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">;
-interface ThreadManagerConfig {
+interface ThreadManagerConfig<T = StoredMessage> {
     redis: Redis;
     threadId: string;
     /** Thread key, defaults to 'messages' */
     key?: string;
+    /** Custom serializer, defaults to JSON.stringify */
+    serialize?: (message: T) => string;
+    /** Custom deserializer, defaults to JSON.parse */
+    deserialize?: (raw: string) => T;
 }
-interface ThreadManager {
-    /** Append a system message to the thread */
-    appendSystemMessage(content: string): Promise<void>;
+/** Generic thread manager for any message type */
+interface BaseThreadManager<T> {
     /** Initialize an empty thread */
     initialize(): Promise<void>;
     /** Load all messages from the thread */
-    load(): Promise<StoredMessage[]>;
+    load(): Promise<T[]>;
     /** Append messages to the thread */
-    append(messages: StoredMessage[]): Promise<void>;
+    append(messages: T[]): Promise<void>;
     /** Delete the thread */
     delete(): Promise<void>;
-    /** Create a SystemMessage (returns StoredMessage for storage) */
-    createSystemMessage(content: string): StoredMessage;
+}
+/** Thread manager with StoredMessage convenience helpers */
+interface ThreadManager extends BaseThreadManager<StoredMessage> {
     /** Create a HumanMessage (returns StoredMessage for storage) */
     createHumanMessage(content: string | MessageContent): StoredMessage;
     /** Create an AIMessage with optional additional kwargs */
@@ -48,17 +51,20 @@ interface ThreadManager {
 }
 /**
  * Creates a thread manager for handling conversation state in Redis.
+ * Without generic args, returns a full ThreadManager with StoredMessage helpers.
+ * With a custom type T, returns a BaseThreadManager<T>.
  */
 declare function createThreadManager(config: ThreadManagerConfig): ThreadManager;
+declare function createThreadManager<T>(config: ThreadManagerConfig<T>): BaseThreadManager<T>;
 
 /**
- * Creates a Task tool configured with the available subagents.
+ * Creates a Subagent 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([
+ * const subagentTool = createSubagentTool([
  *   {
  *     name: "researcher",
  *     description: "Researches topics and gathers information",
@@ -67,7 +73,7 @@ declare function createThreadManager(config: ThreadManagerConfig): ThreadManager
  *   },
  * ]);
  */
-declare function createTaskTool<T extends SubagentConfig[]>(subagents: T): {
+declare function createSubagentTool<T extends SubagentConfig[]>(subagents: T): {
     name: string;
     description: string;
     schema: z.ZodObject<{
@@ -77,156 +83,14 @@ declare function createTaskTool<T extends SubagentConfig[]>(subagents: T): {
     }>;
 };
 /**
- * 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)
+ * Subagent tool args type (when subagent names are not known at compile time)
  */
-type GenericTaskToolSchemaType = {
+type SubagentArgs = {
     subagent: string;
     description: string;
     prompt: string;
 };
 
-/**
- * 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 (converts Zod schemas to JSON Schema for serialization) */
-    setTools(newTools: ToolDefinition[]): void;
-}
-declare const getStateQuery: _temporalio_common.QueryDefinition<BaseAgentState, [], string>;
-/**
- * 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: AgentStateManager<TCustom>): (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;
-};
-/** BashOptions with `fs` required */
-type BashToolOptions = Required<Pick<BashOptions, "fs">> & Omit<BashOptions, "fs">;
-declare const handleBashTool: (bashOptions: BashToolOptions) => 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.
@@ -249,19 +113,27 @@ interface ToolWithHandler<TName extends string = string, TSchema extends z$1.Zod
     handler: ToolHandler<z$1.infer<TSchema>, TResult, TContext>;
     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;
     /** Per-tool lifecycle hooks (run in addition to global hooks) */
     hooks?: ToolHooks<z$1.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;
     schema: z$1.ZodType;
-    handler: (args: any, context: any) => ToolHandlerResponse<any> | Promise<ToolHandlerResponse<any>>;
+    handler: ToolHandler<any, any, any>;
     strict?: boolean;
     max_uses?: number;
+    enabled?: boolean;
     hooks?: ToolHooks<any, any>;
 }>;
 /**
@@ -297,29 +169,29 @@ 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.
+ *
+ * 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> {
+interface ToolHandlerResponse<TResult = null> {
     /** Content sent back to the LLM as the tool call response */
     toolResponse: ToolMessageContent;
     /** Data returned to the workflow and hooks for further processing */
-    data: TResult | null;
+    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;
 }
 /**
  * Context passed to tool handlers for additional data beyond tool args.
  * Use this to pass workflow state like file trees, user context, etc.
+ * Generic so callers can type the context shape, e.g. ToolHandlerContext<ControlTestFsParams>.
  */
-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>;
-    };
-}
+type ToolHandlerContext<T = Record<string, unknown>> = T;
 /**
  * A handler function for a specific tool.
  * Receives the parsed args and context, returns a response with content and result.
@@ -335,7 +207,7 @@ type ToolHandler<TArgs, TResult, TContext = ToolHandlerContext> = (args: TArgs,
  * ```typescript
  * // Filesystem handler with context
  * const readHandler: ActivityToolHandler<
- *   ReadToolSchemaType,
+ *   FileReadArgs,
  *   ReadResult,
  *   { scopedNodes: FileNode[]; provider: FileSystemProvider }
  * > = async (args, context) => {
@@ -362,14 +234,12 @@ type ToolResult<T extends ToolMap, TName extends ToolNames<T>> = Extract<T[keyof
 interface ToolCallResult<TName extends string = string, TResult = unknown> {
     toolCallId: string;
     name: TName;
-    data: TResult | null;
+    data: 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 */
@@ -382,10 +252,6 @@ interface ToolRouterOptions<T extends ToolMap> {
     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.
@@ -486,6 +352,34 @@ interface ToolRouter<T extends ToolMap> {
  * ```
  */
 declare function createToolRouter<T extends ToolMap>(options: ToolRouterOptions<T>): ToolRouter<T>;
+/**
+ * Wraps a tool handler to automatically append its result directly to the
+ * thread and sets `resultAppended: true` on the response.
+ *
+ * Use this for tools whose responses may exceed Temporal's activity payload
+ * limit. The wrapper appends to the thread inside the activity (where Redis
+ * is available), then replaces `toolResponse` with an empty string so the
+ * large payload never travels through the Temporal workflow boundary.
+ *
+ * @param getThread - Factory that returns a thread manager for the given threadId
+ * @param handler   - The original tool handler
+ * @returns A wrapped handler that auto-appends and flags the response
+ *
+ * @example
+ * ```typescript
+ * import { withAutoAppend } from '@bead-ai/zeitlich/workflow';
+ * import { createThreadManager } from '@bead-ai/zeitlich';
+ *
+ * const handler = withAutoAppend(
+ *   (threadId) => createThreadManager({ redis, threadId }),
+ *   async (args, ctx) => ({
+ *     toolResponse: JSON.stringify(largeResult), // appended directly to Redis
+ *     data: { summary: "..." },                  // small data for workflow
+ *   }),
+ * );
+ * ```
+ */
+declare function withAutoAppend<TArgs, TResult, TContext extends ToolHandlerContext = ToolHandlerContext>(threadHandler: (config: ToolResultConfig) => Promise<void>, handler: ActivityToolHandler<TArgs, TResult, TContext>): ActivityToolHandler<TArgs, TResult, TContext>;
 /**
  * Identity function that creates a generic inference context for a tool definition.
  * TypeScript infers TResult from the handler and flows it to hooks automatically.
@@ -542,13 +436,13 @@ declare function defineSubagent<TResult extends z$1.ZodType = z$1.ZodType, TCont
         context: TContext;
     }) => Promise<any>);
     context: TContext;
-    hooks?: SubagentHooks<GenericTaskToolSchemaType, z$1.infer<TResult>>;
+    hooks?: SubagentHooks<SubagentArgs, z$1.infer<TResult>>;
 }): SubagentConfig<TResult>;
 declare function defineSubagent<TResult extends z$1.ZodType = z$1.ZodType>(config: Omit<SubagentConfig<TResult>, "hooks" | "workflow"> & {
     workflow: string | ((input: {
         prompt: string;
     }) => Promise<any>);
-    hooks?: SubagentHooks<GenericTaskToolSchemaType, z$1.infer<TResult>>;
+    hooks?: SubagentHooks<SubagentArgs, z$1.infer<TResult>>;
 }): SubagentConfig<TResult>;
 /**
  * Utility to check if there were no tool calls besides a specific one
@@ -568,6 +462,7 @@ interface BaseAgentState {
     version: number;
     turns: number;
     tasks: Map<string, WorkflowTask>;
+    systemPrompt: string;
 }
 /**
  * File representation for agent workflows
@@ -587,26 +482,40 @@ interface AgentFile {
 /**
  * Agent response from LLM invocation
  */
-interface AgentResponse {
-    message: StoredMessage;
-    stopReason: string | null;
+interface AgentResponse<M = StoredMessage> {
+    message: M;
+    rawToolCalls: RawToolCall[];
     usage?: {
         input_tokens?: number;
         output_tokens?: number;
         total_tokens?: number;
     };
 }
+/**
+ * Thread operations required by a session.
+ * Consumers provide these — typically by wrapping Temporal activities.
+ * Use `proxyDefaultThreadOps()` for the default StoredMessage implementation.
+ */
+interface ThreadOps {
+    /** Initialize an empty thread */
+    initializeThread(threadId: string): Promise<void>;
+    /** Append a human message to the thread */
+    appendHumanMessage(threadId: string, content: string | MessageContent): Promise<void>;
+    /** Append a tool result to the thread */
+    appendToolResult(config: ToolResultConfig): Promise<void>;
+}
 /**
  * Configuration for a Zeitlich agent session
  */
-interface ZeitlichAgentConfig<T extends ToolMap> {
-    buildFileTree?: () => Promise<string>;
+interface ZeitlichAgentConfig<T extends ToolMap, M = StoredMessage> {
     threadId: string;
     agentName: string;
     metadata?: Record<string, unknown>;
     maxTurns?: number;
     /** Workflow-specific runAgent activity (with tools pre-bound) */
-    runAgent: RunAgentActivity;
+    runAgent: RunAgentActivity<M>;
+    /** Thread operations (initialize, append messages, parse tool calls) */
+    threadOps: ThreadOps;
     /** Tool router for processing tool calls (optional if agent has no tools) */
     tools?: T;
     /** Subagent configurations */
@@ -615,27 +524,11 @@ interface ZeitlichAgentConfig<T extends ToolMap> {
     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"];
-    };
 }
 /**
  * A JSON-serializable tool definition for state storage.
@@ -660,13 +553,15 @@ interface RunAgentConfig {
 /**
  * Type signature for workflow-specific runAgent activity
  */
-type RunAgentActivity = (config: RunAgentConfig) => Promise<AgentResponse>;
+type RunAgentActivity<M = StoredMessage> = (config: RunAgentConfig) => Promise<AgentResponse<M>>;
 /**
  * Configuration for appending a tool result
  */
 interface ToolResultConfig {
     threadId: string;
     toolCallId: string;
+    /** The name of the tool that produced this result */
+    toolName: string;
     /** Content for the tool message (string or complex content parts) */
     content: ToolMessageContent;
 }
@@ -873,7 +768,7 @@ interface ToolHooks<TArgs = unknown, TResult = unknown> {
     /** Called after this tool executes successfully */
     onPostToolUse?: (ctx: {
         args: TArgs;
-        result: TResult | null;
+        result: TResult;
         threadId: string;
         turn: number;
         durationMs: number;
@@ -906,10 +801,105 @@ interface Hooks<T extends ToolMap, TResult = unknown> {
  */
 declare function isTerminalStatus(status: AgentStatus): boolean;
 
-interface ZeitlichSession {
+/**
+ * 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 (converts Zod schemas to JSON Schema for serialization) */
+    setTools(newTools: ToolDefinition[]): void;
+}
+declare const getStateQuery: _temporalio_common.QueryDefinition<BaseAgentState, [], string>;
+/**
+ * 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";
+};
+
+interface ZeitlichSession<M = unknown> {
     runSession<T extends JsonSerializable<T>>(args: {
         stateManager: AgentStateManager<T>;
-    }): Promise<StoredMessage | null>;
+    }): Promise<M | null>;
 }
 /**
  * Session-level hooks for lifecycle events
@@ -920,24 +910,26 @@ interface SessionLifecycleHooks {
     /** 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>;
-
+declare const createSession: <T extends ToolMap, M = unknown>({ threadId, agentName, maxTurns, metadata, runAgent, threadOps, buildContextMessage, subagents, tools, processToolsInParallel, hooks, }: ZeitlichAgentConfig<T, M>) => Promise<ZeitlichSession<M>>;
 /**
- * Result from a task handler execution
+ * Proxy the default ZeitlichSharedActivities as ThreadOps<StoredMessage>.
+ * Call this in workflow code for the standard LangChain/StoredMessage setup.
+ *
+ * @example
+ * ```typescript
+ * const session = await createSession({
+ *   threadOps: proxyDefaultThreadOps(),
+ *   // ...
+ * });
+ * ```
  */
-interface TaskHandlerResult<TResult = unknown> {
-    /** The validated result from the child workflow */
-    result: TResult;
-    /** The child workflow ID (for reference/debugging) */
-    childWorkflowId: string;
-}
+declare function proxyDefaultThreadOps(options?: Parameters<typeof proxyActivities>[0]): ThreadOps;
 
 /**
  * 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.
@@ -947,10 +939,6 @@ interface ZeitlichSharedActivities {
      * 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.
      */
@@ -959,11 +947,6 @@ interface ZeitlichSharedActivities {
      * 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
@@ -988,9 +971,9 @@ declare const askUserQuestionTool: {
             multiSelect: z.ZodBoolean;
         }, z.core.$strip>>;
     }, z.core.$strip>;
-    strict: boolean;
+    strict: true;
 };
-type AskUserQuestionToolSchemaType = z.infer<typeof askUserQuestionTool.schema>;
+type AskUserQuestionArgs = z.infer<typeof askUserQuestionTool.schema>;
 
 declare const globTool: {
     name: "Glob";
@@ -999,9 +982,9 @@ declare const globTool: {
         pattern: z$1.ZodString;
         root: z$1.ZodOptional<z$1.ZodString>;
     }, z$1.core.$strip>;
-    strict: boolean;
+    strict: true;
 };
-type GlobToolSchemaType = z$1.infer<typeof globTool.schema>;
+type GlobArgs = z$1.infer<typeof globTool.schema>;
 
 declare const grepTool: {
     name: "Grep";
@@ -1014,9 +997,9 @@ declare const grepTool: {
         excludePatterns: z$1.ZodOptional<z$1.ZodArray<z$1.ZodString>>;
         contextLines: z$1.ZodOptional<z$1.ZodNumber>;
     }, z$1.core.$strip>;
-    strict: boolean;
+    strict: true;
 };
-type GrepToolSchemaType = z$1.infer<typeof grepTool.schema>;
+type GrepArgs = z$1.infer<typeof grepTool.schema>;
 
 declare const readTool: {
     name: "FileRead";
@@ -1026,9 +1009,9 @@ declare const readTool: {
         offset: z$1.ZodOptional<z$1.ZodNumber>;
         limit: z$1.ZodOptional<z$1.ZodNumber>;
     }, z$1.core.$strip>;
-    strict: boolean;
+    strict: true;
 };
-type ReadToolSchemaType = z$1.infer<typeof readTool.schema>;
+type FileReadArgs = z$1.infer<typeof readTool.schema>;
 
 declare const writeTool: {
     name: "FileWrite";
@@ -1037,9 +1020,9 @@ declare const writeTool: {
         file_path: z$1.ZodString;
         content: z$1.ZodString;
     }, z$1.core.$strip>;
-    strict: boolean;
+    strict: true;
 };
-type WriteToolSchemaType = z$1.infer<typeof writeTool.schema>;
+type FileWriteArgs = z$1.infer<typeof writeTool.schema>;
 
 declare const editTool: {
     name: "FileEdit";
@@ -1050,9 +1033,29 @@ declare const editTool: {
         new_string: z$1.ZodString;
         replace_all: z$1.ZodOptional<z$1.ZodBoolean>;
     }, z$1.core.$strip>;
-    strict: boolean;
+    strict: true;
 };
-type EditToolSchemaType = z$1.infer<typeof editTool.schema>;
+type FileEditArgs = z$1.infer<typeof editTool.schema>;
+
+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 TaskCreateArgs = z.infer<typeof taskCreateTool.schema>;
+
+/**
+ * Creates a TaskCreate handler that adds tasks to the workflow state.
+ *
+ * @param stateManager - State manager containing tasks state
+ * @returns A ToolHandler for TaskCreate tool calls
+ */
+declare function createTaskCreateHandler<TCustom extends JsonSerializable<TCustom>>(stateManager: AgentStateManager<TCustom>): ToolHandler<TaskCreateArgs, WorkflowTask>;
 
 declare const taskGetTool: {
     name: "TaskGet";
@@ -1061,36 +1064,30 @@ declare const taskGetTool: {
         taskId: z.ZodString;
     }, z.core.$strip>;
 };
-type TaskGetToolSchemaType = z.infer<typeof taskGetTool.schema>;
+type TaskGetArgs = 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);
+ * @returns A ToolHandler for TaskGet tool calls
  */
-declare function createTaskGetHandler<TCustom extends JsonSerializable<TCustom>>(stateManager: AgentStateManager<TCustom>): (args: TaskGetToolSchemaType) => ToolHandlerResponse<WorkflowTask | null>;
+declare function createTaskGetHandler<TCustom extends JsonSerializable<TCustom>>(stateManager: AgentStateManager<TCustom>): ToolHandler<TaskGetArgs, WorkflowTask | null>;
 
 declare const taskListTool: {
     name: "TaskList";
     description: string;
     schema: z.ZodObject<{}, z.core.$strip>;
 };
-type TaskListToolSchemaType = z.infer<typeof taskListTool.schema>;
+type TaskListArgs = 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);
+ * @returns A ToolHandler for TaskList tool calls
  */
-declare function createTaskListHandler<TCustom extends JsonSerializable<TCustom>>(stateManager: AgentStateManager<TCustom>): (args: TaskListToolSchemaType) => ToolHandlerResponse<WorkflowTask[]>;
+declare function createTaskListHandler<TCustom extends JsonSerializable<TCustom>>(stateManager: AgentStateManager<TCustom>): ToolHandler<TaskListArgs, WorkflowTask[]>;
 
 declare const taskUpdateTool: {
     name: "TaskUpdate";
@@ -1106,17 +1103,27 @@ declare const taskUpdateTool: {
         addBlocks: z.ZodArray<z.ZodString>;
     }, z.core.$strip>;
 };
-type TaskUpdateToolSchemaType = z.infer<typeof taskUpdateTool.schema>;
+type TaskUpdateArgs = 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);
+ * @returns A ToolHandler for TaskUpdate tool calls
  */
-declare function createTaskUpdateHandler<TCustom extends JsonSerializable<TCustom>>(stateManager: AgentStateManager<TCustom>): (args: TaskUpdateToolSchemaType) => ToolHandlerResponse<WorkflowTask | null>;
+declare function createTaskUpdateHandler<TCustom extends JsonSerializable<TCustom>>(stateManager: AgentStateManager<TCustom>): ToolHandler<TaskUpdateArgs, WorkflowTask | null>;
+
+declare const createBashToolDescription: ({ fileTree, }: {
+    fileTree: string;
+}) => string;
+declare const bashTool: {
+    name: "Bash";
+    description: string;
+    schema: z.ZodObject<{
+        command: z.ZodString;
+    }, z.core.$strip>;
+    strict: true;
+};
+type BashArgs = z.infer<typeof bashTool.schema>;
 
-export { type ToolHandlerContext 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 SubagentHooks as L, type SubagentInput as M, type TaskGetToolSchemaType as N, type TaskHandlerResult as O, type ParsedToolCall as P, type TaskStatus as Q, type RawToolCall as R, type SessionEndHook as S, type TaskCreateToolSchemaType as T, type TaskToolSchemaType as U, type TaskUpdateToolSchemaType as V, type ToolArgs as W, type ToolCallResult as X, type ToolCallResultUnion as Y, type ToolDefinition as Z, type ToolHandler as _, type ActivityToolHandler as a, type ToolHandlerResponse as a0, type ToolHooks as a1, type ToolMap as a2, type ToolMessageContent as a3, type ToolNames as a4, type ToolResult as a5, type ToolResultConfig as a6, type ToolRouter as a7, type ToolWithHandler as a8, type WorkflowTask as a9, readTool as aA, taskCreateTool as aB, taskGetTool as aC, taskListTool as aD, taskUpdateTool as aE, writeTool as aF, type WriteToolSchemaType as aa, type ZeitlichAgentConfig as ab, type ZeitlichSession as ac, type ZeitlichSharedActivities as ad, askUserQuestionTool as ae, bashTool as af, type bashToolSchemaType as ag, createAgentStateManager as ah, createSession as ai, createSharedActivities as aj, createTaskCreateHandler as ak, createTaskGetHandler as al, createTaskListHandler as am, createTaskTool as an, createTaskUpdateHandler as ao, createThreadManager as ap, createToolRouter as aq, defineSubagent as ar, defineTool as as, editTool as at, getStateQuery as au, globTool as av, grepTool as aw, handleBashTool as ax, hasNoOtherToolCalls as ay, isTerminalStatus 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 };
+export { type ToolArgs as $, type AgentResponse as A, type BashArgs as B, type RunAgentConfig as C, type SessionEndHookContext as D, type SessionExitReason as E, type FileEditArgs as F, type GlobArgs as G, type SessionLifecycleHooks as H, type InferToolResults as I, type JsonPrimitive as J, type SessionStartHook as K, type SessionStartHookContext as L, type SubagentArgs as M, type SubagentConfig as N, type SubagentHooks as O, type ParsedToolCall as P, type SubagentInput as Q, type RawToolCall as R, type SessionEndHook as S, type TaskCreateArgs as T, type TaskGetArgs as U, type TaskListArgs as V, type TaskStatus as W, type TaskUpdateArgs as X, type ThreadManager as Y, type ThreadManagerConfig as Z, type ThreadOps as _, type ActivityToolHandler as a, type ToolCallResult as a0, type ToolCallResultUnion as a1, type ToolDefinition as a2, type ToolHandler as a3, type ToolHandlerContext as a4, type ToolHandlerResponse as a5, type ToolHooks as a6, type ToolMap as a7, type ToolMessageContent as a8, type ToolNames as a9, grepTool as aA, hasNoOtherToolCalls as aB, isTerminalStatus as aC, proxyDefaultThreadOps as aD, readTool as aE, taskCreateTool as aF, taskGetTool as aG, taskListTool as aH, taskUpdateTool as aI, withAutoAppend as aJ, writeTool as aK, type ToolResult as aa, type ToolResultConfig as ab, type ToolRouter as ac, type ToolWithHandler as ad, type WorkflowTask as ae, type ZeitlichAgentConfig as af, type ZeitlichSession as ag, type ZeitlichSharedActivities as ah, askUserQuestionTool as ai, bashTool as aj, createAgentStateManager as ak, createBashToolDescription as al, createSession as am, createSharedActivities as an, createSubagentTool as ao, createTaskCreateHandler as ap, createTaskGetHandler as aq, createTaskListHandler as ar, createTaskUpdateHandler as as, createThreadManager as at, createToolRouter as au, defineSubagent as av, defineTool as aw, editTool as ax, getStateQuery as ay, globTool as az, type AskUserQuestionArgs 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 BaseAgentState as i, type BaseThreadManager as j, type FileReadArgs as k, type FileWriteArgs as l, type GrepArgs as m, type JsonSerializable as n, type JsonValue as o, type ParsedToolCallUnion as p, type PostToolUseFailureHook as q, type PostToolUseFailureHookContext as r, type PostToolUseFailureHookResult as s, type PostToolUseHook as t, type PostToolUseHookContext as u, type PreToolUseHook as v, type PreToolUseHookContext as w, type PreToolUseHookResult as x, type ProcessToolCallsContext as y, type RunAgentActivity as z };