zeitlich 0.2.6 → 0.2.8

package/dist/{workflow-Dg5JMeOC.d.cts → workflow-BdAuMMjY.d.cts}

@@ -2,7 +2,7 @@ import { Workflow, proxyActivities } from '@temporalio/workflow';
 import Redis from 'ioredis';
 import { $InferMessageContent, MessageStructure, StoredMessage, MessageContent } from '@langchain/core/messages';
 import z, { z as z$1 } from 'zod';
-import * as _temporalio_common from '@temporalio/common';
+import { Duration } from '@temporalio/common';
 
 /**
  * Content for a tool message response.
@@ -116,7 +116,7 @@ interface ToolWithHandler<TName extends string = string, TSchema extends z$1.Zod
     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;
+    enabled?: () => boolean;
     /** Per-tool lifecycle hooks (run in addition to global hooks) */
     hooks?: ToolHooks<z$1.infer<TSchema>, TResult>;
 }
@@ -135,7 +135,7 @@ type ToolMap = Record<string, {
     handler: ToolHandler<any, any, any>;
     strict?: boolean;
     max_uses?: number;
-    enabled?: boolean;
+    enabled?: () => boolean;
     hooks?: ToolHooks<any, any>;
 }>;
 /**
@@ -187,6 +187,8 @@ interface ToolHandlerResponse<TResult = null> {
      * payloads through Temporal's activity payload limit.
      */
     resultAppended?: boolean;
+    /** Token usage from the tool execution (e.g. child agent invocations) */
+    usage?: TokenUsage;
 }
 /**
  * Context passed to tool handlers for additional data beyond tool args.
@@ -237,6 +239,7 @@ interface ToolCallResult<TName extends string = string, TResult = unknown> {
     toolCallId: string;
     name: TName;
     data: TResult;
+    usage?: TokenUsage;
 }
 /**
  * Options for creating a tool router.
@@ -465,6 +468,10 @@ interface BaseAgentState {
     turns: number;
     tasks: Map<string, WorkflowTask>;
     systemPrompt: string;
+    totalInputTokens: number;
+    totalOutputTokens: number;
+    cachedWriteTokens: number;
+    cachedReadtTokens: number;
 }
 /**
  * File representation for agent workflows
@@ -481,17 +488,20 @@ interface AgentFile {
     /** MIME type of the file */
     mimeType?: string;
 }
+interface TokenUsage {
+    inputTokens?: number;
+    outputTokens?: number;
+    cachedWriteTokens?: number;
+    cachedReadTokens?: number;
+    reasonTokens?: number;
+}
 /**
  * Agent response from LLM invocation
  */
 interface AgentResponse<M = StoredMessage> {
     message: M;
     rawToolCalls: RawToolCall[];
-    usage?: {
-        input_tokens?: number;
-        output_tokens?: number;
-        total_tokens?: number;
-    };
+    usage?: TokenUsage;
 }
 /**
  * Thread operations required by a session.
@@ -509,16 +519,27 @@ interface ThreadOps {
     appendSystemMessage(threadId: string, content: string): Promise<void>;
 }
 /**
- * Configuration for a Zeitlich agent session
+ * Configuration for a Zeitlich agent
  */
-interface ZeitlichAgentConfig<T extends ToolMap, M = StoredMessage> {
-    threadId: string;
+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;
+    /** The system prompt to append to the thread */
     systemPrompt?: string;
+}
+/**
+ * Configuration for a Zeitlich agent session
+ */
+interface SessionConfig<T extends ToolMap, M = StoredMessage> {
+    /** The thread ID to use for the session */
+    threadId: string;
+    /** Metadata for the session */
     metadata?: Record<string, unknown>;
+    /** Whether to append the system prompt as message to the thread */
     appendSystemPrompt?: boolean;
+    /** How many turns to run the session for */
     maxTurns?: number;
     /** Workflow-specific runAgent activity (with tools pre-bound) */
     runAgent: RunAgentActivity<M>;
@@ -537,6 +558,8 @@ interface ZeitlichAgentConfig<T extends ToolMap, M = StoredMessage> {
      * Returns MessageContent array for the initial HumanMessage.
      */
     buildContextMessage: () => MessageContent | Promise<MessageContent>;
+    /** How long to wait for input before cancelling the workflow */
+    waitForInputTimeout?: Duration;
 }
 /**
  * A JSON-serializable tool definition for state storage.
@@ -553,9 +576,10 @@ interface SerializableToolDefinition {
 /**
  * Configuration passed to runAgent activity
  */
-interface RunAgentConfig {
+interface RunAgentConfig extends AgentConfig {
+    /** The thread ID to use for the session */
     threadId: string;
-    agentName: string;
+    /** Metadata for the session */
     metadata?: Record<string, unknown>;
 }
 /**
@@ -584,7 +608,7 @@ interface SubagentConfig<TResult extends z$1.ZodType = z$1.ZodType> {
     /** Description shown to the parent agent explaining what this subagent does */
     description: string;
     /** Whether this subagent is available (default: true). Disabled subagents are excluded from the Subagent tool. */
-    enabled?: boolean;
+    enabled?: () => boolean;
     /** Temporal workflow function or type name (used with executeChild) */
     workflow: string | Workflow;
     /** Optional task queue - defaults to parent's queue if not specified */
@@ -745,6 +769,32 @@ interface SessionStartHookContext {
  * SessionStart hook - called when session begins
  */
 type SessionStartHook = (ctx: SessionStartHookContext) => void | Promise<void>;
+/**
+ * Context for PreHumanMessageAppend hook - called before each human message is appended to the thread
+ */
+interface PreHumanMessageAppendHookContext {
+    /** The message about to be appended */
+    message: MessageContent;
+    /** Thread identifier */
+    threadId: string;
+}
+/**
+ * PreHumanMessageAppend hook - called before each human message is appended to the thread
+ */
+type PreHumanMessageAppendHook = (ctx: PreHumanMessageAppendHookContext) => void | Promise<void>;
+/**
+ * PostHumanMessageAppend hook - called after each human message is appended to the thread
+ */
+type PostHumanMessageAppendHook = (ctx: PostHumanMessageAppendHookContext) => void | Promise<void>;
+/**
+ * Context for PostHumanMessageAppend hook - called after each human message is appended to the thread
+ */
+interface PostHumanMessageAppendHookContext {
+    /** The message that was appended */
+    message: MessageContent;
+    /** Thread identifier */
+    threadId: string;
+}
 /**
  * Context for SessionEnd hook - called when session ends
  */
@@ -795,6 +845,10 @@ interface ToolHooks<TArgs = unknown, TResult = unknown> {
  * Combined hooks interface for session lifecycle
  */
 interface Hooks<T extends ToolMap, TResult = unknown> {
+    /** Called before each human message is appended to the thread */
+    onPreHumanMessageAppend?: PreHumanMessageAppendHook;
+    /** Called after each human message is appended to the thread */
+    onPostHumanMessageAppend?: PostHumanMessageAppendHook;
     /** Called before each tool execution - can block or modify */
     onPreToolUse?: PreToolUseHook<T>;
     /** Called after each successful tool execution */
@@ -884,8 +938,24 @@ interface AgentStateManager<TCustom extends JsonSerializable<TCustom>> {
     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;
+    };
 }
-declare const getStateQuery: _temporalio_common.QueryDefinition<BaseAgentState, [], string>;
 /**
  * Creates an agent state manager for tracking workflow state.
  *
@@ -896,7 +966,10 @@ declare const getStateQuery: _temporalio_common.QueryDefinition<BaseAgentState,
  * 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>;
+declare function createAgentStateManager<TCustom extends JsonSerializable<TCustom> = Record<string, never>>({ initialState, agentConfig, }: {
+    initialState?: Partial<BaseAgentState> & TCustom;
+    agentConfig: AgentConfig;
+}): AgentStateManager<TCustom>;
 /**
  * Handler names used across agents
  */
@@ -909,7 +982,11 @@ declare const AGENT_HANDLER_NAMES: {
 interface ZeitlichSession<M = unknown> {
     runSession<T extends JsonSerializable<T>>(args: {
         stateManager: AgentStateManager<T>;
-    }): Promise<M | null>;
+    }): Promise<{
+        finalMessage: M | null;
+        exitReason: SessionExitReason;
+        usage: ReturnType<AgentStateManager<T>["getTotalUsage"]>;
+    }>;
 }
 /**
  * Session-level hooks for lifecycle events
@@ -920,7 +997,7 @@ interface SessionLifecycleHooks {
     /** Called when session ends */
     onSessionEnd?: SessionEndHook;
 }
-declare const createSession: <T extends ToolMap, M = unknown>({ threadId, agentName, maxTurns, metadata, runAgent, threadOps, buildContextMessage, subagents, tools, processToolsInParallel, hooks, appendSystemPrompt, systemPrompt, }: ZeitlichAgentConfig<T, M>) => Promise<ZeitlichSession<M>>;
+declare const createSession: <T extends ToolMap, M = unknown>({ threadId, agentName, description, maxTurns, metadata, runAgent, threadOps, buildContextMessage, subagents, tools, processToolsInParallel, hooks, appendSystemPrompt, systemPrompt, waitForInputTimeout, }: SessionConfig<T, M> & AgentConfig) => Promise<ZeitlichSession<M>>;
 /**
  * Proxy the default ZeitlichSharedActivities as ThreadOps<StoredMessage>.
  * Call this in workflow code for the standard LangChain/StoredMessage setup.
@@ -971,24 +1048,6 @@ interface ZeitlichSharedActivities {
  */
 declare function createSharedActivities(redis: Redis): ZeitlichSharedActivities;
 
-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>;
-
 declare const globTool: {
     name: "Glob";
     description: string;
@@ -1140,4 +1199,37 @@ declare const bashTool: {
 };
 type BashArgs = z.infer<typeof bashTool.schema>;
 
-export { type ToolArgs as $, type AgentResponse as A, type BashArgs as B, type RunAgentConfig as C, type SessionEndHookContext as D, type SessionExitReason as E, type FileEditArgs as F, type GlobArgs as G, type SessionLifecycleHooks as H, type InferToolResults as I, type JsonPrimitive as J, type SessionStartHook as K, type SessionStartHookContext as L, type SubagentArgs as M, type SubagentConfig as N, type SubagentHooks as O, type ParsedToolCall as P, type SubagentInput as Q, type RawToolCall as R, type SessionEndHook as S, type TaskCreateArgs as T, type TaskGetArgs as U, type TaskListArgs as V, type TaskStatus as W, type TaskUpdateArgs as X, type ThreadManager as Y, type ThreadManagerConfig as Z, type ThreadOps as _, type ActivityToolHandler as a, type ToolCallResult as a0, type ToolCallResultUnion as a1, type ToolDefinition as a2, type ToolHandler as a3, type ToolHandlerContext as a4, type ToolHandlerResponse as a5, type ToolHooks as a6, type ToolMap as a7, type ToolMessageContent as a8, type ToolNames as a9, grepTool as aA, hasNoOtherToolCalls as aB, isTerminalStatus as aC, proxyDefaultThreadOps as aD, readTool as aE, taskCreateTool as aF, taskGetTool as aG, taskListTool as aH, taskUpdateTool as aI, withAutoAppend as aJ, writeTool as aK, type ToolResult as aa, type ToolResultConfig as ab, type ToolRouter as ac, type ToolWithHandler as ad, type WorkflowTask as ae, type ZeitlichAgentConfig as af, type ZeitlichSession as ag, type ZeitlichSharedActivities as ah, askUserQuestionTool as ai, bashTool as aj, createAgentStateManager as ak, createBashToolDescription as al, createSession as am, createSharedActivities as an, createSubagentTool as ao, createTaskCreateHandler as ap, createTaskGetHandler as aq, createTaskListHandler as ar, createTaskUpdateHandler as as, createThreadManager as at, createToolRouter as au, defineSubagent as av, defineTool as aw, editTool as ax, getStateQuery as ay, globTool as az, type AskUserQuestionArgs as b, AGENT_HANDLER_NAMES as c, type AgentFile as d, type AgentState as e, type AgentStateManager as f, type AgentStatus as g, type AppendToolResultFn as h, type BaseAgentState as i, type BaseThreadManager as j, type FileReadArgs as k, type FileWriteArgs as l, type GrepArgs as m, type JsonSerializable as n, type JsonValue as o, type ParsedToolCallUnion as p, type PostToolUseFailureHook as q, type PostToolUseFailureHookContext as r, type PostToolUseFailureHookResult as s, type PostToolUseHook as t, type PostToolUseHookContext as u, type PreToolUseHook as v, type PreToolUseHookContext as w, type PreToolUseHookResult as x, type ProcessToolCallsContext as y, type RunAgentActivity as z };
+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 handler for user interaction tool - creates AI messages for display.
+ */
+declare const createAskUserQuestionHandler: () => ToolHandler<AskUserQuestionArgs, {
+    questions: {
+        question: string;
+        header: string;
+        options: {
+            label: string;
+            description: string;
+        }[];
+        multiSelect: boolean;
+    }[];
+}>;
+
+export { type ThreadOps as $, type AgentResponse as A, type BashArgs as B, type RunAgentActivity as C, type RunAgentConfig as D, type SessionEndHookContext as E, type FileEditArgs as F, type GlobArgs as G, type SessionExitReason as H, type InferToolResults as I, type JsonPrimitive as J, type SessionLifecycleHooks as K, type SessionStartHook as L, type SessionStartHookContext as M, type SubagentArgs as N, type SubagentConfig as O, type ParsedToolCall as P, type SubagentHooks as Q, type RawToolCall as R, type SessionEndHook as S, type SubagentInput as T, type TaskCreateArgs as U, type TaskGetArgs 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, grepTool as aA, hasNoOtherToolCalls as aB, isTerminalStatus as aC, proxyDefaultThreadOps as aD, readTool as aE, taskCreateTool as aF, taskGetTool as aG, taskListTool as aH, taskUpdateTool as aI, withAutoAppend as aJ, writeTool as aK, type ToolNames as aa, type ToolResult as ab, type ToolResultConfig as ac, type ToolRouter as ad, type ToolWithHandler as ae, type WorkflowTask as af, type ZeitlichSession as ag, type ZeitlichSharedActivities as ah, askUserQuestionTool as ai, bashTool as aj, createAgentStateManager as ak, createAskUserQuestionHandler as al, createBashToolDescription as am, createSession as an, createSharedActivities as ao, createSubagentTool as ap, createTaskCreateHandler as aq, createTaskGetHandler as ar, createTaskListHandler as as, createTaskUpdateHandler as at, createThreadManager as au, createToolRouter as av, defineSubagent as aw, defineTool as ax, editTool as ay, globTool as az, AGENT_HANDLER_NAMES as b, type AgentConfig as c, type AgentFile as d, type AgentState as e, type AgentStateManager as f, type AgentStatus as g, type AppendToolResultFn as h, type AskUserQuestionArgs as i, type BaseAgentState as j, type BaseThreadManager as k, type FileReadArgs as l, type FileWriteArgs as m, type GrepArgs as n, type JsonSerializable as o, type JsonValue as p, type ParsedToolCallUnion as q, type PostToolUseFailureHook as r, type PostToolUseFailureHookContext as s, type PostToolUseFailureHookResult as t, type PostToolUseHook as u, type PostToolUseHookContext as v, type PreToolUseHook as w, type PreToolUseHookContext as x, type PreToolUseHookResult as y, type ProcessToolCallsContext as z };

package/dist/{workflow-Dg5JMeOC.d.ts → workflow-BdAuMMjY.d.ts}

@@ -2,7 +2,7 @@ import { Workflow, proxyActivities } from '@temporalio/workflow';
 import Redis from 'ioredis';
 import { $InferMessageContent, MessageStructure, StoredMessage, MessageContent } from '@langchain/core/messages';
 import z, { z as z$1 } from 'zod';
-import * as _temporalio_common from '@temporalio/common';
+import { Duration } from '@temporalio/common';
 
 /**
  * Content for a tool message response.
@@ -116,7 +116,7 @@ interface ToolWithHandler<TName extends string = string, TSchema extends z$1.Zod
     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;
+    enabled?: () => boolean;
     /** Per-tool lifecycle hooks (run in addition to global hooks) */
     hooks?: ToolHooks<z$1.infer<TSchema>, TResult>;
 }
@@ -135,7 +135,7 @@ type ToolMap = Record<string, {
     handler: ToolHandler<any, any, any>;
     strict?: boolean;
     max_uses?: number;
-    enabled?: boolean;
+    enabled?: () => boolean;
     hooks?: ToolHooks<any, any>;
 }>;
 /**
@@ -187,6 +187,8 @@ interface ToolHandlerResponse<TResult = null> {
      * payloads through Temporal's activity payload limit.
      */
     resultAppended?: boolean;
+    /** Token usage from the tool execution (e.g. child agent invocations) */
+    usage?: TokenUsage;
 }
 /**
  * Context passed to tool handlers for additional data beyond tool args.
@@ -237,6 +239,7 @@ interface ToolCallResult<TName extends string = string, TResult = unknown> {
     toolCallId: string;
     name: TName;
     data: TResult;
+    usage?: TokenUsage;
 }
 /**
  * Options for creating a tool router.
@@ -465,6 +468,10 @@ interface BaseAgentState {
     turns: number;
     tasks: Map<string, WorkflowTask>;
     systemPrompt: string;
+    totalInputTokens: number;
+    totalOutputTokens: number;
+    cachedWriteTokens: number;
+    cachedReadtTokens: number;
 }
 /**
  * File representation for agent workflows
@@ -481,17 +488,20 @@ interface AgentFile {
     /** MIME type of the file */
     mimeType?: string;
 }
+interface TokenUsage {
+    inputTokens?: number;
+    outputTokens?: number;
+    cachedWriteTokens?: number;
+    cachedReadTokens?: number;
+    reasonTokens?: number;
+}
 /**
  * Agent response from LLM invocation
  */
 interface AgentResponse<M = StoredMessage> {
     message: M;
     rawToolCalls: RawToolCall[];
-    usage?: {
-        input_tokens?: number;
-        output_tokens?: number;
-        total_tokens?: number;
-    };
+    usage?: TokenUsage;
 }
 /**
  * Thread operations required by a session.
@@ -509,16 +519,27 @@ interface ThreadOps {
     appendSystemMessage(threadId: string, content: string): Promise<void>;
 }
 /**
- * Configuration for a Zeitlich agent session
+ * Configuration for a Zeitlich agent
  */
-interface ZeitlichAgentConfig<T extends ToolMap, M = StoredMessage> {
-    threadId: string;
+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;
+    /** The system prompt to append to the thread */
     systemPrompt?: string;
+}
+/**
+ * Configuration for a Zeitlich agent session
+ */
+interface SessionConfig<T extends ToolMap, M = StoredMessage> {
+    /** The thread ID to use for the session */
+    threadId: string;
+    /** Metadata for the session */
     metadata?: Record<string, unknown>;
+    /** Whether to append the system prompt as message to the thread */
     appendSystemPrompt?: boolean;
+    /** How many turns to run the session for */
     maxTurns?: number;
     /** Workflow-specific runAgent activity (with tools pre-bound) */
     runAgent: RunAgentActivity<M>;
@@ -537,6 +558,8 @@ interface ZeitlichAgentConfig<T extends ToolMap, M = StoredMessage> {
      * Returns MessageContent array for the initial HumanMessage.
      */
     buildContextMessage: () => MessageContent | Promise<MessageContent>;
+    /** How long to wait for input before cancelling the workflow */
+    waitForInputTimeout?: Duration;
 }
 /**
  * A JSON-serializable tool definition for state storage.
@@ -553,9 +576,10 @@ interface SerializableToolDefinition {
 /**
  * Configuration passed to runAgent activity
  */
-interface RunAgentConfig {
+interface RunAgentConfig extends AgentConfig {
+    /** The thread ID to use for the session */
     threadId: string;
-    agentName: string;
+    /** Metadata for the session */
     metadata?: Record<string, unknown>;
 }
 /**
@@ -584,7 +608,7 @@ interface SubagentConfig<TResult extends z$1.ZodType = z$1.ZodType> {
     /** Description shown to the parent agent explaining what this subagent does */
     description: string;
     /** Whether this subagent is available (default: true). Disabled subagents are excluded from the Subagent tool. */
-    enabled?: boolean;
+    enabled?: () => boolean;
     /** Temporal workflow function or type name (used with executeChild) */
     workflow: string | Workflow;
     /** Optional task queue - defaults to parent's queue if not specified */
@@ -745,6 +769,32 @@ interface SessionStartHookContext {
  * SessionStart hook - called when session begins
  */
 type SessionStartHook = (ctx: SessionStartHookContext) => void | Promise<void>;
+/**
+ * Context for PreHumanMessageAppend hook - called before each human message is appended to the thread
+ */
+interface PreHumanMessageAppendHookContext {
+    /** The message about to be appended */
+    message: MessageContent;
+    /** Thread identifier */
+    threadId: string;
+}
+/**
+ * PreHumanMessageAppend hook - called before each human message is appended to the thread
+ */
+type PreHumanMessageAppendHook = (ctx: PreHumanMessageAppendHookContext) => void | Promise<void>;
+/**
+ * PostHumanMessageAppend hook - called after each human message is appended to the thread
+ */
+type PostHumanMessageAppendHook = (ctx: PostHumanMessageAppendHookContext) => void | Promise<void>;
+/**
+ * Context for PostHumanMessageAppend hook - called after each human message is appended to the thread
+ */
+interface PostHumanMessageAppendHookContext {
+    /** The message that was appended */
+    message: MessageContent;
+    /** Thread identifier */
+    threadId: string;
+}
 /**
  * Context for SessionEnd hook - called when session ends
  */
@@ -795,6 +845,10 @@ interface ToolHooks<TArgs = unknown, TResult = unknown> {
  * Combined hooks interface for session lifecycle
  */
 interface Hooks<T extends ToolMap, TResult = unknown> {
+    /** Called before each human message is appended to the thread */
+    onPreHumanMessageAppend?: PreHumanMessageAppendHook;
+    /** Called after each human message is appended to the thread */
+    onPostHumanMessageAppend?: PostHumanMessageAppendHook;
     /** Called before each tool execution - can block or modify */
     onPreToolUse?: PreToolUseHook<T>;
     /** Called after each successful tool execution */
@@ -884,8 +938,24 @@ interface AgentStateManager<TCustom extends JsonSerializable<TCustom>> {
     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;
+    };
 }
-declare const getStateQuery: _temporalio_common.QueryDefinition<BaseAgentState, [], string>;
 /**
  * Creates an agent state manager for tracking workflow state.
  *
@@ -896,7 +966,10 @@ declare const getStateQuery: _temporalio_common.QueryDefinition<BaseAgentState,
  * 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>;
+declare function createAgentStateManager<TCustom extends JsonSerializable<TCustom> = Record<string, never>>({ initialState, agentConfig, }: {
+    initialState?: Partial<BaseAgentState> & TCustom;
+    agentConfig: AgentConfig;
+}): AgentStateManager<TCustom>;
 /**
  * Handler names used across agents
  */
@@ -909,7 +982,11 @@ declare const AGENT_HANDLER_NAMES: {
 interface ZeitlichSession<M = unknown> {
     runSession<T extends JsonSerializable<T>>(args: {
         stateManager: AgentStateManager<T>;
-    }): Promise<M | null>;
+    }): Promise<{
+        finalMessage: M | null;
+        exitReason: SessionExitReason;
+        usage: ReturnType<AgentStateManager<T>["getTotalUsage"]>;
+    }>;
 }
 /**
  * Session-level hooks for lifecycle events
@@ -920,7 +997,7 @@ interface SessionLifecycleHooks {
     /** Called when session ends */
     onSessionEnd?: SessionEndHook;
 }
-declare const createSession: <T extends ToolMap, M = unknown>({ threadId, agentName, maxTurns, metadata, runAgent, threadOps, buildContextMessage, subagents, tools, processToolsInParallel, hooks, appendSystemPrompt, systemPrompt, }: ZeitlichAgentConfig<T, M>) => Promise<ZeitlichSession<M>>;
+declare const createSession: <T extends ToolMap, M = unknown>({ threadId, agentName, description, maxTurns, metadata, runAgent, threadOps, buildContextMessage, subagents, tools, processToolsInParallel, hooks, appendSystemPrompt, systemPrompt, waitForInputTimeout, }: SessionConfig<T, M> & AgentConfig) => Promise<ZeitlichSession<M>>;
 /**
  * Proxy the default ZeitlichSharedActivities as ThreadOps<StoredMessage>.
  * Call this in workflow code for the standard LangChain/StoredMessage setup.
@@ -971,24 +1048,6 @@ interface ZeitlichSharedActivities {
  */
 declare function createSharedActivities(redis: Redis): ZeitlichSharedActivities;
 
-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>;
-
 declare const globTool: {
     name: "Glob";
     description: string;
@@ -1140,4 +1199,37 @@ declare const bashTool: {
 };
 type BashArgs = z.infer<typeof bashTool.schema>;
 
-export { type ToolArgs as $, type AgentResponse as A, type BashArgs as B, type RunAgentConfig as C, type SessionEndHookContext as D, type SessionExitReason as E, type FileEditArgs as F, type GlobArgs as G, type SessionLifecycleHooks as H, type InferToolResults as I, type JsonPrimitive as J, type SessionStartHook as K, type SessionStartHookContext as L, type SubagentArgs as M, type SubagentConfig as N, type SubagentHooks as O, type ParsedToolCall as P, type SubagentInput as Q, type RawToolCall as R, type SessionEndHook as S, type TaskCreateArgs as T, type TaskGetArgs as U, type TaskListArgs as V, type TaskStatus as W, type TaskUpdateArgs as X, type ThreadManager as Y, type ThreadManagerConfig as Z, type ThreadOps as _, type ActivityToolHandler as a, type ToolCallResult as a0, type ToolCallResultUnion as a1, type ToolDefinition as a2, type ToolHandler as a3, type ToolHandlerContext as a4, type ToolHandlerResponse as a5, type ToolHooks as a6, type ToolMap as a7, type ToolMessageContent as a8, type ToolNames as a9, grepTool as aA, hasNoOtherToolCalls as aB, isTerminalStatus as aC, proxyDefaultThreadOps as aD, readTool as aE, taskCreateTool as aF, taskGetTool as aG, taskListTool as aH, taskUpdateTool as aI, withAutoAppend as aJ, writeTool as aK, type ToolResult as aa, type ToolResultConfig as ab, type ToolRouter as ac, type ToolWithHandler as ad, type WorkflowTask as ae, type ZeitlichAgentConfig as af, type ZeitlichSession as ag, type ZeitlichSharedActivities as ah, askUserQuestionTool as ai, bashTool as aj, createAgentStateManager as ak, createBashToolDescription as al, createSession as am, createSharedActivities as an, createSubagentTool as ao, createTaskCreateHandler as ap, createTaskGetHandler as aq, createTaskListHandler as ar, createTaskUpdateHandler as as, createThreadManager as at, createToolRouter as au, defineSubagent as av, defineTool as aw, editTool as ax, getStateQuery as ay, globTool as az, type AskUserQuestionArgs as b, AGENT_HANDLER_NAMES as c, type AgentFile as d, type AgentState as e, type AgentStateManager as f, type AgentStatus as g, type AppendToolResultFn as h, type BaseAgentState as i, type BaseThreadManager as j, type FileReadArgs as k, type FileWriteArgs as l, type GrepArgs as m, type JsonSerializable as n, type JsonValue as o, type ParsedToolCallUnion as p, type PostToolUseFailureHook as q, type PostToolUseFailureHookContext as r, type PostToolUseFailureHookResult as s, type PostToolUseHook as t, type PostToolUseHookContext as u, type PreToolUseHook as v, type PreToolUseHookContext as w, type PreToolUseHookResult as x, type ProcessToolCallsContext as y, type RunAgentActivity as z };
+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 handler for user interaction tool - creates AI messages for display.
+ */
+declare const createAskUserQuestionHandler: () => ToolHandler<AskUserQuestionArgs, {
+    questions: {
+        question: string;
+        header: string;
+        options: {
+            label: string;
+            description: string;
+        }[];
+        multiSelect: boolean;
+    }[];
+}>;
+
+export { type ThreadOps as $, type AgentResponse as A, type BashArgs as B, type RunAgentActivity as C, type RunAgentConfig as D, type SessionEndHookContext as E, type FileEditArgs as F, type GlobArgs as G, type SessionExitReason as H, type InferToolResults as I, type JsonPrimitive as J, type SessionLifecycleHooks as K, type SessionStartHook as L, type SessionStartHookContext as M, type SubagentArgs as N, type SubagentConfig as O, type ParsedToolCall as P, type SubagentHooks as Q, type RawToolCall as R, type SessionEndHook as S, type SubagentInput as T, type TaskCreateArgs as U, type TaskGetArgs 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, grepTool as aA, hasNoOtherToolCalls as aB, isTerminalStatus as aC, proxyDefaultThreadOps as aD, readTool as aE, taskCreateTool as aF, taskGetTool as aG, taskListTool as aH, taskUpdateTool as aI, withAutoAppend as aJ, writeTool as aK, type ToolNames as aa, type ToolResult as ab, type ToolResultConfig as ac, type ToolRouter as ad, type ToolWithHandler as ae, type WorkflowTask as af, type ZeitlichSession as ag, type ZeitlichSharedActivities as ah, askUserQuestionTool as ai, bashTool as aj, createAgentStateManager as ak, createAskUserQuestionHandler as al, createBashToolDescription as am, createSession as an, createSharedActivities as ao, createSubagentTool as ap, createTaskCreateHandler as aq, createTaskGetHandler as ar, createTaskListHandler as as, createTaskUpdateHandler as at, createThreadManager as au, createToolRouter as av, defineSubagent as aw, defineTool as ax, editTool as ay, globTool as az, AGENT_HANDLER_NAMES as b, type AgentConfig as c, type AgentFile as d, type AgentState as e, type AgentStateManager as f, type AgentStatus as g, type AppendToolResultFn as h, type AskUserQuestionArgs as i, type BaseAgentState as j, type BaseThreadManager as k, type FileReadArgs as l, type FileWriteArgs as m, type GrepArgs as n, type JsonSerializable as o, type JsonValue as p, type ParsedToolCallUnion as q, type PostToolUseFailureHook as r, type PostToolUseFailureHookContext as s, type PostToolUseFailureHookResult as t, type PostToolUseHook as u, type PostToolUseHookContext as v, type PreToolUseHook as w, type PreToolUseHookContext as x, type PreToolUseHookResult as y, type ProcessToolCallsContext as z };