@vecteur/cli 0.2.4 → 0.3.1

package/bin/vecteur-mcp.js

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+import { serveStdio } from "@modelcontextprotocol/server/stdio";
+
+import { redact } from "../src/client.js";
+import { createVecteurMcpServer } from "../src/mcp.js";
+
+const shutdown = new AbortController();
+const handle = serveStdio(() => createVecteurMcpServer(undefined, shutdown.signal), {
+  onerror(error) {
+    process.stderr.write(`mcp_transport_error: ${redact(error?.message ?? "MCP transport failed")}\n`);
+  },
+});
+
+let closing;
+function close() {
+  if (!closing) {
+    shutdown.abort();
+    closing = handle.close().catch((error) => {
+      process.stderr.write(`mcp_close_error: ${redact(error?.message ?? "MCP close failed")}\n`);
+      process.exitCode = 1;
+    });
+  }
+  return closing;
+}
+
+process.stdin.once("end", () => { void close(); });
+for (const signal of ["SIGINT", "SIGTERM"]) {
+  process.once(signal, () => { void close(); });
+}

package/bin/vecteur.js

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+import { CliError, VecteurClient, configuration, redact } from "../src/client.js";
+import { clearCredentials, credentialsPath, readCredentials, writeCredentials } from "../src/credentials.js";
+import { canonicalJson, human, progress } from "../src/format.js";
+
+/**
+ * Read one line from stdin, with no echo concerns: the token is PIPED, never typed into argv.
+ *
+ * `--token vct_…` would put a live credential in `ps`, in `/proc/<pid>/cmdline` for every local
+ * user, and in the shell history file afterwards. That exposure is not hypothetical here —
+ * `SHIP-007` on this project's own backlog exists to rotate production credentials that reached
+ * a command line. A door must not ship a convenient way to repeat it.
+ */
+async function readTokenFromStdin() {
+  if (process.stdin.isTTY) {
+    throw new CliError("token_required",
+      "pipe the personal access token in: `vecteur login --url <origin> < token.txt`");
+  }
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  const token = Buffer.concat(chunks).toString("utf8").trim();
+  if (!token) throw new CliError("token_required", "stdin held no personal access token");
+  return token;
+}
+
+function parseCommand(argv) {
+  const json = argv.at(-1) === "--json";
+  const args = json ? argv.slice(0, -1) : [...argv];
+  const value = (candidate) => typeof candidate === "string" && candidate.length > 0 &&
+    !candidate.startsWith("-");
+  if (args.length === 3 && args[0] === "login" && args[1] === "--url" && value(args[2])) {
+    return { kind: "login", origin: args[2], json };
+  }
+  if (args.length === 1 && args[0] === "logout") return { kind: "logout", json };
+  if (args.length === 1 && args[0] === "whoami") return { kind: "whoami", json };
+  if (args.length === 3 && args[0] === "project" && args[1] === "get" && value(args[2])) {
+    return { kind: "project_get", id: args[2], json };
+  }
+  if (args.length === 6 && args[0] === "run" && args[1] === "submit" &&
+      args[2] === "--project" && value(args[3]) && args[4] === "--ask" && value(args[5])) {
+    return { kind: "run_submit", projectId: args[3], ask: args[5], json };
+  }
+  if (args.length === 3 && args[0] === "run" && args[1] === "get" && value(args[2])) {
+    return { kind: "run_get", id: args[2], json };
+  }
+  if (args.length === 3 && args[0] === "run" && args[1] === "events" && value(args[2])) {
+    return { kind: "run_events", id: args[2], json };
+  }
+  throw new CliError("usage_invalid", "Invalid command grammar");
+}
+
+async function main() {
+  const command = parseCommand(process.argv.slice(2));
+
+  // The login commands run BEFORE a client is constructed. Constructing one resolves a
+  // configuration, and requiring a valid login in order to log in is the shape of bug that
+  // makes a first run impossible.
+  if (command.kind === "login") {
+    const token = await readTokenFromStdin();
+    // Shape-check HERE so the refusal names what is wrong with what was just piped in. Falling
+    // straight through to `configuration` reported "no login found: run `vecteur login`" to a
+    // user in the middle of running exactly that.
+    if (!/^vct_[A-Za-z0-9_-]{43}$/.test(token)) {
+      throw new CliError("token_invalid",
+        `stdin held ${token.length} characters; a personal access token is \`vct_\` and 43 more`);
+    }
+    // Then through the SAME function every command resolves through, so an origin this CLI
+    // would later refuse is refused now, while the user is still holding the token — not on
+    // their next command with the credential already on disk.
+    const checked = configuration({ VECTEUR_TOKEN: token, VECTEUR_BASE_URL: command.origin }, null);
+    const path = writeCredentials({ origin: checked.origin, token }, process.env);
+    process.stdout.write(command.json
+      ? canonicalJson({ logged_in: true, origin: checked.origin, credentials: path })
+      : `logged in to ${checked.origin}\ncredentials: ${path}\n`);
+    return;
+  }
+  if (command.kind === "logout") {
+    const path = clearCredentials(process.env);
+    process.stdout.write(command.json
+      ? canonicalJson({ logged_in: false, credentials: path })
+      : `logged out\ncredentials removed: ${path}\n`);
+    return;
+  }
+  if (command.kind === "whoami") {
+    const saved = readCredentials(process.env);
+    // NEVER the token, not even a prefix. A door that prints part of a credential teaches the
+    // habit of pasting it somewhere, and a prefix is enough to confirm a guess.
+    process.stdout.write(command.json
+      ? canonicalJson({ logged_in: Boolean(saved), origin: saved?.origin ?? null })
+      : saved ? `logged in to ${saved.origin}\n` : "not logged in\n");
+    process.exitCode = saved ? 0 : 1;
+    return;
+  }
+
+  const client = new VecteurClient();
+  const onEvent = command.json ? null : (event) => process.stderr.write(progress(event));
+  let value;
+  if (command.kind === "project_get") value = await client.projectGet(command.id);
+  else if (command.kind === "run_submit") {
+    value = await client.runSubmit(command.projectId, command.ask, onEvent);
+  } else if (command.kind === "run_get") value = await client.runGet(command.id);
+  else value = await client.runEvents(command.id, onEvent);
+  process.stdout.write(command.json ? canonicalJson(value) : human(value));
+}
+
+main().catch((error) => {
+  const code = error instanceof CliError ? error.code : "internal_error";
+  process.stderr.write(`${code}: ${redact(error?.message ?? "CLI failed")}\n`);
+  process.exitCode = code === "usage_invalid" ? 2 : 1;
+});

package/package.json

@@ -1,63 +1,41 @@
 {
   "name": "@vecteur/cli",
-  "version": "0.2.4",
-  "description": "Vecteur CLI — a thin client for the Vecteur space-engineering platform (login, ask, projects, files). Hosted brain; no IP ships.",
+  "version": "0.3.1",
   "type": "module",
-  "license": "MIT",
-  "author": "Vecteur <hello@vecteur.space>",
-  "homepage": "https://vecteur.space",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/vecteurspace/vecteur-cli.git"
-  },
-  "bugs": {
-    "url": "https://github.com/vecteurspace/vecteur-cli/issues"
-  },
-  "keywords": [
-    "vecteur",
-    "space",
-    "space-systems",
-    "engineering",
-    "cli",
-    "agent",
-    "mcp"
-  ],
   "bin": {
-    "vecteur": "dist/index.js"
+    "cli": "bin/vecteur.js",
+    "vecteur": "bin/vecteur.js",
+    "vecteur-mcp": "bin/vecteur-mcp.js"
   },
   "files": [
-    "dist",
-    "README.md",
-    "LICENSE"
+    "bin/vecteur-mcp.js",
+    "bin/vecteur.js",
+    "src/client.js",
+    "src/contract.js",
+    "src/credentials.js",
+    "src/errors.js",
+    "src/format.js",
+    "src/mcp.js"
   ],
-  "publishConfig": {
-    "access": "public",
-    "provenance": true
+  "scripts": {
+    "test": "node --test tests/*.test.js",
+    "contract:check": "node scripts/gen-contract.mjs --check",
+    "verify-package": "node scripts/verify-package.mjs",
+    "prepublishOnly": "npm test && npm run contract:check && npm run verify-package"
   },
   "engines": {
     "node": ">=20"
   },
-  "scripts": {
-    "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
-    "build": "npm run clean && tsc -p tsconfig.json",
-    "dev": "tsc -w -p tsconfig.json",
-    "start": "node dist/index.js",
-    "typecheck": "tsc --noEmit -p tsconfig.json"
-  },
   "dependencies": {
-    "commander": "^12.1.0",
-    "ink": "^5.2.1",
-    "ink-spinner": "^5.0.0",
-    "ink-text-input": "^6.0.0",
-    "react": "^18.3.1",
-    "ws": "^8.18.0"
+    "@modelcontextprotocol/server": "2.0.0",
+    "zod": "4.4.3"
   },
   "devDependencies": {
-    "@types/node": "^22.0.0",
-    "@types/react": "^18.3.31",
-    "@types/ws": "^8.5.12",
-    "ink-testing-library": "^4.0.0",
-    "typescript": "^5.6.0",
-    "vitest": "^2.1.9"
+    "@modelcontextprotocol/client": "2.0.0"
+  },
+  "description": "The Vecteur command line \u2014 one login, the same product as the web app, from any directory.",
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "access": "public"
   }
 }

package/src/client.js

@@ -0,0 +1,399 @@
+import { createHash, randomUUID } from "node:crypto";
+
+import { EVENT_KINDS, validateAdmitted, validateProject, validateRunAck } from "./contract.js";
+import { readCredentials } from "./credentials.js";
+import { CliError } from "./errors.js";
+import { canonicalJson } from "./format.js";
+
+// Re-exported so every existing importer keeps its one import site; `errors.js` owns the type.
+export { CliError };
+
+const DEFAULT_TIMEOUT_MS = 120_000;
+const TOKEN_PATTERN = /vct_[A-Za-z0-9_-]{20,}/g;
+const RELEASE_TIMEOUT = Symbol("release-timeout");
+const RESPONSE_ACTIVITY = Symbol("response-activity");
+const MAX_RESPONSE_BYTES = 8 * 1024 * 1024;
+const MAX_FRAME_BYTES = 1024 * 1024;
+const MAX_EVENTS = 10_000;
+
+
+export function redact(value) {
+  return String(value).replace(TOKEN_PATTERN, "[REDACTED]");
+}
+
+function refuseSecretValue(value) {
+  if (/vct_[A-Za-z0-9_-]{20,}/.test(JSON.stringify(value))) {
+    throw new CliError("secret_response_refused", "Public API response contains credential-shaped data");
+  }
+  return value;
+}
+
+/**
+ * Where a run gets its origin and its token, in one place, with the environment winning.
+ *
+ * The environment first, because that is how CI and a container pass a credential and neither
+ * should have to write a file to do it. The stored login second, so a human logs in once —
+ * SRD 06's release bar for this door is "one persistent login, the same product from any
+ * working directory", and reading only the environment made "logged in" last one shell.
+ *
+ * Both are all-or-nothing per field: a stored login does not lend its token to an environment
+ * that names a different origin, because a token minted for one deployment silently pointed at
+ * another is a credential leak with a good explanation.
+ */
+export function configuration(env = process.env, stored = undefined) {
+  const saved = stored === undefined ? readCredentials(env) : stored;
+  const token = env.VECTEUR_TOKEN ?? saved?.token ?? "";
+
+  // A STORED TOKEN GOES TO THE ORIGIN IT WAS STORED FOR, AND NOWHERE ELSE.
+  //
+  // The two sources resolve field by field, which on its own lets `VECTEUR_BASE_URL=<other>`
+  // borrow the stored token and send it somewhere it was never minted for — a credential leak
+  // with a plausible explanation, and one a user would never see happen. If the environment
+  // names an origin, it must bring its own token.
+  if (!env.VECTEUR_TOKEN && saved && env.VECTEUR_BASE_URL &&
+      env.VECTEUR_BASE_URL.replace(/\/+$/, "") !== saved.origin) {
+    throw new CliError("origin_mismatch",
+      `the stored login is for ${saved.origin} and VECTEUR_BASE_URL names `
+      + `${env.VECTEUR_BASE_URL} — set VECTEUR_TOKEN for that origin, or log in to it`);
+  }
+
+  if (!/^vct_[A-Za-z0-9_-]{43}$/.test(token)) {
+    throw new CliError("token_invalid", saved
+      ? "the stored login does not hold one personal access token — run `vecteur login` again"
+      : "no login found: run `vecteur login --url <origin>`, or set VECTEUR_TOKEN");
+  }
+  const raw = env.VECTEUR_BASE_URL ?? saved?.origin ?? "";
+  let url;
+  try {
+    url = new URL(raw);
+  } catch {
+    throw new CliError("origin_invalid", "VECTEUR_BASE_URL must be an absolute public origin");
+  }
+  const lexicalLoopback = /^http:\/\/(?:127\.0\.0\.1|localhost|\[::1\])(?::\d{1,5})?$/.test(raw);
+  if ((url.protocol !== "https:" && !lexicalLoopback) ||
+      url.username || url.password || url.pathname !== "/" || url.search || url.hash) {
+    throw new CliError("origin_invalid", "VECTEUR_BASE_URL must be HTTPS or an exact loopback HTTP origin");
+  }
+  const timeout = Number(env.VECTEUR_TIMEOUT_MS ?? DEFAULT_TIMEOUT_MS);
+  if (!Number.isInteger(timeout) || timeout < 100 || timeout > 120_000) {
+    throw new CliError("timeout_invalid", "VECTEUR_TIMEOUT_MS must be 100 to 120000");
+  }
+  return { origin: url.origin, token, timeout };
+}
+
+function exactObject(value, fields, code) {
+  if (!value || typeof value !== "object" || Array.isArray(value) ||
+      Object.keys(value).sort().join("\n") !== [...fields].sort().join("\n")) {
+    throw new CliError(code, "Server returned malformed owner data");
+  }
+  return value;
+}
+
+export function validateEvent(value, runId, expectedSeq) {
+  exactObject(value, ["run_id", "seq", "kind", "payload"], "event_invalid");
+  if (value.run_id !== runId || !Number.isInteger(value.seq) || value.seq !== expectedSeq ||
+      !EVENT_KINDS.includes(value.kind) || !value.payload || typeof value.payload !== "object" ||
+      Array.isArray(value.payload)) {
+    throw new CliError("event_sequence_invalid", `Expected event sequence ${expectedSeq}`);
+  }
+  if (value.payload.evidence_dag !== undefined) {
+    validateEvidenceDag(value.payload.evidence_dag, runId);
+  }
+  return value;
+}
+
+function evidenceReplayInvalid(message) {
+  throw new CliError("evidence_replay_invalid", `EvidenceDAG ${message}`);
+}
+
+function exactKeys(value, keys) {
+  return value && typeof value === "object" && !Array.isArray(value)
+    && Object.keys(value).sort().join("\n") === [...keys].sort().join("\n");
+}
+
+export function validateEvidenceDag(value, runId) {
+  if (!exactKeys(value, ["id", "schema_version", "run_id", "nodes", "edges"])) {
+    evidenceReplayInvalid("shape is invalid");
+  }
+  if (value.schema_version !== "evidence-dag.v1" || value.run_id !== runId ||
+      typeof value.id !== "string" || !value.id || !Array.isArray(value.nodes) ||
+      !Array.isArray(value.edges)) {
+    evidenceReplayInvalid("identity or arrays are invalid");
+  }
+  const digest = createHash("sha256").update(canonicalJson({
+    schema_version: value.schema_version, run_id: value.run_id,
+    nodes: value.nodes, edges: value.edges,
+  }).trimEnd(), "utf8").digest("hex");
+  if (value.id !== `evidence-dag:sha256:${digest}`) evidenceReplayInvalid("id seal is invalid");
+  return value;
+}
+
+export async function parseSse(response, runId, onEvent = null) {
+  if (!response.body) throw new CliError("sse_invalid", "Event response has no body");
+  const decoder = new TextDecoder("utf-8", { fatal: true });
+  let buffer = "";
+  let total = 0;
+  const events = [];
+  let terminalSeen = false;
+  const reader = response.body.getReader();
+  const signal = response["vecteurAbortSignal"];
+  while (true) {
+    let result;
+    if (signal) {
+      let rejectAbort;
+      const aborted = new Promise((_, reject) => {
+        rejectAbort = () => reject(new DOMException("Aborted", "AbortError"));
+        signal.addEventListener("abort", rejectAbort, { once: true });
+      });
+      try { result = await Promise.race([reader.read(), aborted]); }
+      finally { signal.removeEventListener("abort", rejectAbort); }
+    } else result = await reader.read();
+    if (result.done) break;
+    const chunk = result.value;
+    response[RESPONSE_ACTIVITY]?.();
+    total += chunk.byteLength;
+    if (total > MAX_RESPONSE_BYTES) throw new CliError("response_too_large", "Event response exceeds limit");
+    try { buffer += decoder.decode(chunk, { stream: true }); }
+    catch { throw new CliError("sse_invalid", "Event stream is not UTF-8"); }
+    buffer = buffer.replace(/\r\n/g, "\n");
+    let boundary;
+    while ((boundary = buffer.indexOf("\n\n")) >= 0) {
+      const frame = buffer.slice(0, boundary).replace(/\r/g, "");
+      if (Buffer.byteLength(frame, "utf8") > MAX_FRAME_BYTES) {
+        throw new CliError("sse_invalid", "SSE frame exceeds limit");
+      }
+      buffer = buffer.slice(boundary + 2);
+      if (!frame || frame.startsWith(":")) continue;
+      if (terminalSeen) throw new CliError("terminal_invalid", "Event stream contains data after terminal");
+      const lines = frame.split("\n");
+      if (lines.length !== 3 || !lines[0].startsWith("id:") ||
+          !lines[1].startsWith("event:") || !lines[2].startsWith("data:")) {
+        throw new CliError("sse_invalid", "Event stream contains malformed framing");
+      }
+      const id = lines[0].slice(3).trim();
+      const kind = lines[1].slice(6).trim();
+      let value;
+      try { value = JSON.parse(lines[2].slice(5).trimStart()); }
+      catch { throw new CliError("event_invalid", "Event stream contains malformed JSON"); }
+      if (id !== String(events.length) || kind !== value.kind) {
+        throw new CliError("sse_invalid", "SSE metadata disagrees with event data");
+      }
+      events.push(validateEvent(refuseSecretValue(value), runId, events.length));
+      await onEvent?.(events.at(-1));
+      if (events.length > MAX_EVENTS) throw new CliError("response_too_large", "Event count exceeds limit");
+      terminalSeen = events.at(-1).kind === "terminal";
+    }
+    if (Buffer.byteLength(buffer, "utf8") > MAX_FRAME_BYTES) {
+      throw new CliError("sse_invalid", "SSE partial frame exceeds limit");
+    }
+  }
+  buffer += decoder.decode();
+  if (buffer.trim()) throw new CliError("sse_invalid", "Event stream ended with a partial frame");
+  return events;
+}
+
+export class VecteurClient {
+  constructor(config = configuration(), fetchImpl = fetch) {
+    this.config = config;
+    this.fetchImpl = fetchImpl;
+  }
+
+  async request(method, path, { body, idempotencyKey, accept, signal } = {}) {
+    const controller = new AbortController();
+    const cancel = () => controller.abort();
+    signal?.addEventListener("abort", cancel, { once: true });
+    if (signal?.aborted) controller.abort();
+    const overallTimer = setTimeout(() => controller.abort(), this.config.timeout);
+    // THE IDLE WINDOW CATCHES A DEAD CONNECTION, NOT A THINKING AGENT.
+    //
+    // Five seconds is right for a request/response call: nothing legitimate is silent that long.
+    // It is wrong for the RUN EVENT STREAM, where silence between events is the agent working —
+    // `run submit` waits for a whole turn, and every turn that thought for more than five
+    // seconds died as `request_timeout: Public API request timed out`, which reads as a dead
+    // endpoint. That is every engineering ask, on a released door, and no environment variable
+    // could widen it because `VECTEUR_TIMEOUT_MS` was capped by this same `min`.
+    //
+    // A stream is still BOUNDED — by `overallTimer`, which no branch here changes. What goes is
+    // the assumption that a quiet socket is a broken one, which only ever held for the calls
+    // that answer immediately.
+    const idleMs = accept === "text/event-stream"
+      ? this.config.timeout
+      : Math.min(this.config.timeout, 5_000);
+    let idleTimer;
+    const activity = () => {
+      clearTimeout(idleTimer);
+      idleTimer = setTimeout(() => controller.abort(), idleMs);
+    };
+    activity();
+    try {
+      const response = await this.fetchImpl(`${this.config.origin}${path}`, {
+        method,
+        redirect: "manual",
+        signal: controller.signal,
+        headers: {
+          Authorization: `Bearer ${this.config.token}`,
+          ...(body === undefined ? {} : { "Content-Type": "application/json" }),
+          ...(idempotencyKey ? { "Idempotency-Key": idempotencyKey } : {}),
+          ...(accept ? { Accept: accept } : {}),
+        },
+        body: body === undefined ? undefined : JSON.stringify(body),
+      });
+      const abortBody = () => response.body?.cancel().catch(() => {});
+      controller.signal.addEventListener("abort", abortBody, { once: true });
+      response[RESPONSE_ACTIVITY] = activity;
+      response["vecteurAbortSignal"] = controller.signal;
+      response[RELEASE_TIMEOUT] = () => {
+        controller.signal.removeEventListener("abort", abortBody);
+        signal?.removeEventListener("abort", cancel);
+        clearTimeout(overallTimer); clearTimeout(idleTimer);
+      };
+      if (response.status >= 300 && response.status < 400) {
+        throw new CliError("redirect_refused", "Public API redirects are refused");
+      }
+      if (!response.ok) {
+        let code = `http_${response.status}`;
+        try {
+          const candidate = parseOwnerJson(await boundedText(response)).error?.code;
+          if (typeof candidate === "string" && /^[a-z][a-z0-9_]{0,63}$/.test(candidate)) {
+            code = candidate;
+          }
+        } catch (error) {
+          if (error?.name === "AbortError") throw error;
+        }
+        throw new CliError(code, `Public API refused request with HTTP ${response.status}`);
+      }
+      return response;
+    } catch (error) {
+      signal?.removeEventListener("abort", cancel);
+      clearTimeout(overallTimer); clearTimeout(idleTimer);
+      if (error?.name === "AbortError") {
+        if (signal?.aborted) throw new CliError("request_cancelled", "Public API request was cancelled");
+        throw new CliError("request_timeout", "Public API request timed out");
+      }
+      if (error instanceof CliError) throw error;
+      throw new CliError("request_failed", "Public API request failed");
+    }
+  }
+
+  async projectGet(projectId, signal = undefined) {
+    const value = await this.#json("GET", `/api/projects/${encodeURIComponent(projectId)}`, { signal });
+    if (!validateProject(value) || value.id !== projectId) {
+      throw new CliError("project_invalid", "Server returned malformed project data");
+    }
+    return value;
+  }
+
+  async runSubmit(projectId, ask, onEvent = null, signal = undefined) {
+    const value = await this.#json("POST", `/api/projects/${encodeURIComponent(projectId)}/runs`, {
+      body: { ask, attachments: [], parent_state_hash: null, ui_context: null },
+      idempotencyKey: randomUUID(),
+      signal,
+    });
+    if (!validateRunAck(value)) {
+      throw new CliError("run_ack_invalid", "Server returned malformed run acknowledgement");
+    }
+    return this.runEvents(value.run_id, onEvent, signal);
+  }
+
+  async runGet(runId, signal = undefined) {
+    const value = await this.#json("GET", `/api/runs/${encodeURIComponent(runId)}`, { signal });
+    if (!validateAdmitted(value) || value.run_id !== runId) {
+      throw new CliError("run_invalid", "Server returned malformed run record");
+    }
+    value.events.forEach((event, seq) => validateEvent(event, runId, seq));
+    return value;
+  }
+
+  async runEvents(runId, onEvent = null, signal = undefined) {
+    const response = await this.request("GET", `/api/runs/${encodeURIComponent(runId)}/events`, {
+      accept: "text/event-stream",
+      signal,
+    });
+    let events;
+    try {
+      const type = response.headers.get("content-type")?.split(";", 1)[0];
+      if (type !== "text/event-stream") {
+        throw new CliError("sse_invalid", "Event route is not an SSE stream");
+      }
+      events = await parseSse(response, runId, onEvent);
+    } catch (error) {
+      if (error?.name === "AbortError") {
+        throw new CliError("request_timeout", "Public API request timed out");
+      }
+      throw error;
+    } finally {
+      response[RELEASE_TIMEOUT]?.();
+    }
+    if (events.length === 0 || events.at(-1).kind !== "terminal") {
+      throw new CliError("terminal_invalid", "Event stream has no final terminal event");
+    }
+    const direct = await this.runGet(runId, signal);
+    if (JSON.stringify(events) !== JSON.stringify(direct.events)) {
+      throw new CliError("record_mismatch", "Event stream disagrees with direct replay");
+    }
+    const eventTerminal = events.at(-1).payload.state ?? events.at(-1).payload.terminal;
+    if (eventTerminal !== direct.terminal) {
+      throw new CliError("terminal_mismatch", "Terminal event disagrees with direct record");
+    }
+    return direct;
+  }
+
+  async #json(method, path, options) {
+    const response = await this.request(method, path, options);
+    try {
+      if (response.headers.get("content-type")?.split(";", 1)[0] !== "application/json") {
+        throw new CliError("response_invalid", "Public API response is not JSON");
+      }
+      try { return refuseSecretValue(parseOwnerJson(await boundedText(response))); }
+      catch (error) {
+        if (error?.name === "AbortError") {
+          throw new CliError("request_timeout", "Public API request timed out");
+        }
+        if (error instanceof CliError) throw error;
+        throw new CliError("response_invalid", "Public API returned malformed JSON");
+      }
+    } finally {
+      response[RELEASE_TIMEOUT]?.();
+    }
+  }
+}
+
+async function boundedText(response) {
+  if (!response.body) throw new CliError("response_invalid", "Public API response has no body");
+  const chunks = [];
+  let size = 0;
+  for await (const chunk of response.body) {
+    response[RESPONSE_ACTIVITY]?.();
+    size += chunk.byteLength;
+    if (size > MAX_RESPONSE_BYTES) throw new CliError("response_too_large", "Public API response exceeds limit");
+    chunks.push(chunk);
+  }
+  try {
+    return new TextDecoder("utf-8", { fatal: true }).decode(Buffer.concat(chunks));
+  } catch {
+    throw new CliError("response_invalid", "Public API response is not UTF-8");
+  }
+}
+
+function parseOwnerJson(text) {
+  let inString = false;
+  let escaped = false;
+  let outside = "";
+  for (const character of text) {
+    if (inString) {
+      if (escaped) escaped = false;
+      else if (character === "\\") escaped = true;
+      else if (character === '"') inString = false;
+      outside += " ";
+    } else if (character === '"') {
+      inString = true; outside += " ";
+    } else outside += character;
+  }
+  for (const match of outside.matchAll(/-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?/g)) {
+    const number = Number(match[0]);
+    if (!Number.isFinite(number) || (Number.isInteger(number) && !Number.isSafeInteger(number))) {
+      throw new CliError("response_invalid", "Public API response contains an unsafe number");
+    }
+  }
+  return JSON.parse(text);
+}

package/src/contract.js

@@ -0,0 +1,12 @@
+// GENERATED by scripts/gen-contract.mjs from owner TypeScript projections.
+export const OWNER_CONTRACT_SHA256 = "a8a1bfec596231c560f80e9f9dbbc38f4b9dff0eef7e87db5bc4687f98b89597";
+export const EVENT_KINDS = Object.freeze(["source","step_started","step_finished","synthesis","artifact","cta","state_advanced","terminal","heartbeat","assistant_delta","step_label","context_frame","knowledge_binding","engineering_projection"]);
+export const ORIGIN_KINDS = Object.freeze(["user","hypothesis","derived","file","catalog","default"]);
+export const ORIGIN_WORD = Object.freeze({"user":"your brief","hypothesis":"assumed","derived":"derived","file":"your file","catalog":"catalogue","default":"default","unattributed":"unstated"});
+const exact=(v,k)=>!!v&&typeof v==="object"&&!Array.isArray(v)&&Object.keys(v).sort().join("\n")===[...k].sort().join("\n");
+const text=(v)=>typeof v==="string"&&v.length>0; const integer=(v)=>Number.isSafeInteger(v);
+const member=(v)=>exact(v,["user_id","email","display_name","role"])&&[v.user_id,v.email,v.display_name].every(text)&&["OWNER","ADMIN","EDITOR","VIEWER"].includes(v.role);
+export const validateProject=(v)=>exact(v,["id","name","org_id","workspace_id","role","role_source","members","created_at","updated_at"])&&[v.id,v.name,v.org_id,v.workspace_id].every(text)&&["OWNER","ADMIN","EDITOR","VIEWER"].includes(v.role)&&["workspace","project"].includes(v.role_source)&&Array.isArray(v.members)&&v.members.every(member)&&integer(v.created_at)&&integer(v.updated_at);
+export const validateRunAck=(v)=>exact(v,["run_id","state_hash","accepted_at","profile"])&&[v.run_id,v.state_hash,v.profile].every(text)&&integer(v.accepted_at);
+const usage=(v)=>exact(v,["state","provider","model_id","input_tokens","output_tokens","cost_usd"])&&["recorded","usage_unavailable"].includes(v.state)&&[v.provider,v.model_id].every(text)&&[v.input_tokens,v.output_tokens].every(x=>x===null||(integer(x)&&x>=0))&&(v.cost_usd===null||(typeof v.cost_usd==="number"&&Number.isFinite(v.cost_usd)&&v.cost_usd>=0));
+export const validateAdmitted=(v)=>exact(v,["run_id","state_hash","result_hash","profile","terminal","usage","events"])&&[v.run_id,v.state_hash,v.result_hash,v.profile].every(text)&&["ok","partial","blocked","refused","infeasible_physics","capability_gap"].includes(v.terminal)&&usage(v.usage)&&Array.isArray(v.events);