zeitlich 0.2.13 → 0.2.14

package/src/adapters/{langchain → thread/langchain}/model-invoker.ts

@@ -1,19 +1,16 @@
 import type Redis from "ioredis";
-import type { AgentResponse } from "../../lib/types";
-import type { ModelInvokerConfig } from "../../lib/model-invoker";
+import type { AgentResponse } from "../../../lib/model";
+import type { ModelInvokerConfig } from "../../../lib/model";
 import { mapStoredMessagesToChatMessages } from "@langchain/core/messages";
 import type { StoredMessage } from "@langchain/core/messages";
 import { v4 as uuidv4 } from "uuid";
-import type {
-  BaseChatModel,
-  BaseChatModelCallOptions,
-  BindToolsInput,
-} from "@langchain/core/language_models/chat_models";
+import type { BaseChatModel } from "@langchain/core/language_models/chat_models";
 import { createLangChainThreadManager } from "./thread-manager";
 
-export interface LangChainModelInvokerConfig {
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export interface LangChainModelInvokerConfig<TModel extends BaseChatModel<any> = BaseChatModel<any>> {
   redis: Redis;
-  model: BaseChatModel<BaseChatModelCallOptions & { tools?: BindToolsInput }>;
+  model: TModel;
 }
 
 /**
@@ -25,21 +22,20 @@ export interface LangChainModelInvokerConfig {
  *
  * @example
  * ```typescript
- * import { createLangChainModelInvoker } from 'zeitlich/adapters/langchain';
+ * import { createLangChainModelInvoker } from 'zeitlich/adapters/thread/langchain';
  * import { createRunAgentActivity } from 'zeitlich';
  * import { ChatAnthropic } from '@langchain/anthropic';
  *
  * const model = new ChatAnthropic({ model: "claude-sonnet-4-6" });
  * const invoker = createLangChainModelInvoker({ redis, model });
  *
- * // Wrap with createRunAgentActivity to use as runAgent activity:
  * return { runAgent: createRunAgentActivity(client, invoker) };
  * ```
  */
-export function createLangChainModelInvoker({
-  redis,
-  model,
-}: LangChainModelInvokerConfig) {
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function createLangChainModelInvoker<TModel extends BaseChatModel<any> = BaseChatModel<any>>(
+  { redis, model }: LangChainModelInvokerConfig<TModel>,
+) {
   return async function invokeLangChainModel(
     config: ModelInvokerConfig
   ): Promise<AgentResponse<StoredMessage>> {
@@ -54,7 +50,7 @@ export function createLangChainModelInvoker({
       {
         runName: agentName,
         runId,
-        metadata: { thread_id: threadId, ...metadata },
+        metadata: { thread_id: `${agentName}-${threadId}`, ...metadata },
         tools: state.tools,
       }
     );
@@ -88,14 +84,15 @@ export function createLangChainModelInvoker({
  * Convenience wrapper around createLangChainModelInvoker for cases where
  * you don't need to reuse the invoker.
  */
-export async function invokeLangChainModel({
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export async function invokeLangChainModel<TModel extends BaseChatModel<any> = BaseChatModel<any>>({
   redis,
   model,
   config,
 }: {
   redis: Redis;
   config: ModelInvokerConfig;
-  model: BaseChatModel<BaseChatModelCallOptions & { tools?: BindToolsInput }>;
+  model: TModel;
 }): Promise<AgentResponse<StoredMessage>> {
   const invoker = createLangChainModelInvoker({ redis, model });
   return invoker(config);

package/src/adapters/{langchain → thread/langchain}/thread-manager.ts

@@ -14,7 +14,7 @@ import {
   createThreadManager,
   type BaseThreadManager,
   type ThreadManagerConfig,
-} from "../../lib/thread-manager";
+} from "../../../lib/thread";
 
 export type LangChainToolMessageContent = $InferMessageContent<
   MessageStructure,

package/src/index.ts

@@ -3,20 +3,25 @@
  *
  * Import from `zeitlich` in activity files and worker setup.
  * For LangChain-specific adapters (model invoker, thread manager, adapter),
- * import from `zeitlich/adapters/langchain`.
+ * import from `zeitlich/adapters/thread/langchain`.
  * For workflow code, use `zeitlich/workflow` instead.
  *
  * @example
  * ```typescript
  * // In your activities file
  * import {
- *   createBashHandler,
- *   createAskUserQuestionHandler,
+ *   SandboxManager,
+ *   withSandbox,
+ *   bashHandler,
+ *   editHandler,
  *   toTree,
  * } from 'zeitlich';
  *
+ * // In-memory sandbox adapter
+ * import { InMemorySandboxProvider } from 'zeitlich/adapters/sandbox/inmemory';
+ *
  * // LangChain adapter
- * import { createLangChainAdapter } from 'zeitlich/adapters/langchain';
+ * import { createLangChainAdapter } from 'zeitlich/adapters/thread/langchain';
  * ```
  */
 
@@ -24,34 +29,37 @@
 // (Activities can use these too)
 export * from "./workflow";
 
+// Skills (activity-side: filesystem provider uses node:path)
+export { FileSystemSkillProvider } from "./lib/skills/fs-provider";
+
 // Thread manager (generic, framework-agnostic)
-export { createThreadManager } from "./lib/thread-manager";
-export type {
-  BaseThreadManager,
-  ThreadManagerConfig,
-} from "./lib/thread-manager";
+export { createThreadManager } from "./lib/thread";
+export type { BaseThreadManager, ThreadManagerConfig } from "./lib/thread";
 
 // Model invoker contract (framework-agnostic)
-export type { ModelInvoker, ModelInvokerConfig } from "./lib/model-invoker";
+export type { ModelInvoker, ModelInvokerConfig } from "./lib/model";
 
-// Auto-append wrapper for large tool results (activity-side only)
-export { withAutoAppend } from "./lib/tool-router";
+// Activity-side handler wrappers
+export { withAutoAppend, withSandbox } from "./lib/tool-router";
+export type { SandboxContext } from "./lib/tool-router";
 
-// Workflow state helpers (requires Temporal client)
+// Activity-side wrappers (requires Temporal client)
 export {
   queryParentWorkflowState,
   createRunAgentActivity,
-} from "./lib/workflow-helpers";
-
-// Tool handlers (activity implementations)
-// All handlers follow the factory pattern: createXHandler(deps) => handler(args)
-export { createGlobHandler } from "./tools/glob/handler";
-
-export { createEditHandler } from "./tools/edit/handler";
+  withParentWorkflowState,
+} from "./lib/activity";
+export type { AgentStateContext } from "./lib/activity";
 
-export { createBashHandler } from "./tools/bash/handler";
+// Sandbox (activity-side: manager)
+export { SandboxManager } from "./lib/sandbox/manager";
 
-export { toTree } from "./lib/fs";
+// Tool handlers (activity implementations)
+// Wrap sandbox handlers with withSandbox(manager, handler) at registration time
+export { bashHandler } from "./tools/bash/handler";
+export { editHandler } from "./tools/edit/handler";
+export { globHandler } from "./tools/glob/handler";
+export { readFileHandler } from "./tools/read-file/handler";
+export { writeFileHandler } from "./tools/write-file/handler";
 
-// Skills (activity-side: filesystem provider)
-export { FileSystemSkillProvider } from "./lib/skills/fs-provider";
+export { toTree } from "./lib/sandbox";

package/src/lib/activity.ts

@@ -0,0 +1,87 @@
+import { Context } from "@temporalio/activity";
+import type { WorkflowClient } from "@temporalio/client";
+import type { BaseAgentState, RunAgentConfig } from "./types";
+import type {
+  ActivityToolHandler,
+  RouterContext,
+  ToolHandlerResponse,
+} from "./tool-router/types";
+
+/**
+ * Query the parent workflow's state from within an activity.
+ * Resolves the workflow handle from the current activity context.
+ */
+export async function queryParentWorkflowState<T>(
+  client: WorkflowClient
+): Promise<T> {
+  const { workflowExecution } = Context.current().info;
+  const handle = client.getHandle(
+    workflowExecution.workflowId,
+    workflowExecution.runId
+  );
+  return handle.query<T>("getAgentState");
+}
+
+/**
+ * Wraps a handler into a `RunAgentActivity` by auto-fetching the parent
+ * workflow's agent state before each invocation.
+ *
+ * @example
+ * ```typescript
+ * import { createRunAgentActivity } from 'zeitlich';
+ * import { createLangChainModelInvoker } from 'zeitlich/adapters/thread/langchain';
+ *
+ * const invoker = createLangChainModelInvoker({ redis, model });
+ * return { runAgent: createRunAgentActivity(client, invoker) };
+ * ```
+ */
+export function createRunAgentActivity<R, S extends BaseAgentState = BaseAgentState>(
+  client: WorkflowClient,
+  handler: (config: RunAgentConfig & { state: S }) => Promise<R>,
+): (config: RunAgentConfig) => Promise<R> {
+  return async (config: RunAgentConfig) => {
+    const state = await queryParentWorkflowState<S>(client);
+    return handler({ ...config, state });
+  };
+}
+
+/**
+ * Context injected into tool handlers created via {@link withParentWorkflowState}.
+ */
+export interface AgentStateContext<S extends BaseAgentState = BaseAgentState> extends RouterContext {
+  state: S;
+}
+
+/**
+ * Wraps a tool handler into an `ActivityToolHandler` by auto-fetching the
+ * parent workflow's agent state before each invocation.
+ *
+ * @typeParam S - Custom agent state type (defaults to `BaseAgentState`)
+ *
+ * @example
+ * ```typescript
+ * import { withParentWorkflowState, type AgentStateContext } from 'zeitlich';
+ *
+ * // With custom state:
+ * interface MyState extends BaseAgentState { customField: string }
+ * const myHandler = withParentWorkflowState<MyArgs, MyResult, MyState>(
+ *   client,
+ *   async (args, ctx) => {
+ *     console.log(ctx.state.customField);
+ *     return { toolResponse: 'done', data: null };
+ *   },
+ * );
+ * ```
+ */
+export function withParentWorkflowState<TArgs, TResult, S extends BaseAgentState = BaseAgentState>(
+  client: WorkflowClient,
+  handler: (
+    args: TArgs,
+    context: AgentStateContext<S>,
+  ) => Promise<ToolHandlerResponse<TResult>>,
+): ActivityToolHandler<TArgs, TResult> {
+  return async (args, context) => {
+    const state = await queryParentWorkflowState<S>(client);
+    return handler(args, { ...context, state });
+  };
+}

package/src/lib/hooks/index.ts

@@ -0,0 +1,11 @@
+export type {
+  SessionStartHookContext,
+  SessionStartHook,
+  SessionEndHookContext,
+  SessionEndHook,
+  PreHumanMessageAppendHookContext,
+  PreHumanMessageAppendHook,
+  PostHumanMessageAppendHookContext,
+  PostHumanMessageAppendHook,
+  Hooks,
+} from "./types";

package/src/lib/hooks/types.ts

@@ -0,0 +1,98 @@
+import type { MessageContent, SessionExitReason } from "../types";
+import type {
+  ToolMap,
+  ToolRouterHooks,
+} from "../tool-router/types";
+
+// ============================================================================
+// Session Lifecycle Hooks
+// ============================================================================
+
+/**
+ * Context for SessionStart hook - called when session begins
+ */
+export interface SessionStartHookContext {
+  threadId: string;
+  agentName: string;
+  metadata: Record<string, unknown>;
+}
+
+/**
+ * SessionStart hook - called when session begins
+ */
+export type SessionStartHook = (
+  ctx: SessionStartHookContext
+) => void | Promise<void>;
+
+/**
+ * Context for SessionEnd hook - called when session ends
+ */
+export interface SessionEndHookContext {
+  threadId: string;
+  agentName: string;
+  exitReason: SessionExitReason;
+  turns: number;
+  metadata: Record<string, unknown>;
+}
+
+/**
+ * SessionEnd hook - called when session ends
+ */
+export type SessionEndHook = (
+  ctx: SessionEndHookContext
+) => void | Promise<void>;
+
+// ============================================================================
+// Message Lifecycle Hooks
+// ============================================================================
+
+/**
+ * Context for PreHumanMessageAppend hook - called before each human message is appended to the thread
+ */
+export interface PreHumanMessageAppendHookContext {
+  message: MessageContent;
+  threadId: string;
+}
+
+/**
+ * PreHumanMessageAppend hook - called before each human message is appended to the thread
+ */
+export type PreHumanMessageAppendHook = (
+  ctx: PreHumanMessageAppendHookContext
+) => void | Promise<void>;
+
+/**
+ * Context for PostHumanMessageAppend hook - called after each human message is appended to the thread
+ */
+export interface PostHumanMessageAppendHookContext {
+  message: MessageContent;
+  threadId: string;
+}
+
+/**
+ * PostHumanMessageAppend hook - called after each human message is appended to the thread
+ */
+export type PostHumanMessageAppendHook = (
+  ctx: PostHumanMessageAppendHookContext
+) => void | Promise<void>;
+
+// ============================================================================
+// Combined Hooks Interface
+// ============================================================================
+
+/**
+ * Full hooks interface for a session — combines tool execution hooks
+ * (consumed by the router) with session/message lifecycle hooks
+ * (consumed directly by the session).
+ */
+export interface Hooks<T extends ToolMap, TResult = unknown>
+  extends ToolRouterHooks<T, TResult> {
+  /** Called before each human message is appended to the thread */
+  onPreHumanMessageAppend?: PreHumanMessageAppendHook;
+  /** Called after each human message is appended to the thread */
+  onPostHumanMessageAppend?: PostHumanMessageAppendHook;
+  /** Called when session starts */
+  onSessionStart?: SessionStartHook;
+  /** Called when session ends */
+  onSessionEnd?: SessionEndHook;
+}

package/src/lib/model/helpers.ts

@@ -0,0 +1,6 @@
+export {
+  queryParentWorkflowState,
+  createRunAgentActivity,
+  withParentWorkflowState,
+} from "../activity";
+export type { AgentStateContext } from "../activity";

package/src/lib/model/index.ts

@@ -0,0 +1,13 @@
+export {
+  queryParentWorkflowState,
+  createRunAgentActivity,
+  withParentWorkflowState,
+} from "./helpers";
+export type { AgentStateContext } from "./helpers";
+
+export type {
+  AgentResponse,
+  RunAgentActivity,
+  ModelInvokerConfig,
+  ModelInvoker,
+} from "./types";

package/src/lib/{model-invoker.ts → model/types.ts}

@@ -1,4 +1,21 @@
-import type { AgentResponse, BaseAgentState } from "./types";
+import type { TokenUsage, BaseAgentState, RunAgentConfig } from "../types";
+import type { RawToolCall } from "../tool-router/types";
+
+/**
+ * Agent response from LLM invocation
+ */
+export interface AgentResponse<M = unknown> {
+  message: M;
+  rawToolCalls: RawToolCall[];
+  usage?: TokenUsage;
+}
+
+/**
+ * Type signature for workflow-specific runAgent activity
+ */
+export type RunAgentActivity<M = unknown> = (
+  config: RunAgentConfig
+) => Promise<AgentResponse<M>>;
 
 /**
  * Configuration passed to a ModelInvoker.

package/src/lib/sandbox/index.ts

@@ -0,0 +1,19 @@
+export { SandboxManager } from "./manager";
+export { toTree } from "./tree";
+export type {
+  Sandbox,
+  SandboxCapabilities,
+  SandboxCreateOptions,
+  SandboxFileSystem,
+  SandboxOps,
+  SandboxProvider,
+  SandboxSnapshot,
+  ExecOptions,
+  ExecResult,
+  DirentEntry,
+  FileStat,
+} from "./types";
+export {
+  SandboxNotFoundError,
+  SandboxNotSupportedError,
+} from "./types";

package/src/lib/sandbox/manager.ts

@@ -0,0 +1,76 @@
+import type {
+  Sandbox,
+  SandboxCreateOptions,
+  SandboxOps,
+  SandboxProvider,
+  SandboxSnapshot,
+} from "./types";
+
+/**
+ * Stateless facade over a {@link SandboxProvider}.
+ *
+ * Delegates all lifecycle operations to the provider, which is responsible
+ * for its own instance management strategy (e.g. in-memory map, remote API).
+ *
+ * @example
+ * ```typescript
+ * const manager = new SandboxManager(new InMemorySandboxProvider());
+ * const activities = {
+ *   ...manager.createActivities(),
+ *   bashHandler: withSandbox(manager, bashHandler),
+ * };
+ * ```
+ */
+export class SandboxManager<
+  TOptions extends SandboxCreateOptions = SandboxCreateOptions,
+  TSandbox extends Sandbox = Sandbox,
+> {
+  constructor(private provider: SandboxProvider<TOptions, TSandbox>) {}
+
+  async create(
+    options?: TOptions
+  ): Promise<{ sandboxId: string; stateUpdate?: Record<string, unknown> }> {
+    const { sandbox, stateUpdate } = await this.provider.create(options);
+    return { sandboxId: sandbox.id, ...(stateUpdate && { stateUpdate }) };
+  }
+
+  async getSandbox(id: string): Promise<TSandbox> {
+    return this.provider.get(id);
+  }
+
+  async destroy(id: string): Promise<void> {
+    await this.provider.destroy(id);
+  }
+
+  async snapshot(id: string): Promise<SandboxSnapshot> {
+    return this.provider.snapshot(id);
+  }
+
+  async restore(snapshot: SandboxSnapshot): Promise<string> {
+    const sandbox = await this.provider.restore(snapshot);
+    return sandbox.id;
+  }
+
+  /**
+   * Returns Temporal activity functions matching {@link SandboxOps}.
+   * Spread these into your worker's activity map.
+   */
+  createActivities(): SandboxOps<TOptions> {
+    return {
+      createSandbox: async (
+        options?: TOptions
+      ): Promise<{
+        sandboxId: string;
+        stateUpdate?: Record<string, unknown>;
+      }> => {
+        return this.create(options);
+      },
+      destroySandbox: async (sandboxId: string): Promise<void> => {
+        await this.destroy(sandboxId);
+      },
+      snapshotSandbox: async (sandboxId: string): Promise<SandboxSnapshot> => {
+        return this.snapshot(sandboxId);
+      },
+    };
+  }
+}

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

@@ -0,0 +1,158 @@
+import { describe, expect, it, beforeEach } from "vitest";
+import { SandboxManager } from "./manager";
+import { InMemorySandboxProvider } from "../../adapters/sandbox/inmemory/index";
+import { SandboxNotFoundError } from "./types";
+
+describe("SandboxManager", () => {
+  let manager: SandboxManager;
+
+  beforeEach(() => {
+    manager = new SandboxManager(new InMemorySandboxProvider());
+  });
+
+  it("creates a sandbox and returns an id", async () => {
+    const { sandboxId } = await manager.create();
+    expect(sandboxId).toBeTruthy();
+    const sandbox = await manager.getSandbox(sandboxId);
+    expect(sandbox.id).toBe(sandboxId);
+  });
+
+  it("creates a sandbox with a custom id", async () => {
+    const { sandboxId } = await manager.create({ id: "my-sandbox" });
+    expect(sandboxId).toBe("my-sandbox");
+  });
+
+  it("gets an existing sandbox", async () => {
+    const { sandboxId } = await manager.create();
+    const sandbox = await manager.getSandbox(sandboxId);
+    expect(sandbox.id).toBe(sandboxId);
+  });
+
+  it("throws SandboxNotFoundError for unknown id", async () => {
+    await expect(manager.getSandbox("nonexistent")).rejects.toThrow(
+      SandboxNotFoundError,
+    );
+  });
+
+  it("destroys a sandbox", async () => {
+    const { sandboxId } = await manager.create();
+    await manager.getSandbox(sandboxId);
+    await manager.destroy(sandboxId);
+    await expect(manager.getSandbox(sandboxId)).rejects.toThrow(SandboxNotFoundError);
+  });
+
+  it("destroy is idempotent for unknown ids", async () => {
+    await expect(manager.destroy("nonexistent")).resolves.not.toThrow();
+  });
+
+  it("snapshots and restores a sandbox", async () => {
+    const { sandboxId } = await manager.create({
+      initialFiles: { "/data.txt": "hello" },
+    });
+    const sandbox = await manager.getSandbox(sandboxId);
+    await sandbox.fs.writeFile("/extra.txt", "world");
+
+    const snapshot = await manager.snapshot(sandboxId);
+    expect(snapshot.sandboxId).toBe(sandboxId);
+    expect(snapshot.providerId).toBe("inmemory");
+
+    await manager.destroy(sandboxId);
+    await expect(manager.getSandbox(sandboxId)).rejects.toThrow(SandboxNotFoundError);
+
+    const restoredId = await manager.restore(snapshot);
+    expect(restoredId).toBe(sandboxId);
+    const restored = await manager.getSandbox(restoredId);
+    const content = await restored.fs.readFile("/data.txt");
+    expect(content).toBe("hello");
+    const extra = await restored.fs.readFile("/extra.txt");
+    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");
+
+    const { sandboxId } = await activities.createSandbox();
+    await expect(manager.getSandbox(sandboxId)).resolves.toBeTruthy();
+
+    await activities.destroySandbox(sandboxId);
+    await expect(manager.getSandbox(sandboxId)).rejects.toThrow(
+      SandboxNotFoundError,
+    );
+  });
+});
+
+describe("InMemorySandboxProvider", () => {
+  let manager: SandboxManager;
+
+  beforeEach(() => {
+    manager = new SandboxManager(new InMemorySandboxProvider());
+  });
+
+  it("creates sandbox with initial files", async () => {
+    const { sandboxId } = await manager.create({
+      initialFiles: {
+        "/src/index.ts": 'console.log("hello");',
+        "/README.md": "# Hello",
+      },
+    });
+    const sandbox = await manager.getSandbox(sandboxId);
+    const content = await sandbox.fs.readFile("/src/index.ts");
+    expect(content).toBe('console.log("hello");');
+  });
+
+  it("supports filesystem operations", async () => {
+    const { sandboxId } = await manager.create();
+    const { fs } = await manager.getSandbox(sandboxId);
+
+    await fs.writeFile("/test.txt", "hello");
+    expect(await fs.exists("/test.txt")).toBe(true);
+    expect(await fs.readFile("/test.txt")).toBe("hello");
+
+    await fs.appendFile("/test.txt", " world");
+    expect(await fs.readFile("/test.txt")).toBe("hello world");
+
+    await fs.mkdir("/mydir", { recursive: true });
+    expect(await fs.exists("/mydir")).toBe(true);
+
+    const stat = await fs.stat("/test.txt");
+    expect(stat.isFile).toBe(true);
+    expect(stat.isDirectory).toBe(false);
+  });
+
+  it("supports shell execution", async () => {
+    const { sandboxId } = await manager.create({
+      initialFiles: { "/data.txt": "hello world" },
+    });
+    const sandbox = await manager.getSandbox(sandboxId);
+
+    const result = await sandbox.exec("cat /data.txt");
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toBe("hello world");
+  });
+
+  it("reports correct capabilities", async () => {
+    const { sandboxId } = await manager.create();
+    const sandbox = await manager.getSandbox(sandboxId);
+    expect(sandbox.capabilities).toEqual({
+      filesystem: true,
+      execution: true,
+      persistence: true,
+    });
+  });
+
+  it("readdirWithFileTypes works", async () => {
+    const { sandboxId } = await manager.create({
+      initialFiles: {
+        "/dir/a.txt": "a",
+        "/dir/b.txt": "b",
+      },
+    });
+    const { fs } = await manager.getSandbox(sandboxId);
+    const entries = await fs.readdirWithFileTypes("/dir");
+    expect(entries.length).toBe(2);
+    expect(entries.every((e) => e.isFile)).toBe(true);
+  });
+});