zeitlich 0.2.13 → 0.2.14

package/src/lib/{fs.ts → sandbox/tree.ts}

@@ -1,4 +1,4 @@
-import type { IFileSystem } from "just-bash";
+import type { SandboxFileSystem } from "./types";
 
 const basename = (path: string, separator: string): string => {
   if (path[path.length - 1] === separator) path = path.slice(0, -1);
@@ -25,10 +25,10 @@ const printTree = async (
 };
 
 /**
- * Generates a formatted file tree string from an `IFileSystem` instance.
+ * Generates a formatted file tree string from a {@link SandboxFileSystem}.
  * Useful for including filesystem context in agent prompts.
  *
- * @param fs - File system implementation (e.g. from `just-bash`)
+ * @param fs - Sandbox filesystem implementation
  * @param opts - Optional configuration for tree generation
  * @param opts.dir - Root directory to start from (defaults to `/`)
  * @param opts.separator - Path separator (`/` or `\\`, defaults to `/`)
@@ -40,7 +40,7 @@ const printTree = async (
  * ```typescript
  * import { toTree } from 'zeitlich';
  *
- * const fileTree = await toTree(inMemoryFileSystem);
+ * const fileTree = await toTree(sandbox.fs);
  * // Returns:
  * // /
  * // ├─ src/
@@ -50,7 +50,7 @@ const printTree = async (
  * ```
  */
 export const toTree = async (
-  fs: IFileSystem,
+  fs: SandboxFileSystem,
   opts: {
     dir?: string;
     separator?: "/" | "\\";
@@ -67,7 +67,7 @@ export const toTree = async (
   const sort = opts.sort ?? true;
   let subtree = " (...)";
   if (depth > 0) {
-    const list = (await fs.readdirWithFileTypes?.(dir)) || [];
+    const list = await fs.readdirWithFileTypes(dir);
     if (sort) {
       list.sort((a, b) => {
         if (a.isDirectory && b.isDirectory) {

package/src/lib/sandbox/types.ts

@@ -0,0 +1,164 @@
+// ============================================================================
+// Sandbox Filesystem
+// ============================================================================
+
+export interface DirentEntry {
+  name: string;
+  isFile: boolean;
+  isDirectory: boolean;
+  isSymbolicLink: boolean;
+}
+
+export interface FileStat {
+  isFile: boolean;
+  isDirectory: boolean;
+  isSymbolicLink: boolean;
+  size: number;
+  mtime: Date;
+}
+
+/**
+ * Provider-agnostic filesystem interface.
+ *
+ * Implementations that don't support a method should throw
+ * {@link SandboxNotSupportedError}.
+ */
+export interface SandboxFileSystem {
+  readFile(path: string): Promise<string>;
+  readFileBuffer(path: string): Promise<Uint8Array>;
+  writeFile(path: string, content: string | Uint8Array): Promise<void>;
+  appendFile(path: string, content: string | Uint8Array): Promise<void>;
+  exists(path: string): Promise<boolean>;
+  stat(path: string): Promise<FileStat>;
+  mkdir(path: string, options?: { recursive?: boolean }): Promise<void>;
+  readdir(path: string): Promise<string[]>;
+  readdirWithFileTypes(path: string): Promise<DirentEntry[]>;
+  rm(path: string, options?: { recursive?: boolean; force?: boolean }): Promise<void>;
+  cp(src: string, dest: string, options?: { recursive?: boolean }): Promise<void>;
+  mv(src: string, dest: string): Promise<void>;
+  readlink(path: string): Promise<string>;
+  resolvePath(base: string, path: string): string;
+}
+
+// ============================================================================
+// Execution
+// ============================================================================
+
+export interface ExecOptions {
+  timeout?: number;
+  cwd?: string;
+  env?: Record<string, string>;
+}
+
+export interface ExecResult {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+}
+
+// ============================================================================
+// Capabilities
+// ============================================================================
+
+export interface SandboxCapabilities {
+  /** Sandbox supports filesystem operations */
+  filesystem: boolean;
+  /** Sandbox supports shell/command execution */
+  execution: boolean;
+  /** Sandbox state can be persisted and restored */
+  persistence: boolean;
+}
+
+// ============================================================================
+// Sandbox
+// ============================================================================
+
+export interface Sandbox {
+  readonly id: string;
+  readonly capabilities: SandboxCapabilities;
+  readonly fs: SandboxFileSystem;
+
+  exec(command: string, options?: ExecOptions): Promise<ExecResult>;
+  destroy(): Promise<void>;
+}
+
+// ============================================================================
+// Snapshots
+// ============================================================================
+
+export interface SandboxSnapshot {
+  sandboxId: string;
+  providerId: string;
+  /** Provider-specific serialised state */
+  data: unknown;
+  createdAt: string;
+}
+
+// ============================================================================
+// Provider
+// ============================================================================
+
+export interface SandboxCreateOptions {
+  /** Preferred sandbox ID (provider may ignore) */
+  id?: string;
+  /** Seed the filesystem with these files */
+  initialFiles?: Record<string, string | Uint8Array>;
+  /** Environment variables available inside the sandbox */
+  env?: Record<string, string>;
+}
+
+export interface SandboxCreateResult {
+  sandbox: Sandbox;
+  /** Optional state to merge into the workflow's `AgentState` via the session. */
+  stateUpdate?: Record<string, unknown>;
+}
+
+export interface SandboxProvider<
+  TOptions extends SandboxCreateOptions = SandboxCreateOptions,
+  TSandbox extends Sandbox = Sandbox,
+> {
+  readonly id: string;
+  readonly capabilities: SandboxCapabilities;
+
+  create(options?: TOptions): Promise<SandboxCreateResult>;
+  get(sandboxId: string): Promise<TSandbox>;
+  destroy(sandboxId: string): Promise<void>;
+  snapshot(sandboxId: string): Promise<SandboxSnapshot>;
+  restore(snapshot: SandboxSnapshot): Promise<Sandbox>;
+}
+
+// ============================================================================
+// SandboxOps — workflow-side activity interface (like ThreadOps)
+// ============================================================================
+
+export interface SandboxOps<
+  TOptions extends SandboxCreateOptions = SandboxCreateOptions,
+> {
+  createSandbox(
+    options?: TOptions,
+  ): Promise<{ sandboxId: string; stateUpdate?: Record<string, unknown> }>;
+  destroySandbox(sandboxId: string): Promise<void>;
+  snapshotSandbox(sandboxId: string): Promise<SandboxSnapshot>;
+}
+
+// ============================================================================
+// Errors
+// ============================================================================
+
+import { ApplicationFailure } from "@temporalio/common";
+
+export class SandboxNotSupportedError extends ApplicationFailure {
+  constructor(operation: string) {
+    super(
+      `Sandbox does not support: ${operation}`,
+      "SandboxNotSupportedError",
+      true,
+    );
+  }
+}
+
+export class SandboxNotFoundError extends ApplicationFailure {
+  constructor(sandboxId: string) {
+    super(`Sandbox not found: ${sandboxId}`, "SandboxNotFoundError", true);
+  }
+}

package/src/lib/session/index.ts

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

package/src/lib/{session.ts → session/session.ts}

@@ -5,42 +5,15 @@ import {
   setHandler,
   ApplicationFailure,
 } from "@temporalio/workflow";
-import type {
-  ThreadOps,
-  AgentConfig,
-  SessionStartHook,
-  SessionEndHook,
-  SessionExitReason,
-  SessionConfig,
-} from "./types";
-import { type AgentStateManager, type JsonSerializable } from "./state-manager";
-import {
-  createToolRouter,
-  type ParsedToolCallUnion,
-  type ToolMap,
-} from "./tool-router";
-import type { MessageContent } from "./types";
-import { getShortId } from "./thread-id";
-
-export interface ZeitlichSession<M = unknown> {
-  runSession<T extends JsonSerializable<T>>(args: {
-    stateManager: AgentStateManager<T>;
-  }): Promise<{
-    finalMessage: M | null;
-    exitReason: SessionExitReason;
-    usage: ReturnType<AgentStateManager<T>["getTotalUsage"]>;
-  }>;
-}
-
-/**
- * Session-level hooks for lifecycle events
- */
-export interface SessionLifecycleHooks {
-  /** Called when session starts */
-  onSessionStart?: SessionStartHook;
-  /** Called when session ends */
-  onSessionEnd?: SessionEndHook;
-}
+import type { SessionExitReason, MessageContent } from "../types";
+import type { ThreadOps, SessionConfig, ZeitlichSession } from "./types";
+import type { SandboxOps } from "../sandbox/types";
+import { type AgentStateManager, type JsonSerializable } from "../state/types";
+import { createToolRouter } from "../tool-router/router";
+import type { ParsedToolCallUnion, ToolMap } from "../tool-router/types";
+import { getShortId } from "../thread/id";
+import { buildSubagentRegistration } from "../subagent/register";
+import { buildSkillRegistration } from "../skills/register";
 
 /**
  * Creates an agent session that manages the agent loop: LLM invocation,
@@ -89,7 +62,9 @@ export const createSession = async <T extends ToolMap, M = unknown>({
   appendSystemPrompt = true,
   continueThread = false,
   waitForInputTimeout = "48h",
-}: SessionConfig<T, M> & AgentConfig): Promise<ZeitlichSession<M>> => {
+  sandbox: sandboxOps,
+  sandboxId: inheritedSandboxId,
+}: SessionConfig<T, M>): Promise<ZeitlichSession<M>> => {
   const threadId = providedThreadId ?? getShortId();
 
   const {
@@ -99,17 +74,25 @@ export const createSession = async <T extends ToolMap, M = unknown>({
     appendSystemMessage,
   } = threadOps ?? proxyDefaultThreadOps();
 
+  const plugins: ToolMap[string][] = [];
+  if (subagents) {
+    const reg = buildSubagentRegistration(subagents);
+    if (reg) plugins.push(reg);
+  }
+  if (skills) {
+    const reg = buildSkillRegistration(skills);
+    if (reg) plugins.push(reg);
+  }
+
   const toolRouter = createToolRouter({
     tools,
     appendToolResult,
     threadId,
     hooks,
-    subagents,
-    skills,
+    plugins,
     parallel: processToolsInParallel,
   });
 
-  // Helper to call session end hook
   const callSessionEnd = async (
     exitReason: SessionExitReason,
     turns: number
@@ -126,12 +109,15 @@ export const createSession = async <T extends ToolMap, M = unknown>({
   };
 
   return {
-    runSession: async ({
+    runSession: async <TState extends JsonSerializable<TState>>({
       stateManager,
+    }: {
+      stateManager: AgentStateManager<TState>;
     }): Promise<{
+      threadId: string;
       finalMessage: M | null;
       exitReason: SessionExitReason;
-      usage: ReturnType<typeof stateManager.getTotalUsage>;
+      usage: ReturnType<AgentStateManager<TState>["getTotalUsage"]>;
     }> => {
       setHandler(
         defineUpdate<unknown, [MessageContent]>(`add${agentName}Message`),
@@ -153,6 +139,19 @@ export const createSession = async <T extends ToolMap, M = unknown>({
         }
       );
 
+      // --- Sandbox lifecycle: create or inherit ---
+      let sandboxId: string | undefined = inheritedSandboxId;
+      const ownsSandbox = !sandboxId && !!sandboxOps;
+      if (ownsSandbox) {
+        const result = await sandboxOps.createSandbox({ id: threadId });
+        sandboxId = result.sandboxId;
+        if (result.stateUpdate) {
+          stateManager.mergeUpdate(
+            result.stateUpdate as Partial<TState>,
+          );
+        }
+      }
+
       if (hooks.onSessionStart) {
         await hooks.onSessionStart({
           threadId,
@@ -201,18 +200,17 @@ export const createSession = async <T extends ToolMap, M = unknown>({
             stateManager.updateUsage(usage);
           }
 
-          // No tools configured - treat any non-end_turn as completed
           if (!toolRouter.hasTools() || rawToolCalls.length === 0) {
             stateManager.complete();
             exitReason = "completed";
             return {
+              threadId,
               finalMessage: message,
               exitReason,
               usage: stateManager.getTotalUsage(),
             };
           }
 
-          // Parse all tool calls uniformly through the router
           const parsedToolCalls: ParsedToolCallUnion<T>[] = [];
           for (const tc of rawToolCalls) {
             try {
@@ -229,11 +227,11 @@ export const createSession = async <T extends ToolMap, M = unknown>({
             }
           }
 
-          // Hooks can call stateManager.waitForInput() to pause the session
           const toolCallResults = await toolRouter.processToolCalls(
             parsedToolCalls,
             {
               turn: currentTurn,
+              ...(sandboxId !== undefined && { sandboxId }),
             }
           );
 
@@ -250,14 +248,12 @@ export const createSession = async <T extends ToolMap, M = unknown>({
             );
             if (!conditionMet) {
               stateManager.cancel();
-              // Wait briefly to allow pending waitForStateChange handlers to complete
               await condition(() => false, "2s");
               break;
             }
           }
         }
 
-        // Check if we hit max turns
         if (stateManager.getTurns() >= maxTurns && stateManager.isRunning()) {
           exitReason = "max_turns";
         }
@@ -265,11 +261,15 @@ export const createSession = async <T extends ToolMap, M = unknown>({
         exitReason = "failed";
         throw ApplicationFailure.fromError(error);
       } finally {
-        // SessionEnd hook - always called
         await callSessionEnd(exitReason, stateManager.getTurns());
+
+        if (ownsSandbox && sandboxId && sandboxOps) {
+          await sandboxOps.destroySandbox(sandboxId);
+        }
       }
 
       return {
+        threadId,
         finalMessage: null,
         exitReason,
         usage: stateManager.getTotalUsage(),
@@ -306,3 +306,31 @@ export function proxyDefaultThreadOps(
     }
   );
 }
+
+/**
+ * Proxy sandbox lifecycle operations as Temporal activities.
+ * Call this in workflow code when the agent needs a sandbox.
+ *
+ * @example
+ * ```typescript
+ * const session = await createSession({
+ *   sandbox: proxySandboxOps(),
+ *   // ...
+ * });
+ * ```
+ */
+export function proxySandboxOps(
+  options?: Parameters<typeof proxyActivities>[0]
+): SandboxOps {
+  return proxyActivities<SandboxOps>(
+    options ?? {
+      startToCloseTimeout: "30s",
+      retry: {
+        maximumAttempts: 3,
+        initialInterval: "2s",
+        maximumInterval: "30s",
+        backoffCoefficient: 2,
+      },
+    }
+  );
+}

package/src/lib/session/types.ts

@@ -0,0 +1,93 @@
+import type { Duration } from "@temporalio/common";
+import type {
+  MessageContent,
+  ToolResultConfig,
+  SessionExitReason,
+} from "../types";
+import type {
+  ToolMap,
+  ToolCallResultUnion,
+  InferToolResults,
+} from "../tool-router/types";
+import type { Hooks } from "../hooks/types";
+import type { SubagentConfig } from "../subagent/types";
+import type { Skill } from "../skills/types";
+import type { SandboxOps } from "../sandbox/types";
+import type { RunAgentActivity } from "../model/types";
+import type { AgentStateManager, JsonSerializable } from "../state/types";
+
+/**
+ * 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 session
+ */
+export interface SessionConfig<T extends ToolMap, M = unknown> {
+  /** The name of the agent, should be unique within the workflows */
+  agentName: string;
+  /** 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;
+  /** Sandbox lifecycle operations (optional — omit for agents that don't need a sandbox) */
+  sandbox?: SandboxOps;
+  /**
+   * Pre-existing sandbox ID to reuse (e.g. inherited from a parent agent).
+   * When set, the session skips `createSandbox` and will not destroy the
+   * sandbox on exit (the owner is responsible for cleanup).
+   */
+  sandboxId?: string;
+}
+
+export interface ZeitlichSession<M = unknown> {
+  runSession<T extends JsonSerializable<T>>(args: {
+    stateManager: AgentStateManager<T>;
+  }): Promise<{
+    threadId: string;
+    finalMessage: M | null;
+    exitReason: SessionExitReason;
+    usage: ReturnType<AgentStateManager<T>["getTotalUsage"]>;
+  }>;
+}

package/src/lib/skills/fs-provider.ts

@@ -1,10 +1,10 @@
-import { readdir, readFile } from "node:fs/promises";
 import { join } from "node:path";
+import type { SandboxFileSystem } from "../sandbox/types";
 import type { Skill, SkillMetadata, SkillProvider } from "./types";
 import { parseSkillFile } from "./parse";
 
 /**
- * Loads skills from a filesystem directory following the agentskills.io layout:
+ * Loads skills from a directory following the agentskills.io layout:
  *
  * ```
  * skills/
@@ -14,17 +14,21 @@ import { parseSkillFile } from "./parse";
  * │   └── SKILL.md
  * ```
  *
- * Activity-side only — cannot be used in Temporal workflow code.
+ * Uses the sandbox filesystem abstraction — works with any backend
+ * (in-memory, host FS, Wasmer, Daytona, etc.).
  */
 export class FileSystemSkillProvider implements SkillProvider {
-  constructor(private readonly baseDir: string) {}
+  constructor(
+    private readonly fs: SandboxFileSystem,
+    private readonly baseDir: string,
+  ) {}
 
   async listSkills(): Promise<SkillMetadata[]> {
     const dirs = await this.discoverSkillDirs();
     const skills: SkillMetadata[] = [];
 
     for (const dir of dirs) {
-      const raw = await readFile(join(this.baseDir, dir, "SKILL.md"), "utf-8");
+      const raw = await this.fs.readFile(join(this.baseDir, dir, "SKILL.md"));
       const { frontmatter } = parseSkillFile(raw);
       skills.push(frontmatter);
     }
@@ -33,15 +37,14 @@ export class FileSystemSkillProvider implements SkillProvider {
   }
 
   async getSkill(name: string): Promise<Skill> {
-    const raw = await readFile(
+    const raw = await this.fs.readFile(
       join(this.baseDir, name, "SKILL.md"),
-      "utf-8"
     );
     const { frontmatter, body } = parseSkillFile(raw);
 
     if (frontmatter.name !== name) {
       throw new Error(
-        `Skill directory "${name}" contains SKILL.md with mismatched name "${frontmatter.name}"`
+        `Skill directory "${name}" contains SKILL.md with mismatched name "${frontmatter.name}"`,
       );
     }
 
@@ -57,7 +60,7 @@ export class FileSystemSkillProvider implements SkillProvider {
     const skills: Skill[] = [];
 
     for (const dir of dirs) {
-      const raw = await readFile(join(this.baseDir, dir, "SKILL.md"), "utf-8");
+      const raw = await this.fs.readFile(join(this.baseDir, dir, "SKILL.md"));
       const { frontmatter, body } = parseSkillFile(raw);
       skills.push({ ...frontmatter, instructions: body });
     }
@@ -66,16 +69,14 @@ export class FileSystemSkillProvider implements SkillProvider {
   }
 
   private async discoverSkillDirs(): Promise<string[]> {
-    const entries = await readdir(this.baseDir, { withFileTypes: true });
+    const entries = await this.fs.readdirWithFileTypes(this.baseDir);
     const dirs: string[] = [];
 
     for (const entry of entries) {
-      if (!entry.isDirectory()) continue;
-      try {
-        await readFile(join(this.baseDir, entry.name, "SKILL.md"), "utf-8");
+      if (!entry.isDirectory) continue;
+      const skillPath = join(this.baseDir, entry.name, "SKILL.md");
+      if (await this.fs.exists(skillPath)) {
         dirs.push(entry.name);
-      } catch {
-        // No SKILL.md — skip
       }
     }
 

package/src/lib/skills/handler.ts

@@ -0,0 +1,31 @@
+import type { Skill } from "./types";
+import type { ToolHandlerResponse } from "../tool-router";
+import type { ReadSkillArgs } from "./tool";
+
+/**
+ * Creates a ReadSkill handler that looks up skills from an in-memory array.
+ * Runs directly in the workflow (like task tools) — no activity needed.
+ */
+export function createReadSkillHandler(
+  skills: Skill[]
+): (args: ReadSkillArgs) => ToolHandlerResponse<null> {
+  const skillMap = new Map(skills.map((s) => [s.name, s]));
+
+  return (args: ReadSkillArgs): ToolHandlerResponse<null> => {
+    const skill = skillMap.get(args.skill_name);
+
+    if (!skill) {
+      return {
+        toolResponse: JSON.stringify({
+          error: `Skill "${args.skill_name}" not found`,
+        }),
+        data: null,
+      };
+    }
+
+    return {
+      toolResponse: skill.instructions,
+      data: null,
+    };
+  };
+}

package/src/lib/skills/index.ts

@@ -1,3 +1,7 @@
 export type { Skill, SkillMetadata, SkillProvider } from "./types";
 export { parseSkillFile } from "./parse";
-export { FileSystemSkillProvider } from "./fs-provider";
+export { createReadSkillTool, READ_SKILL_TOOL_NAME } from "./tool";
+export type { ReadSkillArgs } from "./tool";
+export { createReadSkillHandler } from "./handler";
+export { buildSkillRegistration } from "./register";
+

package/src/lib/skills/register.ts

@@ -0,0 +1,20 @@
+import type { ToolMap } from "../tool-router/types";
+import type { Skill } from "./types";
+import { createReadSkillTool } from "./tool";
+import { createReadSkillHandler } from "./handler";
+
+/**
+ * Builds a fully wired tool entry for the ReadSkill tool.
+ *
+ * Returns null if no skills are provided.
+ */
+export function buildSkillRegistration(
+  skills: Skill[]
+): ToolMap[string] | null {
+  if (skills.length === 0) return null;
+
+  return {
+    ...createReadSkillTool(skills),
+    handler: createReadSkillHandler(skills),
+  };
+}