zeitlich 0.2.0 → 0.2.2

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

@@ -1,13 +1,93 @@
+import Redis from 'ioredis';
 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';
+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 {
+    redis: Redis;
+    threadId: string;
+    /** Thread key, defaults to 'messages' */
+    key?: string;
+}
+interface ThreadManager {
+    /** Append a system message to the thread */
+    appendSystemMessage(content: string): Promise<void>;
+    /** Initialize an empty thread */
+    initialize(): Promise<void>;
+    /** Load all messages from the thread */
+    load(): Promise<StoredMessage[]>;
+    /** Append messages to the thread */
+    append(messages: StoredMessage[]): Promise<void>;
+    /** Delete the thread */
+    delete(): Promise<void>;
+    /** Create a SystemMessage (returns StoredMessage for storage) */
+    createSystemMessage(content: string): 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>;
+}
+/**
+ * Creates a thread manager for handling conversation state in Redis.
+ */
+declare function createThreadManager(config: ThreadManagerConfig): ThreadManager;
+
+/**
+ * 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",
+ *     workflow: "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;
+};
 
 /**
  * JSON primitive types that Temporal can serialize
@@ -80,9 +160,10 @@ interface AgentStateManager<TCustom extends JsonSerializable<TCustom>> {
     setTask(task: WorkflowTask): void;
     /** Delete a task by ID */
     deleteTask(id: string): boolean;
-    /** Set the tools */
+    /** 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.
  *
@@ -125,10 +206,7 @@ type TaskCreateToolSchemaType = z.infer<typeof taskCreateTool.schema>;
  * @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 function createTaskCreateHandler<TCustom extends JsonSerializable<TCustom>>(stateManager: AgentStateManager<TCustom>): (args: TaskCreateToolSchemaType) => ToolHandlerResponse<WorkflowTask>;
 
 declare const bashTool: {
     name: "Bash";
@@ -145,7 +223,9 @@ type BashExecOut = {
     stderr: string;
     stdout: string;
 };
-declare const handleBashTool: (fs: IFileSystem) => ActivityToolHandler<bashToolSchemaType, BashExecOut | null>;
+/** 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.
@@ -169,6 +249,8 @@ interface ToolWithHandler<TName extends string = string, TSchema extends z$1.Zod
     handler: ToolHandler<z$1.infer<TSchema>, TResult, TContext>;
     strict?: boolean;
     max_uses?: number;
+    /** 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.
@@ -180,6 +262,7 @@ type ToolMap = Record<string, {
     handler: (args: any, context: any) => ToolHandlerResponse<any> | Promise<ToolHandlerResponse<any>>;
     strict?: boolean;
     max_uses?: number;
+    hooks?: ToolHooks<any, any>;
 }>;
 /**
  * Extract the tool names from a tool map (uses the tool's name property, not the key).
@@ -216,10 +299,10 @@ type AppendToolResultFn = (config: ToolResultConfig) => Promise<void>;
  * 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;
+    /** 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;
 }
 /**
  * Context passed to tool handlers for additional data beyond tool args.
@@ -279,7 +362,7 @@ 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 | null;
 }
 /**
  * Options for creating a tool router.
@@ -403,6 +486,70 @@ interface ToolRouter<T extends ToolMap> {
  * ```
  */
 declare function createToolRouter<T extends ToolMap>(options: ToolRouterOptions<T>): ToolRouter<T>;
+/**
+ * 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<GenericTaskToolSchemaType, 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>>;
+}): SubagentConfig<TResult>;
 /**
  * Utility to check if there were no tool calls besides a specific one
  */
@@ -416,7 +563,7 @@ 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;
@@ -490,6 +637,18 @@ interface ZeitlichAgentConfig<T extends ToolMap> {
         [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
  */
@@ -521,12 +680,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
@@ -534,6 +724,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
@@ -667,6 +859,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 | null;
+        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
  */
@@ -703,44 +922,6 @@ interface SessionLifecycleHooks {
 }
 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
  */
@@ -938,4 +1119,4 @@ type TaskUpdateToolSchemaType = z.infer<typeof taskUpdateTool.schema>;
  */
 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 };
+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 };