syndai 0.1.1 → 0.3.0

package/src/changes.js

@@ -0,0 +1,307 @@
+// The change lifecycle: change, watch, answer, review, go-live, revert, cancel, status,
+// edit-text. Each command is a thin call to one route plus, where there is an outcome to
+// wait for, `watchChange`.
+
+import { randomUUID } from "node:crypto";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { ApiError, CliError, EXIT } from "./errors.js";
+import { projectHost, projectLabel, resolveProject } from "./projects.js";
+import { clearPending, findPending, writePending } from "./store.js";
+import { ask, parseDuration, ulid } from "./ui.js";
+import { answerInteractively, describe, finish, getChange, nextFor, respond, watchChange } from "./watch.js";
+
+const TERMINAL_PHASES = new Set(["completed", "failed", "cancelled"]);
+const IMAGE_TYPES = {
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".webp": "image/webp",
+};
+
+const timeoutOf = (flags) => (flags.timeout ? parseDuration(flags.timeout) : null);
+
+function needRun(runId, command) {
+  if (!runId) throw new CliError(EXIT.USAGE, `Which change? syndai ${command} <run-id>`);
+  return runId;
+}
+
+export async function change(ctx, words) {
+  const { flags, ui, paths, io } = ctx;
+  const text = words.join(" ").trim();
+  if (!text) throw new CliError(EXIT.USAGE, 'Say what to change: syndai change "make the header blue"');
+  const timeoutMs = timeoutOf(flags);
+  const project = await resolveProject(ctx, { app: flags.app });
+  const outcome = flags.review ? "opens a pull request for your review" : "goes live when checks pass";
+  ui.progress(`Changing ${projectHost(project)} · ${outcome}`);
+
+  const imageRefs = [];
+  for (const file of flags.image ?? []) imageRefs.push(await uploadImage(ctx, file));
+
+  // The request id is on disk BEFORE the POST: a retry, or a rerun after a crash, sends the
+  // same external_request_id, and the server answers with the run it already made.
+  const pending = findPending(paths, { app: project.id, text }) ?? {
+    request_id: `cli:${ulid()}`,
+    app: project.id,
+    text,
+    created_at: new Date(io.now()).toISOString(),
+  };
+  writePending(paths, pending);
+  const runId = await createRun(ctx, {
+    body: {
+      prompt: text,
+      coding_repository_id: project.id,
+      external_request_id: pending.request_id,
+      ...(imageRefs.length ? { image_refs: imageRefs } : {}),
+      ...(flags.review ? { policy_config: { autonomy: "auto" } } : {}),
+    },
+  });
+  clearPending(paths, pending.request_id);
+  ui.progress(ui.dim(`Change ${runId}`));
+  if (flags["no-wait"]) {
+    return finish(ctx, await getChange(ctx, runId), { exitCode: EXIT.OK, next: `syndai watch ${runId}` });
+  }
+  return watchChange(ctx, runId, { timeoutMs });
+}
+
+async function createRun(ctx, { body }) {
+  try {
+    const created = await ctx.client.call("createRun", { body, retry: true });
+    return created.run.id;
+  } catch (err) {
+    if (!(err instanceof ApiError && err.code === "IDEMPOTENCY_REPLAY")) throw err;
+    const location = err.headers?.get("location") ?? "";
+    const fromLocation = /\/runs\/([^/?#]+)/.exec(location)?.[1];
+    const runId = fromLocation ?? err.problem.existing_run_id;
+    if (!runId) throw err;
+    return runId;
+  }
+}
+
+async function uploadImage(ctx, file) {
+  const contentType = IMAGE_TYPES[path.extname(file).toLowerCase()];
+  if (!contentType)
+    throw new CliError(EXIT.USAGE, `--image takes a png, jpeg, gif or webp file, not ${file}.`);
+  let bytes;
+  try {
+    bytes = readFileSync(file);
+  } catch {
+    throw new CliError(EXIT.USAGE, `Cannot read ${file}.`);
+  }
+  const stored = await ctx.client.call("imageIngest", {
+    body: { content_type: contentType, data_base64: bytes.toString("base64") },
+  });
+  return { object_key: stored.object_key, content_type: contentType };
+}
+
+export async function watch(ctx, runId) {
+  return watchChange(ctx, needRun(runId, "watch"), {
+    timeoutMs: timeoutOf(ctx.flags),
+    logs: ctx.flags.logs === true,
+  });
+}
+
+export async function answer(ctx, runId) {
+  const { flags, ui } = ctx;
+  needRun(runId, "answer");
+  const state = await getChange(ctx, runId);
+  const questions = state.state === "needs_input" ? (state.needs_input ?? []) : [];
+  if (questions.length === 0) {
+    ui.result({ ...state, next: nextFor(state) }, `Nothing to answer. ${describe(state)}`);
+    return EXIT.OK;
+  }
+  if (typeof flags.json === "string") {
+    let body;
+    try {
+      body = JSON.parse(flags.json);
+    } catch {
+      throw new CliError(
+        EXIT.USAGE,
+        '--json must be JSON, like {"entries":[{"input_id":"q1","text":"blue"}]}.',
+      );
+    }
+    const entries = Array.isArray(body) ? body : body.entries;
+    const hitlRequestId =
+      body.hitl_request_id ?? (questions.length === 1 ? questions[0].hitl_request_id : null);
+    if (!hitlRequestId || !Array.isArray(entries)) {
+      throw new CliError(
+        EXIT.USAGE,
+        "--json needs entries, and hitl_request_id when several questions are open.",
+      );
+    }
+    await respond(ctx, runId, hitlRequestId, entries);
+  } else if (ui.interactive) {
+    await answerInteractively(ctx, runId, questions);
+  } else {
+    return finish(ctx, state);
+  }
+  const next = `syndai watch ${runId}`;
+  ui.result({ run_id: runId, answered: true, next }, "Answered.");
+  if (!ui.json) ui.progress(`Next: ${next}`);
+  return EXIT.OK;
+}
+
+export async function review(ctx, runId) {
+  const { flags, ui, io, client } = ctx;
+  needRun(runId, "review");
+  if (flags.retry && flags.close) throw new CliError(EXIT.USAGE, "Pick one of --retry and --close.");
+  const params = { run_id: runId };
+  const state = await getChange(ctx, runId);
+  if (state.state !== "held") return finish(ctx, state);
+  if (flags.retry) {
+    await client.call("landRetry", { params });
+    ui.progress("Running the checks again.");
+    return watchChange(ctx, runId, { untilNot: "held" });
+  }
+  if (flags.close) {
+    await client.call("landClose", { params });
+    ui.result({ run_id: runId, closed: true }, "Closed. Nothing went live.");
+    return EXIT.OK;
+  }
+  const diff = await client.call("heldDiff", { params });
+  const reviewUrl = state.held?.review_url ?? null;
+  if (ui.json) {
+    ui.result({ ...state, held_diff: diff, next: reviewUrl ?? nextFor(state) }, "");
+    return EXIT.NEEDS_YOU;
+  }
+  await io.page(renderHeldDiff(state, diff));
+  if (!ui.interactive || !reviewUrl) {
+    ui.progress(`Next: ${reviewUrl ?? `syndai review ${runId}`}`);
+    return EXIT.NEEDS_YOU;
+  }
+  const yes = (await ask(io, "Approve in your browser? [Y/n] ")).toLowerCase();
+  if (yes && !yes.startsWith("y")) {
+    ui.progress(`Next: syndai review ${runId}`);
+    return EXIT.NEEDS_YOU;
+  }
+  ui.progress(`Opening ${reviewUrl}`);
+  io.openUrl(reviewUrl);
+  ui.progress(ui.dim("Waiting for your decision (Ctrl-C stops watching, not the review)..."));
+  return watchChange(ctx, runId, { untilNot: "held" });
+}
+
+export function renderHeldDiff(state, diff) {
+  const lines = [describe(state)];
+  if (diff.head_sha) {
+    const by = diff.expires_at ? ` · decide by ${diff.expires_at.slice(0, 10)}` : "";
+    lines.push(`At ${diff.head_sha.slice(0, 12)}${by}`);
+  }
+  lines.push("", "Files:");
+  for (const file of diff.paths ?? []) {
+    const modes =
+      file.old_mode !== file.new_mode && file.new_mode
+        ? ` (${file.old_mode ?? "none"} -> ${file.new_mode})`
+        : "";
+    lines.push(`  ${file.change.padEnd(10)} ${file.path}${modes}`);
+  }
+  for (const file of diff.paths ?? []) {
+    lines.push("", `--- ${file.path}`);
+    lines.push(file.binary ? "(binary file)" : (file.diff ?? "(no text diff)"));
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+export async function goLive(ctx, runId) {
+  needRun(runId, "go-live");
+  await ctx.client.call("goLive", { params: { run_id: runId } });
+  ctx.ui.progress("Going live.");
+  return watchChange(ctx, runId, { timeoutMs: timeoutOf(ctx.flags), untilNot: "ready" });
+}
+
+export async function revert(ctx, runId) {
+  needRun(runId, "revert");
+  let reverted;
+  try {
+    // Idempotent per landing: a retry returns the same revert change.
+    reverted = await ctx.client.call("revert", {
+      params: { run_id: runId },
+      body: { force: ctx.flags.force === true },
+      retry: true,
+    });
+  } catch (err) {
+    if (err instanceof ApiError && String(err.problem.detail ?? "").startsWith("revert_conflict")) {
+      throw new CliError(EXIT.FAILED, "Newer changes landed on top of this one.", {
+        next: `syndai revert ${runId} --force`,
+      });
+    }
+    throw err;
+  }
+  ctx.ui.progress(`Reverting with change ${reverted.run.id}.`);
+  return watchChange(ctx, reverted.run.id, { timeoutMs: timeoutOf(ctx.flags) });
+}
+
+export async function cancel(ctx, runId) {
+  needRun(runId, "cancel");
+  await ctx.client.call("cancel", { params: { run_id: runId }, body: {} });
+  ctx.ui.result({ run_id: runId, cancelled: true }, "Cancelled.");
+  return EXIT.OK;
+}
+
+export async function status(ctx) {
+  const { client, ui, flags } = ctx;
+  const project = await resolveProject(ctx, { app: flags.app, required: false, picker: false });
+  const query = { coding_repository_id: project?.id, limit: 20 };
+  const [needs, recent] = await Promise.all([
+    client.call("listRuns", { query: { ...query, needs: "owner" } }),
+    client.call("listRuns", { query }),
+  ]);
+  // The ChangeState names the exact next command, so read it rather than guess from the run.
+  const needsYou = await Promise.all(
+    needs.runs.slice(0, 10).map(async (run) => ({ run, state: await getChange(ctx, run.id) })),
+  );
+  const needIds = new Set(needs.runs.map((run) => run.id));
+  const active = recent.runs.filter((run) => !TERMINAL_PHASES.has(run.current_phase) && !needIds.has(run.id));
+  const title = (run) => run.title ?? run.prompt?.slice(0, 60) ?? run.id;
+  const lines = [];
+  if (project) lines.push(ui.bold(projectLabel(project)));
+  if (needsYou.length) {
+    lines.push("Needs you:");
+    for (const { run, state } of needsYou)
+      lines.push(`  ${title(run)}  ${describe(state)}  -> ${nextFor(state)}`);
+  }
+  if (active.length) {
+    lines.push("Running:");
+    for (const run of active) lines.push(`  ${title(run)}  ${run.current_phase}  -> syndai watch ${run.id}`);
+  }
+  if (!needsYou.length && !active.length) lines.push("Nothing needs you, and nothing is running.");
+  ui.result(
+    {
+      project: project ? { id: project.id, name: project.name, live_url: project.live_url } : null,
+      needs_you: needsYou.map(({ state }) => ({ ...state, next: nextFor(state) })),
+      running: active.map((run) => ({ run_id: run.id, title: title(run), phase: run.current_phase })),
+    },
+    lines.join("\n"),
+  );
+  return EXIT.OK;
+}
+
+export async function editText(ctx) {
+  const { flags, ui, client } = ctx;
+  const project = await resolveProject(ctx, { app: flags.app });
+  const params = { coding_repository_id: project.id };
+  if (flags.undo) {
+    const undone = await client.call("undoTextEdit", { params: { ...params, sha: flags.undo }, retry: true });
+    ui.result(undone, `Undone on ${projectHost(project)}.`);
+    return EXIT.OK;
+  }
+  if (flags.from === undefined || flags.to === undefined) {
+    throw new CliError(EXIT.USAGE, 'Give the exact text: syndai edit-text --page / --from "Old" --to "New"');
+  }
+  const pagePath = flags.page ?? "/";
+  const edited = await client.call("textEdit", {
+    params,
+    body: {
+      page: pagePath,
+      before: flags.from,
+      after: flags.to,
+      all: flags.all === true,
+      request_id: randomUUID(),
+    },
+    retry: true,
+  });
+  const next = `syndai edit-text --app ${project.id} --undo ${edited.commit_sha}`;
+  ui.result({ ...edited, next }, `Edited ${projectHost(project)}${pagePath}; live in a few seconds.`);
+  if (!ui.json) ui.progress(`Undo: ${next}`);
+  return EXIT.OK;
+}

package/src/errors.js

@@ -0,0 +1,128 @@
+// Exit codes and the one place a server problem becomes a sentence plus the next command.
+//
+// The exit codes are a contract with scripts and agents (docs: cli.mdx "Exit codes"):
+// never renumber one.
+
+export const EXIT = Object.freeze({
+  OK: 0,
+  FAILED: 1, // the change failed, was reverted or cancelled; or the request was refused
+  USAGE: 2, // bad arguments, or no project could be resolved
+  NEEDS_YOU: 3, // a question, a hold, or an approval only a browser session can give
+  UNVERIFIED: 4, // live, but the live check did not confirm it
+  AUTH: 5, // 401/402/403: key, scope, role or plan
+  TIMEOUT: 6, // --timeout reached; the change keeps going
+  UNAVAILABLE: 7, // the service did not answer after retries
+  INTERRUPTED: 130, // Ctrl-C; the change keeps going
+});
+
+/** A user-facing failure: `message` is one sentence, `next` the command (or URL) to run next. */
+export class CliError extends Error {
+  constructor(exitCode, message, { next = null, result = null } = {}) {
+    super(message);
+    this.exitCode = exitCode;
+    this.next = next;
+    // `result` is printed to stdout (JSON for scripts) before the error line.
+    this.result = result;
+  }
+}
+
+/** A non-2xx answer from the API. `problem` is the parsed body (problem+json or plain JSON). */
+export class ApiError extends Error {
+  constructor(status, problem, headers) {
+    super(problem?.detail || problem?.title || `HTTP ${status}`);
+    this.status = status;
+    this.problem = problem ?? {};
+    this.code = this.problem.code ?? null;
+    this.headers = headers;
+  }
+}
+
+/** The service did not answer (network error, 5xx or 429) after the retry budget. */
+export class UnavailableError extends Error {}
+
+const BILLING_URL = "https://app.syndai.ai/billing";
+
+// code -> [exit, sentence, next]. Either may be a function of the problem body.
+const KNOWN = {
+  INVALID_TOKEN: [EXIT.AUTH, "Your Syndai key is missing, expired or revoked.", "syndai login"],
+  INVALID_SCOPE: [EXIT.AUTH, "This key is not allowed to do that.", "syndai login"],
+  ROLE_REQUIRED: [EXIT.AUTH, "Only workspace owners and admins can do that.", null],
+  PLAN_UPGRADE_REQUIRED: [EXIT.AUTH, "Your plan does not include that.", BILLING_URL],
+  BUDGET_EXHAUSTED: [EXIT.AUTH, "This workspace is out of credits.", BILLING_URL],
+  QUOTA_EXCEEDED: [EXIT.AUTH, "This workspace is out of credits for now.", BILLING_URL],
+  CUSTOMER_DISABLED: [EXIT.AUTH, "This workspace is disabled. Contact Syndai support.", null],
+  HUMAN_APPROVAL_REQUIRED: [
+    EXIT.NEEDS_YOU,
+    "Only you can approve this, in your browser.",
+    (p) => p.review_url ?? p.extensions?.review_url ?? null,
+  ],
+  PROTECTED_PATHS_MANAGED_ONLY: [
+    EXIT.FAILED,
+    "Protected files work on Syndai-hosted projects only; use the code host's branch rules.",
+    null,
+  ],
+  CLI_UPGRADE_REQUIRED: [EXIT.FAILED, "This version of syndai is too old.", "npx -y syndai@latest"],
+  RUN_CONCURRENCY_LIMIT: [EXIT.FAILED, "Too many changes are running at once.", "syndai status"],
+  REPO_NOT_BOUND: [EXIT.USAGE, "That project is not available to this workspace.", "syndai link"],
+  INSTALLATION_INCOMPLETE: [
+    EXIT.FAILED,
+    "A code-host connection needs finishing in the portal.",
+    "https://app.syndai.ai",
+  ],
+  HITL_REQUEST_SETTLED: [EXIT.FAILED, "That question is already answered or closed.", null],
+  RUN_TERMINATED_BEFORE_RESPONSE: [EXIT.FAILED, "The change ended before your answer arrived.", null],
+  TEXT_EDIT_REFUSED: [
+    EXIT.FAILED,
+    (p) => oneSentence(p.detail || "The text edit was refused."),
+    // Text built from code: the server hands back a ready change instruction.
+    (p) => (p.refusal === "NOT_LITERAL" && p.prompt ? `syndai change ${shellQuote(p.prompt)}` : null),
+  ],
+  RUN_IN_FLIGHT: [
+    EXIT.FAILED,
+    "A change is in flight on this site; edit text once it lands.",
+    (p) => (p.run_id ? `syndai watch ${p.run_id}` : "syndai status"),
+  ],
+  NOT_FOUND: [EXIT.FAILED, "Not found.", "syndai status"],
+  RATE_LIMITED: [EXIT.UNAVAILABLE, "Syndai is rate-limiting this workspace.", null],
+};
+
+/** Map any thrown error to {exitCode, message, next}. */
+export function explain(err) {
+  if (err instanceof CliError) {
+    return { exitCode: err.exitCode, message: err.message, next: err.next };
+  }
+  if (err instanceof UnavailableError) {
+    return {
+      exitCode: EXIT.UNAVAILABLE,
+      message: `Syndai is not answering right now (${err.message}).`,
+      next: "try again in a minute",
+    };
+  }
+  if (err instanceof ApiError) {
+    const known = err.code ? KNOWN[err.code] : null;
+    if (known) {
+      const [exitCode, sentence, next] = known;
+      return {
+        exitCode,
+        message: typeof sentence === "function" ? sentence(err.problem) : sentence,
+        next: typeof next === "function" ? next(err.problem) : next,
+      };
+    }
+    const auth = err.status === 401 || err.status === 402 || err.status === 403;
+    return {
+      exitCode: auth ? EXIT.AUTH : EXIT.FAILED,
+      message: oneSentence(err.problem.detail || err.problem.title || `HTTP ${err.status}`),
+      next: err.status === 401 ? "syndai login" : null,
+    };
+  }
+  return { exitCode: EXIT.FAILED, message: oneSentence(String(err?.message ?? err)), next: null };
+}
+
+function shellQuote(text) {
+  return `'${String(text).replace(/'/g, "'\\''")}'`;
+}
+
+function oneSentence(text) {
+  const line = String(text).split("\n")[0].trim();
+  return /[.!?]$/.test(line) ? line : `${line}.`;
+}

package/src/http.js

@@ -0,0 +1,153 @@
+// The one HTTP client. Raw `fetch`, no SDK: `test/contract.test.js` checks every route
+// against the published OpenAPI instead.
+//
+// Retry rule (docs: cli.mdx "Retries"): only GETs and POSTs that carry their own
+// idempotency key are retried — callers opt in with `retry: true`. A 429 waits out
+// `Retry-After`; a 5xx, 408, network error or `MISSION_BUSY_RETRY` backs off from 0.5 s
+// towards 8 s with jitter. Five tries, then `UnavailableError` (exit 7).
+
+import { readFileSync } from "node:fs";
+import { ApiError, CliError, EXIT, UnavailableError } from "./errors.js";
+import { route } from "./routes.js";
+
+export const VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+export const USER_AGENT = `syndai-cli/${VERSION}`;
+export const DEFAULT_API_URL = "https://api.syndai.ai";
+
+const TRIES = 5;
+const MAX_WAIT_MS = 8_000;
+const MAX_RETRY_AFTER_MS = 60_000;
+
+export function backoffMs(attempt, random = Math.random) {
+  const base = 500 * 2 ** (attempt - 1);
+  return Math.min(MAX_WAIT_MS, Math.round(base * (1 + random() / 2)));
+}
+
+/** `Retry-After` as milliseconds (delta-seconds or an HTTP date), or null. */
+export function retryAfterMs(value, now = Date.now()) {
+  if (!value) return null;
+  const seconds = Number(value);
+  if (Number.isFinite(seconds)) return Math.max(0, seconds * 1000);
+  const at = Date.parse(value);
+  return Number.isNaN(at) ? null : Math.max(0, at - now);
+}
+
+export function interrupted() {
+  return new CliError(EXIT.INTERRUPTED, "Interrupted.");
+}
+
+/**
+ * @param {{baseUrl: string, getKey: () => Promise<string>, io: object}} options
+ */
+export function createClient({ baseUrl, getKey, io }) {
+  /** Call a named route from `routes.js`. */
+  function call(name, { params, ...opts } = {}) {
+    const [method, path] = route(name, params);
+    return send(method, path, opts);
+  }
+
+  async function send(
+    method,
+    path,
+    { query, body, retry = method === "GET", auth = true, timeoutMs = 30_000, raw = false, signal } = {},
+  ) {
+    const url = new URL(baseUrl + path);
+    for (const [key, value] of Object.entries(query ?? {})) {
+      if (value !== undefined && value !== null && value !== "") {
+        url.searchParams.set(key, String(value));
+      }
+    }
+    const headers = { "user-agent": USER_AGENT, accept: "application/json" };
+    if (body !== undefined) headers["content-type"] = "application/json";
+    if (auth) headers.authorization = `Bearer ${await getKey()}`;
+    const payload = body === undefined ? undefined : JSON.stringify(body);
+
+    for (let attempt = 1; ; attempt++) {
+      let res;
+      let parsed;
+      try {
+        res = await fetch(url, {
+          method,
+          headers,
+          body: payload,
+          signal: AbortSignal.any([io.signal, AbortSignal.timeout(timeoutMs), signal].filter(Boolean)),
+        });
+        parsed = await readBody(res);
+      } catch (err) {
+        if (io.signal.aborted) throw interrupted();
+        if (signal?.aborted) throw signal.reason;
+        if (!retry || attempt >= TRIES) throw new UnavailableError(networkReason(err));
+        await pause(backoffMs(attempt), signal);
+        continue;
+      }
+
+      const problem = res.ok ? null : new ApiError(res.status, parsed, res.headers);
+      const transient =
+        problem !== null &&
+        (res.status >= 500 ||
+          res.status === 408 ||
+          (res.status === 429 && (!problem.code || problem.code === "RATE_LIMITED")) ||
+          problem.code === "MISSION_BUSY_RETRY");
+      if (!transient) {
+        if (raw) return { status: res.status, body: parsed, headers: res.headers };
+        if (problem) throw problem;
+        return parsed;
+      }
+      if (!retry || attempt >= TRIES) {
+        throw new UnavailableError(`HTTP ${res.status}${problem.code ? ` ${problem.code}` : ""}`);
+      }
+      const hinted = res.status === 429 ? retryAfterMs(res.headers.get("retry-after")) : null;
+      const wait = hinted ?? backoffMs(attempt);
+      if (wait > MAX_RETRY_AFTER_MS) {
+        throw new UnavailableError(`rate-limited for ${Math.ceil(wait / 1000)} s`);
+      }
+      await pause(wait, signal);
+    }
+  }
+
+  /** Open a streaming GET (SSE). Returns the Response; non-2xx throws ApiError. */
+  async function stream(name, { params, query, headers = {}, signal } = {}) {
+    const [, path] = route(name, params);
+    const url = new URL(baseUrl + path);
+    for (const [key, value] of Object.entries(query ?? {})) url.searchParams.set(key, value);
+    const res = await fetch(url, {
+      headers: {
+        "user-agent": USER_AGENT,
+        accept: "text/event-stream",
+        authorization: `Bearer ${await getKey()}`,
+        ...headers,
+      },
+      signal: AbortSignal.any([io.signal, signal].filter(Boolean)),
+    });
+    if (!res.ok) throw new ApiError(res.status, await readBody(res), res.headers);
+    return res;
+  }
+
+  async function pause(ms, signal) {
+    try {
+      await io.sleep(ms, AbortSignal.any([io.signal, signal].filter(Boolean)));
+    } catch (err) {
+      if (io.signal.aborted) throw interrupted();
+      if (signal?.aborted) throw signal.reason;
+      throw err;
+    }
+  }
+
+  return { call, send, stream, baseUrl };
+}
+
+async function readBody(res) {
+  const text = await res.text();
+  if (!text) return null;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return { detail: text.slice(0, 500) };
+  }
+}
+
+function networkReason(err) {
+  if (err?.name === "TimeoutError") return "timed out";
+  const code = err?.cause?.code ?? err?.code;
+  return code ? String(code) : String(err?.cause?.message ?? err?.message ?? "network error");
+}