zeitlich 0.2.19 → 0.2.21

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

@@ -15,10 +15,7 @@ vi.mock("@temporalio/workflow", () => {
       err.nonRetryable = nonRetryable;
       return err;
     }
-    static fromError(
-      error: unknown,
-      options?: { nonRetryable?: boolean },
-    ) {
+    static fromError(error: unknown, options?: { nonRetryable?: boolean }) {
       const src = error instanceof Error ? error : new Error(String(error));
       const err = new MockApplicationFailure(src.message);
       err.nonRetryable = options?.nonRetryable;
@@ -45,7 +42,9 @@ const echoTool = defineTool({
   name: "Echo" as const,
   description: "Echoes back the input",
   schema: z.object({ text: z.string() }),
-  handler: async (args: { text: string }): Promise<ToolHandlerResponse<{ echoed: string }>> => ({
+  handler: async (args: {
+    text: string;
+  }): Promise<ToolHandlerResponse<{ echoed: string }>> => ({
     toolResponse: `Echo: ${args.text}`,
     data: { echoed: args.text },
   }),
@@ -55,7 +54,10 @@ const mathTool = defineTool({
   name: "Add" as const,
   description: "Adds two numbers",
   schema: z.object({ a: z.number(), b: z.number() }),
-  handler: async (args: { a: number; b: number }): Promise<ToolHandlerResponse<{ sum: number }>> => ({
+  handler: async (args: {
+    a: number;
+    b: number;
+  }): Promise<ToolHandlerResponse<{ sum: number }>> => ({
     toolResponse: `Sum: ${args.a + args.b}`,
     data: { sum: args.a + args.b },
   }),
@@ -65,7 +67,9 @@ const failingTool = defineTool({
   name: "Fail" as const,
   description: "Always fails",
   schema: z.object({ reason: z.string() }),
-  handler: async (args: { reason: string }): Promise<ToolHandlerResponse<null>> => {
+  handler: async (args: {
+    reason: string;
+  }): Promise<ToolHandlerResponse<null>> => {
     throw new Error(args.reason);
   },
 });
@@ -86,9 +90,20 @@ function createTools() {
 
 function createAppendSpy() {
   const calls: ToolResultConfig[] = [];
-  const fn: AppendToolResultFn = async (config) => {
-    calls.push(config);
-  };
+  const fn = Object.assign(
+    async (_id: string, config: ToolResultConfig) => {
+      calls.push(config);
+    },
+    {
+      executeWithOptions: (
+        _opts: unknown,
+        [, config]: [string, ToolResultConfig]
+      ) => {
+        calls.push(config);
+        return Promise.resolve();
+      },
+    }
+  ) as AppendToolResultFn;
   return { fn, calls };
 }
 
@@ -163,7 +178,7 @@ describe("createToolRouter integration", () => {
     });
 
     expect(() =>
-      router.parseToolCall({ id: "tc-1", name: "Unknown", args: {} }),
+      router.parseToolCall({ id: "tc-1", name: "Unknown", args: {} })
     ).toThrow("Tool Unknown not found");
   });
 
@@ -175,7 +190,7 @@ describe("createToolRouter integration", () => {
     });
 
     expect(() =>
-      router.parseToolCall({ id: "tc-1", name: "Echo", args: { text: 123 } }),
+      router.parseToolCall({ id: "tc-1", name: "Echo", args: { text: 123 } })
     ).toThrow();
   });
 
@@ -324,7 +339,7 @@ describe("createToolRouter integration", () => {
         toolCallId: "tc-99",
         toolName: "Spy",
         sandboxId: "sandbox-1",
-      }),
+      })
     );
   });
 
@@ -352,12 +367,18 @@ describe("createToolRouter integration", () => {
       },
     });
 
-    const parsed = router.parseToolCall({ id: "tc-1", name: "Skippable", args: {} });
+    const parsed = router.parseToolCall({
+      id: "tc-1",
+      name: "Skippable",
+      args: {},
+    });
     const results = await router.processToolCalls([parsed], { turn: 1 });
 
     expect(handlerSpy).not.toHaveBeenCalled();
     expect(results).toHaveLength(0);
-    expect(at(appendSpy.calls, 0).content).toContain("Skipped by PreToolUse hook");
+    expect(at(appendSpy.calls, 0).content).toContain(
+      "Skipped by PreToolUse hook"
+    );
   });
 
   it("pre-hook can modify arguments", async () => {
@@ -416,7 +437,11 @@ describe("createToolRouter integration", () => {
       appendToolResult: appendSpy.fn,
     });
 
-    const parsed = router.parseToolCall({ id: "tc-1", name: "Hooked", args: {} });
+    const parsed = router.parseToolCall({
+      id: "tc-1",
+      name: "Hooked",
+      args: {},
+    });
     const results = await router.processToolCalls([parsed], { turn: 1 });
 
     expect(handlerSpy).not.toHaveBeenCalled();
@@ -445,7 +470,10 @@ describe("createToolRouter integration", () => {
     await router.processToolCalls([parsed], { turn: 1 });
 
     expect(hookData).not.toBeNull();
-    const data = hookData as unknown as { result: { data: unknown }; durationMs: number };
+    const data = hookData as unknown as {
+      result: { data: unknown };
+      durationMs: number;
+    };
     expect(data.result.data).toEqual({ sum: 7 });
     expect(data.durationMs).toBeGreaterThanOrEqual(0);
   });
@@ -506,7 +534,10 @@ describe("createToolRouter integration", () => {
     const results = await router.processToolCalls([parsed], { turn: 1 });
 
     expect(results).toHaveLength(1);
-    expect(at(results, 0).data).toEqual({ error: "Error: boom", recovered: true });
+    expect(at(results, 0).data).toEqual({
+      error: "Error: boom",
+      recovered: true,
+    });
     expect(at(appendSpy.calls, 0).content).toBe("recovered gracefully");
   });
 
@@ -515,7 +546,9 @@ describe("createToolRouter integration", () => {
       name: "Fail" as const,
       description: "fails but suppresses",
       schema: z.object({ reason: z.string() }),
-      handler: async (args: { reason: string }): Promise<ToolHandlerResponse<null>> => {
+      handler: async (args: {
+        reason: string;
+      }): Promise<ToolHandlerResponse<null>> => {
         throw new Error(args.reason);
       },
       hooks: {
@@ -557,7 +590,7 @@ describe("createToolRouter integration", () => {
     });
 
     await expect(
-      router.processToolCalls([parsed], { turn: 1 }),
+      router.processToolCalls([parsed], { turn: 1 })
     ).rejects.toThrow("unrecoverable");
   });
 
@@ -581,7 +614,7 @@ describe("createToolRouter integration", () => {
     expect(router.hasTool("Disabled")).toBe(false);
     expect(router.getToolNames()).not.toContain("Disabled");
     expect(() =>
-      router.parseToolCall({ id: "tc-1", name: "Disabled", args: {} }),
+      router.parseToolCall({ id: "tc-1", name: "Disabled", args: {} })
     ).toThrow("Tool Disabled not found");
   });
 
@@ -638,7 +671,7 @@ describe("createToolRouter integration", () => {
       async (args: { text: string }) => ({
         toolResponse: `custom: ${args.text}`,
         data: { custom: args.text },
-      }),
+      })
     );
 
     expect(results).toHaveLength(2);
@@ -691,7 +724,11 @@ describe("createToolRouter integration", () => {
       appendToolResult: appendSpy.fn,
     });
 
-    const parsed = router.parseToolCall({ id: "tc-1", name: "SelfAppend", args: {} });
+    const parsed = router.parseToolCall({
+      id: "tc-1",
+      name: "SelfAppend",
+      args: {},
+    });
     await router.processToolCalls([parsed]);
 
     expect(appendSpy.calls).toHaveLength(0);

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

@@ -20,7 +20,7 @@ import type {
 } from "./types";
 
 import type { z } from "zod";
-import { ApplicationFailure } from "@temporalio/workflow";
+import { ApplicationFailure, uuid4 } from "@temporalio/workflow";
 
 /**
  * Creates a tool router for declarative tool call processing.
@@ -63,7 +63,7 @@ export function createToolRouter<T extends ToolMap>(
     toolMap.set(tool.name, tool as T[keyof T]);
   }
 
-  const resolve = <T,>(v: T | (() => T)): T =>
+  const resolve = <T>(v: T | (() => T)): T =>
     typeof v === "function" ? (v as () => T)() : v;
 
   const isEnabled = (tool: ToolMap[string]): boolean =>
@@ -130,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 }),
@@ -146,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 }),
@@ -197,11 +203,14 @@ export function createToolRouter<T extends ToolMap>(
     // --- Pre-hooks: may skip or modify args ---
     const preResult = await runPreHooks(toolCall, tool, turn);
     if (preResult.skip) {
-      await appendToolResult({
+      await appendToolResult(uuid4(), {
         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;
     }
@@ -232,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`,
+        },
+        [uuid4(), config]
+      );
     }
 
     const toolResult = {
@@ -254,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;
   }
@@ -316,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
@@ -327,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);
         }
@@ -339,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>,
@@ -361,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>,
@@ -369,12 +390,20 @@ 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`,
+            },
+            [
+              uuid4(),
+              {
+                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
@@ -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<
+  (id: string, 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";