zeitlich 0.2.18 → 0.2.20

package/src/lib/tool-router/router.ts

@@ -63,9 +63,11 @@ export function createToolRouter<T extends ToolMap>(
     toolMap.set(tool.name, tool as T[keyof T]);
   }
 
-  /** Check if a tool is enabled (defaults to true when not specified) */
+  const resolve = <T>(v: T | (() => T)): T =>
+    typeof v === "function" ? (v as () => T)() : v;
+
   const isEnabled = (tool: ToolMap[string]): boolean =>
-    typeof tool.enabled === "function" ? tool.enabled() : (tool.enabled ?? true);
+    resolve(tool.enabled) ?? true;
 
   if (options.plugins) {
     for (const plugin of options.plugins) {
@@ -128,7 +130,10 @@ export function createToolRouter<T extends ToolMap>(
         turn,
       });
       if (r?.fallbackContent !== undefined)
-        return { content: r.fallbackContent, result: { error: errorStr, recovered: true } };
+        return {
+          content: r.fallbackContent,
+          result: { error: errorStr, recovered: true },
+        };
       if (r?.suppress)
         return {
           content: JSON.stringify({ error: errorStr, suppressed: true }),
@@ -144,7 +149,10 @@ export function createToolRouter<T extends ToolMap>(
         turn,
       });
       if (r?.fallbackContent !== undefined)
-        return { content: r.fallbackContent, result: { error: errorStr, recovered: true } };
+        return {
+          content: r.fallbackContent,
+          result: { error: errorStr, recovered: true },
+        };
       if (r?.suppress)
         return {
           content: JSON.stringify({ error: errorStr, suppressed: true }),
@@ -199,7 +207,10 @@ export function createToolRouter<T extends ToolMap>(
         threadId: options.threadId,
         toolCallId: toolCall.id,
         toolName: toolCall.name,
-        content: JSON.stringify({ skipped: true, reason: "Skipped by PreToolUse hook" }),
+        content: JSON.stringify({
+          skipped: true,
+          reason: "Skipped by PreToolUse hook",
+        }),
       });
       return null;
     }
@@ -230,19 +241,31 @@ export function createToolRouter<T extends ToolMap>(
         content = JSON.stringify(result, null, 2);
       }
     } catch (error) {
-      const recovery = await runFailureHooks(toolCall, tool, error, effectiveArgs, turn);
+      const recovery = await runFailureHooks(
+        toolCall,
+        tool,
+        error,
+        effectiveArgs,
+        turn
+      );
       result = recovery.result;
       content = recovery.content;
     }
 
     // --- Append result to thread (unless handler already did) ---
     if (!resultAppended) {
-      await appendToolResult({
+      const config = {
         threadId: options.threadId,
         toolCallId: toolCall.id,
         toolName: toolCall.name,
         content,
-      });
+      };
+      await appendToolResult.executeWithOptions(
+        {
+          summary: `Append ${toolCall.name} result`,
+        },
+        [config]
+      );
     }
 
     const toolResult = {
@@ -252,7 +275,14 @@ export function createToolRouter<T extends ToolMap>(
     } as ToolCallResultUnion<TResults>;
 
     // --- Post-hooks ---
-    await runPostHooks(toolCall, tool, toolResult, effectiveArgs, turn, Date.now() - startTime);
+    await runPostHooks(
+      toolCall,
+      tool,
+      toolResult,
+      effectiveArgs,
+      turn,
+      Date.now() - startTime
+    );
 
     return toolResult;
   }
@@ -269,7 +299,7 @@ export function createToolRouter<T extends ToolMap>(
         throw new Error(`Tool ${toolCall.name} not found`);
       }
 
-      const parsedArgs = tool.schema.parse(toolCall.args);
+      const parsedArgs = resolve(tool.schema).parse(toolCall.args);
 
       return {
         id: toolCall.id ?? "",
@@ -294,8 +324,8 @@ export function createToolRouter<T extends ToolMap>(
         .filter(([, tool]) => isEnabled(tool))
         .map(([name, tool]) => ({
           name,
-          description: tool.description,
-          schema: tool.schema,
+          description: resolve(tool.description),
+          schema: resolve(tool.schema),
           strict: tool.strict,
           max_uses: tool.max_uses,
         }));
@@ -314,9 +344,7 @@ export function createToolRouter<T extends ToolMap>(
 
       if (options.parallel) {
         const results = await Promise.all(
-          toolCalls.map((tc) =>
-            processToolCall(tc, turn, sandboxId)
-          )
+          toolCalls.map((tc) => processToolCall(tc, turn, sandboxId))
         );
         return results.filter(
           (r): r is NonNullable<typeof r> => r !== null
@@ -325,11 +353,7 @@ export function createToolRouter<T extends ToolMap>(
 
       const results: ToolCallResultUnion<TResults>[] = [];
       for (const toolCall of toolCalls) {
-        const result = await processToolCall(
-          toolCall,
-          turn,
-          sandboxId
-        );
+        const result = await processToolCall(toolCall, turn, sandboxId);
         if (result !== null) {
           results.push(result);
         }
@@ -337,10 +361,7 @@ export function createToolRouter<T extends ToolMap>(
       return results;
     },
 
-    async processToolCallsByName<
-      TName extends ToolNames<T>,
-      TResult,
-    >(
+    async processToolCallsByName<TName extends ToolNames<T>, TResult>(
       toolCalls: ParsedToolCallUnion<T>[],
       toolName: TName,
       handler: ToolHandler<ToolArgs<T, TName>, TResult>,
@@ -359,7 +380,9 @@ export function createToolRouter<T extends ToolMap>(
           threadId: options.threadId,
           toolCallId: toolCall.id,
           toolName: toolCall.name as TName,
-          ...(context?.sandboxId !== undefined && { sandboxId: context.sandboxId }),
+          ...(context?.sandboxId !== undefined && {
+            sandboxId: context.sandboxId,
+          }),
         };
         const response = await handler(
           toolCall.args as ToolArgs<T, TName>,
@@ -367,12 +390,19 @@ export function createToolRouter<T extends ToolMap>(
         );
 
         if (!response.resultAppended) {
-          await appendToolResult({
-            threadId: options.threadId,
-            toolCallId: toolCall.id,
-            toolName: toolCall.name,
-            content: response.toolResponse,
-          });
+          await appendToolResult.executeWithOptions(
+            {
+              summary: `Append ${toolCall.name} result`,
+            },
+            [
+              {
+                threadId: options.threadId,
+                toolCallId: toolCall.id,
+                toolName: toolCall.name,
+                content: response.toolResponse,
+              },
+            ]
+          );
         }
 
         return {

package/src/lib/tool-router/types.ts

@@ -4,6 +4,7 @@ import type {
   ToolResultConfig,
 } from "../types";
 import type { z } from "zod";
+import type { ActivityFunctionWithOptions } from "@temporalio/workflow";
 
 // ============================================================================
 // Tool Definition Types
@@ -58,8 +59,8 @@ export type ToolMap = Record<
   string,
   {
     name: string;
-    description: string;
-    schema: z.ZodType;
+    description: string | (() => string);
+    schema: z.ZodType | (() => z.ZodType);
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     handler: ToolHandler<any, any, any>;
     strict?: boolean;
@@ -114,7 +115,9 @@ export type ParsedToolCallUnion<T extends ToolMap> = {
 /**
  * Function signature for appending tool results to a thread.
  */
-export type AppendToolResultFn = (config: ToolResultConfig) => Promise<void>;
+export type AppendToolResultFn = ActivityFunctionWithOptions<
+  (config: ToolResultConfig) => Promise<void>
+>;
 
 /**
  * The response from a tool handler.
@@ -157,7 +160,11 @@ export interface RouterContext {
  * Receives the parsed args and a context that always includes {@link RouterContext}
  * fields, plus any additional properties when TContext extends RouterContext.
  */
-export type ToolHandler<TArgs, TResult, TContext extends RouterContext = RouterContext> = (
+export type ToolHandler<
+  TArgs,
+  TResult,
+  TContext extends RouterContext = RouterContext,
+> = (
   args: TArgs,
   context: TContext
 ) => ToolHandlerResponse<TResult> | Promise<ToolHandlerResponse<TResult>>;
@@ -392,7 +399,8 @@ export interface ToolRouterOptions<T extends ToolMap> {
   tools: T;
   /** Thread ID for appending tool results */
   threadId: string;
-  /** Function to append tool results to the thread (called automatically after each handler) */
+  /** Function to append tool results to the thread (called automatically after each handler).
+   *  Accepts a Temporal activity proxy with {@link ActivityFunctionWithOptions}. */
   appendToolResult: AppendToolResultFn;
   /** Whether to process tools in parallel (default: true) */
   parallel?: boolean;
@@ -445,10 +453,7 @@ export interface ToolRouter<T extends ToolMap> {
    * Process tool calls matching a specific name with a custom handler.
    * Useful for overriding the default handler for specific cases.
    */
-  processToolCallsByName<
-    TName extends ToolNames<T>,
-    TResult,
-  >(
+  processToolCallsByName<TName extends ToolNames<T>, TResult>(
     toolCalls: ParsedToolCallUnion<T>[],
     toolName: TName,
     handler: ToolHandler<ToolArgs<T, TName>, TResult>,

package/src/lib/workflow.test.ts

@@ -5,11 +5,13 @@ import {
   type WorkflowSessionInput,
 } from "./workflow";
 
+const cfg = { name: "test-workflow" };
+
 describe("defineWorkflow", () => {
   it("maps previousThreadId to threadId + continueThread", async () => {
     let capturedSession: WorkflowSessionInput | undefined;
 
-    const workflow = defineWorkflow(async (_input, sessionInput) => {
+    const workflow = defineWorkflow(cfg, async (_input, sessionInput) => {
       capturedSession = sessionInput;
       return { ok: true };
     });
@@ -25,7 +27,7 @@ describe("defineWorkflow", () => {
   it("maps sandboxId", async () => {
     let capturedSession: WorkflowSessionInput | undefined;
 
-    const workflow = defineWorkflow(async (_input, sessionInput) => {
+    const workflow = defineWorkflow(cfg, async (_input, sessionInput) => {
       capturedSession = sessionInput;
       return { ok: true };
     });
@@ -38,7 +40,7 @@ describe("defineWorkflow", () => {
   it("maps both previousThreadId and sandboxId together", async () => {
     let capturedSession: WorkflowSessionInput | undefined;
 
-    const workflow = defineWorkflow(async (_input, sessionInput) => {
+    const workflow = defineWorkflow(cfg, async (_input, sessionInput) => {
       capturedSession = sessionInput;
       return { ok: true };
     });
@@ -55,7 +57,7 @@ describe("defineWorkflow", () => {
   it("returns empty sessionInput when no previousThreadId or sandboxId", async () => {
     let capturedSession: WorkflowSessionInput | undefined;
 
-    const workflow = defineWorkflow(async (_input, sessionInput) => {
+    const workflow = defineWorkflow(cfg, async (_input, sessionInput) => {
       capturedSession = sessionInput;
       return { ok: true };
     });
@@ -73,7 +75,7 @@ describe("defineWorkflow", () => {
       metadata: { key: string };
       previousThreadId?: string;
       sandboxId?: string;
-    }, { ok: boolean }>(async (input, _sessionInput) => {
+    }, { ok: boolean }>(cfg, async (input, _sessionInput) => {
       capturedInput = input;
       return { ok: true };
     });
@@ -94,6 +96,7 @@ describe("defineWorkflow", () => {
     let capturedSession: WorkflowSessionInput | undefined;
 
     const workflow = defineWorkflow<{ prompt: string }, { ok: boolean }>(
+      cfg,
       async (input, sessionInput) => {
         capturedInput = input;
         capturedSession = sessionInput;
@@ -116,7 +119,7 @@ describe("defineWorkflow", () => {
   });
 
   it("returns the handler response unchanged", async () => {
-    const workflow = defineWorkflow(async () => ({
+    const workflow = defineWorkflow(cfg, async () => ({
       finalMessage: "result text",
       threadId: "thread-123",
     }));
@@ -128,4 +131,13 @@ describe("defineWorkflow", () => {
       threadId: "thread-123",
     });
   });
+
+  it("sets the function name from config", () => {
+    const workflow = defineWorkflow(
+      { name: "my-main-workflow" },
+      async () => ({}),
+    );
+
+    expect(workflow.name).toBe("my-main-workflow");
+  });
 });

package/src/lib/workflow.ts

@@ -19,20 +19,26 @@ export interface WorkflowInput {
   sandboxId?: string;
 }
 
+export interface WorkflowConfig {
+  /** Workflow name — used as the Temporal workflow function name */
+  name: string;
+}
+
 /**
  * Wraps a main workflow function, translating workflow input fields into
  * session-compatible fields that can be spread directly into `createSession`.
  *
  * The wrapper:
- * - Accepts a generic typed `input` as first argument
- * - Accepts optional `workflowInput` ({ previousThreadId, sandboxId }) as second argument
+ * - Accepts a `config` with at least a `name` (used for Temporal workflow naming)
+ * - Accepts a handler `fn` receiving `(input, sessionInput)`
  * - Derives `threadId` + `continueThread` from `workflowInput.previousThreadId`
  * - Derives `sandboxId` from `workflowInput.sandboxId`
  */
 export function defineWorkflow<TInput, TResult>(
+  config: WorkflowConfig,
   fn: (input: TInput, sessionInput: WorkflowSessionInput) => Promise<TResult>,
 ): (input: TInput, workflowInput?: WorkflowInput) => Promise<TResult> {
-  return async (input, workflowInput = {}) => {
+  const workflow = async (input: TInput, workflowInput: WorkflowInput = {}) => {
     const sessionInput: WorkflowSessionInput = {
       ...(workflowInput.previousThreadId && {
         threadId: workflowInput.previousThreadId,
@@ -42,4 +48,8 @@ export function defineWorkflow<TInput, TResult>(
     };
     return fn(input, sessionInput);
   };
+
+  Object.defineProperty(workflow, "name", { value: config.name });
+
+  return workflow;
 }

package/src/tools/task-create/handler.ts

@@ -1,11 +1,8 @@
-import type {
-  AgentStateManager,
-  JsonSerializable,
-} from "../../lib/state";
+import type { AgentStateManager, JsonSerializable } from "../../lib/state";
 import type { ToolHandler } from "../../lib/tool-router";
 import type { WorkflowTask } from "../../lib/types";
+import { getShortId } from "../../workflow";
 import type { TaskCreateArgs } from "./tool";
-import { uuid4 } from "@temporalio/workflow";
 
 /**
  * Creates a TaskCreate handler that adds tasks to the workflow state.
@@ -20,7 +17,7 @@ export function createTaskCreateHandler<
 ): ToolHandler<TaskCreateArgs, WorkflowTask> {
   return (args) => {
     const task: WorkflowTask = {
-      id: uuid4(),
+      id: getShortId(),
       subject: args.subject,
       description: args.description,
       activeForm: args.activeForm,

package/src/workflow.ts

@@ -26,10 +26,10 @@ export {
 } from "./lib/session";
 export type { ZeitlichSession, ThreadOps, SessionConfig } from "./lib/session";
 export { defineWorkflow } from "./lib/workflow";
-export type { WorkflowInput, WorkflowSessionInput } from "./lib/workflow";
+export type { WorkflowConfig, WorkflowInput, WorkflowSessionInput } from "./lib/workflow";
 
 // Thread utilities
-export { getShortId } from "./lib/thread";
+export { getShortId } from "./lib/thread/id";
 
 // State management
 export { createAgentStateManager } from "./lib/state";