zeitlich 0.2.20 → 0.2.21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zeitlich",
-  "version": "0.2.20",
+  "version": "0.2.21",
   "description": "[EXPERIMENTAL] An opinionated AI agent implementation for Temporal",
   "main": "./dist/index.js",
   "module": "./dist/index.js",

package/src/adapters/thread/google-genai/activities.ts

@@ -68,7 +68,7 @@ export interface GoogleGenAIAdapter {
  * ```
  */
 export function createGoogleGenAIAdapter(
-  config: GoogleGenAIAdapterConfig,
+  config: GoogleGenAIAdapterConfig
 ): GoogleGenAIAdapter {
   const { redis, client } = config;
 
@@ -80,29 +80,31 @@ export function createGoogleGenAIAdapter(
 
     async appendHumanMessage(
       threadId: string,
-      content: string | MessageContent,
+      id: string,
+      content: string | MessageContent
     ): Promise<void> {
       const thread = createGoogleGenAIThreadManager({ redis, threadId });
-      await thread.appendUserMessage(content);
+      await thread.appendUserMessage(id, content);
     },
 
     async appendSystemMessage(
       threadId: string,
-      content: string,
+      id: string,
+      content: string
     ): Promise<void> {
       const thread = createGoogleGenAIThreadManager({ redis, threadId });
-      await thread.appendSystemMessage(content);
+      await thread.appendSystemMessage(id, content);
     },
 
-    async appendToolResult(cfg: ToolResultConfig): Promise<void> {
+    async appendToolResult(id: string, cfg: ToolResultConfig): Promise<void> {
       const { threadId, toolCallId, toolName, content } = cfg;
       const thread = createGoogleGenAIThreadManager({ redis, threadId });
-      await thread.appendToolResult(toolCallId, toolName, content);
+      await thread.appendToolResult(id, toolCallId, toolName, content);
     },
 
     async forkThread(
       sourceThreadId: string,
-      targetThreadId: string,
+      targetThreadId: string
     ): Promise<void> {
       const thread = createGoogleGenAIThreadManager({
         redis,
@@ -120,7 +122,7 @@ export function createGoogleGenAIAdapter(
     : ((() => {
         throw new Error(
           "No default model provided to createGoogleGenAIAdapter. " +
-            "Either pass `model` in the config or use `createModelInvoker(model)` instead.",
+            "Either pass `model` in the config or use `createModelInvoker(model)` instead."
         );
       }) as unknown as ModelInvoker<Content>);
 

package/src/adapters/thread/google-genai/model-invoker.ts

@@ -1,13 +1,10 @@
 import type Redis from "ioredis";
-import type {
-  GoogleGenAI,
-  Content,
-  FunctionDeclaration,
-} from "@google/genai";
+import type { GoogleGenAI, Content, FunctionDeclaration } from "@google/genai";
 import type { SerializableToolDefinition } from "../../../lib/types";
 import type { AgentResponse } from "../../../lib/model";
 import type { ModelInvokerConfig } from "../../../lib/model";
 import { createGoogleGenAIThreadManager } from "./thread-manager";
+import { v4 as uuidv4 } from "uuid";
 
 export interface GoogleGenAIModelInvokerConfig {
   redis: Redis;
@@ -16,7 +13,7 @@ export interface GoogleGenAIModelInvokerConfig {
 }
 
 function toFunctionDeclarations(
-  tools: SerializableToolDefinition[],
+  tools: SerializableToolDefinition[]
 ): FunctionDeclaration[] {
   return tools.map((t) => ({
     name: t.name,
@@ -73,7 +70,7 @@ export function createGoogleGenAIModelInvoker({
   model,
 }: GoogleGenAIModelInvokerConfig) {
   return async function invokeGoogleGenAIModel(
-    config: ModelInvokerConfig,
+    config: ModelInvokerConfig
   ): Promise<AgentResponse<Content>> {
     const { threadId, state } = config;
 
@@ -97,9 +94,7 @@ export function createGoogleGenAIModelInvoker({
 
     const functionDeclarations = toFunctionDeclarations(state.tools);
     const tools =
-      functionDeclarations.length > 0
-        ? [{ functionDeclarations }]
-        : undefined;
+      functionDeclarations.length > 0 ? [{ functionDeclarations }] : undefined;
 
     const response = await client.models.generateContent({
       model,
@@ -113,7 +108,7 @@ export function createGoogleGenAIModelInvoker({
     const responseParts = response.candidates?.[0]?.content?.parts ?? [];
     const modelContent: Content = { role: "model", parts: responseParts };
 
-    await thread.appendModelContent(responseParts);
+    await thread.appendModelContent(uuidv4(), responseParts);
 
     const functionCalls = response.functionCalls ?? [];
 

package/src/adapters/thread/google-genai/thread-manager.ts

@@ -21,23 +21,30 @@ export interface GoogleGenAIThreadManagerConfig {
 }
 
 /** Thread manager with Google GenAI Content convenience helpers */
-export interface GoogleGenAIThreadManager
-  extends BaseThreadManager<StoredContent> {
-  createUserContent(content: string | MessageContent): StoredContent;
-  createSystemContent(content: string): StoredContent;
-  createModelContent(parts: Part[]): StoredContent;
+export interface GoogleGenAIThreadManager extends BaseThreadManager<StoredContent> {
+  createUserContent(
+    id: string,
+    content: string | MessageContent
+  ): StoredContent;
+  createSystemContent(id: string, content: string): StoredContent;
+  createModelContent(id: string, parts: Part[]): StoredContent;
   createToolResponseContent(
+    id: string,
     toolCallId: string,
     toolName: string,
-    content: ToolMessageContent,
+    content: ToolMessageContent
   ): StoredContent;
-  appendUserMessage(content: string | MessageContent): Promise<void>;
-  appendSystemMessage(content: string): Promise<void>;
-  appendModelContent(parts: Part[]): Promise<void>;
+  appendUserMessage(
+    id: string,
+    content: string | MessageContent
+  ): Promise<void>;
+  appendSystemMessage(id: string, content: string): Promise<void>;
+  appendModelContent(id: string, parts: Part[]): Promise<void>;
   appendToolResult(
+    id: string,
     toolCallId: string,
     toolName: string,
-    content: ToolMessageContent,
+    content: ToolMessageContent
   ): Promise<void>;
 }
 
@@ -47,7 +54,7 @@ function storedContentId(msg: StoredContent): string {
 
 /** Convert zeitlich MessageContent to Google GenAI Part[] */
 export function messageContentToParts(
-  content: string | MessageContent,
+  content: string | MessageContent
 ): Part[] {
   if (typeof content === "string") {
     return [{ text: content }];
@@ -65,7 +72,7 @@ export function messageContentToParts(
 
 /** Parse ToolMessageContent into a Record suitable for functionResponse */
 function parseToolResponse(
-  content: ToolMessageContent,
+  content: ToolMessageContent
 ): Record<string, unknown> {
   if (typeof content === "string") {
     try {
@@ -86,7 +93,7 @@ function parseToolResponse(
  * appending typed Content messages.
  */
 export function createGoogleGenAIThreadManager(
-  config: GoogleGenAIThreadManagerConfig,
+  config: GoogleGenAIThreadManagerConfig
 ): GoogleGenAIThreadManager {
   const baseConfig: ThreadManagerConfig<StoredContent> = {
     redis: config.redis,
@@ -98,34 +105,38 @@ export function createGoogleGenAIThreadManager(
   const base = createThreadManager(baseConfig);
 
   const helpers = {
-    createUserContent(content: string | MessageContent): StoredContent {
+    createUserContent(
+      id: string,
+      content: string | MessageContent
+    ): StoredContent {
       return {
-        id: crypto.randomUUID(),
+        id,
         content: { role: "user", parts: messageContentToParts(content) },
       };
     },
 
-    createSystemContent(content: string): StoredContent {
+    createSystemContent(id: string, content: string): StoredContent {
       return {
-        id: crypto.randomUUID(),
+        id,
         content: { role: "system", parts: [{ text: content }] },
       };
     },
 
-    createModelContent(parts: Part[]): StoredContent {
+    createModelContent(id: string, parts: Part[]): StoredContent {
       return {
-        id: crypto.randomUUID(),
+        id,
         content: { role: "model", parts },
       };
     },
 
     createToolResponseContent(
+      id: string,
       toolCallId: string,
       toolName: string,
-      content: ToolMessageContent,
+      content: ToolMessageContent
     ): StoredContent {
       return {
-        id: crypto.randomUUID(),
+        id,
         content: {
           role: "user",
           parts: [
@@ -141,26 +152,30 @@ export function createGoogleGenAIThreadManager(
       };
     },
 
-    async appendUserMessage(content: string | MessageContent): Promise<void> {
-      await base.append([helpers.createUserContent(content)]);
+    async appendUserMessage(
+      id: string,
+      content: string | MessageContent
+    ): Promise<void> {
+      await base.append([helpers.createUserContent(id, content)]);
     },
 
-    async appendSystemMessage(content: string): Promise<void> {
+    async appendSystemMessage(id: string, content: string): Promise<void> {
       await base.initialize();
-      await base.append([helpers.createSystemContent(content)]);
+      await base.append([helpers.createSystemContent(id, content)]);
     },
 
-    async appendModelContent(parts: Part[]): Promise<void> {
-      await base.append([helpers.createModelContent(parts)]);
+    async appendModelContent(id: string, parts: Part[]): Promise<void> {
+      await base.append([helpers.createModelContent(id, parts)]);
     },
 
     async appendToolResult(
+      id: string,
       toolCallId: string,
       toolName: string,
-      content: ToolMessageContent,
+      content: ToolMessageContent
     ): Promise<void> {
       await base.append([
-        helpers.createToolResponseContent(toolCallId, toolName, content),
+        helpers.createToolResponseContent(id, toolCallId, toolName, content),
       ]);
     },
   };

package/src/adapters/thread/langchain/activities.ts

@@ -74,24 +74,26 @@ export function createLangChainAdapter(
 
     async appendHumanMessage(
       threadId: string,
+      id: string,
       content: string | MessageContent
     ): Promise<void> {
       const thread = createLangChainThreadManager({ redis, threadId });
-      await thread.appendHumanMessage(content);
+      await thread.appendHumanMessage(id, content);
     },
 
     async appendSystemMessage(
       threadId: string,
+      id: string,
       content: string
     ): Promise<void> {
       const thread = createLangChainThreadManager({ redis, threadId });
-      await thread.appendSystemMessage(content);
+      await thread.appendSystemMessage(id, content);
     },
 
-    async appendToolResult(cfg: ToolResultConfig): Promise<void> {
+    async appendToolResult(id: string, cfg: ToolResultConfig): Promise<void> {
       const { threadId, toolCallId, content } = cfg;
       const thread = createLangChainThreadManager({ redis, threadId });
-      await thread.appendToolMessage(content, toolCallId);
+      await thread.appendToolMessage(id, content, toolCallId);
     },
 
     async forkThread(

package/src/adapters/thread/langchain/thread-manager.ts

@@ -9,7 +9,6 @@ import {
   SystemMessage,
   ToolMessage,
 } from "@langchain/core/messages";
-import { v4 as uuidv4 } from "uuid";
 import {
   createThreadManager,
   type BaseThreadManager,
@@ -30,31 +29,44 @@ export interface LangChainThreadManagerConfig {
 
 /** Thread manager with LangChain StoredMessage convenience helpers */
 export interface LangChainThreadManager extends BaseThreadManager<StoredMessage> {
-  createHumanMessage(content: string | MessageContent): StoredMessage;
-  createSystemMessage(content: string): StoredMessage;
+  createHumanMessage(
+    id: string,
+    content: string | MessageContent
+  ): StoredMessage;
+  createSystemMessage(id: string, content: string): StoredMessage;
   createAIMessage(
+    id: string,
     content: string | MessageContent,
     kwargs?: { header?: string; options?: string[]; multiSelect?: boolean }
   ): StoredMessage;
   createToolMessage(
+    id: string,
     content: LangChainToolMessageContent,
     toolCallId: string
   ): StoredMessage;
-  appendHumanMessage(content: string | MessageContent): Promise<void>;
-  appendSystemMessage(content: string): Promise<void>;
+  appendHumanMessage(
+    id: string,
+    content: string | MessageContent
+  ): Promise<void>;
+  appendSystemMessage(id: string, content: string): Promise<void>;
   appendToolMessage(
+    id: string,
     content: LangChainToolMessageContent,
     toolCallId: string
   ): Promise<void>;
-  appendAIMessage(content: string | MessageContent): Promise<void>;
+  appendAIMessage(id: string, content: string | MessageContent): Promise<void>;
 }
 
 function storedMessageId(msg: StoredMessage): string {
-  if (msg.type === "tool") {
-    return msg.data.tool_call_id ?? "";
+  if (msg.type === "tool" && msg.data.tool_call_id) {
+    return msg.data.tool_call_id;
+  }
+
+  if (msg.data.id) {
+    return msg.data.id;
   }
 
-  return msg.data.id ?? "";
+  throw new Error("No id found for message");
 }
 
 /**
@@ -75,26 +87,30 @@ export function createLangChainThreadManager(
   const base = createThreadManager(baseConfig);
 
   const helpers = {
-    createHumanMessage(content: string | MessageContent): StoredMessage {
+    createHumanMessage(
+      id: string,
+      content: string | MessageContent
+    ): StoredMessage {
       return new HumanMessage({
-        id: uuidv4(),
+        id,
         content: content as string,
       }).toDict();
     },
 
-    createSystemMessage(content: string): StoredMessage {
+    createSystemMessage(id: string, content: string): StoredMessage {
       return new SystemMessage({
-        id: uuidv4(),
+        id,
         content: content as string,
       }).toDict();
     },
 
     createAIMessage(
+      id: string,
       content: string,
       kwargs?: { header?: string; options?: string[]; multiSelect?: boolean }
     ): StoredMessage {
       return new AIMessage({
-        id: uuidv4(),
+        id,
         content,
         additional_kwargs: kwargs
           ? {
@@ -107,36 +123,44 @@ export function createLangChainThreadManager(
     },
 
     createToolMessage(
+      id: string,
       content: LangChainToolMessageContent,
       toolCallId: string
     ): StoredMessage {
       return new ToolMessage({
-        id: uuidv4(),
+        id,
         content: content as MessageContent,
         tool_call_id: toolCallId,
       }).toDict();
     },
 
-    async appendHumanMessage(content: string | MessageContent): Promise<void> {
-      const message = helpers.createHumanMessage(content);
+    async appendHumanMessage(
+      id: string,
+      content: string | MessageContent
+    ): Promise<void> {
+      const message = helpers.createHumanMessage(id, content);
       await base.append([message]);
     },
 
     async appendToolMessage(
+      id: string,
       content: LangChainToolMessageContent,
       toolCallId: string
     ): Promise<void> {
-      const message = helpers.createToolMessage(content, toolCallId);
+      const message = helpers.createToolMessage(id, content, toolCallId);
       await base.append([message]);
     },
 
-    async appendAIMessage(content: string | MessageContent): Promise<void> {
-      const message = helpers.createAIMessage(content as string);
+    async appendAIMessage(
+      id: string,
+      content: string | MessageContent
+    ): Promise<void> {
+      const message = helpers.createAIMessage(id, content as string);
       await base.append([message]);
     },
 
-    async appendSystemMessage(content: string): Promise<void> {
-      const message = helpers.createSystemMessage(content);
+    async appendSystemMessage(id: string, content: string): Promise<void> {
+      const message = helpers.createSystemMessage(id, content);
       await base.initialize();
       await base.append([message]);
     },

package/src/lib/session/session.ts

@@ -15,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,
@@ -134,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,
@@ -176,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";
 
@@ -222,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,

package/src/lib/session/types.ts

@@ -27,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>;
 }

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");