zeitlich 0.2.20 → 0.2.21

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

@@ -1,5 +1,6 @@
 import type { ToolResultConfig } from "../types";
 import type { ActivityToolHandler, RouterContext } from "./types";
+import { v4 as uuidv4 } from "uuid";
 
 /**
  * Wraps a tool handler to automatically append its result directly to the
@@ -33,13 +34,13 @@ export function withAutoAppend<
   TResult,
   TContext extends RouterContext = RouterContext,
 >(
-  threadHandler: (config: ToolResultConfig) => Promise<void>,
+  threadHandler: (id: string, config: ToolResultConfig) => Promise<void>,
   handler: ActivityToolHandler<TArgs, TResult, TContext>
 ): ActivityToolHandler<TArgs, TResult, TContext> {
   return async (args: TArgs, context: TContext) => {
     const response = await handler(args, context);
 
-    await threadHandler({
+    await threadHandler(uuidv4(), {
       threadId: context.threadId,
       toolCallId: context.toolCallId,
       toolName: context.toolName,

package/src/lib/tool-router/router-edge-cases.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;
@@ -29,22 +26,24 @@ vi.mock("@temporalio/workflow", () => {
 });
 
 import { createToolRouter, defineTool, hasNoOtherToolCalls } from "./router";
-import type {
-  ToolMap,
-  ToolHandlerResponse,
-  AppendToolResultFn,
-} from "./types";
+import type { ToolMap, ToolHandlerResponse, AppendToolResultFn } from "./types";
 import type { ToolResultConfig } from "../types";
 
 function createAppendSpy() {
   const calls: ToolResultConfig[] = [];
   const fn = Object.assign(
-    async (config: ToolResultConfig) => { calls.push(config); },
-    { executeWithOptions: (_opts: unknown, [config]: [ToolResultConfig]) => {
+    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 };
 }
@@ -151,7 +150,11 @@ describe("createToolRouter edge cases", () => {
       },
     });
 
-    const parsed = router.parseToolCall({ id: "tc-1", name: "Hooked", args: {} });
+    const parsed = router.parseToolCall({
+      id: "tc-1",
+      name: "Hooked",
+      args: {},
+    });
     await router.processToolCalls([parsed], { turn: 1 });
 
     expect(order).toEqual(["global-pre", "tool-pre", "handler"]);
@@ -190,7 +193,11 @@ describe("createToolRouter edge cases", () => {
       },
     });
 
-    const parsed = router.parseToolCall({ id: "tc-1", name: "Hooked", args: {} });
+    const parsed = router.parseToolCall({
+      id: "tc-1",
+      name: "Hooked",
+      args: {},
+    });
     await router.processToolCalls([parsed], { turn: 1 });
 
     expect(order).toEqual(["global-pre-skip"]);
@@ -224,7 +231,11 @@ describe("createToolRouter edge cases", () => {
       },
     });
 
-    const parsed = router.parseToolCall({ id: "tc-1", name: "Hooked", args: {} });
+    const parsed = router.parseToolCall({
+      id: "tc-1",
+      name: "Hooked",
+      args: {},
+    });
     await router.processToolCalls([parsed], { turn: 1 });
 
     expect(order).toEqual(["tool-post", "global-post"]);
@@ -264,7 +275,10 @@ describe("createToolRouter edge cases", () => {
     const results = await router.processToolCalls([parsed], { turn: 1 });
 
     expect(at(appendSpy.calls, 0).content).toBe("tool-level recovery");
-    expect(at(results, 0).data).toEqual({ error: "Error: boom", recovered: true });
+    expect(at(results, 0).data).toEqual({
+      error: "Error: boom",
+      recovered: true,
+    });
     expect(globalHookSpy).not.toHaveBeenCalled();
   });
 
@@ -370,7 +384,11 @@ describe("createToolRouter edge cases", () => {
       plugins: [pluginTool],
     });
 
-    const parsed = router.parseToolCall({ id: "tc-1", name: "MyTool", args: {} });
+    const parsed = router.parseToolCall({
+      id: "tc-1",
+      name: "MyTool",
+      args: {},
+    });
     const results = await router.processToolCalls([parsed]);
 
     expect(at(results, 0).data).toEqual({ source: "plugin" });
@@ -398,7 +416,7 @@ describe("createToolRouter edge cases", () => {
     const results = await router.processToolCallsByName(
       [],
       "Echo",
-      async () => ({ toolResponse: "ok", data: null }),
+      async () => ({ toolResponse: "ok", data: null })
     );
 
     expect(results).toEqual([]);
@@ -426,7 +444,11 @@ describe("createToolRouter edge cases", () => {
       appendToolResult: appendSpy.fn,
     });
 
-    const parsed = router.parseToolCall({ id: "tc-1", name: "Complex", args: {} });
+    const parsed = router.parseToolCall({
+      id: "tc-1",
+      name: "Complex",
+      args: {},
+    });
     await router.processToolCalls([parsed]);
 
     const appended = at(appendSpy.calls, 0);
@@ -440,7 +462,9 @@ describe("createToolRouter edge cases", () => {
       name: "Sync" as const,
       description: "sync handler",
       schema: z.object({ n: z.number() }),
-      handler: (args: { n: number }): ToolHandlerResponse<{ doubled: number }> => ({
+      handler: (args: {
+        n: number;
+      }): ToolHandlerResponse<{ doubled: number }> => ({
         toolResponse: `${args.n * 2}`,
         data: { doubled: args.n * 2 },
       }),
@@ -452,7 +476,11 @@ describe("createToolRouter edge cases", () => {
       appendToolResult: appendSpy.fn,
     });
 
-    const parsed = router.parseToolCall({ id: "tc-1", name: "Sync", args: { n: 5 } });
+    const parsed = router.parseToolCall({
+      id: "tc-1",
+      name: "Sync",
+      args: { n: 5 },
+    });
     const results = await router.processToolCalls([parsed]);
 
     expect(at(results, 0).data).toEqual({ doubled: 10 });
@@ -509,7 +537,11 @@ describe("createToolRouter edge cases", () => {
       appendToolResult: appendSpy.fn,
     });
 
-    const parsed = router.parseToolCall({ id: "tc-1", name: "Suppress", args: {} });
+    const parsed = router.parseToolCall({
+      id: "tc-1",
+      name: "Suppress",
+      args: {},
+    });
     const results = await router.processToolCalls([parsed], { turn: 1 });
 
     expect(at(results, 0).data).toEqual({
@@ -595,7 +627,11 @@ describe("createToolRouter edge cases", () => {
       },
     });
 
-    const parsed = router.parseToolCall({ id: "tc-1", name: "ThrowString", args: {} });
+    const parsed = router.parseToolCall({
+      id: "tc-1",
+      name: "ThrowString",
+      args: {},
+    });
     const results = await router.processToolCalls([parsed], { turn: 1 });
 
     expect(at(results, 0).data).toEqual({

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);
   },
 });
@@ -87,12 +91,18 @@ function createTools() {
 function createAppendSpy() {
   const calls: ToolResultConfig[] = [];
   const fn = Object.assign(
-    async (config: ToolResultConfig) => { calls.push(config); },
-    { executeWithOptions: (_opts: unknown, [config]: [ToolResultConfig]) => {
+    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 };
 }
@@ -168,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");
   });
 
@@ -180,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();
   });
 
@@ -329,7 +339,7 @@ describe("createToolRouter integration", () => {
         toolCallId: "tc-99",
         toolName: "Spy",
         sandboxId: "sandbox-1",
-      }),
+      })
     );
   });
 
@@ -357,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 () => {
@@ -421,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();
@@ -450,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);
   });
@@ -511,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");
   });
 
@@ -520,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: {
@@ -562,7 +590,7 @@ describe("createToolRouter integration", () => {
     });
 
     await expect(
-      router.processToolCalls([parsed], { turn: 1 }),
+      router.processToolCalls([parsed], { turn: 1 })
     ).rejects.toThrow("unrecoverable");
   });
 
@@ -586,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");
   });
 
@@ -643,7 +671,7 @@ describe("createToolRouter integration", () => {
       async (args: { text: string }) => ({
         toolResponse: `custom: ${args.text}`,
         data: { custom: args.text },
-      }),
+      })
     );
 
     expect(results).toHaveLength(2);
@@ -696,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.
@@ -203,7 +203,7 @@ 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,
@@ -264,7 +264,7 @@ export function createToolRouter<T extends ToolMap>(
         {
           summary: `Append ${toolCall.name} result`,
         },
-        [config]
+        [uuid4(), config]
       );
     }
 
@@ -395,6 +395,7 @@ export function createToolRouter<T extends ToolMap>(
               summary: `Append ${toolCall.name} result`,
             },
             [
+              uuid4(),
               {
                 threadId: options.threadId,
                 toolCallId: toolCall.id,

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

@@ -116,7 +116,7 @@ export type ParsedToolCallUnion<T extends ToolMap> = {
  * Function signature for appending tool results to a thread.
  */
 export type AppendToolResultFn = ActivityFunctionWithOptions<
-  (config: ToolResultConfig) => Promise<void>
+  (id: string, config: ToolResultConfig) => Promise<void>
 >;
 
 /**