zeitlich 0.2.11 → 0.2.13

package/src/lib/session.ts

@@ -5,7 +5,6 @@ import {
   setHandler,
   ApplicationFailure,
 } from "@temporalio/workflow";
-import type { ZeitlichSharedActivities } from "../activities";
 import type {
   ThreadOps,
   AgentConfig,
@@ -20,7 +19,8 @@ import {
   type ParsedToolCallUnion,
   type ToolMap,
 } from "./tool-router";
-import type { MessageContent } from "@langchain/core/messages";
+import type { MessageContent } from "./types";
+import { getShortId } from "./thread-id";
 
 export interface ZeitlichSession<M = unknown> {
   runSession<T extends JsonSerializable<T>>(args: {
@@ -42,8 +42,39 @@ export interface SessionLifecycleHooks {
   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 });
+ * ```
+ */
 export const createSession = async <T extends ToolMap, M = unknown>({
-  threadId,
+  threadId: providedThreadId,
   agentName,
   maxTurns = 50,
   metadata = {},
@@ -56,8 +87,11 @@ export const createSession = async <T extends ToolMap, M = unknown>({
   processToolsInParallel = true,
   hooks = {},
   appendSystemPrompt = true,
+  continueThread = false,
   waitForInputTimeout = "48h",
 }: SessionConfig<T, M> & AgentConfig): Promise<ZeitlichSession<M>> => {
+  const threadId = providedThreadId ?? getShortId();
+
   const {
     appendToolResult,
     appendHumanMessage,
@@ -129,15 +163,18 @@ export const createSession = async <T extends ToolMap, M = unknown>({
 
       const systemPrompt = stateManager.getSystemPrompt();
 
-      await initializeThread(threadId);
-      if (appendSystemPrompt) {
-        if (!systemPrompt || systemPrompt.trim() === "") {
-          throw ApplicationFailure.create({
-            message: "No system prompt in state",
-            nonRetryable: true,
-          });
+      if (!continueThread) {
+        if (appendSystemPrompt) {
+          if (!systemPrompt || systemPrompt.trim() === "") {
+            throw ApplicationFailure.create({
+              message: "No system prompt in state",
+              nonRetryable: true,
+            });
+          }
+          await appendSystemMessage(threadId, systemPrompt);
+        } else {
+          await initializeThread(threadId);
         }
-        await appendSystemMessage(threadId, systemPrompt);
       }
       await appendHumanMessage(threadId, await buildContextMessage());
 
@@ -242,8 +279,9 @@ export const createSession = async <T extends ToolMap, M = unknown>({
 };
 
 /**
- * Proxy the default ZeitlichSharedActivities as ThreadOps<StoredMessage>.
- * Call this in workflow code for the standard LangChain/StoredMessage setup.
+ * 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
@@ -256,7 +294,7 @@ export const createSession = async <T extends ToolMap, M = unknown>({
 export function proxyDefaultThreadOps(
   options?: Parameters<typeof proxyActivities>[0]
 ): ThreadOps {
-  const activities = proxyActivities<ZeitlichSharedActivities>(
+  return proxyActivities<ThreadOps>(
     options ?? {
       startToCloseTimeout: "10s",
       retry: {
@@ -267,11 +305,4 @@ export function proxyDefaultThreadOps(
       },
     }
   );
-
-  return {
-    initializeThread: activities.initializeThread,
-    appendHumanMessage: activities.appendHumanMessage,
-    appendToolResult: activities.appendToolResult,
-    appendSystemMessage: activities.appendSystemMessage,
-  };
 }

package/src/lib/state-manager.ts

@@ -151,13 +151,31 @@ export interface AgentStateManager<TCustom extends JsonSerializable<TCustom>> {
 
 /**
  * Creates an agent state manager for tracking workflow state.
+ * Automatically registers Temporal query and update handlers for the agent.
  *
- * @param initialState - Optional initial values for base and custom state
- *   Base state defaults: status="RUNNING", version=0, turns=0, tasks=empty, fileTree=[]
+ * @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
  *
- * Note: Due to Temporal's workflow isolation, handlers must be set up
- * in the workflow file using defineQuery/defineUpdate and setHandler.
- * This manager provides the state and logic needed for those handlers.
+ * @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,
+ * });
+ * ```
  */
 export function createAgentStateManager<
   TCustom extends JsonSerializable<TCustom> = Record<string, never>,

package/src/lib/thread-id.ts

@@ -0,0 +1,25 @@
+import { uuid4 } from "@temporalio/workflow";
+
+const BASE62 =
+  "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+
+/**
+ * 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)
+ */
+export function getShortId(length = 12): string {
+  const hex = uuid4().replace(/-/g, "");
+  let result = "";
+  for (let i = 0; i < length; i++) {
+    const byte = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+    result += BASE62[byte % BASE62.length];
+  }
+  return result;
+}

package/src/lib/thread-manager.ts

@@ -1,17 +1,5 @@
 import type Redis from "ioredis";
 
-import {
-  type $InferMessageContent,
-  AIMessage,
-  HumanMessage,
-  type MessageContent,
-  type MessageStructure,
-  type StoredMessage,
-  SystemMessage,
-  ToolMessage,
-} from "@langchain/core/messages";
-import { v4 as uuidv4 } from "uuid";
-
 const THREAD_TTL_SECONDS = 60 * 60 * 24 * 90; // 90 days
 
 /**
@@ -39,13 +27,7 @@ function getThreadKey(threadId: string, key: string): string {
   return `thread:${threadId}:${key}`;
 }
 
-/**
- * Content for a tool message response.
- * Can be a simple string or complex content parts (text, images, cache points, etc.)
- */
-export type ToolMessageContent = $InferMessageContent<MessageStructure, "tool">;
-
-export interface ThreadManagerConfig<T = StoredMessage> {
+export interface ThreadManagerConfig<T> {
   redis: Redis;
   threadId: string;
   /** Thread key, defaults to 'messages' */
@@ -57,7 +39,6 @@ export interface ThreadManagerConfig<T = StoredMessage> {
   /**
    * Extract a unique id from a message for idempotent appends.
    * When provided, `append` uses an atomic Lua script to skip duplicate writes.
-   * Defaults to `StoredMessage.data.id` for the standard ThreadManager.
    */
   idOf?: (message: T) => string;
 }
@@ -78,51 +59,12 @@ export interface BaseThreadManager<T> {
   delete(): Promise<void>;
 }
 
-/** Thread manager with StoredMessage convenience helpers */
-export interface ThreadManager extends BaseThreadManager<StoredMessage> {
-  /** Create a HumanMessage (returns StoredMessage for storage) */
-  createHumanMessage(content: string | MessageContent): StoredMessage;
-  /** Create a SystemMessage (returns StoredMessage for storage) */
-  createSystemMessage(content: string): 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 SystemMessage */
-  appendSystemMessage(content: string): 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>;
-}
-
-/** Default id extractor for StoredMessage */
-function storedMessageId(msg: StoredMessage): string {
-  return msg.data.id ?? "";
-}
-
 /**
- * Creates a thread manager for handling conversation state in Redis.
- * Without generic args, returns a full ThreadManager with StoredMessage helpers.
- * With a custom type T, returns a BaseThreadManager<T>.
+ * Creates a generic thread manager for handling conversation state in Redis.
+ * Framework-agnostic — works with any serializable message type.
  */
-export function createThreadManager(config: ThreadManagerConfig): ThreadManager;
-export function createThreadManager<T>(
-  config: ThreadManagerConfig<T>
-): BaseThreadManager<T>;
 export function createThreadManager<T>(
-  config: ThreadManagerConfig<T>
+  config: ThreadManagerConfig<T>,
 ): BaseThreadManager<T> {
   const {
     redis,
@@ -130,28 +72,33 @@ export function createThreadManager<T>(
     key = "messages",
     serialize = (m: T): string => JSON.stringify(m),
     deserialize = (raw: string): T => JSON.parse(raw) as T,
+    idOf,
   } = config;
   const redisKey = getThreadKey(threadId, key);
+  const metaKey = getThreadKey(threadId, `${key}:meta`);
 
-  // Default idOf for StoredMessage when no custom serialization is used
-  const idOf =
-    config.idOf ??
-    (!config.serialize
-      ? (storedMessageId as unknown as (m: T) => string)
-      : undefined);
+  async function assertThreadExists(): Promise<void> {
+    const exists = await redis.exists(metaKey);
+    if (!exists) {
+      throw new Error(`Thread "${threadId}" (key: ${key}) does not exist`);
+    }
+  }
 
-  const base: BaseThreadManager<T> = {
+  return {
     async initialize(): Promise<void> {
       await redis.del(redisKey);
+      await redis.set(metaKey, "1", "EX", THREAD_TTL_SECONDS);
     },
 
     async load(): Promise<T[]> {
+      await assertThreadExists();
       const data = await redis.lrange(redisKey, 0, -1);
       return data.map(deserialize);
     },
 
     async append(messages: T[]): Promise<void> {
       if (messages.length === 0) return;
+      await assertThreadExists();
 
       if (idOf) {
         const dedupId = messages.map(idOf).join(":");
@@ -162,7 +109,7 @@ export function createThreadManager<T>(
           dedupKey,
           redisKey,
           String(THREAD_TTL_SECONDS),
-          ...messages.map(serialize)
+          ...messages.map(serialize),
         );
       } else {
         await redis.rpush(redisKey, ...messages.map(serialize));
@@ -171,78 +118,7 @@ export function createThreadManager<T>(
     },
 
     async delete(): Promise<void> {
-      await redis.del(redisKey);
-    },
-  };
-
-  // If no custom serialize/deserialize were provided and T defaults to StoredMessage,
-  // the overload guarantees the caller gets ThreadManager with convenience helpers.
-  const helpers = {
-    createHumanMessage(content: string | MessageContent): StoredMessage {
-      return new HumanMessage({
-        id: uuidv4(),
-        content: content as string,
-      }).toDict();
-    },
-
-    createSystemMessage(content: string): StoredMessage {
-      return new SystemMessage({
-        id: uuidv4(),
-        content: content as string,
-      }).toDict();
-    },
-
-    createAIMessage(
-      content: string,
-      kwargs?: { header?: string; options?: string[]; multiSelect?: boolean }
-    ): StoredMessage {
-      return new AIMessage({
-        id: uuidv4(),
-        content,
-        additional_kwargs: kwargs
-          ? {
-              header: kwargs.header,
-              options: kwargs.options,
-              multiSelect: kwargs.multiSelect,
-            }
-          : undefined,
-      }).toDict();
-    },
-
-    createToolMessage(
-      content: ToolMessageContent,
-      toolCallId: string
-    ): StoredMessage {
-      return new ToolMessage({
-        id: uuidv4(),
-        content: content as MessageContent,
-        tool_call_id: toolCallId,
-      }).toDict();
-    },
-
-    async appendHumanMessage(content: string | MessageContent): Promise<void> {
-      const message = helpers.createHumanMessage(content);
-      await (base as BaseThreadManager<StoredMessage>).append([message]);
-    },
-
-    async appendToolMessage(
-      content: ToolMessageContent,
-      toolCallId: string
-    ): Promise<void> {
-      const message = helpers.createToolMessage(content, toolCallId);
-      await (base as BaseThreadManager<StoredMessage>).append([message]);
-    },
-
-    async appendAIMessage(content: string | MessageContent): Promise<void> {
-      const message = helpers.createAIMessage(content as string);
-      await (base as BaseThreadManager<StoredMessage>).append([message]);
-    },
-
-    async appendSystemMessage(content: string): Promise<void> {
-      const message = helpers.createSystemMessage(content);
-      await (base as BaseThreadManager<StoredMessage>).append([message]);
+      await redis.del(redisKey, metaKey);
     },
   };
-
-  return Object.assign(base, helpers);
 }

package/src/lib/tool-router.ts

@@ -1,6 +1,5 @@
-import type { MessageToolDefinition } from "@langchain/core/messages";
-import type { ToolMessageContent } from "./thread-manager";
 import type {
+  ToolMessageContent,
   Hooks,
   PostToolUseFailureHookResult,
   PreToolUseHookResult,
@@ -23,8 +22,6 @@ import {
 import { createReadSkillHandler } from "../tools/read-skill/handler";
 import { ApplicationFailure } from "@temporalio/workflow";
 
-export type { ToolMessageContent };
-
 // ============================================================================
 // Tool Definition Types (merged from tool-registry.ts)
 // ============================================================================
@@ -90,16 +87,6 @@ export type ToolMap = Record<
   }
 >;
 
-/**
- * Converts a ToolMap to MessageStructure-compatible tools type.
- * Maps each tool's name to a MessageToolDefinition with inferred input type from the schema.
- */
-export type ToolMapToMessageTools<T extends ToolMap> = {
-  [K in keyof T as T[K]["name"]]: MessageToolDefinition<
-    z.infer<T[K]["schema"]>
-  >;
-};
-
 /**
  * Extract the tool names from a tool map (uses the tool's name property, not the key).
  */
@@ -163,6 +150,8 @@ export interface ToolHandlerResponse<TResult = null> {
   resultAppended?: boolean;
   /** Token usage from the tool execution (e.g. child agent invocations) */
   usage?: TokenUsage;
+  /** Thread ID used by the handler (surfaced to the LLM for subagent thread continuation) */
+  threadId?: string;
 }
 
 /**
@@ -953,8 +942,10 @@ export function defineSubagent<
   config: Omit<SubagentConfig<TResult>, "hooks" | "workflow" | "context"> & {
     workflow:
       | string
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      | ((input: { prompt: string; context: TContext }) => Promise<any>);
+      | ((input: {
+          prompt: string;
+          context: TContext;
+        }) => Promise<ToolHandlerResponse<z.infer<TResult> | null>>);
     context: TContext;
     hooks?: SubagentHooks<SubagentArgs, z.infer<TResult>>;
   }
@@ -962,8 +953,11 @@ export function defineSubagent<
 // Without context — verifies workflow accepts { prompt }
 export function defineSubagent<TResult extends z.ZodType = z.ZodType>(
   config: Omit<SubagentConfig<TResult>, "hooks" | "workflow"> & {
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    workflow: string | ((input: { prompt: string }) => Promise<any>);
+    workflow:
+      | string
+      | ((input: {
+          prompt: string;
+        }) => Promise<ToolHandlerResponse<z.infer<TResult> | null>>);
     hooks?: SubagentHooks<SubagentArgs, z.infer<TResult>>;
   }
 ): SubagentConfig<TResult>;

package/src/lib/types.ts

@@ -1,4 +1,3 @@
-import type { ToolMessageContent } from "./thread-manager";
 import type {
   InferToolResults,
   ParsedToolCallUnion,
@@ -9,10 +8,22 @@ import type {
 } from "./tool-router";
 import type { Skill } from "./skills/types";
 
-import type { MessageContent, StoredMessage } from "@langchain/core/messages";
 import type { Duration } from "@temporalio/common";
 import type { z } from "zod";
 
+// ============================================================================
+// Framework-agnostic message types
+// ============================================================================
+
+/** A single content part within a structured message (text, image, etc.) */
+export type ContentPart = { type: string; [key: string]: unknown };
+
+/** Message content — plain string or an array of structured content parts */
+export type MessageContent = string | ContentPart[];
+
+/** Content returned by a tool handler */
+export type ToolMessageContent = MessageContent;
+
 /**
  * Agent execution status
  */
@@ -36,7 +47,7 @@ export interface BaseAgentState {
   totalInputTokens: number;
   totalOutputTokens: number;
   cachedWriteTokens: number;
-  cachedReadtTokens: number;
+  cachedReadTokens: number;
 }
 
 /**
@@ -66,7 +77,7 @@ export interface TokenUsage {
 /**
  * Agent response from LLM invocation
  */
-export interface AgentResponse<M = StoredMessage> {
+export interface AgentResponse<M = unknown> {
   message: M;
   rawToolCalls: RawToolCall[];
   usage?: TokenUsage;
@@ -75,7 +86,6 @@ export interface AgentResponse<M = StoredMessage> {
 /**
  * Thread operations required by a session.
  * Consumers provide these — typically by wrapping Temporal activities.
- * Use `proxyDefaultThreadOps()` for the default StoredMessage implementation.
  */
 export interface ThreadOps {
   /** Initialize an empty thread */
@@ -104,9 +114,9 @@ export interface AgentConfig {
 /**
  * Configuration for a Zeitlich agent session
  */
-export interface SessionConfig<T extends ToolMap, M = StoredMessage> {
-  /** The thread ID to use for the session */
-  threadId: string;
+export interface SessionConfig<T extends ToolMap, M = unknown> {
+  /** The thread ID to use for the session (defaults to a short generated ID) */
+  threadId?: string;
   /** Metadata for the session */
   metadata?: Record<string, unknown>;
   /** Whether to append the system prompt as message to the thread */
@@ -132,6 +142,8 @@ export interface SessionConfig<T extends ToolMap, M = StoredMessage> {
    * Returns MessageContent array for the initial HumanMessage.
    */
   buildContextMessage: () => MessageContent | Promise<MessageContent>;
+  /** When true, skip thread initialization and system prompt — append only the new human message to the existing thread. */
+  continueThread?: boolean;
   /** How long to wait for input before cancelling the workflow */
   waitForInputTimeout?: Duration;
 }
@@ -162,7 +174,7 @@ export interface RunAgentConfig extends AgentConfig {
 /**
  * Type signature for workflow-specific runAgent activity
  */
-export type RunAgentActivity<M = StoredMessage> = (
+export type RunAgentActivity<M = unknown> = (
   config: RunAgentConfig
 ) => Promise<AgentResponse<M>>;
 
@@ -184,7 +196,7 @@ export interface ToolResultConfig {
 
 export type SubagentWorkflow<TResult extends z.ZodType = z.ZodType> = (
   input: SubagentInput
-) => Promise<ToolHandlerResponse<TResult | null>>;
+) => Promise<ToolHandlerResponse<z.infer<TResult> | null>>;
 
 /** Infer the z.infer'd result type from a SubagentConfig, or null if no schema */
 export type InferSubagentResult<T extends SubagentConfig> =
@@ -210,6 +222,8 @@ export interface SubagentConfig<TResult extends z.ZodType = z.ZodType> {
   resultSchema?: TResult;
   /** Optional static context passed to the subagent on every invocation */
   context?: Record<string, unknown>;
+  /** Allow the parent agent to pass a threadId for this subagent to continue (default: false) */
+  allowThreadContinuation?: boolean;
   /** Per-subagent lifecycle hooks */
   hooks?: SubagentHooks;
 }
@@ -250,6 +264,8 @@ export interface SubagentInput {
   prompt: string;
   /** Optional context parameters passed from the parent agent */
   context?: Record<string, unknown>;
+  /** When set, the subagent should continue this thread instead of starting a new one */
+  threadId?: string;
 }
 
 // ============================================================================

package/src/lib/workflow-helpers.ts

@@ -0,0 +1,50 @@
+import { Context } from "@temporalio/activity";
+import type { WorkflowClient } from "@temporalio/client";
+import type { ModelInvoker } from "./model-invoker";
+import type { AgentResponse, BaseAgentState, RunAgentConfig } from "./types";
+import { agentQueryName } from "./types";
+
+/**
+ * Query the parent workflow's state from within an activity.
+ * Resolves the workflow handle from the current activity context.
+ */
+export async function queryParentWorkflowState<T>(
+  client: WorkflowClient,
+  queryName: string
+): Promise<T> {
+  const { workflowExecution } = Context.current().info;
+  const handle = client.getHandle(
+    workflowExecution.workflowId,
+    workflowExecution.runId
+  );
+  return handle.query<T>(queryName);
+}
+
+/**
+ * Wraps a `ModelInvoker` into a `RunAgentActivity` by automatically
+ * loading tool definitions from the parent workflow state via query.
+ *
+ * This is the generic bridge between any provider-specific model invoker
+ * and the session's `runAgent` contract.
+ *
+ * @example
+ * ```typescript
+ * import { createRunAgentActivity } from 'zeitlich';
+ * import { createLangChainModelInvoker } from 'zeitlich/adapters/langchain';
+ *
+ * const invoker = createLangChainModelInvoker({ redis, model });
+ * return { runAgent: createRunAgentActivity(client, invoker) };
+ * ```
+ */
+export function createRunAgentActivity<M>(
+  client: WorkflowClient,
+  invoker: ModelInvoker<M>
+): (config: RunAgentConfig) => Promise<AgentResponse<M>> {
+  return async (config: RunAgentConfig) => {
+    const state = await queryParentWorkflowState<BaseAgentState>(
+      client,
+      agentQueryName(config.agentName)
+    );
+    return invoker({ ...config, state });
+  };
+}

package/src/tools/ask-user-question/handler.ts

@@ -2,7 +2,31 @@ import type { ActivityToolHandler } from "../../lib/tool-router";
 import type { AskUserQuestionArgs } from "./tool";
 
 /**
- * Creates handler for user interaction tool - creates AI messages for display.
+ * 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(); },
+ *     },
+ *   }),
+ * }
+ * ```
  */
 export const createAskUserQuestionHandler =
   (): ActivityToolHandler<