zeitlich 0.2.1 → 0.2.3

package/dist/{workflow-CCoHnc3B.d.cts → workflow-D-2vp4Pq.d.cts}

@@ -1,153 +1,95 @@
+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 { BashOptions } from 'just-bash';
-import Redis from 'ioredis';
+import * as _temporalio_common from '@temporalio/common';
 
 /**
  * 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;
+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;
+}
+/** 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<T[]>;
+    /** Append messages to the thread */
+    append(messages: T[]): Promise<void>;
+    /** Delete the thread */
+    delete(): Promise<void>;
+}
+/** 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 */
+    createAIMessage(content: string | MessageContent, kwargs?: {
+        header?: string;
+        options?: string[];
+        multiSelect?: boolean;
+    }): StoredMessage;
+    /** Create a ToolMessage */
+    createToolMessage(content: ToolMessageContent, toolCallId: string): StoredMessage;
+    /** Create and append a HumanMessage */
+    appendHumanMessage(content: string | MessageContent): Promise<void>;
+    /** Create and append a ToolMessage */
+    appendToolMessage(content: ToolMessageContent, toolCallId: string): Promise<void>;
+    /** Create and append an AIMessage */
+    appendAIMessage(content: string | MessageContent): Promise<void>;
+}
 /**
- * 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.
+ * 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>.
  */
-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;
-}
+declare function createThreadManager(config: ThreadManagerConfig): ThreadManager;
+declare function createThreadManager<T>(config: ThreadManagerConfig<T>): BaseThreadManager<T>;
+
 /**
- * Creates an agent state manager for tracking workflow state.
+ * Creates a Task tool configured with the available subagents.
  *
- * @param initialState - Optional initial values for base and custom state
- *   Base state defaults: status="RUNNING", version=0, turns=0, tasks=empty, fileTree=[]
+ * @param subagents - Array of subagent configurations (must have at least one)
+ * @returns A tool definition with dynamic schema based on available subagents
  *
- * 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
+ * @example
+ * const taskTool = createTaskTool([
+ *   {
+ *     name: "researcher",
+ *     description: "Researches topics and gathers information",
+ *     workflow: "researcherWorkflow",
+ *     resultSchema: z.object({ findings: z.string() }),
+ *   },
+ * ]);
  */
-declare const AGENT_HANDLER_NAMES: {
-    readonly getAgentState: "getAgentState";
-    readonly waitForStateChange: "waitForStateChange";
-    readonly addMessage: "addMessage";
-};
-
-declare const taskCreateTool: {
-    name: "TaskCreate";
+declare function createTaskTool<T extends SubagentConfig[]>(subagents: T): {
+    name: string;
     description: string;
     schema: z.ZodObject<{
-        subject: z.ZodString;
+        subagent: z.ZodEnum<Record<string, string>>;
         description: z.ZodString;
-        activeForm: z.ZodString;
-        metadata: z.ZodRecord<z.ZodString, z.ZodString>;
-    }, z.core.$strip>;
+        prompt: z.ZodString;
+    }>;
 };
-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);
+ * Task tool args type (when subagent names are not known at compile time)
  */
-declare function createTaskCreateHandler<TCustom extends JsonSerializable<TCustom>>({ stateManager, idGenerator, }: {
-    stateManager: AgentStateManager<TCustom>;
-    idGenerator: () => string;
-}): (args: TaskCreateToolSchemaType) => ToolHandlerResponse<WorkflowTask>;
-
-declare const bashTool: {
-    name: "Bash";
+type TaskArgs = {
+    subagent: string;
     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;
+    prompt: 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.
@@ -171,17 +113,28 @@ 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>;
 }>;
 /**
  * Extract the tool names from a tool map (uses the tool's name property, not the key).
@@ -216,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.
- */
-interface ToolHandlerResponse<TResult> {
-    /** Content for the tool message added to the thread */
-    content: ToolMessageContent;
-    /** Result returned from processToolCalls */
-    result: TResult;
+ *
+ * Tools that don't return additional data should use `data: null` (TResult defaults to null).
+ * Tools that may fail to produce data should type TResult as `SomeType | null`.
+ */
+interface ToolHandlerResponse<TResult = null> {
+    /** 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;
+    /**
+     * 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.
@@ -254,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) => {
@@ -281,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;
-    result: TResult;
+    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 */
@@ -301,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.
@@ -405,6 +352,98 @@ 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.
+ *
+ * @example
+ * ```typescript
+ * tools: {
+ *   AskUser: defineTool({
+ *     ...askUserTool,
+ *     handler: handleAskUser,
+ *     hooks: {
+ *       onPostToolUse: ({ result }) => {
+ *         // result is correctly typed as the handler's return data type
+ *       },
+ *     },
+ *   }),
+ * }
+ * ```
+ */
+declare function defineTool<TName extends string, TSchema extends z$1.ZodType, TResult, TContext = ToolHandlerContext>(tool: ToolWithHandler<TName, TSchema, TResult, TContext>): ToolWithHandler<TName, TSchema, TResult, TContext>;
+/**
+ * Identity function that provides full type inference for subagent configurations.
+ * Verifies the workflow function's input parameters match the configured context,
+ * and properly types the lifecycle hooks with Task tool args and inferred result type.
+ *
+ * @example
+ * ```ts
+ * // With typed context — workflow must accept { prompt, context }
+ * const researcher = defineSubagent({
+ *   name: "researcher",
+ *   description: "Researches topics",
+ *   workflow: researcherWorkflow, // (input: { prompt: string; context: { apiKey: string } }) => Promise<...>
+ *   context: { apiKey: "..." },
+ *   resultSchema: z.object({ findings: z.string() }),
+ *   hooks: {
+ *     onPostExecution: ({ result }) => {
+ *       // result is typed as { findings: string }
+ *     },
+ *   },
+ * });
+ *
+ * // Without context — workflow only needs { prompt }
+ * const writer = defineSubagent({
+ *   name: "writer",
+ *   description: "Writes content",
+ *   workflow: writerWorkflow, // (input: { prompt: string }) => Promise<...>
+ *   resultSchema: z.object({ content: z.string() }),
+ * });
+ * ```
+ */
+declare function defineSubagent<TResult extends z$1.ZodType = z$1.ZodType, TContext extends Record<string, unknown> = Record<string, unknown>>(config: Omit<SubagentConfig<TResult>, "hooks" | "workflow" | "context"> & {
+    workflow: string | ((input: {
+        prompt: string;
+        context: TContext;
+    }) => Promise<any>);
+    context: TContext;
+    hooks?: SubagentHooks<TaskArgs, 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<TaskArgs, z$1.infer<TResult>>;
+}): SubagentConfig<TResult>;
 /**
  * Utility to check if there were no tool calls besides a specific one
  */
@@ -418,11 +457,12 @@ type AgentStatus = "RUNNING" | "WAITING_FOR_INPUT" | "COMPLETED" | "FAILED" | "C
  * Base state that all agents must have
  */
 interface BaseAgentState {
-    tools: ToolDefinition[];
+    tools: SerializableToolDefinition[];
     status: AgentStatus;
     version: number;
     turns: number;
     tasks: Map<string, WorkflowTask>;
+    systemPrompt: string;
 }
 /**
  * File representation for agent workflows
@@ -442,8 +482,8 @@ interface AgentFile {
 /**
  * Agent response from LLM invocation
  */
-interface AgentResponse {
-    message: StoredMessage;
+interface AgentResponse<M = StoredMessage> {
+    message: M;
     stopReason: string | null;
     usage?: {
         input_tokens?: number;
@@ -451,17 +491,33 @@ interface AgentResponse {
         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<M = StoredMessage> {
+    /** 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>;
+    /** Extract raw tool calls from a message */
+    parseToolCalls(message: M): Promise<RawToolCall[]>;
+}
 /**
  * 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<M>;
     /** Tool router for processing tool calls (optional if agent has no tools) */
     tools?: T;
     /** Subagent configurations */
@@ -470,27 +526,23 @@ 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.
+ * Uses a plain JSON Schema object instead of a live Zod instance,
+ * so it survives Temporal serialization without losing constraints (min, max, etc.).
+ */
+interface SerializableToolDefinition {
+    name: string;
+    description: string;
+    schema: Record<string, unknown>;
+    strict?: boolean;
+    max_uses?: number;
 }
 /**
  * Configuration passed to runAgent activity
@@ -503,13 +555,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;
 }
@@ -523,12 +577,43 @@ interface SubagentConfig<TResult extends z$1.ZodType = z$1.ZodType> {
     name: string;
     /** Description shown to the parent agent explaining what this subagent does */
     description: string;
-    /** Temporal workflow type name (used with executeChild) */
-    workflowType: string;
+    /** Temporal workflow function or type name (used with executeChild) */
+    workflow: string | Workflow;
     /** Optional task queue - defaults to parent's queue if not specified */
     taskQueue?: string;
     /** Optional Zod schema to validate the child workflow's result. If omitted, result is passed through as-is. */
     resultSchema?: TResult;
+    /** Optional static context passed to the subagent on every invocation */
+    context?: Record<string, unknown>;
+    /** Per-subagent lifecycle hooks */
+    hooks?: SubagentHooks;
+}
+/**
+ * Per-subagent lifecycle hooks - defined on a SubagentConfig.
+ * Runs in addition to global hooks (global pre → subagent pre → execute → subagent post → global post).
+ */
+interface SubagentHooks<TArgs = unknown, TResult = unknown> {
+    /** Called before this subagent executes - can skip or modify args */
+    onPreExecution?: (ctx: {
+        args: TArgs;
+        threadId: string;
+        turn: number;
+    }) => PreToolUseHookResult | Promise<PreToolUseHookResult>;
+    /** Called after this subagent executes successfully */
+    onPostExecution?: (ctx: {
+        args: TArgs;
+        result: TResult;
+        threadId: string;
+        turn: number;
+        durationMs: number;
+    }) => void | Promise<void>;
+    /** Called when this subagent execution fails */
+    onExecutionFailure?: (ctx: {
+        args: TArgs;
+        error: Error;
+        threadId: string;
+        turn: number;
+    }) => PostToolUseFailureHookResult | Promise<PostToolUseFailureHookResult>;
 }
 /**
  * Input passed to child workflows when spawned as subagents
@@ -536,6 +621,8 @@ interface SubagentConfig<TResult extends z$1.ZodType = z$1.ZodType> {
 interface SubagentInput {
     /** The prompt/task from the parent agent */
     prompt: string;
+    /** Optional context parameters passed from the parent agent */
+    context?: Record<string, unknown>;
 }
 /**
  * Status of a workflow task
@@ -669,6 +756,33 @@ interface SessionEndHookContext {
  * SessionEnd hook - called when session ends
  */
 type SessionEndHook = (ctx: SessionEndHookContext) => void | Promise<void>;
+/**
+ * Per-tool lifecycle hooks - defined directly on a tool definition.
+ * Runs in addition to global hooks (global pre → tool pre → execute → tool post → global post).
+ */
+interface ToolHooks<TArgs = unknown, TResult = unknown> {
+    /** Called before this tool executes - can skip or modify args */
+    onPreToolUse?: (ctx: {
+        args: TArgs;
+        threadId: string;
+        turn: number;
+    }) => PreToolUseHookResult | Promise<PreToolUseHookResult>;
+    /** Called after this tool executes successfully */
+    onPostToolUse?: (ctx: {
+        args: TArgs;
+        result: TResult;
+        threadId: string;
+        turn: number;
+        durationMs: number;
+    }) => void | Promise<void>;
+    /** Called when this tool execution fails */
+    onPostToolUseFailure?: (ctx: {
+        args: TArgs;
+        error: Error;
+        threadId: string;
+        turn: number;
+    }) => PostToolUseFailureHookResult | Promise<PostToolUseFailureHookResult>;
+}
 /**
  * Combined hooks interface for session lifecycle
  */
@@ -689,10 +803,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
@@ -703,45 +912,20 @@ 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>>;
 /**
- * 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
+ * Proxy the default ZeitlichSharedActivities as ThreadOps<StoredMessage>.
+ * Call this in workflow code for the standard LangChain/StoredMessage setup.
  *
  * @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)
+ * ```typescript
+ * const session = await createSession({
+ *   threadOps: proxyDefaultThreadOps(),
+ *   // ...
+ * });
+ * ```
  */
-type GenericTaskToolSchemaType = {
-    subagent: string;
-    description: string;
-    prompt: string;
-};
+declare function proxyDefaultThreadOps(options?: Parameters<typeof proxyActivities>[0]): ThreadOps<StoredMessage>;
 
 /**
  * Result from a task handler execution
@@ -758,7 +942,6 @@ interface TaskHandlerResult<TResult = unknown> {
  * 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.
@@ -768,10 +951,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.
      */
@@ -809,9 +988,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";
@@ -820,9 +999,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";
@@ -835,9 +1014,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";
@@ -847,9 +1026,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";
@@ -858,9 +1037,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";
@@ -871,9 +1050,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 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 EditToolSchemaType = z$1.infer<typeof editTool.schema>;
+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";
@@ -882,36 +1081,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";
@@ -927,17 +1120,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 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 };
+export { type ThreadOps 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 SubagentConfig as M, type SubagentHooks as N, type SubagentInput as O, type ParsedToolCall as P, type TaskCreateArgs as Q, type RawToolCall as R, type SessionEndHook as S, type TaskArgs as T, type TaskGetArgs as U, type TaskHandlerResult as V, type TaskListArgs as W, type TaskStatus as X, type TaskUpdateArgs as Y, type ThreadManager as Z, type ThreadManagerConfig as _, type ActivityToolHandler as a, type ToolArgs as a0, type ToolCallResult as a1, type ToolCallResultUnion as a2, type ToolDefinition as a3, type ToolHandler as a4, type ToolHandlerContext as a5, type ToolHandlerResponse as a6, type ToolHooks as a7, type ToolMap as a8, type ToolMessageContent as a9, globTool as aA, grepTool as aB, hasNoOtherToolCalls as aC, isTerminalStatus as aD, proxyDefaultThreadOps as aE, readTool as aF, taskCreateTool as aG, taskGetTool as aH, taskListTool as aI, taskUpdateTool as aJ, withAutoAppend as aK, writeTool as aL, type ToolNames as aa, type ToolResult as ab, type ToolResultConfig as ac, type ToolRouter as ad, type ToolWithHandler as ae, type WorkflowTask as af, type ZeitlichAgentConfig as ag, type ZeitlichSession as ah, type ZeitlichSharedActivities as ai, askUserQuestionTool as aj, bashTool as ak, createAgentStateManager as al, createBashToolDescription as am, createSession as an, createSharedActivities as ao, createTaskCreateHandler as ap, createTaskGetHandler as aq, createTaskListHandler as ar, createTaskTool as as, createTaskUpdateHandler as at, createThreadManager as au, createToolRouter as av, defineSubagent as aw, defineTool as ax, editTool as ay, getStateQuery 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 };