zeitlich 0.2.11 → 0.2.13

package/dist/workflow.d.cts

@@ -1,7 +1,460 @@
-export { a as ActivityToolHandler, d as AgentConfig, e as AgentFile, A as AgentResponse, f as AgentState, g as AgentStateManager, h as AgentStatus, i as AppendToolResultFn, j as AskUserQuestionArgs, k as BaseAgentState, B as BashArgs, F as FileEditArgs, m as FileReadArgs, n as FileWriteArgs, G as GlobArgs, o as GrepArgs, I as InferToolResults, J as JsonPrimitive, p as JsonSerializable, q as JsonValue, P as ParsedToolCall, r as ParsedToolCallUnion, s as PostToolUseFailureHook, t as PostToolUseFailureHookContext, u as PostToolUseFailureHookResult, v as PostToolUseHook, w as PostToolUseHookContext, x as PreToolUseHook, y as PreToolUseHookContext, z as PreToolUseHookResult, C as ProcessToolCallsContext, R as RawToolCall, D as ReadSkillArgs, E as RunAgentActivity, H as RunAgentConfig, K as SessionEndHook, L as SessionEndHookContext, M as SessionExitReason, N as SessionLifecycleHooks, O as SessionStartHook, Q as SessionStartHookContext, c as Skill, b as SkillMetadata, S as SkillProvider, T as SubagentArgs, U as SubagentConfig, V as SubagentHooks, W as SubagentInput, X as SubagentWorkflow, Y as TaskCreateArgs, Z as TaskGetArgs, _ as TaskListArgs, $ as TaskStatus, a0 as TaskUpdateArgs, a3 as ThreadOps, a4 as ToolArgs, a5 as ToolCallResult, a6 as ToolCallResultUnion, a7 as ToolDefinition, a8 as ToolHandler, a9 as ToolHandlerContext, aa as ToolHandlerResponse, ab as ToolHooks, ac as ToolMap, ad as ToolMessageContent, ae as ToolNames, af as ToolResult, ag as ToolResultConfig, ah as ToolRouter, ai as ToolWithHandler, aj as WorkflowTask, ak as ZeitlichSession, al as ZeitlichSharedActivities, am as agentQueryName, an as agentStateChangeUpdateName, ao as askUserQuestionTool, ap as bashTool, aq as createAgentStateManager, ar as createAskUserQuestionHandler, as as createBashToolDescription, at as createReadSkillHandler, au as createReadSkillTool, av as createSession, ax as createSubagentTool, ay as createTaskCreateHandler, az as createTaskGetHandler, aA as createTaskListHandler, aB as createTaskUpdateHandler, aD as createToolRouter, aE as defineSubagent, aF as defineTool, aG as editTool, aH as globTool, aI as grepTool, aJ as hasNoOtherToolCalls, aK as isTerminalStatus, aL as parseSkillFile, aM as proxyDefaultThreadOps, aN as readFileTool, aO as taskCreateTool, aP as taskGetTool, aQ as taskListTool, aR as taskUpdateTool, aT as writeFileTool } from './workflow-BhjsEQc1.cjs';
-import '@temporalio/workflow';
-import 'ioredis';
-import '@langchain/core/messages';
-import 'zod';
+import { QueryDefinition, proxyActivities } from '@temporalio/workflow';
+import { B as BaseAgentState, g as AgentStatus, a9 as WorkflowTask, Z as ToolDefinition, G as SessionStartHook, D as SessionEndHook, F as SessionExitReason, a2 as ToolMap, z as SessionConfig, e as AgentConfig, T as ThreadOps, c as SkillMetadata, d as Skill, a0 as ToolHandlerResponse, _ as ToolHandler, b as ActivityToolHandler } from './model-invoker-y_zlyMqu.cjs';
+export { f as AgentFile, A as AgentResponse, h as AppendToolResultFn, C as ContentPart, H as Hooks, I as InferToolResults, i as MessageContent, M as ModelInvoker, a as ModelInvokerConfig, P as ParsedToolCall, j as ParsedToolCallUnion, k as PostHumanMessageAppendHook, l as PostHumanMessageAppendHookContext, m as PostToolUseFailureHook, n as PostToolUseFailureHookContext, o as PostToolUseFailureHookResult, p as PostToolUseHook, q as PostToolUseHookContext, r as PreHumanMessageAppendHook, s as PreHumanMessageAppendHookContext, t as PreToolUseHook, u as PreToolUseHookContext, v as PreToolUseHookResult, w as ProcessToolCallsContext, x as RawToolCall, y as RunAgentActivity, R as RunAgentConfig, E as SessionEndHookContext, J as SessionStartHookContext, S as SkillProvider, K as SubagentArgs, L as SubagentConfig, N as SubagentHooks, O as SubagentInput, Q as SubagentWorkflow, U as TaskStatus, V as TokenUsage, W as ToolArgs, X as ToolCallResult, Y as ToolCallResultUnion, $ as ToolHandlerContext, a1 as ToolHooks, a3 as ToolMessageContent, a4 as ToolNames, a5 as ToolResult, a6 as ToolResultConfig, a7 as ToolRouter, a8 as ToolWithHandler, aa as agentQueryName, ab as agentStateChangeUpdateName, ac as createSubagentTool, ad as createToolRouter, ae as defineSubagent, af as defineTool, ag as hasNoOtherToolCalls, ah as isTerminalStatus } from './model-invoker-y_zlyMqu.cjs';
+import { UpdateDefinition } from '@temporalio/common/lib/interfaces';
+import z, { z as z$1 } from 'zod';
 import '@temporalio/common';
-import '@temporalio/common/lib/interfaces';
+
+/**
+ * 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>> {
+    /** Typed query definition registered for this agent's state */
+    readonly stateQuery: QueryDefinition<AgentState<TCustom>>;
+    /** Typed update definition registered for waiting on this agent's state change */
+    readonly stateChangeUpdate: UpdateDefinition<AgentState<TCustom>, [number]>;
+    /** 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 the system prompt */
+    getSystemPrompt(): string | undefined;
+    /** Set the system prompt */
+    setSystemPrompt(newSystemPrompt: string): void;
+    /** 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;
+    /** Update the usage */
+    updateUsage(usage: {
+        inputTokens?: number;
+        outputTokens?: number;
+        cachedWriteTokens?: number;
+        cachedReadTokens?: number;
+        reasonTokens?: number;
+    }): void;
+    /** Get the total usage */
+    getTotalUsage(): {
+        totalInputTokens: number;
+        totalOutputTokens: number;
+        totalCachedWriteTokens: number;
+        totalCachedReadTokens: number;
+        totalReasonTokens: number;
+        turns: number;
+    };
+}
+/**
+ * Creates an agent state manager for tracking workflow state.
+ * Automatically registers Temporal query and update handlers for the agent.
+ *
+ * @param options.agentName - Unique agent name, used to derive query/update handler names
+ * @param options.initialState - Optional initial values for base and custom state.
+ *   Use `systemPrompt` here to set the agent's system prompt.
+ *   Base state defaults: status="RUNNING", version=0, turns=0, tasks=empty
+ *
+ * @example
+ * ```typescript
+ * const stateManager = createAgentStateManager({
+ *   initialState: {
+ *     systemPrompt: "You are a helpful assistant.",
+ *   },
+ *   agentName: "my-agent",
+ * });
+ *
+ * // With custom state fields
+ * const stateManager = createAgentStateManager({
+ *   initialState: {
+ *     systemPrompt: agentConfig.systemPrompt,
+ *     customField: "value",
+ *   },
+ *   agentName: agentConfig.agentName,
+ * });
+ * ```
+ */
+declare function createAgentStateManager<TCustom extends JsonSerializable<TCustom> = Record<string, never>>({ initialState, agentName, }: {
+    initialState?: Partial<BaseAgentState> & TCustom;
+    agentName: string;
+}): AgentStateManager<TCustom>;
+
+interface ZeitlichSession<M = unknown> {
+    runSession<T extends JsonSerializable<T>>(args: {
+        stateManager: AgentStateManager<T>;
+    }): Promise<{
+        finalMessage: M | null;
+        exitReason: SessionExitReason;
+        usage: ReturnType<AgentStateManager<T>["getTotalUsage"]>;
+    }>;
+}
+/**
+ * Session-level hooks for lifecycle events
+ */
+interface SessionLifecycleHooks {
+    /** Called when session starts */
+    onSessionStart?: SessionStartHook;
+    /** Called when session ends */
+    onSessionEnd?: SessionEndHook;
+}
+/**
+ * Creates an agent session that manages the agent loop: LLM invocation,
+ * tool routing, subagent coordination, and lifecycle hooks.
+ *
+ * @param config - Session and agent configuration (merged `SessionConfig` and `AgentConfig`)
+ * @returns A session object with `runSession()` to start the agent loop
+ *
+ * @example
+ * ```typescript
+ * import { createSession, createAgentStateManager, defineTool, bashTool } from 'zeitlich/workflow';
+ *
+ * const stateManager = createAgentStateManager({
+ *   initialState: { systemPrompt: "You are a helpful assistant." },
+ *   agentName: "my-agent",
+ * });
+ *
+ * const session = await createSession({
+ *   agentName: "my-agent",
+ *   maxTurns: 20,
+ *   threadId: runId,
+ *   runAgent: runAgentActivity,
+ *   buildContextMessage: () => [{ type: "text", text: prompt }],
+ *   subagents: [researcherSubagent],
+ *   tools: {
+ *     Bash: defineTool({ ...bashTool, handler: bashHandlerActivity }),
+ *   },
+ * });
+ *
+ * const { finalMessage, exitReason } = await session.runSession({ stateManager });
+ * ```
+ */
+declare const createSession: <T extends ToolMap, M = unknown>({ threadId: providedThreadId, agentName, maxTurns, metadata, runAgent, threadOps, buildContextMessage, subagents, skills, tools, processToolsInParallel, hooks, appendSystemPrompt, continueThread, waitForInputTimeout, }: SessionConfig<T, M> & AgentConfig) => Promise<ZeitlichSession<M>>;
+/**
+ * Proxy the adapter's thread operations as Temporal activities.
+ * Call this in workflow code to delegate thread operations to the
+ * adapter-provided activities registered on the worker.
+ *
+ * @example
+ * ```typescript
+ * const session = await createSession({
+ *   threadOps: proxyDefaultThreadOps(),
+ *   // ...
+ * });
+ * ```
+ */
+declare function proxyDefaultThreadOps(options?: Parameters<typeof proxyActivities>[0]): ThreadOps;
+
+/**
+ * Generate a compact, workflow-deterministic identifier.
+ *
+ * Uses Temporal's `uuid4()` internally (seeded by the workflow's RNG),
+ * then re-encodes the hex bytes into a base-62 alphabet for a shorter,
+ * more token-efficient identifier (~3 tokens vs ~10 for a full UUID).
+ *
+ * Suitable for thread IDs, child workflow IDs, or any workflow-scoped identifier.
+ *
+ * @param length - Number of base-62 characters (default 12, ~71 bits of entropy)
+ */
+declare function getShortId(length?: number): string;
+
+/**
+ * Parse a SKILL.md file into its frontmatter fields and markdown body.
+ *
+ * Handles the limited YAML subset used by the agentskills.io spec:
+ * flat key-value pairs plus one-level nested `metadata` map.
+ * No external YAML dependency required.
+ */
+declare function parseSkillFile(raw: string): {
+    frontmatter: SkillMetadata;
+    body: string;
+};
+
+/**
+ * Creates a ReadSkill tool configured with the available skills.
+ * The tool description embeds skill metadata so the agent discovers
+ * skills purely through the tool definition.
+ */
+declare function createReadSkillTool(skills: Skill[]): {
+    name: string;
+    description: string;
+    schema: z.ZodObject<{
+        skill_name: z.ZodEnum<Record<string, string>>;
+    }>;
+};
+type ReadSkillArgs = {
+    skill_name: string;
+};
+
+/**
+ * Creates a ReadSkill handler that looks up skills from an in-memory array.
+ * Runs directly in the workflow (like task tools) — no activity needed.
+ */
+declare function createReadSkillHandler(skills: Skill[]): (args: ReadSkillArgs) => ToolHandlerResponse<null>;
+
+declare const globTool: {
+    name: "Glob";
+    description: string;
+    schema: z$1.ZodObject<{
+        pattern: z$1.ZodString;
+        root: z$1.ZodOptional<z$1.ZodString>;
+    }, z$1.core.$strip>;
+    strict: true;
+};
+type GlobArgs = z$1.infer<typeof globTool.schema>;
+
+declare const grepTool: {
+    name: "Grep";
+    description: string;
+    schema: z$1.ZodObject<{
+        pattern: z$1.ZodString;
+        ignoreCase: z$1.ZodOptional<z$1.ZodBoolean>;
+        maxMatches: z$1.ZodOptional<z$1.ZodNumber>;
+        includePatterns: z$1.ZodOptional<z$1.ZodArray<z$1.ZodString>>;
+        excludePatterns: z$1.ZodOptional<z$1.ZodArray<z$1.ZodString>>;
+        contextLines: z$1.ZodOptional<z$1.ZodNumber>;
+    }, z$1.core.$strip>;
+    strict: true;
+};
+type GrepArgs = z$1.infer<typeof grepTool.schema>;
+
+declare const readFileTool: {
+    name: "FileRead";
+    description: string;
+    schema: z$1.ZodObject<{
+        path: z$1.ZodString;
+        offset: z$1.ZodOptional<z$1.ZodNumber>;
+        limit: z$1.ZodOptional<z$1.ZodNumber>;
+    }, z$1.core.$strip>;
+    strict: true;
+};
+type FileReadArgs = z$1.infer<typeof readFileTool.schema>;
+
+declare const writeFileTool: {
+    name: "FileWrite";
+    description: string;
+    schema: z$1.ZodObject<{
+        file_path: z$1.ZodString;
+        content: z$1.ZodString;
+    }, z$1.core.$strip>;
+    strict: true;
+};
+type FileWriteArgs = z$1.infer<typeof writeFileTool.schema>;
+
+declare const editTool: {
+    name: "FileEdit";
+    description: string;
+    schema: z$1.ZodObject<{
+        file_path: z$1.ZodString;
+        old_string: z$1.ZodString;
+        new_string: z$1.ZodString;
+        replace_all: z$1.ZodOptional<z$1.ZodBoolean>;
+    }, z$1.core.$strip>;
+    strict: 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 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";
+    description: string;
+    schema: z.ZodObject<{
+        taskId: z.ZodString;
+    }, z.core.$strip>;
+};
+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 ToolHandler for TaskGet tool calls
+ */
+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 TaskListArgs = z.infer<typeof taskListTool.schema>;
+
+/**
+ * Creates a TaskList handler that returns all tasks.
+ *
+ * @param stateManager - State manager containing tasks state
+ * @returns A ToolHandler for TaskList tool calls
+ */
+declare function createTaskListHandler<TCustom extends JsonSerializable<TCustom>>(stateManager: AgentStateManager<TCustom>): ToolHandler<TaskListArgs, WorkflowTask[]>;
+
+declare const taskUpdateTool: {
+    name: "TaskUpdate";
+    description: string;
+    schema: z.ZodObject<{
+        taskId: z.ZodString;
+        status: z.ZodEnum<{
+            pending: "pending";
+            in_progress: "in_progress";
+            completed: "completed";
+        }>;
+        addBlockedBy: z.ZodArray<z.ZodString>;
+        addBlocks: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>;
+};
+type 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 ToolHandler for TaskUpdate tool calls
+ */
+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>;
+
+declare const askUserQuestionTool: {
+    name: "AskUserQuestion";
+    description: string;
+    schema: z.ZodObject<{
+        questions: z.ZodArray<z.ZodObject<{
+            question: z.ZodString;
+            header: z.ZodString;
+            options: z.ZodArray<z.ZodObject<{
+                label: z.ZodString;
+                description: z.ZodString;
+            }, z.core.$strip>>;
+            multiSelect: z.ZodBoolean;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    strict: true;
+};
+type AskUserQuestionArgs = z.infer<typeof askUserQuestionTool.schema>;
+
+/**
+ * Creates a handler for the AskUserQuestion tool.
+ * Returns question data for display to the user via your UI layer.
+ *
+ * Typically paired with `stateManager.waitForInput()` in a `hooks.onPostToolUse`
+ * callback to pause the agent loop until the user responds.
+ *
+ * @example
+ * ```typescript
+ * import { createAskUserQuestionHandler } from 'zeitlich';
+ * import { askUserQuestionTool, defineTool } from 'zeitlich/workflow';
+ *
+ * // In activities
+ * const askUserQuestionHandlerActivity = createAskUserQuestionHandler();
+ *
+ * // In workflow
+ * tools: {
+ *   AskUserQuestion: defineTool({
+ *     ...askUserQuestionTool,
+ *     handler: askUserQuestionHandlerActivity,
+ *     hooks: {
+ *       onPostToolUse: () => { stateManager.waitForInput(); },
+ *     },
+ *   }),
+ * }
+ * ```
+ */
+declare const createAskUserQuestionHandler: () => ActivityToolHandler<AskUserQuestionArgs, {
+    questions: {
+        question: string;
+        header: string;
+        options: {
+            label: string;
+            description: string;
+        }[];
+        multiSelect: boolean;
+    }[];
+}>;
+
+export { ActivityToolHandler, AgentConfig, type AgentState, type AgentStateManager, AgentStatus, type AskUserQuestionArgs, BaseAgentState, type BashArgs, type FileEditArgs, type FileReadArgs, type FileWriteArgs, type GlobArgs, type GrepArgs, type JsonPrimitive, type JsonSerializable, type JsonValue, type ReadSkillArgs, SessionConfig, SessionEndHook, SessionExitReason, type SessionLifecycleHooks, SessionStartHook, Skill, SkillMetadata, type TaskCreateArgs, type TaskGetArgs, type TaskListArgs, type TaskUpdateArgs, ThreadOps, ToolDefinition, ToolHandler, ToolHandlerResponse, ToolMap, WorkflowTask, type ZeitlichSession, askUserQuestionTool, bashTool, createAgentStateManager, createAskUserQuestionHandler, createBashToolDescription, createReadSkillHandler, createReadSkillTool, createSession, createTaskCreateHandler, createTaskGetHandler, createTaskListHandler, createTaskUpdateHandler, editTool, getShortId, globTool, grepTool, parseSkillFile, proxyDefaultThreadOps, readFileTool, taskCreateTool, taskGetTool, taskListTool, taskUpdateTool, writeFileTool };