zeitlich 0.2.19 → 0.2.21

package/src/lib/session/session-edge-cases.integration.test.ts

@@ -5,6 +5,7 @@ import type { ThreadOps } from "./types";
 import type { RunAgentActivity } from "../model/types";
 import type { RawToolCall } from "../tool-router/types";
 import type { SandboxOps } from "../sandbox/types";
+import type { ActivityInterfaceFor } from "@temporalio/workflow";
 
 let idCounter = 0;
 
@@ -51,9 +52,26 @@ type TurnScript = {
   usage?: TokenUsage;
 };
 
+/**
+ * Wraps every method on a ThreadOps object so it also has `.executeWithOptions()`,
+ * matching Temporal's `ActivityInterfaceFor<ThreadOps>` shape.
+ */
+function toActivityInterface(
+  raw: ThreadOps,
+): ActivityInterfaceFor<ThreadOps> {
+  const result = {} as Record<string, unknown>;
+  for (const [key, fn] of Object.entries(raw)) {
+    const wrapped = (...args: unknown[]) => (fn as (...a: unknown[]) => unknown)(...args);
+    wrapped.executeWithOptions = (_opts: unknown, args: unknown[]) =>
+      (fn as (...a: unknown[]) => unknown)(...args);
+    result[key] = wrapped;
+  }
+  return result as ActivityInterfaceFor<ThreadOps>;
+}
+
 function createMockThreadOps() {
   const log: { op: string; args: unknown[] }[] = [];
-  const ops: ThreadOps = {
+  const ops = toActivityInterface({
     initializeThread: async (threadId) => {
       log.push({ op: "initializeThread", args: [threadId] });
     },
@@ -69,7 +87,7 @@ function createMockThreadOps() {
     forkThread: async (source, target) => {
       log.push({ op: "forkThread", args: [source, target] });
     },
-  };
+  });
   return { ops, log };
 }
 

package/src/lib/session/session.integration.test.ts

@@ -5,6 +5,7 @@ import type { ThreadOps } from "./types";
 import type { RunAgentActivity } from "../model/types";
 import type { RawToolCall } from "../tool-router/types";
 import type { SandboxOps } from "../sandbox/types";
+import type { ActivityInterfaceFor } from "@temporalio/workflow";
 
 // ---------------------------------------------------------------------------
 // Mock @temporalio/workflow
@@ -58,10 +59,23 @@ function at<T>(arr: T[], index: number): T {
   return val;
 }
 
+function toActivityInterface(
+  raw: ThreadOps,
+): ActivityInterfaceFor<ThreadOps> {
+  const result = {} as Record<string, unknown>;
+  for (const [key, fn] of Object.entries(raw)) {
+    const wrapped = (...args: unknown[]) => (fn as (...a: unknown[]) => unknown)(...args);
+    wrapped.executeWithOptions = (_opts: unknown, args: unknown[]) =>
+      (fn as (...a: unknown[]) => unknown)(...args);
+    result[key] = wrapped;
+  }
+  return result as ActivityInterfaceFor<ThreadOps>;
+}
+
 function createMockThreadOps() {
   const log: { op: string; args: unknown[] }[] = [];
 
-  const ops: ThreadOps = {
+  const ops = toActivityInterface({
     initializeThread: async (threadId) => {
       log.push({ op: "initializeThread", args: [threadId] });
     },
@@ -77,7 +91,7 @@ function createMockThreadOps() {
     forkThread: async (source, target) => {
       log.push({ op: "forkThread", args: [source, target] });
     },
-  };
+  });
 
   return { ops, log };
 }

package/src/lib/session/session.ts

@@ -4,6 +4,7 @@ import {
   defineUpdate,
   setHandler,
   ApplicationFailure,
+  type ActivityInterfaceFor,
 } from "@temporalio/workflow";
 import type { SessionExitReason, MessageContent } from "../types";
 import type { ThreadOps, SessionConfig, ZeitlichSession } from "./types";
@@ -14,6 +15,7 @@ import type { ParsedToolCallUnion, ToolMap } from "../tool-router/types";
 import { getShortId } from "../thread/id";
 import { buildSubagentRegistration } from "../subagent/register";
 import { buildSkillRegistration } from "../skills/register";
+import { uuid4 } from "@temporalio/workflow";
 
 /**
  * Creates an agent session that manages the agent loop: LLM invocation,
@@ -133,7 +135,7 @@ export const createSession = async <T extends ToolMap, M = unknown>({
               threadId,
             });
           }
-          await appendHumanMessage(threadId, message);
+          await appendHumanMessage(threadId, uuid4(), message);
           if (hooks.onPostHumanMessageAppend) {
             await hooks.onPostHumanMessageAppend({
               message,
@@ -175,12 +177,12 @@ export const createSession = async <T extends ToolMap, M = unknown>({
               nonRetryable: true,
             });
           }
-          await appendSystemMessage(threadId, systemPrompt);
+          await appendSystemMessage(threadId, uuid4(), systemPrompt);
         } else {
           await initializeThread(threadId);
         }
       }
-      await appendHumanMessage(threadId, await buildContextMessage());
+      await appendHumanMessage(threadId, uuid4(), await buildContextMessage());
 
       let exitReason: SessionExitReason = "completed";
 
@@ -221,7 +223,7 @@ export const createSession = async <T extends ToolMap, M = unknown>({
             try {
               parsedToolCalls.push(toolRouter.parseToolCall(tc));
             } catch (error) {
-              await appendToolResult({
+              await appendToolResult(uuid4(), {
                 threadId,
                 toolCallId: tc.id ?? "",
                 toolName: tc.name,
@@ -299,7 +301,7 @@ export const createSession = async <T extends ToolMap, M = unknown>({
  */
 export function proxyDefaultThreadOps(
   options?: Parameters<typeof proxyActivities>[0]
-): ThreadOps {
+): ActivityInterfaceFor<ThreadOps> {
   return proxyActivities<ThreadOps>(
     options ?? {
       startToCloseTimeout: "10s",

package/src/lib/session/types.ts

@@ -15,6 +15,7 @@ import type { Skill } from "../skills/types";
 import type { SandboxOps } from "../sandbox/types";
 import type { RunAgentActivity } from "../model/types";
 import type { AgentStateManager, JsonSerializable } from "../state/types";
+import type { ActivityInterfaceFor } from "@temporalio/workflow";
 
 /**
  * Thread operations required by a session.
@@ -26,12 +27,17 @@ export interface ThreadOps {
   /** Append a human message to the thread */
   appendHumanMessage(
     threadId: string,
+    id: string,
     content: string | MessageContent
   ): Promise<void>;
   /** Append a tool result to the thread */
-  appendToolResult(config: ToolResultConfig): Promise<void>;
+  appendToolResult(id: string, config: ToolResultConfig): Promise<void>;
   /** Append a system message to the thread */
-  appendSystemMessage(threadId: string, content: string): Promise<void>;
+  appendSystemMessage(
+    threadId: string,
+    id: string,
+    content: string
+  ): Promise<void>;
   /** Copy all messages from sourceThreadId into a new thread at targetThreadId */
   forkThread(sourceThreadId: string, targetThreadId: string): Promise<void>;
 }
@@ -53,7 +59,7 @@ export interface SessionConfig<T extends ToolMap, M = unknown> {
   /** Workflow-specific runAgent activity (with tools pre-bound) */
   runAgent: RunAgentActivity<M>;
   /** Thread operations (initialize, append messages, parse tool calls) */
-  threadOps?: ThreadOps;
+  threadOps?: ActivityInterfaceFor<ThreadOps>;
   /** Tool router for processing tool calls (optional if agent has no tools) */
   tools?: T;
   /** Subagent configurations */

package/src/lib/subagent/handler.ts

@@ -89,7 +89,7 @@ export function createSubagentHandler<
     if (config.allowThreadContinuation && childThreadId) {
       finalToolResponse =
         typeof toolResponse === "string"
-          ? `${toolResponse}\n\n[Thread ID: ${childThreadId}]`
+          ? `${toolResponse}\n\n[${config.agentName} Thread ID: ${childThreadId}]`
           : toolResponse;
     }
 

package/src/lib/subagent/subagent.integration.test.ts

@@ -476,13 +476,14 @@ describe("buildSubagentRegistration", () => {
 
     expect(reg).toBeDefined();
     if (reg) {
-      expect(reg.description).toContain("Agent A");
-      expect(reg.description).toContain("Agent B");
+      const desc = reg.description as () => string;
+      expect(desc()).toContain("Agent A");
+      expect(desc()).toContain("Agent B");
 
       bEnabled = false;
 
-      expect(reg.description).toContain("Agent A");
-      expect(reg.description).not.toContain("Agent B");
+      expect(desc()).toContain("Agent A");
+      expect(desc()).not.toContain("Agent B");
     }
   });
 });

package/src/lib/subagent/tool.ts

@@ -57,7 +57,7 @@ export function createSubagentTool<T extends SubagentConfig[]>(
           .string()
           .nullable()
           .describe(
-            "Thread ID to continue an existing conversation, or null to start a new one"
+            "Thread ID to continue an existing conversation from the same subagent, or null to start a new one"
           ),
       })
     : z.object(baseFields);

package/src/lib/thread/index.ts

@@ -1,5 +1,4 @@
 export { createThreadManager } from "./manager";
-export { getShortId } from "./id";
 
 export type {
   ThreadManagerConfig,

package/src/lib/tool-router/auto-append-sandbox.integration.test.ts

@@ -12,13 +12,13 @@ import type { Sandbox } from "../sandbox/types";
 describe("withAutoAppend", () => {
   it("appends tool result via threadHandler and sets resultAppended", async () => {
     const appended: ToolResultConfig[] = [];
-    const threadHandler = async (config: ToolResultConfig) => {
+    const threadHandler = async (_id: string, config: ToolResultConfig) => {
       appended.push(config);
     };
 
     const innerHandler = async (
       args: { text: string },
-      _ctx: RouterContext,
+      _ctx: RouterContext
     ): Promise<ToolHandlerResponse<{ echoed: string }>> => ({
       toolResponse: `Echo: ${args.text}`,
       data: { echoed: args.text },
@@ -32,7 +32,7 @@ describe("withAutoAppend", () => {
         threadId: "thread-1",
         toolCallId: "tc-1",
         toolName: "Echo",
-      },
+      }
     );
 
     expect(result.resultAppended).toBe(true);
@@ -62,7 +62,7 @@ describe("withAutoAppend", () => {
 
     const result = await wrapped(
       {},
-      { threadId: "t", toolCallId: "tc", toolName: "BigTool" },
+      { threadId: "t", toolCallId: "tc", toolName: "BigTool" }
     );
 
     expect(result.toolResponse).toBe("Response appended via withAutoAppend");
@@ -81,10 +81,7 @@ describe("withAutoAppend", () => {
     const wrapped = withAutoAppend(threadHandler, innerHandler);
 
     await expect(
-      wrapped(
-        {},
-        { threadId: "t", toolCallId: "tc", toolName: "Fail" },
-      ),
+      wrapped({}, { threadId: "t", toolCallId: "tc", toolName: "Fail" })
     ).rejects.toThrow("handler failed");
 
     expect(appendSpy).not.toHaveBeenCalled();
@@ -92,7 +89,7 @@ describe("withAutoAppend", () => {
 
   it("uses correct context fields for thread handler config", async () => {
     let capturedConfig: ToolResultConfig | null = null;
-    const threadHandler = async (config: ToolResultConfig) => {
+    const threadHandler = async (_id: string, config: ToolResultConfig) => {
       capturedConfig = config;
     };
 
@@ -110,7 +107,7 @@ describe("withAutoAppend", () => {
         toolCallId: "my-tc",
         toolName: "MyTool",
         sandboxId: "sb-1",
-      },
+      }
     );
 
     expect(capturedConfig).toEqual({
@@ -177,7 +174,7 @@ describe("withSandbox", () => {
 
     const handler = async (
       _args: { text: string },
-      ctx: RouterContext & { sandbox: Sandbox; sandboxId: string },
+      ctx: RouterContext & { sandbox: Sandbox; sandboxId: string }
     ): Promise<ToolHandlerResponse<null>> => {
       capturedSandbox = ctx.sandbox;
       capturedSandboxId = ctx.sandboxId;
@@ -193,7 +190,7 @@ describe("withSandbox", () => {
         toolCallId: "tc-1",
         toolName: "Test",
         sandboxId: "sb-42",
-      },
+      }
     );
 
     expect(result.toolResponse).toBe("ok");
@@ -219,7 +216,7 @@ describe("withSandbox", () => {
         threadId: "thread-1",
         toolCallId: "tc-1",
         toolName: "Bash",
-      },
+      }
     );
 
     expect(result.toolResponse).toContain("No sandbox configured");
@@ -247,7 +244,7 @@ describe("withSandbox", () => {
         toolCallId: "tc",
         toolName: "Grep",
         sandboxId: undefined,
-      },
+      }
     );
 
     expect(result.toolResponse).toContain("No sandbox configured");
@@ -276,8 +273,8 @@ describe("withSandbox", () => {
           toolCallId: "tc",
           toolName: "Test",
           sandboxId: "sb-missing",
-        },
-      ),
+        }
+      )
     ).rejects.toThrow("sandbox not found");
   });
 
@@ -285,11 +282,13 @@ describe("withSandbox", () => {
     const mockSandbox = createMockSandbox();
     const manager = { getSandbox: async () => mockSandbox };
 
-    let capturedCtx: (RouterContext & { sandbox: Sandbox; sandboxId: string }) | null = null;
+    let capturedCtx:
+      | (RouterContext & { sandbox: Sandbox; sandboxId: string })
+      | null = null;
 
     const handler = async (
       _args: unknown,
-      ctx: RouterContext & { sandbox: Sandbox; sandboxId: string },
+      ctx: RouterContext & { sandbox: Sandbox; sandboxId: string }
     ): Promise<ToolHandlerResponse<null>> => {
       capturedCtx = ctx;
       return { toolResponse: "ok", data: null };
@@ -304,7 +303,7 @@ describe("withSandbox", () => {
         toolCallId: "my-tc",
         toolName: "MyTool",
         sandboxId: "my-sandbox",
-      },
+      }
     );
 
     expect(capturedCtx).toEqual(
@@ -314,7 +313,7 @@ describe("withSandbox", () => {
         toolName: "MyTool",
         sandboxId: "my-sandbox",
         sandbox: mockSandbox,
-      }),
+      })
     );
   });
 
@@ -335,7 +334,7 @@ describe("withSandbox", () => {
         toolCallId: "tc",
         toolName: "Test",
         sandboxId: "",
-      },
+      }
     );
 
     expect(result.toolResponse).toContain("No sandbox configured");

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,18 +26,25 @@ 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: 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 };
 }
 
@@ -146,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"]);
@@ -185,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"]);
@@ -219,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"]);
@@ -259,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();
   });
 
@@ -365,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" });
@@ -393,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([]);
@@ -421,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);
@@ -435,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 },
       }),
@@ -447,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 });
@@ -504,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({
@@ -590,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({