@zocomputer/agent-sdk 0.5.0

package/src/park-delivery.ts

@@ -0,0 +1,247 @@
+// Generic park-delivery: queue items for a session and release them as one
+// batch exactly when the session is parked (`session.waiting`) and reachable
+// (a continuation token has been seen). Two producers ride this core today —
+// read-image redelivery (./redeliver.ts, items observed off stream events)
+// and background-task notifications (./watch-output.ts matches posted through
+// the bridge below) — and the effectful hook (./hooks.ts) performs the sends.
+//
+// eve hooks are observe-only for model context, so "delivery" means starting
+// the session's NEXT turn, exactly like a user hitting send. Two paths emit a
+// request:
+// - `observe` — a `session.waiting` event arrives with items pending.
+// - `enqueue` — an item arrives while the session is ALREADY parked (a
+//   background task matching its watcher mid-park; no further stream events
+//   will fire until something starts a turn, so the enqueue itself must
+//   trigger the send).
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Recover the client-facing continuation token from a hook's runtime one.
+ * eve namespaces the runtime token as `<namespace>:<client token>` (its
+ * `namespaceContinuationToken` treats everything before the FIRST colon as the
+ * namespace; the default HTTP channel's client token is itself `eve:<uuid>`,
+ * so the runtime form is `eve:eve:<uuid>`). The continue route wants the
+ * client token — sending the namespaced form silently creates a NEW session.
+ */
+export function clientContinuationToken(runtimeToken: string): string {
+  const sep = runtimeToken.indexOf(":");
+  if (sep <= 0) return runtimeToken;
+  const rest = runtimeToken.slice(sep + 1);
+  // A client token itself carries a scheme prefix (`eve:<uuid>`). If the
+  // remainder has no colon, the input was already client-facing — keep it.
+  return rest.includes(":") ? rest : runtimeToken;
+}
+
+export interface ParkDeliveryItem<T> {
+  /** Dedupe key: an item delivers at most once per session per process. */
+  readonly key: string;
+  readonly payload: T;
+}
+
+export interface ParkDeliveryRequest<T> {
+  readonly sessionId: string;
+  readonly continuationToken: string;
+  readonly items: readonly ParkDeliveryItem<T>[];
+}
+
+/**
+ * Per-process delivery state across sessions. Feed it every stream event via
+ * `observe`; queue items with `enqueue`. Either returns a request exactly when
+ * a parked, reachable session has items to deliver. The caller performs the
+ * send and reports back with `settle` — on failure the items re-queue.
+ *
+ * Dedup is by item key for the session's lifetime in this process, so an item
+ * never delivers twice even if a failed send races a user message.
+ */
+export function createParkDeliveryState<T>() {
+  interface SessionState {
+    pending: Map<string, ParkDeliveryItem<T>>;
+    delivered: Set<string>;
+    continuationToken?: string;
+    parked: boolean;
+    delivering: boolean;
+  }
+  const sessions = new Map<string, SessionState>();
+
+  function session(id: string): SessionState {
+    let state = sessions.get(id);
+    if (!state) {
+      state = { pending: new Map(), delivered: new Set(), parked: false, delivering: false };
+      sessions.set(id, state);
+    }
+    return state;
+  }
+
+  function drain(id: string, state: SessionState): ParkDeliveryRequest<T> | null {
+    if (state.pending.size === 0 || !state.continuationToken || state.delivering) return null;
+    // Move pending → delivered optimistically; `settle(ok: false)` re-queues.
+    const items = [...state.pending.values()];
+    state.pending.clear();
+    for (const item of items) state.delivered.add(item.key);
+    state.delivering = true;
+    return { sessionId: id, continuationToken: state.continuationToken, items };
+  }
+
+  /**
+   * Queue several items at once — all of them enter pending before any drain,
+   * so a batch enqueued into an already-parked session goes out as ONE
+   * delivery. Enqueuing the same batch item-by-item would let the first
+   * item's immediate flush strand the rest into a second turn.
+   */
+  function enqueueAll(
+    sessionId: string,
+    items: readonly ParkDeliveryItem<T>[],
+  ): ParkDeliveryRequest<T> | null {
+    const state = session(sessionId);
+    let queued = false;
+    for (const item of items) {
+      if (state.delivered.has(item.key) || state.pending.has(item.key)) continue;
+      state.pending.set(item.key, item);
+      queued = true;
+    }
+    if (!queued || !state.parked) return null;
+    return drain(sessionId, state);
+  }
+
+  return {
+    /**
+     * Consume one stream event. `continuationToken` is the hook's runtime
+     * (namespaced) token when known — latest wins; it's translated to the
+     * client-facing token the continue route accepts.
+     */
+    observe(
+      event: unknown,
+      meta: { readonly sessionId: string; readonly continuationToken?: string | undefined },
+    ): ParkDeliveryRequest<T> | null {
+      const state = session(meta.sessionId);
+      if (meta.continuationToken) {
+        state.continuationToken = clientContinuationToken(meta.continuationToken);
+      }
+      if (!isRecord(event)) return null;
+      if (event.type === "session.completed" || event.type === "session.failed") {
+        sessions.delete(meta.sessionId);
+        return null;
+      }
+      // Any non-waiting event means the session is active again; only a
+      // `session.waiting` (the park) makes it deliverable.
+      if (event.type !== "session.waiting") {
+        state.parked = false;
+        return null;
+      }
+      state.parked = true;
+      return drain(meta.sessionId, state);
+    },
+
+    /**
+     * Queue an item for a session. Returns a request immediately when the
+     * session is currently parked and reachable — the caller must perform
+     * that send (no later stream event will fire to flush it). An item whose
+     * key was already delivered (or is already pending) is dropped.
+     */
+    enqueue(sessionId: string, item: ParkDeliveryItem<T>): ParkDeliveryRequest<T> | null {
+      return enqueueAll(sessionId, [item]);
+    },
+
+    enqueueAll,
+
+    /**
+     * Report the send outcome. A failed send re-queues for the next park.
+     * Returns a new request when items queued during the just-finished delivery
+     * need immediate dispatch (the session is still parked).
+     */
+    settle(request: ParkDeliveryRequest<T>, ok: boolean): ParkDeliveryRequest<T> | null {
+      const state = session(request.sessionId);
+      state.delivering = false;
+      if (ok) {
+        // Items may have queued while we were delivering; drain them now if
+        // the session is still parked (no stream event will fire for them).
+        if (state.parked) return drain(request.sessionId, state);
+        return null;
+      }
+      for (const item of request.items) {
+        state.delivered.delete(item.key);
+        state.pending.set(item.key, item);
+      }
+      return null;
+    },
+  };
+}
+
+export type ParkDeliveryState<T> = ReturnType<typeof createParkDeliveryState<T>>;
+
+// ---------------------------------------------------------------------------
+// Notification bridge: how tool code (bash watchers, run_async completion
+// notices) reaches the hook's delivery state from another module graph.
+// Process-global and deduped on globalThis for the same reason as the task
+// registry (see ./async-tasks.ts): eve's mid-session rebuilds duplicate module
+// graphs, and a notification posted into one copy must reach the hook created
+// in another. Posts made before any hook exists queue (bounded) and flush when
+// the hook registers its handler.
+
+/** A background notification for the model, delivered as its next user turn. */
+export interface ParkNotification {
+  /** Dedupe key (e.g. `task_3#2`); one delivery per key per session. */
+  readonly key: string;
+  /** The message text, complete and self-describing. */
+  readonly text: string;
+}
+
+interface NotificationBridge {
+  queued: Map<string, ParkNotification[]>;
+  handler: ((sessionId: string, notification: ParkNotification) => void) | null;
+}
+
+const BRIDGE_KEY = Symbol.for("zocomputer.agent-sdk.park-notification-bridge");
+// A session with no hook wired keeps at most this many queued notifications.
+const MAX_QUEUED_PER_SESSION = 20;
+
+function bridge(): NotificationBridge {
+  const holder = globalThis as { [BRIDGE_KEY]?: NotificationBridge };
+  holder[BRIDGE_KEY] ??= { queued: new Map(), handler: null };
+  return holder[BRIDGE_KEY];
+}
+
+/** Test-only: drop the process-global bridge (handler + queued posts). */
+export function __resetParkNotificationBridgeForTests(): void {
+  const holder = globalThis as { [BRIDGE_KEY]?: NotificationBridge };
+  delete holder[BRIDGE_KEY];
+}
+
+/**
+ * Post a notification for a session. Delivered by the park-delivery hook when
+ * the session parks (immediately, if it's parked right now). Without a hook
+ * the post queues — bounded per session — and flushes when one registers.
+ */
+export function postParkNotification(
+  sessionId: string,
+  notification: ParkNotification,
+): void {
+  const b = bridge();
+  if (b.handler) {
+    b.handler(sessionId, notification);
+    return;
+  }
+  const queue = b.queued.get(sessionId) ?? [];
+  if (queue.length >= MAX_QUEUED_PER_SESSION) return;
+  queue.push(notification);
+  b.queued.set(sessionId, queue);
+}
+
+/**
+ * Register the hook-side consumer (latest registration wins — a rebuilt hook
+ * replaces its stale copy). Flushes any posts queued before registration.
+ */
+export function setParkNotificationHandler(
+  handler: (sessionId: string, notification: ParkNotification) => void,
+): void {
+  const b = bridge();
+  b.handler = handler;
+  const queued = [...b.queued.entries()];
+  b.queued.clear();
+  for (const [sessionId, notifications] of queued) {
+    for (const notification of notifications) handler(sessionId, notification);
+  }
+}

package/src/path-locks.ts

@@ -0,0 +1,52 @@
+// Per-path serialization for the mutating file tools (`edit`, `write`).
+//
+// eve runs a step's tool calls concurrently (`Promise.all`), so a model that
+// batches two `edit` calls against the same file races them: both read the
+// file, both compute their replacement from the same original text, and the
+// second write silently discards the first edit — while both results report
+// success. Serializing the whole read-modify-write critical section per
+// absolute path makes batched same-file edits apply in call order instead:
+// the second edit reads the first one's output, and if the first edit removed
+// the second's `old_string`, the second fails loudly ("not found") instead of
+// silently clobbering.
+//
+// The lock chain lives on `globalThis` (via `Symbol.for`) for the same reason
+// as the task registry (see `async-tasks.ts`): eve's mid-session rebuild forks
+// module-level state across module-graph copies, and two lock maps would
+// serialize nothing.
+
+const LOCKS_KEY = Symbol.for("zocomputer.agent-sdk.path-locks");
+
+function lockChains(): Map<string, Promise<void>> {
+  const holder = globalThis as { [LOCKS_KEY]?: Map<string, Promise<void>> };
+  holder[LOCKS_KEY] ??= new Map();
+  return holder[LOCKS_KEY];
+}
+
+/**
+ * Run `fn` exclusively among all `withPathLock` calls for the same `path` in
+ * this process. Callers queue FIFO; a thrown error releases the lock and
+ * propagates without breaking the chain for later callers.
+ */
+export async function withPathLock<T>(path: string, fn: () => Promise<T>): Promise<T> {
+  const chains = lockChains();
+  const prev = chains.get(path) ?? Promise.resolve();
+  let release!: () => void;
+  const gate = new Promise<void>((resolve) => {
+    release = resolve;
+  });
+  // The stored chain resolves only when our critical section finishes, so the
+  // next caller's `await prev` blocks until then. `gate` always resolves (in
+  // the finally), so the chain never rejects and can't poison later callers.
+  const chained = prev.then(() => gate);
+  chains.set(path, chained);
+  await prev;
+  try {
+    return await fn();
+  } finally {
+    release();
+    // Drop the entry once no later caller has chained onto us, so the map
+    // doesn't grow with every path ever touched in a long session.
+    if (chains.get(path) === chained) chains.delete(path);
+  }
+}

package/src/read-file-content.ts

@@ -0,0 +1,142 @@
+import { imageSize } from "image-size";
+import {
+  type AudioFormat,
+  detectFileKind,
+  type ImageFormat,
+  type SheetFormat,
+  type TextEncoding,
+  type VideoFormat,
+} from "./file-kind";
+import { createStatCache, type StatIdentity } from "./extract/cache";
+import { extractDocx } from "./extract/docx";
+import { extractPdf } from "./extract/pdf";
+import { extractSheets, type SheetMeta } from "./extract/sheet";
+
+// Content routing for the `read` tool: sniff the bytes, then hand back either
+// the text to window (native or extracted from PDF/DOCX/spreadsheets),
+// image/video/audio metadata, or a thrown error for binaries with no text
+// rendering. Kept free of the workspace module so tests can feed fixture
+// paths directly.
+
+export type FileContent =
+  | { readonly kind: "text"; readonly text: string }
+  | { readonly kind: "pdf"; readonly text: string; readonly pages: number }
+  | { readonly kind: "docx"; readonly text: string }
+  | {
+      readonly kind: "sheet";
+      readonly format: SheetFormat;
+      readonly text: string;
+      readonly sheets: readonly SheetMeta[];
+    }
+  | {
+      readonly kind: "image";
+      readonly format: ImageFormat;
+      readonly width: number | null;
+      readonly height: number | null;
+    }
+  | { readonly kind: "video"; readonly format: VideoFormat }
+  | { readonly kind: "audio"; readonly format: AudioFormat };
+
+type ExtractedDoc = Exclude<FileContent, { kind: "text" } | { kind: "image" }>;
+type ExtractableKind =
+  | { readonly kind: "pdf" }
+  | { readonly kind: "docx" }
+  | { readonly kind: "sheet"; readonly format: SheetFormat };
+
+// Extraction is pure parsing, so cache by path + stat identity: re-reading a
+// PDF to page through it (offset/limit) shouldn't re-run PDFium every call.
+// Failures throw out of `compute` and are never cached.
+const EXTRACTION_CACHE_LIMIT = 20;
+const extractionCache = createStatCache<ExtractedDoc>(EXTRACTION_CACHE_LIMIT);
+
+function decodeText(buffer: Buffer, encoding: TextEncoding): string {
+  switch (encoding) {
+    case "utf8":
+      return buffer.toString("utf8");
+    case "utf16le":
+      // Strip the BOM the detector matched on; it isn't content.
+      return buffer.toString("utf16le").replace(/^\uFEFF/, "");
+    case "utf16be": {
+      // Node has no utf16be decoder; byte-swap a copy and decode as LE.
+      const swapped = Buffer.from(buffer).swap16();
+      return swapped.toString("utf16le").replace(/^\uFEFF/, "");
+    }
+  }
+}
+
+async function extractDocument(
+  detected: ExtractableKind,
+  buffer: Buffer,
+  path: string,
+): Promise<ExtractedDoc> {
+  switch (detected.kind) {
+    case "pdf": {
+      const result = await extractPdf(buffer);
+      if (!result.ok) throw new Error(`Could not extract text from PDF ${path}: ${result.reason}`);
+      return { kind: "pdf", text: result.text, pages: result.pages };
+    }
+    case "docx": {
+      const result = await extractDocx(buffer);
+      if (!result.ok) {
+        throw new Error(`Could not extract text from DOCX ${path}: ${result.reason}`);
+      }
+      return { kind: "docx", text: result.text };
+    }
+    case "sheet": {
+      const result = extractSheets(buffer);
+      if (!result.ok) {
+        throw new Error(`Could not extract data from spreadsheet ${path}: ${result.reason}`);
+      }
+      return { kind: "sheet", format: detected.format, text: result.text, sheets: result.sheets };
+    }
+  }
+}
+
+/**
+ * Route a file's bytes to renderable content. `path` labels error messages,
+ * disambiguates container formats by extension, and keys the extraction cache.
+ * Throws for binaries with no text rendering (the tool-error path).
+ */
+export async function loadFileContent(
+  buffer: Buffer,
+  path: string,
+  id: StatIdentity,
+): Promise<FileContent> {
+  const detected = detectFileKind(buffer, path);
+  switch (detected.kind) {
+    case "text":
+      return { kind: "text", text: decodeText(buffer, detected.encoding) };
+    case "pdf":
+    case "docx":
+    case "sheet":
+      return extractionCache.get(path, id, () => extractDocument(detected, buffer, path));
+    case "image": {
+      // Magic bytes matched but the body may still be truncated/corrupt —
+      // dimensions are best-effort, the metadata result is useful either way.
+      let size: { width: number; height: number } | null = null;
+      try {
+        size = imageSize(buffer);
+      } catch {
+        size = null;
+      }
+      return {
+        kind: "image",
+        format: detected.format,
+        width: size?.width ?? null,
+        height: size?.height ?? null,
+      };
+    }
+    // No probing for duration/dimensions — container parsing isn't worth a
+    // dep; the metadata result carries format + size and the bytes ride the
+    // attachment contract when the consumer opted in.
+    case "video":
+      return { kind: "video", format: detected.format };
+    case "audio":
+      return { kind: "audio", format: detected.format };
+    case "binary":
+      throw new Error(
+        `${path} is ${detected.description} — read returns text only. ` +
+          "Use bash (unzip -l, strings, xxd) to inspect it if needed.",
+      );
+  }
+}

package/src/read-text.ts

@@ -0,0 +1,40 @@
+import { readFileSync, statSync } from "node:fs";
+
+// Search tools skip anything bigger — no source file we'd grep comes close,
+// and the cap keeps a stray artifact from stalling a search.
+export const MAX_SEARCH_FILE_BYTES = 1_500_000;
+
+// A NUL byte in the first 8 KB marks a file binary — the same heuristic git
+// and ripgrep use.
+const BINARY_SNIFF_BYTES = 8_192;
+
+export type SearchRead =
+  | { kind: "text"; content: string }
+  | { kind: "too-large"; bytes: number }
+  | { kind: "binary" }
+  | { kind: "unreadable" };
+
+// Bounded read for search: stat before read so an oversized file is skipped
+// without touching its bytes, and sniff raw bytes for NUL before decoding.
+export function readTextForSearch(
+  abs: string,
+  maxBytes: number = MAX_SEARCH_FILE_BYTES,
+): SearchRead {
+  let size: number;
+  try {
+    const stats = statSync(abs);
+    if (!stats.isFile()) return { kind: "unreadable" };
+    size = stats.size;
+  } catch {
+    return { kind: "unreadable" };
+  }
+  if (size > maxBytes) return { kind: "too-large", bytes: size };
+  let buf: Buffer;
+  try {
+    buf = readFileSync(abs);
+  } catch {
+    return { kind: "unreadable" };
+  }
+  if (buf.subarray(0, BINARY_SNIFF_BYTES).includes(0)) return { kind: "binary" };
+  return { kind: "text", content: buf.toString("utf8") };
+}

package/src/redeliver.ts

@@ -0,0 +1,155 @@
+// Media redelivery: decide, from the runtime event stream, when a read
+// image/video/audio file should be re-sent to the session as a real user
+// message part.
+//
+// eve tool results are text/json, so `read` smuggles media bytes out on its raw
+// result under CHAT_ATTACHMENT_FIELD (model-hidden via toModelOutput — see
+// ./attachments.ts). Hooks receive that raw output on `action.result`, and
+// `session.waiting` marks the session parked and deliverable. This module is
+// the media-flavored client of the generic park-delivery core
+// (./park-delivery.ts): extraction + message shape live here, the
+// queue/park/settle state machine lives there, and the effectful hook
+// (./hooks.ts) performs the actual send.
+
+import {
+  readChatAttachment,
+  type ChatAttachment,
+} from "./attachments";
+import {
+  clientContinuationToken,
+  createParkDeliveryState,
+} from "./park-delivery";
+
+export { clientContinuationToken };
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export interface PendingRedelivery {
+  readonly toolCallId: string;
+  readonly attachment: ChatAttachment;
+}
+
+/**
+ * Extract a read-media attachment from an `action.result` stream event, if the
+ * completed tool's raw output carries one. Structural (no eve types) and
+ * tool-name-agnostic: any tool that returns a `CHAT_ATTACHMENT_FIELD` payload
+ * participates.
+ */
+export function redeliveryFromEvent(event: unknown): PendingRedelivery | null {
+  if (!isRecord(event) || event.type !== "action.result") return null;
+  if (!isRecord(event.data)) return null;
+  const result = event.data.result;
+  if (!isRecord(result) || result.kind !== "tool-result") return null;
+  if (typeof result.callId !== "string" || result.callId.length === 0) return null;
+  const attachment = readChatAttachment(result.output);
+  if (!attachment) return null;
+  return { toolCallId: result.callId, attachment };
+}
+
+/** The message parts a redelivery turn sends (AI SDK `UserContent`-shaped). */
+export type RedeliveryMessagePart =
+  | { readonly type: "text"; readonly text: string }
+  | {
+      readonly type: "file";
+      readonly data: string;
+      readonly mediaType: string;
+      readonly filename: string;
+    };
+
+/**
+ * Build the user turn that carries the pending media. A short text part names
+ * the files (so transcripts show what arrived); the file parts carry the
+ * bytes the model was promised by read's "queued" note.
+ */
+export function buildRedeliveryMessage(
+  pending: readonly PendingRedelivery[],
+): RedeliveryMessagePart[] {
+  const names = pending.map((p) => p.attachment.filename).join(", ");
+  return [
+    { type: "text", text: `Attached: ${names} (auto-attached from read).` },
+    ...pending.map((p) => ({
+      type: "file" as const,
+      data: p.attachment.dataUrl,
+      mediaType: p.attachment.mediaType,
+      filename: p.attachment.filename,
+    })),
+  ];
+}
+
+export interface RedeliveryRequest {
+  readonly sessionId: string;
+  readonly continuationToken: string;
+  readonly pending: readonly PendingRedelivery[];
+}
+
+/**
+ * Per-process redelivery state across sessions: the generic park-delivery
+ * state machine specialized to read-media attachments. Feed it every stream
+ * event via `observe`; it returns a `RedeliveryRequest` exactly when a parked
+ * session has media to deliver. The caller performs the send and reports back
+ * with `settle` — on failure the media re-queue for the session's next park.
+ *
+ * Dedup is by tool call id for the session's lifetime in this process, so an
+ * attachment never delivers twice even if a failed send races a user message.
+ */
+export function createRedeliveryState() {
+  const core = createParkDeliveryState<ChatAttachment>();
+
+  function toRequest(
+    request: ReturnType<typeof core.observe>,
+  ): RedeliveryRequest | null {
+    if (!request) return null;
+    return {
+      sessionId: request.sessionId,
+      continuationToken: request.continuationToken,
+      pending: request.items.map((item) => ({
+        toolCallId: item.key,
+        attachment: item.payload,
+      })),
+    };
+  }
+
+  return {
+    /**
+     * Consume one stream event. `continuationToken` is the hook's runtime
+     * (namespaced) token when known — latest wins; it's translated to the
+     * client-facing token the continue route accepts.
+     */
+    observe(
+      event: unknown,
+      meta: { readonly sessionId: string; readonly continuationToken?: string },
+    ): RedeliveryRequest | null {
+      // Observe first: an attachment always arrives on an action.result (a
+      // non-waiting event), so enqueue never fires an immediate delivery here
+      // — media release on the park, exactly as before the extraction.
+      const request = toRequest(core.observe(event, meta));
+      const found = redeliveryFromEvent(event);
+      if (found) {
+        core.enqueue(meta.sessionId, {
+          key: found.toolCallId,
+          payload: found.attachment,
+        });
+      }
+      return request;
+    },
+
+    /** Report the send outcome; a failed send re-queues for the next park. */
+    settle(request: RedeliveryRequest, ok: boolean): void {
+      core.settle(
+        {
+          sessionId: request.sessionId,
+          continuationToken: request.continuationToken,
+          items: request.pending.map((p) => ({
+            key: p.toolCallId,
+            payload: p.attachment,
+          })),
+        },
+        ok,
+      );
+    },
+  };
+}
+
+export type RedeliveryState = ReturnType<typeof createRedeliveryState>;