zeitlich 0.2.13 → 0.2.14

package/src/adapters/sandbox/virtual/filesystem.ts

@@ -0,0 +1,345 @@
+import type {
+  SandboxFileSystem,
+  DirentEntry,
+  FileStat,
+} from "../../../lib/sandbox/types";
+import { SandboxNotSupportedError } from "../../../lib/sandbox/types";
+import type {
+  FileEntry,
+  FileEntryMetadata,
+  FileResolver,
+  TreeMutation,
+} from "./types";
+
+/**
+ * Normalise a virtual path to a canonical form: absolute, no trailing slash
+ * (except root), no double slashes.
+ */
+function normalisePath(p: string): string {
+  if (!p.startsWith("/")) p = "/" + p;
+  p = p.replace(/\/+/g, "/");
+  if (p.length > 1 && p.endsWith("/")) p = p.slice(0, -1);
+  return p;
+}
+
+/** Return the parent directory of a normalised path ("/a/b" → "/a"). */
+function parentDir(p: string): string {
+  const idx = p.lastIndexOf("/");
+  return idx <= 0 ? "/" : p.slice(0, idx);
+}
+
+/**
+ * Collect the set of implicit directory paths from a flat file list.
+ * E.g. "/a/b/c.ts" contributes "/a/b", "/a", "/".
+ */
+function inferDirectories(entries: { path: string }[]): Set<string> {
+  const dirs = new Set<string>();
+  dirs.add("/");
+  for (const entry of entries) {
+    let dir = parentDir(normalisePath(entry.path));
+    while (dir !== "/" && !dirs.has(dir)) {
+      dirs.add(dir);
+      dir = parentDir(dir);
+    }
+    dirs.add("/");
+  }
+  return dirs;
+}
+
+/**
+ * Ephemeral {@link SandboxFileSystem} backed by a {@link FileResolver}.
+ *
+ * Created fresh for each tool invocation from the current workflow file tree.
+ * Directory structure is inferred from file paths. All mutations are tracked
+ * and can be retrieved via {@link getMutations} after the handler completes.
+ */
+export class VirtualSandboxFileSystem<
+  TCtx = unknown,
+  TMeta = FileEntryMetadata,
+> implements SandboxFileSystem
+{
+  private entries: Map<string, FileEntry<TMeta>>;
+  private directories: Set<string>;
+  private mutations: TreeMutation<TMeta>[] = [];
+
+  constructor(
+    tree: FileEntry<TMeta>[],
+    private resolver: FileResolver<TCtx, TMeta>,
+    private ctx: TCtx,
+  ) {
+    this.entries = new Map(
+      tree.map((e) => [normalisePath(e.path), e]),
+    );
+    this.directories = inferDirectories(tree);
+  }
+
+  /** Return all mutations accumulated during this invocation. */
+  getMutations(): TreeMutation<TMeta>[] {
+    return this.mutations;
+  }
+
+  /** Look up a file entry by virtual path. */
+  getEntry(path: string): FileEntry<TMeta> | undefined {
+    return this.entries.get(normalisePath(path));
+  }
+
+  // --------------------------------------------------------------------------
+  // Read operations — delegate to resolver lazily
+  // --------------------------------------------------------------------------
+
+  async readFile(path: string): Promise<string> {
+    const entry = this.entries.get(normalisePath(path));
+    if (!entry) throw new Error(`ENOENT: no such file: ${path}`);
+    return this.resolver.readFile(entry.id, this.ctx);
+  }
+
+  async readFileBuffer(path: string): Promise<Uint8Array> {
+    const entry = this.entries.get(normalisePath(path));
+    if (!entry) throw new Error(`ENOENT: no such file: ${path}`);
+    return this.resolver.readFileBuffer(entry.id, this.ctx);
+  }
+
+  // --------------------------------------------------------------------------
+  // Metadata operations — pure, resolved from the tree
+  // --------------------------------------------------------------------------
+
+  async exists(path: string): Promise<boolean> {
+    const norm = normalisePath(path);
+    return this.entries.has(norm) || this.directories.has(norm);
+  }
+
+  async stat(path: string): Promise<FileStat> {
+    const norm = normalisePath(path);
+    const entry = this.entries.get(norm);
+    if (entry) {
+      return {
+        isFile: true,
+        isDirectory: false,
+        isSymbolicLink: false,
+        size: entry.size,
+        mtime: new Date(entry.mtime),
+      };
+    }
+    if (this.directories.has(norm)) {
+      return {
+        isFile: false,
+        isDirectory: true,
+        isSymbolicLink: false,
+        size: 0,
+        mtime: new Date(),
+      };
+    }
+    throw new Error(`ENOENT: no such file or directory: ${path}`);
+  }
+
+  async readdir(path: string): Promise<string[]> {
+    const norm = normalisePath(path);
+    if (!this.directories.has(norm)) {
+      throw new Error(`ENOENT: no such directory: ${path}`);
+    }
+    const prefix = norm === "/" ? "/" : norm + "/";
+    const names = new Set<string>();
+
+    for (const p of this.entries.keys()) {
+      if (p.startsWith(prefix)) {
+        const rest = p.slice(prefix.length);
+        const seg = rest.split("/")[0];
+        if (seg) names.add(seg);
+      }
+    }
+    for (const d of this.directories) {
+      if (d.startsWith(prefix) && d !== norm) {
+        const rest = d.slice(prefix.length);
+        const seg = rest.split("/")[0];
+        if (seg) names.add(seg);
+      }
+    }
+    return [...names].sort();
+  }
+
+  async readdirWithFileTypes(path: string): Promise<DirentEntry[]> {
+    const names = await this.readdir(path);
+    const norm = normalisePath(path);
+    const prefix = norm === "/" ? "/" : norm + "/";
+
+    return names.map((name) => {
+      const full = prefix + name;
+      const isFile = this.entries.has(full);
+      const isDirectory = this.directories.has(full);
+      return { name, isFile, isDirectory, isSymbolicLink: false };
+    });
+  }
+
+  // --------------------------------------------------------------------------
+  // Write operations — delegate to resolver, record mutations
+  // --------------------------------------------------------------------------
+
+  async writeFile(path: string, content: string | Uint8Array): Promise<void> {
+    const norm = normalisePath(path);
+    const existing = this.entries.get(norm);
+
+    if (existing) {
+      await this.resolver.writeFile(existing.id, content, this.ctx);
+      const size =
+        typeof content === "string"
+          ? new TextEncoder().encode(content).byteLength
+          : content.byteLength;
+      const updated: FileEntry<TMeta> = {
+        ...existing,
+        size,
+        mtime: new Date().toISOString(),
+      };
+      this.entries.set(norm, updated);
+      this.mutations.push({ type: "update", path: norm, entry: updated });
+    } else {
+      const entry = await this.resolver.createFile(norm, content, this.ctx);
+      const normalised = { ...entry, path: norm };
+      this.entries.set(norm, normalised);
+      this.addParentDirectories(norm);
+      this.mutations.push({ type: "add", entry: normalised });
+    }
+  }
+
+  async appendFile(path: string, content: string | Uint8Array): Promise<void> {
+    const norm = normalisePath(path);
+    const existing = this.entries.get(norm);
+
+    if (!existing) {
+      return this.writeFile(path, content);
+    }
+
+    const current = await this.resolver.readFile(existing.id, this.ctx);
+    const appended =
+      typeof content === "string"
+        ? current + content
+        : current + new TextDecoder().decode(content);
+    await this.resolver.writeFile(existing.id, appended, this.ctx);
+
+    const size = new TextEncoder().encode(appended).byteLength;
+    const updated: FileEntry<TMeta> = {
+      ...existing,
+      size,
+      mtime: new Date().toISOString(),
+    };
+    this.entries.set(norm, updated);
+    this.mutations.push({ type: "update", path: norm, entry: updated });
+  }
+
+  async mkdir(_path: string, _options?: { recursive?: boolean }): Promise<void> {
+    const norm = normalisePath(_path);
+    if (this.directories.has(norm)) return;
+
+    if (_options?.recursive) {
+      this.addParentDirectories(norm + "/placeholder");
+      this.directories.add(norm);
+    } else {
+      const parent = parentDir(norm);
+      if (!this.directories.has(parent)) {
+        throw new Error(`ENOENT: no such directory: ${parent}`);
+      }
+      this.directories.add(norm);
+    }
+  }
+
+  async rm(
+    path: string,
+    options?: { recursive?: boolean; force?: boolean },
+  ): Promise<void> {
+    const norm = normalisePath(path);
+    const entry = this.entries.get(norm);
+
+    if (entry) {
+      await this.resolver.deleteFile(entry.id, this.ctx);
+      this.entries.delete(norm);
+      this.mutations.push({ type: "remove", path: norm });
+      return;
+    }
+
+    if (this.directories.has(norm)) {
+      if (!options?.recursive) {
+        throw new Error(`EISDIR: is a directory (use recursive): ${path}`);
+      }
+      const prefix = norm === "/" ? "/" : norm + "/";
+      for (const [p, e] of this.entries) {
+        if (p.startsWith(prefix)) {
+          await this.resolver.deleteFile(e.id, this.ctx);
+          this.entries.delete(p);
+          this.mutations.push({ type: "remove", path: p });
+        }
+      }
+      for (const d of this.directories) {
+        if (d.startsWith(prefix)) this.directories.delete(d);
+      }
+      this.directories.delete(norm);
+      return;
+    }
+
+    if (!options?.force) {
+      throw new Error(`ENOENT: no such file or directory: ${path}`);
+    }
+  }
+
+  async cp(
+    src: string,
+    dest: string,
+    _options?: { recursive?: boolean },
+  ): Promise<void> {
+    const normSrc = normalisePath(src);
+    const normDest = normalisePath(dest);
+
+    const entry = this.entries.get(normSrc);
+    if (entry) {
+      const content = await this.resolver.readFile(entry.id, this.ctx);
+      await this.writeFile(normDest, content);
+      return;
+    }
+
+    if (!this.directories.has(normSrc)) {
+      throw new Error(`ENOENT: no such file or directory: ${src}`);
+    }
+    if (!_options?.recursive) {
+      throw new Error(`EISDIR: is a directory (use recursive): ${src}`);
+    }
+
+    const prefix = normSrc === "/" ? "/" : normSrc + "/";
+    for (const [p, e] of this.entries) {
+      if (p.startsWith(prefix)) {
+        const relative = p.slice(normSrc.length);
+        const content = await this.resolver.readFile(e.id, this.ctx);
+        await this.writeFile(normDest + relative, content);
+      }
+    }
+  }
+
+  async mv(src: string, dest: string): Promise<void> {
+    await this.cp(src, dest, { recursive: true });
+    await this.rm(src, { recursive: true });
+  }
+
+  // --------------------------------------------------------------------------
+  // Unsupported
+  // --------------------------------------------------------------------------
+
+  async readlink(_path: string): Promise<string> {
+    throw new SandboxNotSupportedError("readlink");
+  }
+
+  resolvePath(base: string, path: string): string {
+    if (path.startsWith("/")) return normalisePath(path);
+    const combined =
+      base.endsWith("/") ? base + path : base + "/" + path;
+    return normalisePath(combined);
+  }
+
+  // --------------------------------------------------------------------------
+  // Helpers
+  // --------------------------------------------------------------------------
+
+  private addParentDirectories(filePath: string): void {
+    let dir = parentDir(normalisePath(filePath));
+    while (!this.directories.has(dir)) {
+      this.directories.add(dir);
+      dir = parentDir(dir);
+    }
+  }
+}

package/src/adapters/sandbox/virtual/index.ts

@@ -0,0 +1,88 @@
+import type {
+  Sandbox,
+  SandboxCapabilities,
+  ExecOptions,
+  ExecResult,
+} from "../../../lib/sandbox/types";
+import { SandboxNotSupportedError } from "../../../lib/sandbox/types";
+import { VirtualSandboxFileSystem } from "./filesystem";
+import type {
+  FileEntry,
+  FileEntryMetadata,
+  FileResolver,
+  VirtualSandbox,
+} from "./types";
+
+// ============================================================================
+// VirtualSandbox
+// ============================================================================
+
+class VirtualSandboxImpl<
+  TCtx = unknown,
+  TMeta = FileEntryMetadata,
+> implements Sandbox
+{
+  readonly capabilities: SandboxCapabilities = {
+    filesystem: true,
+    execution: false,
+    persistence: true,
+  };
+
+  readonly fs: VirtualSandboxFileSystem<TCtx, TMeta>;
+
+  constructor(
+    readonly id: string,
+    tree: FileEntry<TMeta>[],
+    resolver: FileResolver<TCtx, TMeta>,
+    ctx: TCtx
+  ) {
+    this.fs = new VirtualSandboxFileSystem(tree, resolver, ctx);
+  }
+
+  async exec(_command: string, _options?: ExecOptions): Promise<ExecResult> {
+    throw new SandboxNotSupportedError("exec");
+  }
+
+  async destroy(): Promise<void> {
+    // Ephemeral — nothing to clean up
+  }
+}
+
+// ============================================================================
+// Factory
+// ============================================================================
+
+/**
+ * Create an ephemeral {@link Sandbox} from a file tree and resolver.
+ *
+ * Used internally by {@link withVirtualSandbox} and
+ * {@link VirtualSandboxProvider}; consumers can also call this directly
+ * if they need a sandbox outside the wrapper pattern.
+ */
+export function createVirtualSandbox<
+  TCtx,
+  TMeta = FileEntryMetadata,
+>(
+  id: string,
+  tree: FileEntry<TMeta>[],
+  resolver: FileResolver<TCtx, TMeta>,
+  ctx: TCtx,
+): VirtualSandbox<TCtx, TMeta> {
+  return new VirtualSandboxImpl(id, tree, resolver, ctx);
+}
+
+// Re-exports for convenience
+export { VirtualSandboxFileSystem } from "./filesystem";
+export { VirtualSandboxProvider } from "./provider";
+export { withVirtualSandbox } from "./with-virtual-sandbox";
+export type {
+  FileEntry,
+  FileEntryMetadata,
+  FileResolver,
+  VirtualFileTree,
+  VirtualSandboxCreateOptions,
+  VirtualSandboxState,
+  VirtualSandboxContext,
+  VirtualSandbox,
+  TreeMutation,
+} from "./types";

package/src/adapters/sandbox/virtual/mutations.ts

@@ -0,0 +1,38 @@
+import type { FileEntryMetadata, VirtualFileTree, TreeMutation } from "./types";
+
+/**
+ * Apply a list of {@link TreeMutation}s to the `fileTree` stored in a state
+ * manager instance, updating it in place and returning the new tree.
+ *
+ * The `stateManager` parameter is structurally typed so any
+ * {@link AgentStateManager} whose custom state includes
+ * `fileTree: VirtualFileTree<TMeta>` will satisfy it.
+ */
+export function applyVirtualTreeMutations<TMeta = FileEntryMetadata>(
+  stateManager: {
+    get(key: "fileTree"): VirtualFileTree<TMeta>;
+    set(key: "fileTree", value: VirtualFileTree<TMeta>): void;
+  },
+  mutations: TreeMutation<TMeta>[],
+): VirtualFileTree<TMeta> {
+  let tree = [...stateManager.get("fileTree")];
+
+  for (const m of mutations) {
+    switch (m.type) {
+      case "add":
+        tree.push(m.entry);
+        break;
+      case "remove":
+        tree = tree.filter((e) => e.path !== m.path);
+        break;
+      case "update":
+        tree = tree.map((e) =>
+          e.path === m.path ? { ...e, ...m.entry } : e
+        );
+        break;
+    }
+  }
+
+  stateManager.set("fileTree", tree);
+  return tree;
+}

package/src/adapters/sandbox/virtual/provider.ts

@@ -0,0 +1,101 @@
+import type {
+  SandboxCapabilities,
+  SandboxCreateResult,
+  SandboxProvider,
+} from "../../../lib/sandbox/types";
+import { SandboxNotSupportedError } from "../../../lib/sandbox/types";
+import { getShortId } from "../../../lib/thread/id";
+import { createVirtualSandbox } from "./index";
+import type {
+  FileEntryMetadata,
+  FileResolver,
+  VirtualSandboxCreateOptions,
+} from "./types";
+
+/**
+ * Stateless {@link SandboxProvider} backed by a {@link FileResolver}.
+ *
+ * The provider holds **no internal state**. All sandbox state (sandboxId,
+ * fileTree, resolverContext) is returned as a `stateUpdate` from
+ * {@link create} and merged into the workflow's `AgentState` by the session.
+ * {@link withVirtualSandbox} reads this state back on every tool invocation.
+ *
+ * @example
+ * ```typescript
+ * const provider = new VirtualSandboxProvider(resolver);
+ * const manager = new SandboxManager(provider);
+ *
+ * export const activities = {
+ *   ...manager.createActivities(),
+ *   readFile: withVirtualSandbox(client, provider, readHandler),
+ * };
+ * ```
+ */
+export class VirtualSandboxProvider<
+  TCtx = unknown,
+  TMeta = FileEntryMetadata,
+> implements SandboxProvider<VirtualSandboxCreateOptions<TCtx>> {
+  readonly id = "virtual";
+  readonly capabilities: SandboxCapabilities = {
+    filesystem: true,
+    execution: false,
+    persistence: true,
+  };
+
+  readonly resolver: FileResolver<TCtx, TMeta>;
+
+  constructor(resolver: FileResolver<TCtx, TMeta>) {
+    this.resolver = resolver;
+  }
+
+  async create(
+    options?: VirtualSandboxCreateOptions<TCtx>
+  ): Promise<SandboxCreateResult> {
+    if (!options || !("resolverContext" in options)) {
+      throw new Error("VirtualSandboxProvider.create requires resolverContext");
+    }
+
+    const sandboxId = options.id ?? getShortId();
+    const fileTree = await this.resolver.resolveEntries(
+      options.resolverContext
+    );
+
+    const sandbox = createVirtualSandbox(
+      sandboxId,
+      fileTree,
+      this.resolver,
+      options.resolverContext
+    );
+
+    return {
+      sandbox,
+      stateUpdate: {
+        sandboxId,
+        fileTree,
+        resolverContext: options.resolverContext,
+      },
+    };
+  }
+
+  async get(): Promise<never> {
+    throw new SandboxNotSupportedError(
+      "get (virtual sandbox state lives in workflow AgentState)"
+    );
+  }
+
+  async destroy(): Promise<void> {
+    // No-op — no internal state to clean up
+  }
+
+  async snapshot(): Promise<never> {
+    throw new SandboxNotSupportedError(
+      "snapshot (virtual sandbox state lives in workflow AgentState)"
+    );
+  }
+
+  async restore(): Promise<never> {
+    throw new SandboxNotSupportedError(
+      "restore (virtual sandbox state lives in workflow AgentState)"
+    );
+  }
+}

package/src/adapters/sandbox/virtual/tree.ts

@@ -0,0 +1,82 @@
+import type { FileEntry } from "./types";
+
+interface TreeNode {
+  name: string;
+  children: Map<string, TreeNode>;
+  isFile: boolean;
+}
+
+const buildTree = <T>(entries: FileEntry<T>[]): TreeNode => {
+  const root: TreeNode = { name: "/", children: new Map(), isFile: false };
+
+  for (const entry of entries) {
+    const parts = entry.path.split("/").filter(Boolean);
+    let current = root;
+    for (const part of parts) {
+      let child = current.children.get(part);
+      if (!child) {
+        child = { name: part, children: new Map(), isFile: false };
+        current.children.set(part, child);
+      }
+      current = child;
+    }
+    current.isFile = current.children.size === 0;
+  }
+
+  return root;
+};
+
+const printNode = (node: TreeNode, tab: string, sort: boolean): string => {
+  const entries = [...node.children.values()];
+  if (sort) {
+    entries.sort((a, b) => {
+      if (!a.isFile && !b.isFile) return a.name.localeCompare(b.name);
+      if (!a.isFile) return -1;
+      if (!b.isFile) return 1;
+      return a.name.localeCompare(b.name);
+    });
+  }
+
+  let str = "";
+  for (const [i, entry] of entries.entries()) {
+    const isLast = i === entries.length - 1;
+    const branch = isLast ? "└─" : "├─";
+    const childTab = tab + (isLast ? "   " : "│  ");
+
+    if (entry.isFile) {
+      str += "\n" + tab + branch + " " + entry.name;
+    } else {
+      const subtree = printNode(entry, childTab, sort);
+      str += "\n" + tab + branch + " " + entry.name + "/" + subtree;
+    }
+  }
+  return str;
+};
+
+/**
+ * Generates a formatted file tree string from a flat {@link FileEntry} list.
+ * Directories are inferred from file paths — no filesystem access needed.
+ *
+ * @param entries - Flat list of file entries
+ * @param opts - Optional configuration
+ * @param opts.sort - Sort entries alphabetically with directories first (defaults to true)
+ * @returns Formatted file tree string
+ *
+ * @example
+ * ```typescript
+ * const tree = formatVirtualFileTree(state.fileTree);
+ * // /
+ * // ├─ src/
+ * // │  ├─ index.ts
+ * // │  └─ utils.ts
+ * // └─ package.json
+ * ```
+ */
+export function formatVirtualFileTree<T>(
+  entries: FileEntry<T>[],
+  opts: { sort?: boolean } = {}
+): string {
+  const sort = opts.sort ?? true;
+  const root = buildTree(entries);
+  return "/" + printNode(root, "", sort);
+}