zeitlich 0.2.20 → 0.2.22

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/sandbox/manager.ts

@@ -2,6 +2,7 @@ import type {
   Sandbox,
   SandboxCreateOptions,
   SandboxOps,
+  PrefixedSandboxOps,
   SandboxProvider,
   SandboxSnapshot,
 } from "./types";
@@ -16,16 +17,18 @@ import type {
  * ```typescript
  * const manager = new SandboxManager(new InMemorySandboxProvider());
  * const activities = {
- *   ...manager.createActivities(),
+ *   ...manager.createActivities("CodingAgent"),
  *   bashHandler: withSandbox(manager, bashHandler),
  * };
+ * // registers: inMemoryCodingAgentCreateSandbox, …
  * ```
  */
 export class SandboxManager<
   TOptions extends SandboxCreateOptions = SandboxCreateOptions,
   TSandbox extends Sandbox = Sandbox,
+  TId extends string = string,
 > {
-  constructor(private provider: SandboxProvider<TOptions, TSandbox>) {}
+  constructor(private provider: SandboxProvider<TOptions, TSandbox> & { readonly id: TId }) {}
 
   async create(
     options?: TOptions
@@ -51,12 +54,36 @@ export class SandboxManager<
     return sandbox.id;
   }
 
+  async fork(sandboxId: string): Promise<string> {
+    const sandbox = await this.provider.fork(sandboxId);
+    return sandbox.id;
+  }
+
   /**
-   * Returns Temporal activity functions matching {@link SandboxOps}.
-   * Spread these into your worker's activity map.
+   * Returns Temporal activity functions with prefixed names.
+   *
+   * The provider's `id` is automatically prepended, so you only need
+   * to pass the workflow/scope name. Use the matching `proxy*SandboxOps()`
+   * helper from the adapter's `/workflow` entrypoint on the workflow side.
+   *
+   * @param scope - Workflow name (appended to the provider id)
+   *
+   * @example
+   * ```typescript
+   * const manager = new SandboxManager(new InMemorySandboxProvider());
+   * manager.createActivities("CodingAgent");
+   * // registers: inMemoryCodingAgentCreateSandbox, inMemoryCodingAgentDestroySandbox, …
+   *
+   * const vmgr = new SandboxManager(new VirtualSandboxProvider(resolver));
+   * vmgr.createActivities("CodingAgent");
+   * // registers: virtualCodingAgentCreateSandbox, …
+   * ```
    */
-  createActivities(): SandboxOps<TOptions> {
-    return {
+  createActivities<S extends string>(
+    scope: S
+  ): PrefixedSandboxOps<`${TId}${Capitalize<S>}`, TOptions> {
+    const prefix = `${this.provider.id}${scope.charAt(0).toUpperCase()}${scope.slice(1)}`;
+    const ops: SandboxOps<TOptions> = {
       createSandbox: async (
         options?: TOptions
       ): Promise<{
@@ -71,6 +98,13 @@ export class SandboxManager<
       snapshotSandbox: async (sandboxId: string): Promise<SandboxSnapshot> => {
         return this.snapshot(sandboxId);
       },
+      forkSandbox: async (sandboxId: string): Promise<string> => {
+        return this.fork(sandboxId);
+      },
     };
+    const cap = (s: string): string => s.charAt(0).toUpperCase() + s.slice(1);
+    return Object.fromEntries(
+      Object.entries(ops).map(([k, v]) => [`${prefix}${cap(k)}`, v])
+    ) as PrefixedSandboxOps<`${TId}${Capitalize<S>}`, TOptions>;
   }
 }

package/src/lib/sandbox/sandbox.test.ts

@@ -1,10 +1,10 @@
 import { describe, expect, it, beforeEach } from "vitest";
 import { SandboxManager } from "./manager";
 import { InMemorySandboxProvider } from "../../adapters/sandbox/inmemory/index";
-import { SandboxNotFoundError } from "./types";
+import { SandboxNotFoundError, type Sandbox, type SandboxCreateOptions } from "./types";
 
 describe("SandboxManager", () => {
-  let manager: SandboxManager;
+  let manager: SandboxManager<SandboxCreateOptions, Sandbox, "inMemory">;
 
   beforeEach(() => {
     manager = new SandboxManager(new InMemorySandboxProvider());
@@ -54,7 +54,7 @@ describe("SandboxManager", () => {
 
     const snapshot = await manager.snapshot(sandboxId);
     expect(snapshot.sandboxId).toBe(sandboxId);
-    expect(snapshot.providerId).toBe("inmemory");
+    expect(snapshot.providerId).toBe("inMemory");
 
     await manager.destroy(sandboxId);
     await expect(manager.getSandbox(sandboxId)).rejects.toThrow(SandboxNotFoundError);
@@ -68,16 +68,17 @@ describe("SandboxManager", () => {
     expect(extra).toBe("world");
   });
 
-  it("createActivities returns SandboxOps-shaped object", async () => {
-    const activities = manager.createActivities();
-    expect(activities.createSandbox).toBeTypeOf("function");
-    expect(activities.destroySandbox).toBeTypeOf("function");
-    expect(activities.snapshotSandbox).toBeTypeOf("function");
+  it("createActivities returns prefixed SandboxOps-shaped object", async () => {
+    // provider.id is "inMemory", scope is "Test" → prefix "inMemoryTest"
+    const activities = manager.createActivities("Test");
+    expect(activities.inMemoryTestCreateSandbox).toBeTypeOf("function");
+    expect(activities.inMemoryTestDestroySandbox).toBeTypeOf("function");
+    expect(activities.inMemoryTestSnapshotSandbox).toBeTypeOf("function");
 
-    const { sandboxId } = await activities.createSandbox();
+    const { sandboxId } = await activities.inMemoryTestCreateSandbox();
     await expect(manager.getSandbox(sandboxId)).resolves.toBeTruthy();
 
-    await activities.destroySandbox(sandboxId);
+    await activities.inMemoryTestDestroySandbox(sandboxId);
     await expect(manager.getSandbox(sandboxId)).rejects.toThrow(
       SandboxNotFoundError,
     );
@@ -85,7 +86,7 @@ describe("SandboxManager", () => {
 });
 
 describe("InMemorySandboxProvider", () => {
-  let manager: SandboxManager;
+  let manager: SandboxManager<SandboxCreateOptions, Sandbox, "inMemory">;
 
   beforeEach(() => {
     manager = new SandboxManager(new InMemorySandboxProvider());

package/src/lib/sandbox/types.ts

@@ -127,6 +127,7 @@ export interface SandboxProvider<
   destroy(sandboxId: string): Promise<void>;
   snapshot(sandboxId: string): Promise<SandboxSnapshot>;
   restore(snapshot: SandboxSnapshot): Promise<Sandbox>;
+  fork(sandboxId: string): Promise<Sandbox>;
 }
 
 // ============================================================================
@@ -141,8 +142,25 @@ export interface SandboxOps<
   ): Promise<{ sandboxId: string; stateUpdate?: Record<string, unknown> }>;
   destroySandbox(sandboxId: string): Promise<void>;
   snapshotSandbox(sandboxId: string): Promise<SandboxSnapshot>;
+  forkSandbox(sandboxId: string): Promise<string>;
 }
 
+/**
+ * Maps generic {@link SandboxOps} method names to adapter-prefixed names.
+ *
+ * @example
+ * ```typescript
+ * type InMemOps = PrefixedSandboxOps<"inMemory">;
+ * // → { inMemoryCreateSandbox, inMemoryDestroySandbox, inMemorySnapshotSandbox }
+ * ```
+ */
+export type PrefixedSandboxOps<
+  TPrefix extends string,
+  TOptions extends SandboxCreateOptions = SandboxCreateOptions,
+> = {
+  [K in keyof SandboxOps<TOptions> as `${TPrefix}${Capitalize<K & string>}`]: SandboxOps<TOptions>[K];
+};
+
 // ============================================================================
 // Errors
 // ============================================================================

package/src/lib/session/index.ts

@@ -1,11 +1,9 @@
-export {
-  createSession,
-  proxyDefaultThreadOps,
-  proxySandboxOps,
-} from "./session";
+export { createSession } from "./session";
 
 export type {
   ThreadOps,
+  PrefixedThreadOps,
+  ScopedPrefix,
   SessionConfig,
   ZeitlichSession,
 } from "./types";

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

@@ -56,12 +56,11 @@ type TurnScript = {
  * Wraps every method on a ThreadOps object so it also has `.executeWithOptions()`,
  * matching Temporal's `ActivityInterfaceFor<ThreadOps>` shape.
  */
-function toActivityInterface(
-  raw: ThreadOps,
-): ActivityInterfaceFor<ThreadOps> {
+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);
+    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;
@@ -75,14 +74,14 @@ function createMockThreadOps() {
     initializeThread: async (threadId) => {
       log.push({ op: "initializeThread", args: [threadId] });
     },
-    appendHumanMessage: async (threadId, content) => {
-      log.push({ op: "appendHumanMessage", args: [threadId, content] });
+    appendHumanMessage: async (threadId, id, content) => {
+      log.push({ op: "appendHumanMessage", args: [threadId, id, content] });
     },
-    appendToolResult: async (config) => {
-      log.push({ op: "appendToolResult", args: [config] });
+    appendToolResult: async (id, config) => {
+      log.push({ op: "appendToolResult", args: [id, config] });
     },
-    appendSystemMessage: async (threadId, content) => {
-      log.push({ op: "appendSystemMessage", args: [threadId, content] });
+    appendSystemMessage: async (threadId, id, content) => {
+      log.push({ op: "appendSystemMessage", args: [threadId, id, content] });
     },
     forkThread: async (source, target) => {
       log.push({ op: "forkThread", args: [source, target] });
@@ -91,7 +90,9 @@ function createMockThreadOps() {
   return { ops, log };
 }
 
-function createScriptedRunAgent(turns: TurnScript[]): RunAgentActivity<unknown> {
+function createScriptedRunAgent(
+  turns: TurnScript[]
+): RunAgentActivity<unknown> {
   let call = 0;
   return async () => {
     const turn = turns[call++];
@@ -113,7 +114,7 @@ function createEchoTool() {
     schema: z.object({ text: z.string() }),
     handler: async (
       args: { text: string },
-      _ctx: RouterContext,
+      _ctx: RouterContext
     ): Promise<ToolHandlerResponse<{ echoed: string }>> => ({
       toolResponse: `Echo: ${args.text}`,
       data: { echoed: args.text },
@@ -216,8 +217,11 @@ describe("createSession edge cases", () => {
 
     const errorResults = log.filter((l) => {
       if (l.op !== "appendToolResult") return false;
-      const config = l.args[0] as ToolResultConfig;
-      return typeof config.content === "string" && config.content.includes("Invalid tool call");
+      const config = l.args[1] as ToolResultConfig;
+      return (
+        typeof config.content === "string" &&
+        config.content.includes("Invalid tool call")
+      );
     });
     expect(errorResults).toHaveLength(2);
   });
@@ -365,7 +369,7 @@ describe("createSession edge cases", () => {
     });
 
     await expect(session.runSession({ stateManager })).rejects.toThrow(
-      "unrecoverable tool",
+      "unrecoverable tool"
     );
     expect(endReason).toBe("failed");
   });
@@ -381,9 +385,7 @@ describe("createSession edge cases", () => {
       agentName: "TestAgent",
       threadId: "thread-1",
       metadata: { env: "test", version: 42 },
-      runAgent: createScriptedRunAgent([
-        { message: "done", toolCalls: [] },
-      ]),
+      runAgent: createScriptedRunAgent([{ message: "done", toolCalls: [] }]),
       threadOps: ops,
       buildContextMessage: () => "go",
       hooks: {
@@ -422,6 +424,7 @@ describe("createSession edge cases", () => {
         data: null,
         createdAt: new Date().toISOString(),
       }),
+      forkSandbox: async () => "forked-sandbox-id",
     };
 
     const session = await createSession({
@@ -438,7 +441,7 @@ describe("createSession edge cases", () => {
     });
 
     await expect(session.runSession({ stateManager })).rejects.toThrow(
-      "sandbox creation failed",
+      "sandbox creation failed"
     );
   });
 
@@ -462,6 +465,7 @@ describe("createSession edge cases", () => {
         data: null,
         createdAt: new Date().toISOString(),
       }),
+      forkSandbox: async () => "forked-sandbox-id",
     };
 
     const session = await createSession({
@@ -480,7 +484,7 @@ describe("createSession edge cases", () => {
     });
 
     await expect(session.runSession({ stateManager })).rejects.toThrow(
-      "LLM crash",
+      "LLM crash"
     );
 
     expect(sandboxLog).toContain("create");
@@ -505,7 +509,7 @@ describe("createSession edge cases", () => {
     });
 
     await expect(session.runSession({ stateManager })).rejects.toThrow(
-      "No system prompt in state",
+      "No system prompt in state"
     );
   });
 
@@ -700,24 +704,27 @@ describe("createSession edge cases", () => {
 
     const toolResults = log.filter((l) => l.op === "appendToolResult");
     const echoResult = toolResults.find((l) => {
-      const config = l.args[0] as ToolResultConfig;
+      const config = l.args[1] as ToolResultConfig;
       return config.toolName === "Echo";
     });
     expect(echoResult).toBeDefined();
     if (echoResult) {
-      expect((echoResult.args[0] as ToolResultConfig).content).toBe("Echo: valid");
+      expect((echoResult.args[1] as ToolResultConfig).content).toBe(
+        "Echo: valid"
+      );
     }
 
     const unknownResult = toolResults.find((l) => {
-      const config = l.args[0] as ToolResultConfig;
+      const config = l.args[1] as ToolResultConfig;
       return config.toolName === "Unknown";
     });
     expect(unknownResult).toBeDefined();
     const unknownContent = unknownResult
-      ? (unknownResult.args[0] as ToolResultConfig).content
+      ? (unknownResult.args[1] as ToolResultConfig).content
       : undefined;
     expect(
-      typeof unknownContent === "string" && unknownContent.includes("Invalid tool call"),
+      typeof unknownContent === "string" &&
+        unknownContent.includes("Invalid tool call")
     ).toBe(true);
   });
 
@@ -729,9 +736,7 @@ describe("createSession edge cases", () => {
     const session = await createSession({
       agentName: "TestAgent",
       threadId: "thread-1",
-      runAgent: createScriptedRunAgent([
-        { message: "done", toolCalls: [] },
-      ]),
+      runAgent: createScriptedRunAgent([{ message: "done", toolCalls: [] }]),
       threadOps: ops,
       buildContextMessage: () => [
         { type: "text", text: "Hello" },
@@ -749,7 +754,7 @@ describe("createSession edge cases", () => {
     expect(humanOps).toHaveLength(1);
     const humanOp = humanOps[0];
     if (!humanOp) throw new Error("expected human op");
-    const content = humanOp.args[1];
+    const content = humanOp.args[2];
     expect(Array.isArray(content)).toBe(true);
     const firstContent = (content as { type: string }[])[0];
     if (!firstContent) throw new Error("expected content item");
@@ -834,7 +839,7 @@ describe("createSession edge cases", () => {
 
     const toolResults = log.filter((l) => {
       if (l.op !== "appendToolResult") return false;
-      const config = l.args[0] as ToolResultConfig;
+      const config = l.args[1] as ToolResultConfig;
       return config.toolName === "SelfAppend";
     });
     expect(toolResults).toHaveLength(0);
@@ -860,7 +865,10 @@ describe("createSession edge cases", () => {
       buildContextMessage: () => "go",
       hooks: {
         onPreToolUse: async ({ toolCall }) => {
-          if (toolCall.args && (toolCall.args as { text: string }).text === "skip-me") {
+          if (
+            toolCall.args &&
+            (toolCall.args as { text: string }).text === "skip-me"
+          ) {
             return { skip: true };
           }
           return {};
@@ -878,8 +886,10 @@ describe("createSession edge cases", () => {
     expect(toolResults).toHaveLength(1);
     const toolResult = toolResults[0];
     if (!toolResult) throw new Error("expected tool result");
-    const content = (toolResult.args[0] as ToolResultConfig).content;
-    expect(typeof content === "string" && content.includes("Skipped")).toBe(true);
+    const content = (toolResult.args[1] as ToolResultConfig).content;
+    expect(typeof content === "string" && content.includes("Skipped")).toBe(
+      true
+    );
   });
 
   // --- Sandbox snapshot is not called on normal flow ---
@@ -897,6 +907,7 @@ describe("createSession edge cases", () => {
       createSandbox: async () => ({ sandboxId: "sb-test" }),
       destroySandbox: async () => {},
       snapshotSandbox: snapshotSpy,
+      forkSandbox: async () => "forked-sandbox-id",
     };
 
     const session = await createSession({