@zocomputer/agent-sdk 0.5.0

package/src/file-view.ts

@@ -0,0 +1,80 @@
+// Bounded windowing for `read`. Tool results enter the transcript
+// permanently — an unbounded file read is the single biggest uncontrolled
+// token source once the prompt prefix is stable — so every read gets a
+// default line limit, a per-line cap, and a total character budget
+// (opencode's 2000-line / 50 KB tool-output budget, adapted). See
+// plans/ben/rib-speed-opencode-lessons.md.
+
+// Default window when the caller passes no `limit`.
+export const READ_FILE_DEFAULT_LINE_LIMIT = 2_000;
+// A single line longer than this (minified bundles, data blobs) is clipped.
+export const READ_FILE_MAX_LINE_CHARS = 2_000;
+// Total budget for the numbered content of one call.
+export const READ_FILE_MAX_CONTENT_CHARS = 50_000;
+// `read` refuses files bigger than this outright (stat guard — the file
+// is never read); the model is steered to `bash` for surgical extraction.
+export const READ_FILE_MAX_BYTES = 10_000_000;
+
+export interface FileView {
+  readonly totalLines: number;
+  /** 1-based first line of the window. */
+  readonly startLine: number;
+  /** 1-based last line included; `startLine - 1` when the window is empty. */
+  readonly endLine: number;
+  /** Line-numbered content, `NNNNNN|text` per line. */
+  readonly content: string;
+  /** True when the view was cut short of the requested window (budget) or a line was clipped. */
+  readonly truncated: boolean;
+  /** Continuation guidance when there is more file past `endLine`, else null. */
+  readonly note: string | null;
+}
+
+/** Build the bounded, line-numbered window of `text` for a read result. */
+export function buildFileView(
+  text: string,
+  opts: { offset?: number | undefined; limit?: number | undefined } = {},
+): FileView {
+  const lines = text.split("\n");
+  const start = opts.offset ? opts.offset - 1 : 0;
+  const requestedEnd = Math.min(start + (opts.limit ?? READ_FILE_DEFAULT_LINE_LIMIT), lines.length);
+
+  const parts: string[] = [];
+  let chars = 0;
+  let included = 0;
+  let clippedLine = false;
+  let budgetStopped = false;
+  for (let i = start; i < requestedEnd; i++) {
+    const raw = lines[i];
+    if (raw === undefined) break;
+    const clipped =
+      raw.length > READ_FILE_MAX_LINE_CHARS
+        ? `${raw.slice(0, READ_FILE_MAX_LINE_CHARS)}… [line truncated]`
+        : raw;
+    if (clipped !== raw) clippedLine = true;
+    const numbered = `${String(i + 1).padStart(6)}|${clipped}`;
+    // Always include at least one line so a pathological first line still returns something.
+    if (included > 0 && chars + numbered.length + 1 > READ_FILE_MAX_CONTENT_CHARS) {
+      budgetStopped = true;
+      break;
+    }
+    parts.push(numbered);
+    chars += numbered.length + 1;
+    included += 1;
+  }
+
+  const endLine = start + included;
+  const note =
+    included === 0 && start >= lines.length
+      ? `Offset ${start + 1} is past the end of the file (${lines.length} lines).`
+      : endLine < lines.length
+        ? `Showing lines ${start + 1}–${endLine} of ${lines.length}${budgetStopped ? " (output budget reached)" : ""}. Continue with offset=${endLine + 1}, or use grep to locate what you need.`
+        : null;
+  return {
+    totalLines: lines.length,
+    startLine: start + 1,
+    endLine,
+    content: parts.join("\n"),
+    truncated: budgetStopped || clippedLine,
+    note,
+  };
+}

package/src/gateway-fetch.ts

@@ -0,0 +1,115 @@
+// Stream guards for the gateway fetch. Neither eve's `defineAgent` nor the AI
+// SDK's gateway provider exposes per-attempt timeouts, so a model call that
+// hangs — headers never arrive, or the SSE body goes quiet mid-stream — hangs
+// the turn forever (we measured a `step.started` that sat silent for good, and
+// a retry loop that burned 33 minutes on an unresponsive connection). The one
+// seam the provider does expose is `fetch`; this wrapper adds the two guards a
+// streaming call needs:
+//
+// - **first byte**: abort when response headers don't arrive in time (the
+//   request-level hang);
+// - **idle**: abort when the response body goes quiet between chunks (the
+//   mid-stream hang — a dropped connection the TCP stack never surfaces).
+//
+// A guard firing rejects/errors like any network failure, so the AI SDK's
+// normal retry-with-backoff takes over instead of waiting on a dead socket.
+
+type FetchLike = typeof globalThis.fetch;
+// The call signature alone: Bun's `typeof fetch` also carries `preconnect`,
+// which test doubles (and the wrapper itself) shouldn't have to fake.
+type FetchCall = (
+  input: Parameters<FetchLike>[0],
+  init?: Parameters<FetchLike>[1],
+) => Promise<Response>;
+
+export interface StreamGuardOptions {
+  /** Max wait for response headers, ms. */
+  readonly firstByteMs: number;
+  /** Max quiet gap between response-body chunks, ms. */
+  readonly idleMs: number;
+}
+
+// Generous on purpose: the point is to convert a *dead* connection into a
+// retryable error, not to race a slow-but-alive model. Headers should arrive
+// in seconds; reasoning models can legitimately pause between chunks, so the
+// idle guard gets minutes.
+export const DEFAULT_STREAM_GUARDS: StreamGuardOptions = {
+  firstByteMs: 60_000,
+  idleMs: 180_000,
+};
+
+/**
+ * Wrap a fetch with first-byte and idle timeouts. The returned fetch chains
+ * any caller-provided abort signal, preserves status/headers, and passes
+ * body-less responses through untouched.
+ */
+export function withStreamGuards(
+  baseFetch: FetchCall,
+  options: StreamGuardOptions = DEFAULT_STREAM_GUARDS,
+): FetchLike {
+  const guarded: FetchCall = async (input, init) => {
+    const controller = new AbortController();
+    const outer = init?.signal;
+    if (outer != null) {
+      if (outer.aborted) controller.abort(outer.reason);
+      else outer.addEventListener("abort", () => controller.abort(outer.reason), { once: true });
+    }
+
+    const firstByteTimer = setTimeout(() => {
+      controller.abort(
+        new Error(`gateway response headers not received within ${options.firstByteMs}ms`),
+      );
+    }, options.firstByteMs);
+
+    let response: Response;
+    try {
+      response = await baseFetch(input, { ...init, signal: controller.signal });
+    } finally {
+      clearTimeout(firstByteTimer);
+    }
+
+    const body = response.body;
+    if (body === null) return response;
+
+    // Re-wrap the body in a pull-based stream that races every read against
+    // the idle timer. The timer is per-read, so a healthy stream never pays
+    // more than one pending timeout, and a stalled one errors (and aborts the
+    // underlying request) after exactly `idleMs` of silence.
+    const reader = body.getReader();
+    const guarded = new ReadableStream<Uint8Array>({
+      async pull(streamController) {
+        let idleTimer: ReturnType<typeof setTimeout> | undefined;
+        const idle = new Promise<never>((_, reject) => {
+          idleTimer = setTimeout(() => {
+            const reason = new Error(`gateway stream idle for ${options.idleMs}ms`);
+            controller.abort(reason);
+            reject(reason);
+          }, options.idleMs);
+        });
+        try {
+          const result = await Promise.race([reader.read(), idle]);
+          if (result.done) streamController.close();
+          else streamController.enqueue(result.value);
+        } catch (error) {
+          await reader.cancel(error).catch(() => {});
+          throw error;
+        } finally {
+          clearTimeout(idleTimer);
+        }
+      },
+      async cancel(reason) {
+        await reader.cancel(reason).catch(() => {});
+      },
+    });
+
+    return new Response(guarded, {
+      status: response.status,
+      statusText: response.statusText,
+      headers: response.headers,
+    });
+  };
+  // Bun's `typeof fetch` requires `preconnect` (a DNS/TLS warm-up hint);
+  // delegate to the global's so the wrapper satisfies the type under both
+  // runtimes. Nothing on the request path calls it.
+  return Object.assign(guarded, { preconnect: globalThis.fetch.preconnect });
+}

package/src/glob-match.ts

@@ -0,0 +1,13 @@
+// Convert a glob to an anchored RegExp over forward-slash paths. `**` (or `**/`)
+// spans any number of directories; `*` matches within a single segment; `?` one
+// non-separator char. Pure and dependency-free so `glob`, `grep`, and their
+// tests all share one matcher.
+export function globToRegExp(glob: string): RegExp {
+  const escaped = glob.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+  const body = escaped
+    .replace(/\*\*\/?/g, "\u0000") // placeholder for "any dirs"
+    .replace(/\*/g, "[^/]*")
+    .replace(/\?/g, "[^/]")
+    .replace(/\u0000/g, "(?:.*/)?");
+  return new RegExp(`^${body}$`);
+}

package/src/hooks.ts

@@ -0,0 +1,213 @@
+import { Client } from "eve/client";
+import { defineHook } from "eve/hooks";
+import type { ChatAttachment } from "./attachments";
+import {
+  createParkDeliveryState,
+  setParkNotificationHandler,
+  type ParkDeliveryRequest,
+} from "./park-delivery";
+import {
+  buildRedeliveryMessage,
+  redeliveryFromEvent,
+  type RedeliveryMessagePart,
+} from "./redeliver";
+import type { SteerMessage } from "./steer";
+import { createSteerInbox } from "./steer-inbox";
+
+// The effectful half of park delivery (pure core: ./park-delivery.ts). An
+// agent wires it as one hook file:
+//
+//   // agent/hooks/park-delivery.ts
+//   import { createParkDeliveryHook } from "@zocomputer/agent-sdk";
+//   export default createParkDeliveryHook();
+//
+// Three producers feed it:
+// - **Read media** (./redeliver.ts): `action.result` events carry read's raw
+//   output (bytes included — toModelOutput only narrows what the model sees);
+//   on park the images/video/audio go back into the session as a real user
+//   turn.
+// - **Background-task notifications** (./watch-output.ts): a bash/run_async
+//   watcher match or a completion notice posted through the notification
+//   bridge; delivered on park — or immediately, when the match lands while
+//   the session is already parked (a background task finishing mid-park is
+//   the whole point of the feature).
+// - **Leftover steers** (./steer-inbox.ts, when `steer.dir` is set): a steered
+//   message normally rides the next completing tool result (./steer-tool.ts),
+//   but a turn that ends first strands the inbox — on park the hook drains it
+//   and sends the messages as the user turn they were meant to be.
+//
+// The send goes through eve's HTTP API on loopback — the hook context hands us
+// the continuation token, and eve's localDev auth accepts loopback callers.
+// Server-side by construction: no browser, no cockpit, no host app.
+//
+// Hooks are observe-only for *model context*, so this doesn't inject anything
+// mid-turn — it starts the NEXT turn, exactly like a user hitting send. The
+// send is fire-and-forget from the handler (awaiting it would stall eve's hook
+// dispatch on a POST back into the same process) with a short retry ladder:
+// the park→send window can race turn finalization or a real user message, and
+// a send that still fails re-queues for the session's next park.
+
+const RETRY_DELAYS_MS = [500, 2_000, 5_000];
+
+/** What one park delivery carries: read media, a note, or a steered message. */
+type DeliveryPayload =
+  | { readonly kind: "media"; readonly attachment: ChatAttachment }
+  | { readonly kind: "note"; readonly text: string }
+  | { readonly kind: "steer"; readonly message: SteerMessage };
+
+function buildDeliveryMessage(
+  request: ParkDeliveryRequest<DeliveryPayload>,
+): RedeliveryMessagePart[] {
+  const media = request.items.flatMap((item) =>
+    item.payload.kind === "media"
+      ? [{ toolCallId: item.key, attachment: item.payload.attachment }]
+      : [],
+  );
+  const notes = request.items.flatMap((item) =>
+    item.payload.kind === "note" ? [item.payload.text] : [],
+  );
+  // Steers are the user's own words — deliver them verbatim, first.
+  const steers = request.items.flatMap((item) =>
+    item.payload.kind === "steer" ? [item.payload.message.text] : [],
+  );
+  return [
+    ...steers.map((text) => ({ type: "text" as const, text })),
+    ...(media.length > 0 ? buildRedeliveryMessage(media) : []),
+    ...notes.map((text) => ({ type: "text" as const, text })),
+  ];
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isSessionWaiting(event: unknown): boolean {
+  return isRecord(event) && event.type === "session.waiting";
+}
+
+export interface ParkDeliveryOptions {
+  /**
+   * Base URL of this agent's own eve server. Defaults to loopback on the
+   * server's port (`$PORT`, eve dev's default 2000 otherwise).
+   */
+  serverUrl?: string;
+  /** Log a line per delivery/failure (default true — it explains agent turns). */
+  log?: boolean;
+  /**
+   * The steer inbox dir (the same one passed to `createStdlib`). When set,
+   * steered messages a turn ends before delivering (no tool completed after
+   * they arrived) go out on park as the next user turn.
+   */
+  steer?: { dir: string };
+}
+
+export function createParkDeliveryHook(options: ParkDeliveryOptions = {}) {
+  const serverUrl =
+    options.serverUrl ?? `http://127.0.0.1:${process.env.PORT ?? "2000"}`;
+  const log = options.log ?? true;
+  const steerInbox = options.steer ? createSteerInbox({ dir: options.steer.dir }) : null;
+  const state = createParkDeliveryState<DeliveryPayload>();
+
+  async function deliver(request: ParkDeliveryRequest<DeliveryPayload>): Promise<void> {
+    const client = new Client({ host: serverUrl });
+    const message = buildDeliveryMessage(request);
+    for (let attempt = 0; ; attempt++) {
+      try {
+        const session = client.session({
+          sessionId: request.sessionId,
+          continuationToken: request.continuationToken,
+          streamIndex: 0,
+        });
+        const response = await session.send({ message });
+        // The continue route echoes the target session id; a mismatch means
+        // eve get-or-created a NEW session (a stale/mis-scoped token) — that's
+        // a failed delivery even though the POST succeeded.
+        if (response.sessionId !== request.sessionId) {
+          throw new Error(
+            `park delivery landed on ${response.sessionId} instead of ${request.sessionId} (continuation token mismatch)`,
+          );
+        }
+        // Drain the turn acknowledgement; the turn itself streams to whoever
+        // is watching the session. We only need the send to be accepted.
+        await response.result();
+        const next = state.settle(request, true);
+        if (log) {
+          const labels = request.items.map((item) =>
+            item.payload.kind === "media" ? item.payload.attachment.filename : item.key,
+          );
+          console.log(
+            `[agent-sdk] park delivery to ${request.sessionId}: ${labels.join(", ")}`,
+          );
+        }
+        // Items may have queued while we were delivering; dispatch them now.
+        if (next) void deliver(next);
+        return;
+      } catch (error) {
+        const delay = RETRY_DELAYS_MS[attempt];
+        if (delay === undefined) {
+          state.settle(request, false);
+          if (log) {
+            console.warn(
+              `[agent-sdk] park delivery to ${request.sessionId} failed; will retry on next park:`,
+              error,
+            );
+          }
+          return;
+        }
+        await new Promise((resolve) => setTimeout(resolve, delay));
+      }
+    }
+  }
+
+  // Tool code (bash watchers, run_async completion notices) posts through the
+  // process-global bridge; a notification arriving while the session is
+  // parked returns a request right here — no stream event will fire for it.
+  setParkNotificationHandler((sessionId, notification) => {
+    const request = state.enqueue(sessionId, {
+      key: notification.key,
+      payload: { kind: "note", text: notification.text },
+    });
+    if (request) void deliver(request);
+  });
+
+  return defineHook({
+    events: {
+      "*"(event, ctx) {
+        const meta = {
+          sessionId: ctx.session.id,
+          continuationToken: ctx.channel.continuationToken,
+        };
+        // Drain leftover steers BEFORE observe processes the park, so they
+        // ride the same delivery the waiting event triggers. The whole drain
+        // enqueues as one batch — item-by-item enqueue would let the first
+        // steer's immediate flush (session already parked) split the rest
+        // into a second turn. Failed sends re-queue in the delivery state
+        // (keyed by steer id), not the file.
+        if (steerInbox && isSessionWaiting(event)) {
+          const steers = steerInbox.drain(meta.sessionId);
+          if (steers.length > 0) {
+            const flush = state.enqueueAll(
+              meta.sessionId,
+              steers.map((message) => ({
+                key: `steer:${message.id}`,
+                payload: { kind: "steer" as const, message },
+              })),
+            );
+            if (flush) void deliver(flush);
+          }
+        }
+        const request = state.observe(event, meta);
+        if (request) void deliver(request);
+        const found = redeliveryFromEvent(event);
+        if (found) {
+          // Media arrive on action.result (a non-waiting event), so this
+          // enqueue never fires an immediate delivery — they ride the park.
+          state.enqueue(meta.sessionId, {
+            key: found.toolCallId,
+            payload: { kind: "media", attachment: found.attachment },
+          });
+        }
+      },
+    },
+  });
+}