@zocomputer/agent-sdk 0.5.0

package/src/async-tasks.ts

@@ -0,0 +1,273 @@
+// Background task registry for the stdlib's async tools.
+//
+// eve runs each turn as a durable, step-checkpointed workflow, and a step can't
+// advance until every tool call in it resolves — so there's no native "return
+// early and keep running". Instead a tool kicks off work, stashes the promise
+// here, and returns a task id immediately; later tools poll or await it.
+//
+// Task metadata/results are persisted to `storePath` so finished work survives
+// an agent restart. In-flight JS promises cannot be reattached after a process
+// exits, so tasks that were still running at boot are marked `lost`.
+//
+// Two hazards shape the registry's sharing model:
+//
+// - **Module-graph duplication.** eve's dev runtime rebuilds authored artifacts
+//   mid-session (e.g. the agent itself touches a watched file), and a rebuild
+//   gives statically-exported tools a fresh module graph while session-scoped
+//   dynamics (the tasks toolset, built on `session.started`) keep their old
+//   closure. Two module instances then hold two `Map`s: `bash` spawns `task_1`
+//   into one, `await_task` looks it up in the other — "No such task". So
+//   registries are deduped per `storePath` on `globalThis` (via `Symbol.for`,
+//   which is shared across module copies): every copy in the process converges
+//   on one instance.
+// - **Out-of-instance readers.** As a second line, lookups that miss in memory
+//   fall back to the persisted store, and `awaitTask` polls it while the task
+//   is running elsewhere — so even a reader in another process reports honest
+//   state instead of "No such task".
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+
+interface BaseTask {
+  readonly id: string;
+  /** Short human label, e.g. the command or query. */
+  readonly label: string;
+  /** Which backgroundable op produced this task. */
+  readonly tool: string;
+  readonly startedAt: number;
+  readonly progress?: unknown;
+}
+
+// Discriminated union so callers can't read `result` off a still-running task.
+export type Task =
+  | (BaseTask & { readonly status: "running" })
+  | (BaseTask & { readonly status: "done"; readonly finishedAt: number; readonly result: unknown })
+  | (BaseTask & { readonly status: "error"; readonly finishedAt: number; readonly error: string })
+  | (BaseTask & { readonly status: "lost"; readonly finishedAt: number; readonly error: string });
+
+export interface TaskRegistry {
+  /** Register `work` as a background task and return its id immediately. */
+  spawnTask(tool: string, label: string, work: Promise<unknown>): string;
+  updateTaskProgress(id: string, progress: unknown): void;
+  listTasks(): Task[];
+  getTask(id: string): Task | undefined;
+  /**
+   * Block until the task settles or `waitMs` elapses, then return its current
+   * state (still "running" if the wait timed out). Undefined for an unknown id.
+   */
+  awaitTask(id: string, waitMs: number): Promise<Task | undefined>;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isTask(value: unknown): value is Task {
+  if (!isRecord(value)) return false;
+  if (
+    typeof value.id !== "string" ||
+    typeof value.tool !== "string" ||
+    typeof value.label !== "string" ||
+    typeof value.startedAt !== "number" ||
+    typeof value.status !== "string"
+  ) {
+    return false;
+  }
+  switch (value.status) {
+    case "running":
+      return true;
+    case "done":
+      return typeof value.finishedAt === "number" && "result" in value;
+    case "error":
+    case "lost":
+      return typeof value.finishedAt === "number" && typeof value.error === "string";
+    default:
+      return false;
+  }
+}
+
+// Keep a registry from growing without bound over a long session; drop the
+// oldest already-settled tasks first (never a running one).
+const MAX_TASKS = 100;
+
+// One registry per store path per process, no matter how many module copies a
+// runtime rebuild creates. `Symbol.for` is process-global, so every copy of
+// this module resolves the same key.
+const REGISTRY_CACHE_KEY = Symbol.for("zocomputer.agent-sdk.task-registries");
+
+function registryCache(): Map<string, TaskRegistry> {
+  const holder = globalThis as { [REGISTRY_CACHE_KEY]?: Map<string, TaskRegistry> };
+  holder[REGISTRY_CACHE_KEY] ??= new Map();
+  return holder[REGISTRY_CACHE_KEY];
+}
+
+/**
+ * Test-only: drop the per-process registry dedupe so a test can simulate an
+ * agent restart (a fresh registry over an existing store).
+ */
+export function __resetTaskRegistryCacheForTests(): void {
+  registryCache().clear();
+}
+
+/** How often awaitTask re-reads the store for a task another instance owns. */
+const STORE_POLL_MS = 500;
+
+export function createTaskRegistry(opts: { storePath: string }): TaskRegistry {
+  const cache = registryCache();
+  const cached = cache.get(opts.storePath);
+  if (cached) return cached;
+  const registry = buildTaskRegistry(opts);
+  cache.set(opts.storePath, registry);
+  return registry;
+}
+
+function buildTaskRegistry(opts: { storePath: string }): TaskRegistry {
+  const { storePath } = opts;
+  const tasks = new Map<string, Task>();
+  const pending = new Map<string, Promise<unknown>>();
+  let counter = 0;
+
+  function listTasks(): Task[] {
+    return [...tasks.values()].sort((a, b) => a.startedAt - b.startedAt);
+  }
+
+  function persist(): void {
+    mkdirSync(dirname(storePath), { recursive: true });
+    writeFileSync(storePath, JSON.stringify({ tasks: listTasks() }, null, 2), "utf8");
+  }
+
+  function readStoreTasks(): Task[] {
+    if (!existsSync(storePath)) return [];
+    try {
+      const parsed: unknown = JSON.parse(readFileSync(storePath, "utf8"));
+      if (!isRecord(parsed) || !Array.isArray(parsed.tasks)) return [];
+      return parsed.tasks.filter(isTask);
+    } catch {
+      // Corrupt local state should not stop the agent from booting.
+      return [];
+    }
+  }
+
+  function loadPersisted(): void {
+    for (const saved of readStoreTasks()) {
+      const task =
+        saved.status === "running"
+          ? {
+              ...saved,
+              status: "lost" as const,
+              finishedAt: Date.now(),
+              error: "The agent restarted before this background task finished.",
+            }
+          : saved;
+      tasks.set(task.id, task);
+      const match = task.id.match(/^task_(\d+)$/);
+      const n = match ? Number(match[1]) : 0;
+      if (Number.isFinite(n)) counter = Math.max(counter, n);
+    }
+  }
+
+  loadPersisted();
+
+  // Read-through for tasks this instance doesn't hold (an owner in another
+  // process). Settled state in the store is authoritative; a "running" entry
+  // is honest live state — its promise just isn't awaitable from here.
+  function storeTask(id: string): Task | undefined {
+    return readStoreTasks().find((task) => task.id === id);
+  }
+
+  function prune(): void {
+    if (tasks.size <= MAX_TASKS) return;
+    const settled = [...tasks.values()]
+      .filter((t) => t.status !== "running")
+      .sort((a, b) => a.startedAt - b.startedAt);
+    for (const t of settled) {
+      if (tasks.size <= MAX_TASKS) break;
+      tasks.delete(t.id);
+      pending.delete(t.id);
+    }
+    persist();
+  }
+
+  // Attaches its own then/catch, so a rejecting op updates the task instead of
+  // surfacing as an unhandledRejection.
+  function spawnTask(tool: string, label: string, work: Promise<unknown>): string {
+    const id = `task_${++counter}`;
+    const startedAt = Date.now();
+    tasks.set(id, { id, tool, label, startedAt, status: "running" });
+    pending.set(id, work);
+    void work.then(
+      (result) => {
+        tasks.set(id, {
+          id,
+          tool,
+          label,
+          startedAt,
+          status: "done",
+          finishedAt: Date.now(),
+          result,
+        });
+        pending.delete(id);
+        persist();
+      },
+      (err: unknown) => {
+        const error = err instanceof Error ? err.message : String(err);
+        tasks.set(id, {
+          id,
+          tool,
+          label,
+          startedAt,
+          status: "error",
+          finishedAt: Date.now(),
+          error,
+        });
+        pending.delete(id);
+        persist();
+      },
+    );
+    prune();
+    persist();
+    return id;
+  }
+
+  return {
+    spawnTask,
+    updateTaskProgress(id, progress) {
+      const task = tasks.get(id);
+      if (!task || task.status !== "running") return;
+      tasks.set(id, { ...task, progress });
+    },
+    listTasks,
+    getTask(id) {
+      return tasks.get(id) ?? storeTask(id);
+    },
+    async awaitTask(id, waitMs) {
+      const current = tasks.get(id);
+      if (current) {
+        if (current.status !== "running") return current;
+        const work = pending.get(id);
+        if (work) {
+          await Promise.race([
+            work.then(
+              () => undefined,
+              () => undefined,
+            ),
+            new Promise<void>((resolve) => setTimeout(resolve, waitMs)),
+          ]);
+        }
+        return tasks.get(id);
+      }
+      // Not ours — poll the persisted store until the owning instance settles
+      // it or the wait elapses (still returns honest "running" state then).
+      const deadline = Date.now() + waitMs;
+      for (;;) {
+        const saved = storeTask(id);
+        if (!saved || saved.status !== "running") return saved;
+        const remaining = deadline - Date.now();
+        if (remaining <= 0) return saved;
+        await new Promise<void>((resolve) =>
+          setTimeout(resolve, Math.min(STORE_POLL_MS, remaining)),
+        );
+      }
+    },
+  };
+}

package/src/attachments.ts

@@ -0,0 +1,109 @@
+// The chat-attachment contract for smuggling media past eve's text/json-only
+// tool results. `read`/`webfetch` put a ChatAttachment on their raw execute()
+// return under CHAT_ATTACHMENT_FIELD — a field the model never sees (stripped
+// by the tool's toModelOutput) — and a connected client (or the park-delivery
+// hook) reads it off the tool-result event (action.result / the reducer's
+// dynamic-tool.output) and re-injects the media as a real user message part on
+// the next turn.
+//
+// This module is deliberately dependency-free (no node:*, no extraction deps),
+// so UI clients can import it via the `@zocomputer/agent-sdk/attachments`
+// subpath without pulling the package's PDF/DOCX/spreadsheet graph into a
+// browser bundle.
+
+/** The result field carrying the model-hidden attachment. */
+export const CHAT_ATTACHMENT_FIELD = "chatAttachment" as const;
+
+/**
+ * Default cap for inlining image bytes on a `read`/`webfetch` result: 3 MiB,
+ * matching eve's attachment-staging hydration cap (`shouldInlineSandboxRefAsBytes`,
+ * eve ≤0.19: images ≤3 MiB inline at model-call time; bigger ones hydrate as a
+ * text stub). Staying under it keeps read's "queued" promise truthful on every
+ * runtime — a bigger image gets the honest metadata-only note instead of
+ * silently degrading after delivery.
+ */
+export const DEFAULT_MAX_INLINE_IMAGE_BYTES = 3 * 1024 * 1024;
+
+/**
+ * Default cap for inlining video/audio bytes: 10 MB, matching read's stat
+ * guard (bigger files never reach the attach decision). Bounds durable-stream
+ * bloat — the data URL rides the stream once per read/fetch.
+ */
+export const DEFAULT_MAX_INLINE_MEDIA_BYTES = 10 * 1024 * 1024;
+
+/** Media kinds the attachment contract carries. Image delivery works with
+ * every vision model; video/audio are provider-gated (the read/webfetch
+ * factories only attach them when the consumer opts in). */
+export type ChatAttachmentKind = "image" | "video" | "audio";
+
+export type ChatAttachment =
+  | {
+      readonly kind: "image";
+      /** A `data:` URL (base64) — drop straight into an AI SDK file part's `data`. */
+      readonly dataUrl: string;
+      /** e.g. `image/png`, `image/jpeg`. */
+      readonly mediaType: string;
+      readonly filename: string;
+      readonly width: number | null;
+      readonly height: number | null;
+    }
+  | {
+      readonly kind: "video";
+      readonly dataUrl: string;
+      /** e.g. `video/mp4`, `video/webm`. */
+      readonly mediaType: string;
+      readonly filename: string;
+    }
+  | {
+      readonly kind: "audio";
+      readonly dataUrl: string;
+      /** e.g. `audio/mpeg`, `audio/wav`. */
+      readonly mediaType: string;
+      readonly filename: string;
+    };
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Read the model-hidden media attachment off a tool result, if present.
+ * Matches by payload shape, not tool name, so it's agnostic to what a
+ * consumer named its read tool. Returns null for any result without a valid
+ * attachment.
+ */
+export function readChatAttachment(toolOutput: unknown): ChatAttachment | null {
+  if (!isRecord(toolOutput)) return null;
+  const raw = toolOutput[CHAT_ATTACHMENT_FIELD];
+  if (!isRecord(raw)) return null;
+  if (typeof raw.dataUrl !== "string" || raw.dataUrl.length === 0) return null;
+  if (typeof raw.mediaType !== "string" || raw.mediaType.length === 0) return null;
+  const base = {
+    dataUrl: raw.dataUrl,
+    mediaType: raw.mediaType,
+  };
+  switch (raw.kind) {
+    case "image":
+      return {
+        kind: "image",
+        ...base,
+        filename: typeof raw.filename === "string" ? raw.filename : "image",
+        width: typeof raw.width === "number" ? raw.width : null,
+        height: typeof raw.height === "number" ? raw.height : null,
+      };
+    case "video":
+      return {
+        kind: "video",
+        ...base,
+        filename: typeof raw.filename === "string" ? raw.filename : "video",
+      };
+    case "audio":
+      return {
+        kind: "audio",
+        ...base,
+        filename: typeof raw.filename === "string" ? raw.filename : "audio",
+      };
+    default:
+      return null;
+  }
+}

package/src/backgroundable.ts

@@ -0,0 +1,88 @@
+import { z } from "zod";
+import type { CommandRunner } from "./run";
+
+// The set of operations run_async can launch in the background. This is the
+// generic mechanism: run_async dispatches by name into this registry, so
+// backgrounding "any tool" is a matter of registering it here — no bespoke
+// per-tool async twin. Register only the ops where waiting actually hurts (a
+// shell command); instant file ops stay synchronous, and mutating ops
+// (edit/write) stay out to avoid the agent racing its own edits.
+
+/** Optional live handles run_async threads into an op (e.g. a watcher tap). */
+export interface OpStartExtras {
+  /** Raw output tap; an op that produces no stream just ignores it. */
+  onOutput?: (chunk: string) => void;
+}
+
+// A registered op erases its input type behind a uniform surface: `start`
+// parses the raw tool input with the op's own schema (throwing a clear error on
+// bad input) and returns a label plus the in-flight promise. The parse lives
+// inside the closure, so the registry stays a plain array with no `any`.
+export interface BackgroundableOp {
+  readonly name: string;
+  readonly description: string;
+  /** JSON Schema of the op's input, surfaced so the model knows what to pass. */
+  readonly inputJsonSchema: unknown;
+  start(
+    rawInput: unknown,
+    extras?: OpStartExtras,
+  ): { label: string; work: Promise<unknown>; progress?: () => unknown };
+}
+
+export function defineOp<I>(cfg: {
+  name: string;
+  description: string;
+  inputSchema: z.ZodType<I>;
+  label: (input: I) => string;
+  run: (
+    input: I,
+    extras?: OpStartExtras,
+  ) => Promise<unknown> | { work: Promise<unknown>; progress?: () => unknown };
+}): BackgroundableOp {
+  return {
+    name: cfg.name,
+    description: cfg.description,
+    inputJsonSchema: z.toJSONSchema(cfg.inputSchema),
+    start(rawInput, extras) {
+      const parsed = cfg.inputSchema.safeParse(rawInput);
+      if (!parsed.success) {
+        throw new Error(`Invalid input for "${cfg.name}": ${parsed.error.message}`);
+      }
+      const started = cfg.run(parsed.data, extras);
+      if (started instanceof Promise) return { label: cfg.label(parsed.data), work: started };
+      return { label: cfg.label(parsed.data), ...started };
+    },
+  };
+}
+
+function truncate(s: string, max = 80): string {
+  const oneLine = s.replace(/\s+/g, " ").trim();
+  return oneLine.length > max ? `${oneLine.slice(0, max)}…` : oneLine;
+}
+
+// The one op every agent wants backgroundable: a shell command through the
+// stdlib's runner. Agents with their own long-running ops append to the array
+// this feeds (see createStdlib's `backgroundables`).
+export function createBashOp(runner: CommandRunner): BackgroundableOp {
+  return defineOp({
+    name: "bash",
+    description:
+      "Run a shell command in the background (git, bun, tests, builds, installs, dev servers). Same as the bash tool, but non-blocking.",
+    inputSchema: z.object({
+      command: z.string().min(1),
+      cwd: z.string().optional(),
+      // Background work is meant to be long; default the kill timeout higher
+      // than the synchronous bash tool's 120s.
+      timeout_ms: z.number().int().positive().optional(),
+    }),
+    label: ({ command }) => truncate(command),
+    run: ({ command, cwd, timeout_ms }, extras) => {
+      const running = runner.startCommand(command, {
+        cwd,
+        timeoutMs: timeout_ms ?? 600_000,
+        onOutput: extras?.onOutput,
+      });
+      return { work: running.result, progress: running.progress };
+    },
+  });
+}

package/src/bounded-output.ts

@@ -0,0 +1,159 @@
+import { appendFileSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+
+// Bounded stream capture for shell output. The old capture kept a 100k-char
+// head and stopped accumulating — the tail (where test runners print the
+// failure summary) was gone forever. This keeps head AND tail within a fixed
+// in-context budget and, on first overflow, spills the *complete* output to a
+// file the model can grep/read instead of re-running the command (opencode's
+// truncate-with-spill design). See plans/ben/rib-speed-opencode-lessons.md.
+
+export const HEAD_CHARS = 25_000;
+export const TAIL_CHARS = 25_000;
+
+// Directory name for spilled outputs under the agent's state dir. Exported so
+// retention sweeps (e.g. rib's) can find and prune old spills.
+export const TOOL_OUTPUT_DIRNAME = "tool-outputs";
+
+export interface CaptureSnapshot {
+  /** Bounded text; when truncated, head + a marker naming the spill file + tail. */
+  readonly text: string;
+  readonly totalChars: number;
+  readonly truncated: boolean;
+  /** Absolute path of the complete output, when spilled successfully. */
+  readonly spillPath: string | null;
+}
+
+export interface BoundedCapture {
+  append(chunk: string): void;
+  snapshot(): CaptureSnapshot;
+  /** The most recent text we hold: the whole output until overflow, the rolling tail after. */
+  latest(): string;
+  totalChars(): number;
+}
+
+// The head/tail cuts index UTF-16 code units, so a naive slice can land inside
+// a surrogate pair and leave a lone surrogate in the transcript (which then
+// breaks JSON encoding to the model API). Nudge every cut off a pair boundary:
+// a head cut never ends on a high surrogate, a tail cut never starts on a low.
+const isHighSurrogate = (code: number): boolean => code >= 0xd800 && code <= 0xdbff;
+const isLowSurrogate = (code: number): boolean => code >= 0xdc00 && code <= 0xdfff;
+
+const endsOnHighSurrogate = (text: string): boolean =>
+  text.length > 0 && isHighSurrogate(text.charCodeAt(text.length - 1));
+
+/** Last `cap` chars of `text`, moved one right if that would open on a low surrogate. */
+function takeTail(text: string, cap: number): string {
+  if (text.length <= cap) return text;
+  let start = text.length - cap;
+  if (isLowSurrogate(text.charCodeAt(start))) start += 1;
+  return text.slice(start);
+}
+
+export function createBoundedCapture(
+  opts: {
+    headChars?: number;
+    tailChars?: number;
+    /** Absolute file path for the complete output; created lazily on first overflow. Omit to disable spilling. */
+    spillPath?: string;
+    /** How the marker names the spill file (e.g. repo-relative path). Defaults to `spillPath`. */
+    spillLabel?: string;
+  } = {},
+): BoundedCapture {
+  const headCap = opts.headChars ?? HEAD_CHARS;
+  const tailCap = opts.tailChars ?? TAIL_CHARS;
+  let head = "";
+  let tail = "";
+  let total = 0;
+  let overflowed = false;
+  // Three-state spill: not started, live, or failed (a failed spill degrades
+  // to bounded-without-file rather than erroring the command).
+  let spill: "none" | "live" | "failed" = opts.spillPath ? "none" : "failed";
+
+  // A surrogate pair split across appends would hit the UTF-8 file write as a
+  // lone surrogate and encode as U+FFFD; hold the high half until its partner
+  // arrives so the spill file stays byte-faithful.
+  let spillCarry = "";
+
+  const writeSpill = (chunk: string, first: boolean): void => {
+    if (spill === "failed" || opts.spillPath === undefined) return;
+    let text = spillCarry + chunk;
+    if (endsOnHighSurrogate(text)) {
+      spillCarry = text.slice(-1);
+      text = text.slice(0, -1);
+    } else {
+      spillCarry = "";
+    }
+    try {
+      if (first) {
+        mkdirSync(dirname(opts.spillPath), { recursive: true });
+        writeFileSync(opts.spillPath, text);
+        spill = "live";
+      } else {
+        appendFileSync(opts.spillPath, text);
+      }
+    } catch {
+      spill = "failed";
+    }
+  };
+
+  return {
+    append(chunk) {
+      total += chunk.length;
+      if (!overflowed) {
+        const room = headCap - head.length;
+        if (chunk.length <= room) {
+          head += chunk;
+          return;
+        }
+        overflowed = true;
+        // Don't cut through a surrogate pair inside this chunk…
+        let cut = room;
+        if (cut > 0 && isHighSurrogate(chunk.charCodeAt(cut - 1))) cut -= 1;
+        head += chunk.slice(0, cut);
+        // …and don't freeze a head that ends on one either (a pair can also be
+        // split across appends: the previous chunk filled the head exactly and
+        // ended on the high half). Move the orphan into the tail stream.
+        let remainder = chunk.slice(cut);
+        if (endsOnHighSurrogate(head)) {
+          remainder = head.slice(-1) + remainder;
+          head = head.slice(0, -1);
+        }
+        // The spill file starts as everything seen so far, so it's always complete.
+        writeSpill(head + remainder, true);
+        tail = takeTail(remainder, tailCap);
+        return;
+      }
+      writeSpill(chunk, false);
+      tail = takeTail(tail + chunk, tailCap);
+    },
+    snapshot() {
+      if (!overflowed) {
+        return { text: head, totalChars: total, truncated: false, spillPath: null };
+      }
+      if (head.length + tail.length === total) {
+        // Head overflowed but the tail still holds the rest — contiguous,
+        // complete. Checked by length (not caps): a surrogate nudge can move a
+        // char from head into a tail that then trims, and that loss must
+        // surface as truncation.
+        return { text: head + tail, totalChars: total, truncated: false, spillPath: null };
+      }
+      const where =
+        spill === "live" ? `; full output: ${opts.spillLabel ?? opts.spillPath}` : "";
+      // Actual lengths, not the caps — surrogate nudges can run a char short.
+      const marker = `\n… [output truncated: showing first ${head.length} and last ${tail.length} of ${total} chars${where}]\n`;
+      return {
+        text: `${head}${marker}${tail}`,
+        totalChars: total,
+        truncated: true,
+        spillPath: spill === "live" && opts.spillPath !== undefined ? opts.spillPath : null,
+      };
+    },
+    latest() {
+      return overflowed ? tail : head;
+    },
+    totalChars() {
+      return total;
+    },
+  };
+}