zeitlich 0.2.21 → 0.2.22

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

@@ -2,11 +2,20 @@ import type Redis from "ioredis";
 import type { GoogleGenAI, Content } from "@google/genai";
 import type { ToolResultConfig } from "../../../lib/types";
 import type { MessageContent } from "../../../lib/types";
-import type { ThreadOps } from "../../../lib/session/types";
+import type {
+  ThreadOps,
+  PrefixedThreadOps,
+  ScopedPrefix,
+} from "../../../lib/session/types";
 import type { ModelInvoker } from "../../../lib/model";
 import { createGoogleGenAIThreadManager } from "./thread-manager";
 import { createGoogleGenAIModelInvoker } from "./model-invoker";
 
+const ADAPTER_PREFIX = "googleGenAI" as const;
+
+export type GoogleGenAIThreadOps<TScope extends string = ""> =
+  PrefixedThreadOps<ScopedPrefix<TScope, typeof ADAPTER_PREFIX>>;
+
 export interface GoogleGenAIAdapterConfig {
   redis: Redis;
   client: GoogleGenAI;
@@ -15,21 +24,37 @@ export interface GoogleGenAIAdapterConfig {
 }
 
 export interface GoogleGenAIAdapter {
-  /** Thread operations (register these as Temporal activities on the worker) */
-  threadOps: ThreadOps;
   /** Model invoker using the default model (only available when `model` was provided) */
   invoker: ModelInvoker<Content>;
   /** Create an invoker for a specific model name (for multi-model setups) */
   createModelInvoker(model: string): ModelInvoker<Content>;
+  /**
+   * Create prefixed thread activities for registration on the worker.
+   *
+   * @param scope - Workflow name appended to the adapter prefix.
+   *   Use different scopes for the main agent vs subagents to avoid collisions.
+   *
+   * @example
+   * ```typescript
+   * adapter.createActivities("codingAgent")
+   * // → { googleGenAICodingAgentInitializeThread, googleGenAICodingAgentAppendHumanMessage, … }
+   *
+   * adapter.createActivities("researchAgent")
+   * // → { googleGenAIResearchAgentInitializeThread, … }
+   * ```
+   */
+  createActivities<S extends string = "">(
+    scope?: S
+  ): GoogleGenAIThreadOps<S>;
 }
 
 /**
  * Creates a Google GenAI adapter that bundles thread operations and model
  * invocation using the `@google/genai` SDK.
  *
- * The returned `threadOps` should be registered as Temporal activities on
- * the worker. The `invoker` (or invokers created via `createModelInvoker`)
- * should be wrapped with `createRunAgentActivity` for per-agent activities.
+ * Use `createActivities(scope)` to register scoped thread operations as
+ * Temporal activities on the worker. The `invoker` (or invokers created via
+ * `createModelInvoker`) should be wrapped with `createRunAgentActivity`.
  *
  * @example
  * ```typescript
@@ -42,27 +67,23 @@ export interface GoogleGenAIAdapter {
  *
  * export function createActivities(temporalClient: WorkflowClient) {
  *   return {
- *     ...adapter.threadOps,
- *     runAgent: createRunAgentActivity(temporalClient, adapter.invoker),
+ *     ...adapter.createActivities("codingAgent"),
+ *     runCodingAgent: createRunAgentActivity(temporalClient, adapter.invoker),
  *   };
  * }
  * ```
  *
- * @example Multi-model setup
+ * @example Multi-agent worker (main + subagent share the adapter)
  * ```typescript
- * const adapter = createGoogleGenAIAdapter({ redis, client });
- *
  * export function createActivities(temporalClient: WorkflowClient) {
  *   return {
- *     ...adapter.threadOps,
+ *     ...adapter.createActivities("codingAgent"),
+ *     ...adapter.createActivities("researchAgent"),
+ *     runCodingAgent: createRunAgentActivity(temporalClient, adapter.invoker),
  *     runResearchAgent: createRunAgentActivity(
  *       temporalClient,
  *       adapter.createModelInvoker('gemini-2.5-pro'),
  *     ),
- *     runFastAgent: createRunAgentActivity(
- *       temporalClient,
- *       adapter.createModelInvoker('gemini-2.5-flash'),
- *     ),
  *   };
  * }
  * ```
@@ -114,6 +135,19 @@ export function createGoogleGenAIAdapter(
     },
   };
 
+  function createActivities<S extends string = "">(
+    scope?: S
+  ): GoogleGenAIThreadOps<S> {
+    const prefix = scope
+      ? `${ADAPTER_PREFIX}${scope.charAt(0).toUpperCase()}${scope.slice(1)}`
+      : ADAPTER_PREFIX;
+    const cap = (s: string): string =>
+      s.charAt(0).toUpperCase() + s.slice(1);
+    return Object.fromEntries(
+      Object.entries(threadOps).map(([k, v]) => [`${prefix}${cap(k)}`, v])
+    ) as GoogleGenAIThreadOps<S>;
+  }
+
   const makeInvoker = (model: string): ModelInvoker<Content> =>
     createGoogleGenAIModelInvoker({ redis, client, model });
 
@@ -127,7 +161,7 @@ export function createGoogleGenAIAdapter(
       }) as unknown as ModelInvoker<Content>);
 
   return {
-    threadOps,
+    createActivities,
     invoker,
     createModelInvoker: makeInvoker,
   };

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

@@ -22,6 +22,7 @@ export {
   createGoogleGenAIAdapter,
   type GoogleGenAIAdapter,
   type GoogleGenAIAdapterConfig,
+  type GoogleGenAIThreadOps,
 } from "./activities";
 
 // Thread manager

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

@@ -0,0 +1,61 @@
+/**
+ * Workflow-safe proxy for Google GenAI thread operations.
+ *
+ * Import this from `zeitlich/adapters/thread/google-genai/workflow`
+ * in your Temporal workflow files.
+ *
+ * By default the scope is derived from `workflowInfo().workflowType`,
+ * so activities are automatically namespaced per workflow.
+ *
+ * @example
+ * ```typescript
+ * import { proxyGoogleGenAIThreadOps } from 'zeitlich/adapters/thread/google-genai/workflow';
+ *
+ * // Auto-scoped to the current workflow name
+ * const threadOps = proxyGoogleGenAIThreadOps();
+ *
+ * // Explicit scope override
+ * const threadOps = proxyGoogleGenAIThreadOps("customScope");
+ * ```
+ */
+import {
+  proxyActivities,
+  workflowInfo,
+  type ActivityInterfaceFor,
+} from "@temporalio/workflow";
+import type { ThreadOps } from "../../../lib/session/types";
+
+const ADAPTER_PREFIX = "googleGenAI";
+
+export function proxyGoogleGenAIThreadOps(
+  scope?: string,
+  options?: Parameters<typeof proxyActivities>[0]
+): ActivityInterfaceFor<ThreadOps> {
+  const resolvedScope = scope ?? workflowInfo().workflowType;
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const acts = proxyActivities<Record<string, (...args: any[]) => any>>(
+    options ?? {
+      startToCloseTimeout: "10s",
+      retry: {
+        maximumAttempts: 6,
+        initialInterval: "5s",
+        maximumInterval: "15m",
+        backoffCoefficient: 4,
+      },
+    }
+  );
+
+  const prefix =
+    `${ADAPTER_PREFIX}${resolvedScope.charAt(0).toUpperCase()}${resolvedScope.slice(1)}`;
+  const p = (key: string): string =>
+    `${prefix}${key.charAt(0).toUpperCase()}${key.slice(1)}`;
+
+  return {
+    initializeThread: acts[p("initializeThread")],
+    appendHumanMessage: acts[p("appendHumanMessage")],
+    appendToolResult: acts[p("appendToolResult")],
+    appendSystemMessage: acts[p("appendSystemMessage")],
+    forkThread: acts[p("forkThread")],
+  } as ActivityInterfaceFor<ThreadOps>;
+}

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

@@ -1,13 +1,22 @@
 import type Redis from "ioredis";
 import type { ToolResultConfig } from "../../../lib/types";
 import type { MessageContent } from "@langchain/core/messages";
-import type { ThreadOps } from "../../../lib/session/types";
+import type {
+  ThreadOps,
+  PrefixedThreadOps,
+  ScopedPrefix,
+} from "../../../lib/session/types";
 import type { ModelInvoker } from "../../../lib/model";
 import type { StoredMessage } from "@langchain/core/messages";
 import type { BaseChatModel } from "@langchain/core/language_models/chat_models";
 import { createLangChainThreadManager } from "./thread-manager";
 import { createLangChainModelInvoker } from "./model-invoker";
 
+const ADAPTER_PREFIX = "langChain" as const;
+
+export type LangChainThreadOps<TScope extends string = ""> =
+  PrefixedThreadOps<ScopedPrefix<TScope, typeof ADAPTER_PREFIX>>;
+
 export interface LangChainAdapterConfig {
   redis: Redis;
   /** Optional default model — if omitted, use `createModelInvoker()` to create invokers later */
@@ -16,22 +25,34 @@ export interface LangChainAdapterConfig {
 }
 
 export interface LangChainAdapter {
-  /** Thread operations (register these as Temporal activities on the worker) */
-  threadOps: ThreadOps;
   /** Model invoker using the default model (only available when `model` was provided) */
   invoker: ModelInvoker<StoredMessage>;
   /** Create an invoker for a specific model (for multi-model setups) */
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   createModelInvoker(model: BaseChatModel<any>): ModelInvoker<StoredMessage>;
+  /**
+   * Create prefixed thread activities for registration on the worker.
+   *
+   * @param scope - Workflow name appended to the adapter prefix.
+   *
+   * @example
+   * ```typescript
+   * adapter.createActivities("codingAgent")
+   * // → { langChainCodingAgentInitializeThread, langChainCodingAgentAppendHumanMessage, … }
+   * ```
+   */
+  createActivities<S extends string = "">(
+    scope?: S
+  ): LangChainThreadOps<S>;
 }
 
 /**
  * Creates a LangChain adapter that bundles thread operations and model
  * invocation using a consistent message format (StoredMessage).
  *
- * The returned `threadOps` should be registered as Temporal activities on
- * the worker. The `invoker` (or invokers created via `createModelInvoker`)
- * should be wrapped with `createRunAgentActivity` for per-agent activities.
+ * Use `createActivities(scope)` to register scoped thread operations as
+ * Temporal activities on the worker. The `invoker` (or invokers created via
+ * `createModelInvoker`) should be wrapped with `createRunAgentActivity`.
  *
  * @example
  * ```typescript
@@ -42,21 +63,20 @@ export interface LangChainAdapter {
  *
  * export function createActivities(client: WorkflowClient) {
  *   return {
- *     ...adapter.threadOps,
- *     runAgent: createRunAgentActivity(client, adapter.invoker),
+ *     ...adapter.createActivities("codingAgent"),
+ *     runCodingAgent: createRunAgentActivity(client, adapter.invoker),
  *   };
  * }
  * ```
  *
- * @example Multi-model setup
+ * @example Multi-agent worker
  * ```typescript
- * const adapter = createLangChainAdapter({ redis });
- *
  * export function createActivities(client: WorkflowClient) {
  *   return {
- *     ...adapter.threadOps,
+ *     ...adapter.createActivities("codingAgent"),
+ *     ...adapter.createActivities("researchAgent"),
+ *     runCodingAgent: createRunAgentActivity(client, adapter.invoker),
  *     runResearchAgent: createRunAgentActivity(client, adapter.createModelInvoker(claude)),
- *     runWriterAgent: createRunAgentActivity(client, adapter.createModelInvoker(gpt4)),
  *   };
  * }
  * ```
@@ -108,6 +128,19 @@ export function createLangChainAdapter(
     },
   };
 
+  function createActivities<S extends string = "">(
+    scope?: S
+  ): LangChainThreadOps<S> {
+    const prefix = scope
+      ? `${ADAPTER_PREFIX}${scope.charAt(0).toUpperCase()}${scope.slice(1)}`
+      : ADAPTER_PREFIX;
+    const cap = (s: string): string =>
+      s.charAt(0).toUpperCase() + s.slice(1);
+    return Object.fromEntries(
+      Object.entries(threadOps).map(([k, v]) => [`${prefix}${cap(k)}`, v])
+    ) as LangChainThreadOps<S>;
+  }
+
   const makeInvoker = (
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     model: BaseChatModel<any>
@@ -124,7 +157,7 @@ export function createLangChainAdapter(
       };
 
   return {
-    threadOps,
+    createActivities,
     invoker,
     createModelInvoker: makeInvoker,
   };

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

@@ -20,6 +20,7 @@ export {
   createLangChainAdapter,
   type LangChainAdapter,
   type LangChainAdapterConfig,
+  type LangChainThreadOps,
 } from "./activities";
 
 // Thread manager

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

@@ -0,0 +1,61 @@
+/**
+ * Workflow-safe proxy for LangChain thread operations.
+ *
+ * Import this from `zeitlich/adapters/thread/langchain/workflow`
+ * in your Temporal workflow files.
+ *
+ * By default the scope is derived from `workflowInfo().workflowType`,
+ * so activities are automatically namespaced per workflow.
+ *
+ * @example
+ * ```typescript
+ * import { proxyLangChainThreadOps } from 'zeitlich/adapters/thread/langchain/workflow';
+ *
+ * // Auto-scoped to the current workflow name
+ * const threadOps = proxyLangChainThreadOps();
+ *
+ * // Explicit scope override
+ * const threadOps = proxyLangChainThreadOps("customScope");
+ * ```
+ */
+import {
+  proxyActivities,
+  workflowInfo,
+  type ActivityInterfaceFor,
+} from "@temporalio/workflow";
+import type { ThreadOps } from "../../../lib/session/types";
+
+const ADAPTER_PREFIX = "langChain";
+
+export function proxyLangChainThreadOps(
+  scope?: string,
+  options?: Parameters<typeof proxyActivities>[0]
+): ActivityInterfaceFor<ThreadOps> {
+  const resolvedScope = scope ?? workflowInfo().workflowType;
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const acts = proxyActivities<Record<string, (...args: any[]) => any>>(
+    options ?? {
+      startToCloseTimeout: "10s",
+      retry: {
+        maximumAttempts: 6,
+        initialInterval: "5s",
+        maximumInterval: "15m",
+        backoffCoefficient: 4,
+      },
+    }
+  );
+
+  const prefix =
+    `${ADAPTER_PREFIX}${resolvedScope.charAt(0).toUpperCase()}${resolvedScope.slice(1)}`;
+  const p = (key: string): string =>
+    `${prefix}${key.charAt(0).toUpperCase()}${key.slice(1)}`;
+
+  return {
+    initializeThread: acts[p("initializeThread")],
+    appendHumanMessage: acts[p("appendHumanMessage")],
+    appendToolResult: acts[p("appendToolResult")],
+    appendSystemMessage: acts[p("appendSystemMessage")],
+    forkThread: acts[p("forkThread")],
+  } as ActivityInterfaceFor<ThreadOps>;
+}

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