zeitlich 0.2.25 → 0.2.26

package/dist/{types-D_igp10o.d.cts → types-mCVxKIZb.d.cts}

@@ -1,130 +1,6 @@
+import { ActivityFunctionWithOptions, QueryDefinition } from '@temporalio/workflow';
+import { UpdateDefinition } from '@temporalio/common/lib/interfaces';
 import { z } from 'zod';
-import { ActivityFunctionWithOptions } from '@temporalio/workflow';
-
-/** A single content part within a structured message (text, image, etc.) */
-type ContentPart = {
-    type: string;
-    [key: string]: unknown;
-};
-/** Message content — plain string or an array of structured content parts */
-type MessageContent = string | ContentPart[];
-/** Content returned by a tool handler */
-type ToolMessageContent = MessageContent;
-/**
- * Agent execution status
- */
-type AgentStatus = "RUNNING" | "WAITING_FOR_INPUT" | "COMPLETED" | "FAILED" | "CANCELLED";
-/**
- * Base state that all agents must have
- */
-interface BaseAgentState {
-    tools: SerializableToolDefinition[];
-    status: AgentStatus;
-    version: number;
-    turns: number;
-    tasks: Map<string, WorkflowTask>;
-    systemPrompt?: string;
-    totalInputTokens: number;
-    totalOutputTokens: number;
-    cachedWriteTokens: number;
-    cachedReadTokens: number;
-}
-/**
- * File representation for agent workflows
- */
-interface AgentFile {
-    /** Database/S3 file ID */
-    id: string;
-    /** Virtual path for agent (e.g., "evidence/invoice.pdf") */
-    path: string;
-    /** Original filename */
-    filename: string;
-    /** Generic description for prompt */
-    description?: string;
-    /** MIME type of the file */
-    mimeType?: string;
-}
-interface TokenUsage {
-    inputTokens?: number;
-    outputTokens?: number;
-    cachedWriteTokens?: number;
-    cachedReadTokens?: number;
-    reasonTokens?: number;
-}
-/**
- * Configuration for a Zeitlich agent
- */
-interface AgentConfig {
-    /** The name of the agent, should be unique within the workflows, ideally Pascal Case */
-    agentName: string;
-    /** Description, used for sub agents */
-    description?: string;
-}
-/**
- * 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
- */
-interface RunAgentConfig extends AgentConfig {
-    /** The thread ID to use for the session */
-    threadId: string;
-    /** Metadata for the session */
-    metadata?: Record<string, unknown>;
-}
-/**
- * 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;
-}
-/**
- * Status of a workflow task
- */
-type TaskStatus = "pending" | "in_progress" | "completed";
-/**
- * A task managed within a workflow for tracking work items
- */
-interface WorkflowTask {
-    /** Unique task identifier */
-    id: string;
-    /** Brief, actionable title in imperative form */
-    subject: string;
-    /** Detailed description of what needs to be done */
-    description: string;
-    /** Present continuous form shown in spinner when in_progress */
-    activeForm: string;
-    /** Current status of the task */
-    status: TaskStatus;
-    /** Arbitrary key-value pairs for tracking */
-    metadata: Record<string, string>;
-    /** IDs of tasks that must complete before this one can start */
-    blockedBy: string[];
-    /** IDs of tasks that are waiting for this one to complete */
-    blocks: string[];
-}
-/**
- * Exit reasons for session termination
- */
-type SessionExitReason = "completed" | "max_turns" | "waiting_for_input" | "failed" | "cancelled";
-/**
- * Helper to check if status is terminal
- */
-declare function isTerminalStatus(status: AgentStatus): boolean;
 
 /**
  * A tool definition with a name, description, and Zod schema for arguments.
@@ -141,11 +17,11 @@ interface ToolDefinition<TName extends string = string, TSchema extends z.ZodTyp
  * A tool definition with an integrated handler function.
  * This is the primary type for defining tools in the router.
  */
-interface ToolWithHandler<TName extends string = string, TSchema extends z.ZodType = z.ZodType, TResult = unknown, TContext extends RouterContext = RouterContext> {
+interface ToolWithHandler<TName extends string = string, TSchema extends z.ZodType = z.ZodType, TResult = unknown, TContext extends RouterContext = RouterContext, TToolResponse = JsonValue> {
     name: TName;
     description: string;
     schema: TSchema;
-    handler: ToolHandler<z.infer<TSchema>, TResult, TContext>;
+    handler: ToolHandler<z.infer<TSchema>, TResult, TContext, TToolResponse>;
     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. */
@@ -165,7 +41,7 @@ type ToolMap = Record<string, {
     name: string;
     description: string | (() => string);
     schema: z.ZodType | (() => z.ZodType);
-    handler: ToolHandler<any, any, any>;
+    handler: ToolHandler<any, any, any, any>;
     strict?: boolean;
     max_uses?: number;
     enabled?: boolean | (() => boolean);
@@ -208,9 +84,9 @@ type AppendToolResultFn = ActivityFunctionWithOptions<(id: string, config: ToolR
  * 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> {
+interface ToolHandlerResponse<TResult = null, TToolResponse = JsonValue> {
     /** Content sent back to the LLM as the tool call response */
-    toolResponse: ToolMessageContent;
+    toolResponse: TToolResponse;
     /** Data returned to the workflow and hooks for further processing */
     data: TResult;
     /**
@@ -235,6 +111,8 @@ interface ToolHandlerResponse<TResult = null> {
  */
 interface RouterContext {
     threadId: string;
+    /** Redis key suffix for thread storage. Defaults to 'messages'. */
+    threadKey?: string;
     toolCallId: string;
     toolName: string;
     sandboxId?: string;
@@ -246,7 +124,7 @@ interface RouterContext {
  * Receives the parsed args and a context that always includes {@link RouterContext}
  * fields, plus any additional properties when TContext extends RouterContext.
  */
-type ToolHandler<TArgs, TResult, TContext extends RouterContext = RouterContext> = (args: TArgs, context: TContext) => ToolHandlerResponse<TResult> | Promise<ToolHandlerResponse<TResult>>;
+type ToolHandler<TArgs, TResult, TContext extends RouterContext = RouterContext, TToolResponse = JsonValue> = (args: TArgs, context: TContext) => ToolHandlerResponse<TResult, TToolResponse> | Promise<ToolHandlerResponse<TResult, TToolResponse>>;
 /**
  * Activity-compatible tool handler that always returns a Promise.
  * Use this for tool handlers registered as Temporal activities.
@@ -263,7 +141,7 @@ type ToolHandler<TArgs, TResult, TContext extends RouterContext = RouterContext>
  * };
  * ```
  */
-type ActivityToolHandler<TArgs, TResult, TContext extends RouterContext = RouterContext> = (args: TArgs, context: TContext) => Promise<ToolHandlerResponse<TResult>>;
+type ActivityToolHandler<TArgs, TResult, TContext extends RouterContext = RouterContext, TToolResponse = JsonValue> = (args: TArgs, context: TContext) => Promise<ToolHandlerResponse<TResult, TToolResponse>>;
 /**
  * Extract the args type for a specific tool name from a tool map.
  */
@@ -275,7 +153,7 @@ type ToolArgs<T extends ToolMap, TName extends ToolNames<T>> = z.infer<Extract<T
  */
 type ToolResult<T extends ToolMap, TName extends ToolNames<T>> = Extract<T[keyof T], {
     name: TName;
-}>["handler"] extends ToolHandler<unknown, infer R, RouterContext> ? Awaited<R> : never;
+}>["handler"] extends ToolHandler<unknown, infer R, RouterContext, any> ? Awaited<R> : never;
 /**
  * The result of processing a tool call.
  */
@@ -291,7 +169,7 @@ interface ToolCallResult<TName extends string = string, TResult = unknown> {
  * Infer result types from a tool map based on handler return types.
  */
 type InferToolResults<T extends ToolMap> = {
-    [K in keyof T as T[K]["name"]]: T[K]["handler"] extends ToolHandler<any, infer R, any> ? Awaited<R> : never;
+    [K in keyof T as T[K]["name"]]: T[K]["handler"] extends ToolHandler<any, infer R, any, any> ? Awaited<R> : never;
 };
 /**
  * Union of all possible tool call results based on handler return types.
@@ -324,7 +202,7 @@ interface PreToolUseHookResult {
  */
 interface PostToolUseFailureHookResult {
     /** Provide a fallback result instead of throwing */
-    fallbackContent?: ToolMessageContent;
+    fallbackContent?: JsonValue;
     /** Whether to suppress the error (still logs, but continues) */
     suppress?: boolean;
 }
@@ -427,6 +305,8 @@ interface ToolRouterOptions<T extends ToolMap> {
     tools: T;
     /** Thread ID for appending tool results */
     threadId: string;
+    /** Redis key suffix for thread storage. Defaults to 'messages'. */
+    threadKey?: string;
     /** Function to append tool results to the thread (called automatically after each handler).
      *  Accepts a Temporal activity proxy with {@link ActivityFunctionWithOptions}. */
     appendToolResult: AppendToolResultFn;
@@ -486,4 +366,220 @@ interface ToolRouter<T extends ToolMap> {
     getResultsByName<TName extends ToolNames<T>>(results: ToolCallResultUnion<InferToolResults<T>>[], name: TName): ToolCallResult<TName, ToolResult<T, TName>>[];
 }
 
-export { type ActivityToolHandler as A, type BaseAgentState as B, type ContentPart as C, type ToolCallResult as D, type ToolHandler as E, type ToolHooks as F, type ToolNames as G, type ToolResult as H, type InferToolResults as I, type ToolRouter as J, type ToolWithHandler as K, isTerminalStatus as L, type MessageContent as M, type ToolRouterOptions as N, type PreToolUseHookResult as P, type RouterContext as R, type SessionExitReason as S, type ToolMessageContent as T, type WorkflowTask as W, type ToolMap as a, type ToolRouterHooks as b, type ToolHandlerResponse as c, type PostToolUseFailureHookResult as d, type RawToolCall as e, type TokenUsage as f, type RunAgentConfig as g, type AgentStatus as h, type ToolDefinition as i, type ToolResultConfig as j, type ToolCallResultUnion as k, type AgentConfig as l, type AgentFile as m, type AppendToolResultFn as n, type ParsedToolCall as o, type ParsedToolCallUnion as p, type PostToolUseFailureHook as q, type PostToolUseFailureHookContext as r, type PostToolUseHook as s, type PostToolUseHookContext as t, type PreToolUseHook as u, type PreToolUseHookContext as v, type ProcessToolCallsContext as w, type SerializableToolDefinition as x, type TaskStatus as y, type ToolArgs as z };
+/**
+ * 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;
+    /** Bulk-merge a partial update into custom state (e.g. from sandbox stateUpdate) */
+    mergeUpdate(update: Partial<TCustom>): 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: TokenUsage): void;
+    /** Get the total usage */
+    getTotalUsage(): {
+        totalInputTokens: number;
+        totalOutputTokens: number;
+        totalCachedWriteTokens: number;
+        totalCachedReadTokens: number;
+        totalReasonTokens: number;
+        turns: number;
+    };
+}
+
+/**
+ * Agent execution status
+ */
+type AgentStatus = "RUNNING" | "WAITING_FOR_INPUT" | "COMPLETED" | "FAILED" | "CANCELLED";
+/**
+ * Base state that all agents must have
+ */
+interface BaseAgentState {
+    tools: SerializableToolDefinition[];
+    status: AgentStatus;
+    version: number;
+    turns: number;
+    tasks: Map<string, WorkflowTask>;
+    systemPrompt?: string;
+    totalInputTokens: number;
+    totalOutputTokens: number;
+    cachedWriteTokens: number;
+    cachedReadTokens: number;
+}
+/**
+ * File representation for agent workflows
+ */
+interface AgentFile {
+    /** Database/S3 file ID */
+    id: string;
+    /** Virtual path for agent (e.g., "evidence/invoice.pdf") */
+    path: string;
+    /** Original filename */
+    filename: string;
+    /** Generic description for prompt */
+    description?: string;
+    /** MIME type of the file */
+    mimeType?: string;
+}
+interface TokenUsage {
+    inputTokens?: number;
+    outputTokens?: number;
+    cachedWriteTokens?: number;
+    cachedReadTokens?: number;
+    reasonTokens?: number;
+}
+/**
+ * Configuration for a Zeitlich agent
+ */
+interface AgentConfig {
+    /** The name of the agent, should be unique within the workflows, ideally Pascal Case */
+    agentName: string;
+    /** Description, used for sub agents */
+    description?: string;
+}
+/**
+ * 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
+ */
+interface RunAgentConfig extends AgentConfig {
+    /** The thread ID to use for the session */
+    threadId: string;
+    /** Redis key suffix for thread storage. Defaults to 'messages'. */
+    threadKey?: string;
+    /** Metadata for the session */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Configuration for appending a tool result
+ */
+interface ToolResultConfig {
+    threadId: string;
+    /** Redis key suffix for thread storage. Defaults to 'messages'. */
+    threadKey?: string;
+    toolCallId: string;
+    /** The name of the tool that produced this result */
+    toolName: string;
+    /** Content for the tool result — string, object, or array. The adapter converts to its SDK-native format. */
+    content: JsonValue;
+}
+/**
+ * Status of a workflow task
+ */
+type TaskStatus = "pending" | "in_progress" | "completed";
+/**
+ * A task managed within a workflow for tracking work items
+ */
+interface WorkflowTask {
+    /** Unique task identifier */
+    id: string;
+    /** Brief, actionable title in imperative form */
+    subject: string;
+    /** Detailed description of what needs to be done */
+    description: string;
+    /** Present continuous form shown in spinner when in_progress */
+    activeForm: string;
+    /** Current status of the task */
+    status: TaskStatus;
+    /** Arbitrary key-value pairs for tracking */
+    metadata: Record<string, string>;
+    /** IDs of tasks that must complete before this one can start */
+    blockedBy: string[];
+    /** IDs of tasks that are waiting for this one to complete */
+    blocks: string[];
+}
+/**
+ * Exit reasons for session termination
+ */
+type SessionExitReason = "completed" | "max_turns" | "waiting_for_input" | "failed" | "cancelled";
+/**
+ * Helper to check if status is terminal
+ */
+declare function isTerminalStatus(status: AgentStatus): boolean;
+
+export { type ActivityToolHandler as A, type BaseAgentState as B, type TaskStatus as C, type ToolArgs as D, type ToolCallResult as E, type ToolDefinition as F, type ToolHandler as G, type ToolHooks as H, type InferToolResults as I, type JsonValue as J, type ToolNames as K, type ToolResult as L, type ToolRouter as M, type ToolWithHandler as N, isTerminalStatus as O, type PreToolUseHookResult as P, type ToolRouterOptions as Q, type RouterContext as R, type SessionExitReason as S, type ToolHandlerResponse as T, type WorkflowTask as W, type ToolMap as a, type ToolRouterHooks as b, type PostToolUseFailureHookResult as c, type RawToolCall as d, type TokenUsage as e, type RunAgentConfig as f, type ToolResultConfig as g, type ToolCallResultUnion as h, type JsonSerializable as i, type AgentStateManager as j, type AgentConfig as k, type AgentFile as l, type AgentState as m, type AgentStatus as n, type AppendToolResultFn as o, type JsonPrimitive as p, type ParsedToolCall as q, type ParsedToolCallUnion as r, type PostToolUseFailureHook as s, type PostToolUseFailureHookContext as t, type PostToolUseHook as u, type PostToolUseHookContext as v, type PreToolUseHook as w, type PreToolUseHookContext as x, type ProcessToolCallsContext as y, type SerializableToolDefinition as z };