zeitlich 0.2.13 → 0.2.14

package/src/lib/types.ts

@@ -1,16 +1,3 @@
-import type {
-  InferToolResults,
-  ParsedToolCallUnion,
-  RawToolCall,
-  ToolCallResultUnion,
-  ToolHandlerResponse,
-  ToolMap,
-} from "./tool-router";
-import type { Skill } from "./skills/types";
-
-import type { Duration } from "@temporalio/common";
-import type { z } from "zod";
-
 // ============================================================================
 // Framework-agnostic message types
 // ============================================================================
@@ -24,6 +11,10 @@ export type MessageContent = string | ContentPart[];
 /** Content returned by a tool handler */
 export type ToolMessageContent = MessageContent;
 
+// ============================================================================
+// Agent core types
+// ============================================================================
+
 /**
  * Agent execution status
  */
@@ -74,33 +65,6 @@ export interface TokenUsage {
   reasonTokens?: number;
 }
 
-/**
- * Agent response from LLM invocation
- */
-export interface AgentResponse<M = unknown> {
-  message: M;
-  rawToolCalls: RawToolCall[];
-  usage?: TokenUsage;
-}
-
-/**
- * Thread operations required by a session.
- * Consumers provide these — typically by wrapping Temporal activities.
- */
-export interface ThreadOps {
-  /** Initialize an empty thread */
-  initializeThread(threadId: string): Promise<void>;
-  /** Append a human message to the thread */
-  appendHumanMessage(
-    threadId: string,
-    content: string | MessageContent
-  ): Promise<void>;
-  /** Append a tool result to the thread */
-  appendToolResult(config: ToolResultConfig): Promise<void>;
-  /** Append a system message to the thread */
-  appendSystemMessage(threadId: string, content: string): Promise<void>;
-}
-
 /**
  * Configuration for a Zeitlich agent
  */
@@ -111,43 +75,6 @@ export interface AgentConfig {
   description?: string;
 }
 
-/**
- * Configuration for a Zeitlich agent session
- */
-export interface SessionConfig<T extends ToolMap, M = unknown> {
-  /** The thread ID to use for the session (defaults to a short generated ID) */
-  threadId?: string;
-  /** Metadata for the session */
-  metadata?: Record<string, unknown>;
-  /** Whether to append the system prompt as message to the thread */
-  appendSystemPrompt?: boolean;
-  /** How many turns to run the session for */
-  maxTurns?: number;
-  /** Workflow-specific runAgent activity (with tools pre-bound) */
-  runAgent: RunAgentActivity<M>;
-  /** Thread operations (initialize, append messages, parse tool calls) */
-  threadOps?: ThreadOps;
-  /** Tool router for processing tool calls (optional if agent has no tools) */
-  tools?: T;
-  /** Subagent configurations */
-  subagents?: SubagentConfig[];
-  /** Skills available to this agent (metadata + instructions, loaded activity-side) */
-  skills?: Skill[];
-  /** Session lifecycle hooks */
-  hooks?: Hooks<T, ToolCallResultUnion<InferToolResults<T>>>;
-  /** Whether to process tools in parallel */
-  processToolsInParallel?: boolean;
-  /**
-   * Build context message content from agent-specific context.
-   * Returns MessageContent array for the initial HumanMessage.
-   */
-  buildContextMessage: () => MessageContent | Promise<MessageContent>;
-  /** When true, skip thread initialization and system prompt — append only the new human message to the existing thread. */
-  continueThread?: boolean;
-  /** How long to wait for input before cancelling the workflow */
-  waitForInputTimeout?: Duration;
-}
-
 /**
  * A JSON-serializable tool definition for state storage.
  * Uses a plain JSON Schema object instead of a live Zod instance,
@@ -171,13 +98,6 @@ export interface RunAgentConfig extends AgentConfig {
   metadata?: Record<string, unknown>;
 }
 
-/**
- * Type signature for workflow-specific runAgent activity
- */
-export type RunAgentActivity<M = unknown> = (
-  config: RunAgentConfig
-) => Promise<AgentResponse<M>>;
-
 /**
  * Configuration for appending a tool result
  */
@@ -190,84 +110,6 @@ export interface ToolResultConfig {
   content: ToolMessageContent;
 }
 
-// ============================================================================
-// Subagent Configuration
-// ============================================================================
-
-export type SubagentWorkflow<TResult extends z.ZodType = z.ZodType> = (
-  input: SubagentInput
-) => Promise<ToolHandlerResponse<z.infer<TResult> | null>>;
-
-/** Infer the z.infer'd result type from a SubagentConfig, or null if no schema */
-export type InferSubagentResult<T extends SubagentConfig> =
-  T extends SubagentConfig<infer S> ? z.infer<S> : null;
-
-/**
- * Configuration for a subagent that can be spawned by the parent workflow.
- *
- * @template TResult - Zod schema type for validating the child workflow's result
- */
-export interface SubagentConfig<TResult extends z.ZodType = z.ZodType> {
-  /** Identifier used in Task tool's subagent parameter */
-  agentName: string;
-  /** Description shown to the parent agent explaining what this subagent does */
-  description: string;
-  /** Whether this subagent is available (default: true). Disabled subagents are excluded from the Subagent tool. */
-  enabled?: boolean;
-  /** Temporal workflow function or type name (used with executeChild) */
-  workflow: string | SubagentWorkflow<TResult>;
-  /** Optional task queue - defaults to parent's queue if not specified */
-  taskQueue?: string;
-  /** Optional Zod schema to validate the child workflow's result. If omitted, result is passed through as-is. */
-  resultSchema?: TResult;
-  /** Optional static context passed to the subagent on every invocation */
-  context?: Record<string, unknown>;
-  /** Allow the parent agent to pass a threadId for this subagent to continue (default: false) */
-  allowThreadContinuation?: boolean;
-  /** Per-subagent lifecycle hooks */
-  hooks?: SubagentHooks;
-}
-
-/**
- * Per-subagent lifecycle hooks - defined on a SubagentConfig.
- * Runs in addition to global hooks (global pre → subagent pre → execute → subagent post → global post).
- */
-export interface SubagentHooks<TArgs = unknown, TResult = unknown> {
-  /** Called before this subagent executes - can skip or modify args */
-  onPreExecution?: (ctx: {
-    args: TArgs;
-    threadId: string;
-    turn: number;
-  }) => PreToolUseHookResult | Promise<PreToolUseHookResult>;
-  /** Called after this subagent executes successfully */
-  onPostExecution?: (ctx: {
-    args: TArgs;
-    result: TResult;
-    threadId: string;
-    turn: number;
-    durationMs: number;
-  }) => void | Promise<void>;
-  /** Called when this subagent execution fails */
-  onExecutionFailure?: (ctx: {
-    args: TArgs;
-    error: Error;
-    threadId: string;
-    turn: number;
-  }) => PostToolUseFailureHookResult | Promise<PostToolUseFailureHookResult>;
-}
-
-/**
- * Input passed to child workflows when spawned as subagents
- */
-export interface SubagentInput {
-  /** The prompt/task from the parent agent */
-  prompt: string;
-  /** Optional context parameters passed from the parent agent */
-  context?: Record<string, unknown>;
-  /** When set, the subagent should continue this thread instead of starting a new one */
-  threadId?: string;
-}
-
 // ============================================================================
 // Workflow Tasks
 // ============================================================================
@@ -300,7 +142,7 @@ export interface WorkflowTask {
 }
 
 // ============================================================================
-// Session Lifecycle Hooks
+// Session exit
 // ============================================================================
 
 /**
@@ -313,225 +155,6 @@ export type SessionExitReason =
   | "failed"
   | "cancelled";
 
-/**
- * Context for PreToolUse hook - called before tool execution
- */
-export interface PreToolUseHookContext<T extends ToolMap> {
-  /** The tool call about to be executed */
-  toolCall: ParsedToolCallUnion<T>;
-  /** Thread identifier */
-  threadId: string;
-  /** Current turn number */
-  turn: number;
-}
-
-/**
- * Result from PreToolUse hook - can block or modify execution
- */
-export interface PreToolUseHookResult {
-  /** Skip this tool call entirely */
-  skip?: boolean;
-  /** Modified args to use instead (must match schema) */
-  modifiedArgs?: unknown;
-}
-
-/**
- * PreToolUse hook - called before tool execution, can block or modify
- */
-export type PreToolUseHook<T extends ToolMap> = (
-  ctx: PreToolUseHookContext<T>
-) => PreToolUseHookResult | Promise<PreToolUseHookResult>;
-
-/**
- * Context for PostToolUse hook - called after successful tool execution
- */
-export interface PostToolUseHookContext<T extends ToolMap, TResult = unknown> {
-  /** The tool call that was executed */
-  toolCall: ParsedToolCallUnion<T>;
-  /** The result from the tool handler */
-  result: TResult;
-  /** Thread identifier */
-  threadId: string;
-  /** Current turn number */
-  turn: number;
-  /** Execution duration in milliseconds */
-  durationMs: number;
-}
-
-/**
- * PostToolUse hook - called after successful tool execution
- */
-export type PostToolUseHook<T extends ToolMap, TResult = unknown> = (
-  ctx: PostToolUseHookContext<T, TResult>
-) => void | Promise<void>;
-
-/**
- * Context for PostToolUseFailure hook - called when tool execution fails
- */
-export interface PostToolUseFailureHookContext<T extends ToolMap> {
-  /** The tool call that failed */
-  toolCall: ParsedToolCallUnion<T>;
-  /** The error that occurred */
-  error: Error;
-  /** Thread identifier */
-  threadId: string;
-  /** Current turn number */
-  turn: number;
-}
-
-/**
- * Result from PostToolUseFailure hook - can recover from errors
- */
-export interface PostToolUseFailureHookResult {
-  /** Provide a fallback result instead of throwing */
-  fallbackContent?: ToolMessageContent;
-  /** Whether to suppress the error (still logs, but continues) */
-  suppress?: boolean;
-}
-
-/**
- * PostToolUseFailure hook - called when tool execution fails
- */
-export type PostToolUseFailureHook<T extends ToolMap> = (
-  ctx: PostToolUseFailureHookContext<T>
-) => PostToolUseFailureHookResult | Promise<PostToolUseFailureHookResult>;
-
-/**
- * Context for SessionStart hook - called when session begins
- */
-export interface SessionStartHookContext {
-  /** Thread identifier */
-  threadId: string;
-  /** Name of the agent */
-  agentName: string;
-  /** Session metadata */
-  metadata: Record<string, unknown>;
-}
-
-/**
- * SessionStart hook - called when session begins
- */
-export type SessionStartHook = (
-  ctx: SessionStartHookContext
-) => void | Promise<void>;
-
-/**
- * Context for PreHumanMessageAppend hook - called before each human message is appended to the thread
- */
-export interface PreHumanMessageAppendHookContext {
-  /** The message about to be appended */
-  message: MessageContent;
-  /** Thread identifier */
-  threadId: string;
-}
-
-/**
- * PreHumanMessageAppend hook - called before each human message is appended to the thread
- */
-export type PreHumanMessageAppendHook = (
-  ctx: PreHumanMessageAppendHookContext
-) => void | Promise<void>;
-
-/**
- * PostHumanMessageAppend hook - called after each human message is appended to the thread
- */
-export type PostHumanMessageAppendHook = (
-  ctx: PostHumanMessageAppendHookContext
-) => void | Promise<void>;
-
-/**
- * Context for PostHumanMessageAppend hook - called after each human message is appended to the thread
- */
-export interface PostHumanMessageAppendHookContext {
-  /** The message that was appended */
-  message: MessageContent;
-  /** Thread identifier */
-  threadId: string;
-}
-
-/**
- * Context for SessionEnd hook - called when session ends
- */
-export interface SessionEndHookContext {
-  /** Thread identifier */
-  threadId: string;
-  /** Name of the agent */
-  agentName: string;
-  /** Reason the session ended */
-  exitReason: SessionExitReason;
-  /** Total turns executed */
-  turns: number;
-  /** Session metadata */
-  metadata: Record<string, unknown>;
-}
-
-/**
- * SessionEnd hook - called when session ends
- */
-export type SessionEndHook = (
-  ctx: SessionEndHookContext
-) => void | Promise<void>;
-
-/**
- * Per-tool lifecycle hooks - defined directly on a tool definition.
- * Runs in addition to global hooks (global pre → tool pre → execute → tool post → global post).
- */
-export interface ToolHooks<TArgs = unknown, TResult = unknown> {
-  /** Called before this tool executes - can skip or modify args */
-  onPreToolUse?: (ctx: {
-    args: TArgs;
-    threadId: string;
-    turn: number;
-  }) => PreToolUseHookResult | Promise<PreToolUseHookResult>;
-  /** Called after this tool executes successfully */
-  onPostToolUse?: (ctx: {
-    args: TArgs;
-    result: TResult;
-    threadId: string;
-    turn: number;
-    durationMs: number;
-  }) => void | Promise<void>;
-  /** Called when this tool execution fails */
-  onPostToolUseFailure?: (ctx: {
-    args: TArgs;
-    error: Error;
-    threadId: string;
-    turn: number;
-  }) => PostToolUseFailureHookResult | Promise<PostToolUseFailureHookResult>;
-}
-
-/**
- * Combined hooks interface for session lifecycle
- */
-export interface Hooks<T extends ToolMap, TResult = unknown> {
-  /** 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 before each tool execution - can block or modify */
-  onPreToolUse?: PreToolUseHook<T>;
-  /** Called after each successful tool execution */
-  onPostToolUse?: PostToolUseHook<T, TResult>;
-  /** Called when tool execution fails */
-  onPostToolUseFailure?: PostToolUseFailureHook<T>;
-  /** Called when session starts */
-  onSessionStart?: SessionStartHook;
-  /** Called when session ends */
-  onSessionEnd?: SessionEndHook;
-}
-
-// ============================================================================
-// Agent Query/Update Name Helpers
-// ============================================================================
-
-/** Derives the query name for an agent's state (usable in both workflow and activity code) */
-export const agentQueryName = (agentName: string) =>
-  `get${agentName}State` as const;
-
-/** Derives the update name for waiting on an agent's state change */
-export const agentStateChangeUpdateName = (agentName: string) =>
-  `waitFor${agentName}StateChange` as const;
-
 /**
  * Helper to check if status is terminal
  */

package/src/tools/bash/bash.test.ts

@@ -1,18 +1,35 @@
-import { dirname } from "path";
-import { fileURLToPath } from "url";
-import { describe, expect, it } from "vitest";
-import { createBashHandler } from "./handler";
-import { OverlayFs } from "just-bash";
+import { describe, expect, it, beforeEach } from "vitest";
+import { bashHandler } from "./handler";
+import { withSandbox } from "../../lib/tool-router/with-sandbox";
+import { SandboxManager } from "../../lib/sandbox/manager";
+import { InMemorySandboxProvider } from "../../adapters/sandbox/inmemory/index";
+import type { RouterContext } from "../../lib/tool-router/types";
 
-const __dirname = dirname(fileURLToPath(import.meta.url));
+describe("bash handler with sandbox", () => {
+  let manager: SandboxManager;
+  let sandboxId: string;
+  let handler: ReturnType<typeof withSandbox<Parameters<typeof bashHandler>[0], Awaited<ReturnType<typeof bashHandler>>["data"]>>;
 
-describe("bash with default options", () => {
-  const fs = new OverlayFs({ root: __dirname, mountPoint: "/home/user" });
+  beforeEach(async () => {
+    manager = new SandboxManager(new InMemorySandboxProvider());
+    const result = await manager.create({
+      initialFiles: { "/home/user/hello.txt": "world" },
+    });
+    sandboxId = result.sandboxId;
+    handler = withSandbox(manager, bashHandler);
+  });
+
+  const ctx = (id: string): RouterContext => ({
+    sandboxId: id,
+    threadId: "test-thread",
+    toolCallId: "test-call",
+    toolName: "Bash",
+  });
 
   it("executes echo and captures stdout", async () => {
-    const { data } = await createBashHandler({fs})(
+    const { data } = await handler(
       { command: "echo 'hello world'" },
-      {}
+      ctx(sandboxId)
     );
     expect(data).not.toBeNull();
     expect(data?.stdout.trim()).toBe("hello world");
@@ -20,85 +37,66 @@ describe("bash with default options", () => {
   });
 
   it("returns exit code 0 for successful commands", async () => {
-    const { data } = await createBashHandler({fs})({ command: "true" }, {});
+    const { data } = await handler({ command: "true" }, ctx(sandboxId));
     expect(data?.exitCode).toBe(0);
   });
 
   it("returns non-zero exit code for failed commands", async () => {
-    const { data } = await createBashHandler({fs})({ command: "false" }, {});
+    const { data } = await handler({ command: "false" }, ctx(sandboxId));
     expect(data?.exitCode).toBe(1);
   });
 
   it("captures stderr output", async () => {
-    const { data } = await createBashHandler({fs})(
+    const { data } = await handler(
       { command: "echo 'error message' >&2" },
-      {}
+      ctx(sandboxId)
     );
     expect(data?.stderr.trim()).toBe("error message");
     expect(data?.stdout.trim()).toBe("");
   });
 
   it("supports piping between commands", async () => {
-    const { data } = await createBashHandler({fs})(
+    const { data } = await handler(
       { command: "echo 'hello world' | tr 'a-z' 'A-Z'" },
-      {}
+      ctx(sandboxId)
     );
     expect(data?.stdout.trim()).toBe("HELLO WORLD");
   });
 
   it("supports command chaining with &&", async () => {
-    const { data } = await createBashHandler({fs})(
+    const { data } = await handler(
       { command: "echo 'first' && echo 'second'" },
-      {}
+      ctx(sandboxId)
     );
     expect(data?.stdout).toContain("first");
     expect(data?.stdout).toContain("second");
   });
 
-  it("handles multi-line output", async () => {
-    const { data } = await createBashHandler({fs})(
-      { command: "printf 'line1\\nline2\\nline3'" },
-      {}
-    );
-    const lines = data?.stdout.split("\n");
-    expect(lines).toHaveLength(3);
-    expect(lines?.[0]).toBe("line1");
-    expect(lines?.[2]).toBe("line3");
-  });
-
-  it("handles commands with arguments and flags", async () => {
-    const { data } = await createBashHandler({fs})(
-      { command: "echo -n 'no newline'" },
-      {}
-    );
-    expect(data?.stdout).toBe("no newline");
-  });
-
-  it("supports command substitution", async () => {
-    const { data } = await createBashHandler({fs})(
-      { command: "echo \"count: $(echo 'a b c' | wc -w | tr -d ' ')\"" },
-      {}
-    );
-    expect(data?.stdout.trim()).toBe("count: 3");
-  });
-
   it("returns toolResponse string with formatted output", async () => {
-    const { toolResponse } = await createBashHandler({fs})(
+    const { toolResponse } = await handler(
       { command: "echo 'test'" },
-      {}
+      ctx(sandboxId)
     );
     expect(toolResponse).toContain("Exit code: 0");
     expect(toolResponse).toContain("stdout:");
     expect(toolResponse).toContain("test");
   });
-});
 
-describe("bash with overlay filesystem", () => {
-  it("sees files in the current directory", async () => {
-    const fs = new OverlayFs({ root: __dirname, mountPoint: "/home/user" });
-    const { data } = await createBashHandler({fs})({ command: "ls" }, {});
-    expect(data?.stdout).toContain("bash.test.ts");
-    expect(data?.stdout).toContain("handler.ts");
-    expect(data?.stdout).toContain("tool.ts");
+  it("returns error when no sandboxId in context", async () => {
+    const { toolResponse, data } = await handler({ command: "echo hi" }, {
+      threadId: "test-thread",
+      toolCallId: "test-call",
+      toolName: "Bash",
+    });
+    expect(toolResponse).toContain("No sandbox configured");
+    expect(data).toBeNull();
+  });
+
+  it("can read files from the sandbox filesystem", async () => {
+    const { data } = await handler(
+      { command: "cat /home/user/hello.txt" },
+      ctx(sandboxId)
+    );
+    expect(data?.stdout).toBe("world");
   });
 });

package/src/tools/bash/handler.ts

@@ -1,58 +1,30 @@
 import type { ActivityToolHandler } from "../../lib/tool-router";
+import type { SandboxContext } from "../../lib/tool-router/with-sandbox";
 import type { BashArgs } from "./tool";
-import { Bash, type BashOptions } from "just-bash";
-
-type BashExecOut = {
-  exitCode: number;
-  stderr: string;
-  stdout: string;
-};
-
-/** BashOptions with `fs` required */
-type BashToolOptions = Required<Pick<BashOptions, "fs">> & Omit<BashOptions, "fs">;
+import type { ExecResult } from "../../lib/sandbox/types";
 
 /**
- * Creates a Bash tool handler that executes shell commands in a sandboxed environment.
+ * Bash tool handler — executes shell commands inside a {@link Sandbox}.
  *
- * @param bashOptions - Options including a required `fs` (file system implementation from `just-bash`)
- * @returns Activity tool handler for Bash tool calls
- *
- * @example
- * ```typescript
- * import { createBashHandler } from 'zeitlich';
- *
- * const bashHandlerActivity = createBashHandler({ fs: inMemoryFileSystem });
- * ```
+ * Wrap with {@link withSandbox} at activity registration time to inject the
+ * sandbox automatically.
  */
-export const createBashHandler: (
-    bashOptions: BashToolOptions,
-) => ActivityToolHandler<BashArgs, BashExecOut | null> =
-  (bashOptions: BashToolOptions) => async (args: BashArgs, _context) => {
-    const { command } = args;
-
-    const mergedOptions: BashOptions = {
-      ...bashOptions,
-      executionLimits: {
-        maxStringLength: 52428800, // 50MB default
-        ...bashOptions.executionLimits,
-      },
+export const bashHandler: ActivityToolHandler<
+  BashArgs,
+  ExecResult | null,
+  SandboxContext
+> = async (args, { sandbox }) => {
+  try {
+    const result = await sandbox.exec(args.command);
+    return {
+      toolResponse: `Exit code: ${result.exitCode}\n\nstdout:\n${result.stdout}\n\nstderr:\n${result.stderr}`,
+      data: result,
     };
-
-    const bash = new Bash(mergedOptions);
-
-    try {
-      const { exitCode, stderr, stdout } = await bash.exec(command);
-      const bashExecOut = { exitCode, stderr, stdout };
-
-      return {
-        toolResponse: `Exit code: ${exitCode}\n\nstdout:\n${stdout}\n\nstderr:\n${stderr}`,
-        data: bashExecOut,
-      };
-    } catch (error) {
-      const err = error instanceof Error ? error : new Error("Unknown error");
-      return {
-        toolResponse: `Error executing bash command: ${err.message}`,
-        data: null,
-      };
-    }
-  };
+  } catch (error) {
+    const err = error instanceof Error ? error : new Error("Unknown error");
+    return {
+      toolResponse: `Error executing bash command: ${err.message}`,
+      data: null,
+    };
+  }
+};