@vecteur/cli 0.8.0 → 0.9.1

package/src/client.js

@@ -2,9 +2,9 @@ import { createHash, randomUUID } from "node:crypto";
 
 import {
   ARTIFACT_MEDIA_TYPES, EVENT_KINDS, OWNER_CONTRACT_IDENTITY, RETIRED_EVENT_KINDS, validateAdmitted,
-  validateCustomerCostProjection, validateDeviceAuthorization, validateLimitDenial,
+  validateCliRelease, validateCustomerCostProjection, validateDeviceAuthorization, validateLimitDenial,
   validatePatCreated, validateProject, validateRunAck, validateAccount, validateQuotaDenial,
-  RECOVERY_ACTIONS,
+  RECOVERY_ACTIONS, validateRunControl, validateSource, validateSourceOffer,
 } from "./contract.js";
 import { readCredentials } from "./credentials.js";
 import { CliError } from "./errors.js";
@@ -149,11 +149,18 @@ export function shouldOpenBrowser(noBrowser, env = process.env) {
   return true;
 }
 
-export function delay(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
+export function delay(ms, signal = undefined) {
+  return new Promise((resolve, reject) => {
+    const finish = () => { signal?.removeEventListener("abort", cancel); resolve(); };
+    const timer = setTimeout(finish, ms);
+    const cancel = () => { clearTimeout(timer); signal?.removeEventListener("abort", cancel);
+      reject(new CliError("request_cancelled", "Waiting was cancelled")); };
+    signal?.addEventListener("abort", cancel, { once: true });
+    if (signal?.aborted) cancel();
+  });
 }
 
-export async function waitForDeviceAuthorization(client, grant, { sleep = delay, now = Date.now } = {}) {
+export async function waitForDeviceAuthorization(client, grant, { sleep = delay, now = Date.now, signal } = {}) {
   if (!validateDeviceAuthorization(grant)) {
     throw new CliError("device_authorization_invalid", "Server returned malformed owner data");
   }
@@ -163,16 +170,16 @@ export async function waitForDeviceAuthorization(client, grant, { sleep = delay,
       throw new CliError("device_expired", "This code has expired");
     }
     try {
-      const polled = await client.devicePoll(grant.device_code);
+      const polled = await client.devicePoll(grant.device_code, signal);
       if (validatePatCreated(polled)) return polled;
       if (polled && polled.status === "authorization_pending") {
-        await sleep(intervalMs);
+        await sleep(intervalMs, signal);
         continue;
       }
       throw new CliError("device_poll_invalid", "Server returned malformed owner data");
     } catch (error) {
       if (error instanceof CliError && error.code === "device_slow_down") {
-        await sleep(intervalMs);
+        await sleep(intervalMs, signal);
         continue;
       }
       throw error;
@@ -228,7 +235,10 @@ export function validateEvidenceDag(value, runId) {
   return value;
 }
 
-export async function parseSse(response, runId, onEvent = null) {
+export async function parseSse(response, runId, onEvent = null, startSeq = 0) {
+  if (!Number.isSafeInteger(startSeq) || startSeq < 0 || startSeq >= MAX_EVENTS) {
+    throw new CliError("cursor_invalid", "Event cursor is outside the supported history bound");
+  }
   if (!response.body) throw new CliError("sse_invalid", "Event response has no body");
   const decoder = new TextDecoder("utf-8", { fatal: true });
   let buffer = "";
@@ -237,59 +247,65 @@ export async function parseSse(response, runId, onEvent = null) {
   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");
+  try {
+    while (true) {
+      let result;
+      if (signal) {
+        if (signal.aborted) throw new DOMException("Aborted", "AbortError");
+        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(startSeq + events.length) || kind !== value.kind) {
+          throw new CliError("sse_invalid", "SSE metadata disagrees with event data");
+        }
+        events.push(validateEvent(refuseSecretValue(value), runId, startSeq + events.length));
+        await onEvent?.(events.at(-1));
+        if (startSeq + events.length > MAX_EVENTS) throw new CliError("response_too_large", "Event count exceeds limit");
+        terminalSeen = events.at(-1).kind === "terminal";
       }
-      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");
+      if (Buffer.byteLength(buffer, "utf8") > MAX_FRAME_BYTES) {
+        throw new CliError("sse_invalid", "SSE partial frame exceeds limit");
       }
-      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;
+  } finally {
+    try { await reader.cancel(); } catch { /* Preserve the read/validation error from an errored stream. */ }
+    finally { reader.releaseLock(); }
   }
-  buffer += decoder.decode();
-  if (buffer.trim()) throw new CliError("sse_invalid", "Event stream ended with a partial frame");
-  return events;
 }
 
 export class VecteurClient {
@@ -298,7 +314,12 @@ export class VecteurClient {
     this.fetchImpl = fetchImpl;
   }
 
-  async request(method, path, { body, idempotencyKey, accept, acceptEncoding, signal } = {}) {
+  async request(method, path, { body, rawBody, contentType, idempotencyKey, accept, acceptEncoding, signal,
+    lastEventId, anonymousReadiness = false } = {}) {
+    if (anonymousReadiness && (method !== "GET" || path !== "/api/ready" || body !== undefined || rawBody !== undefined)) {
+      throw new CliError("request_invalid", "Anonymous compatibility inspection is restricted to readiness");
+    }
+    if (body !== undefined && rawBody !== undefined) throw new CliError("request_invalid", "Choose JSON or raw bytes");
     const controller = new AbortController();
     const cancel = () => controller.abort();
     signal?.addEventListener("abort", cancel, { once: true });
@@ -331,14 +352,16 @@ export class VecteurClient {
         redirect: "manual",
         signal: controller.signal,
         headers: {
-          "X-Vecteur-Client": OWNER_CONTRACT_IDENTITY,
-          ...(this.config.token ? { Authorization: `Bearer ${this.config.token}` } : {}),
+          ...(!anonymousReadiness ? { "X-Vecteur-Client": OWNER_CONTRACT_IDENTITY } : {}),
+          ...(!anonymousReadiness && this.config.token ? { Authorization: `Bearer ${this.config.token}` } : {}),
           ...(body === undefined ? {} : { "Content-Type": "application/json" }),
+          ...(rawBody === undefined ? {} : { "Content-Type": contentType ?? "application/octet-stream" }),
           ...(idempotencyKey ? { "Idempotency-Key": idempotencyKey } : {}),
           ...(accept ? { Accept: accept } : {}),
           ...(acceptEncoding ? { "Accept-Encoding": acceptEncoding } : {}),
+          ...(lastEventId === undefined ? {} : { "Last-Event-ID": String(lastEventId) }),
         },
-        body: body === undefined ? undefined : JSON.stringify(body),
+        body: rawBody ?? (body === undefined ? undefined : JSON.stringify(body)),
       });
       const abortBody = () => response.body?.cancel().catch(() => {});
       controller.signal.addEventListener("abort", abortBody, { once: true });
@@ -362,6 +385,7 @@ export class VecteurClient {
         let code = `http_${response.status}`;
         let ownerMessage = "";
         let refused = null;
+        let admission = null;
         try {
           // THE GUARD RUNS ON REFUSALS TOO. It sat on the success path alone, so a 401 whose
           // body carried `vct_…` was read for its `error.code` and reported as `pat_revoked`:
@@ -374,6 +398,8 @@ export class VecteurClient {
             if (typeof candidate === "string" && /^[a-z][a-z0-9_]{0,63}$/.test(candidate)) {
               code = candidate;
             }
+            // Only the owner's explicit marker makes a refusal final for its submission key.
+            if (error.admission === "refused") admission = "refused";
             if (candidate === "project_quota_exhausted") {
               if (!validateQuotaDenial(error.quota) || typeof error.message !== "string"
                   || !error.message.length || /[\r\n\0]/.test(error.message)) {
@@ -423,10 +449,12 @@ export class VecteurClient {
           ].includes(error.code)) refused = error;
         }
         if (refused) throw refused;
-        throw new CliError(
+        const failure = new CliError(
           code,
           ownerMessage || `Public API refused request with HTTP ${response.status}`,
         );
+        if (admission) failure.admission = admission;
+        throw failure;
       }
       return response;
     } catch (error) {
@@ -451,9 +479,39 @@ export class VecteurClient {
     return value;
   }
 
-  async projectCreate(name, workspaceId, signal = undefined) {
+  async readiness(signal = undefined) {
+    const response = await this.request("GET", "/api/ready", { signal, anonymousReadiness: true });
+    try {
+      const body = refuseSecretValue(parseOwnerJson(await boundedText(response)));
+      if (body.status !== "ready") throw new CliError("origin_not_ready", "Origin did not report readiness");
+      const contract = response.headers.get("X-Vecteur-Contract");
+      if (!/^api-sha256:[a-f0-9]{64};run-wire-sha256:[a-f0-9]{64}$/.test(contract)) throw new CliError("origin_not_vecteur", "Invalid origin contract");
+      const cli = body.cli ?? null;
+      if (cli && (!validateCliRelease(cli) || !/^\d+\.\d+\.\d+$/.test(cli.version)
+          || cli.contract !== contract || (cli.integrity !== null && !/^sha512-[A-Za-z0-9+/]{86}==$/.test(cli.integrity)))) {
+        throw new CliError("release_invalid", "Origin returned invalid CLI release metadata");
+      }
+      const compatible = contract === OWNER_CONTRACT_IDENTITY;
+      let requiredVersion = cli?.version ?? null;
+      if (!compatible && !cli) {
+        // Older releases expose their pin only in the bounded 426 recovery. Inspect it
+        // through the same read-only route, with client identity but NEVER a credential.
+        const publicClient = new VecteurClient({ ...this.config, token: undefined }, this.fetchImpl);
+        try {
+          const legacy = await publicClient.request("GET", "/api/ready", { signal });
+          await legacy.body?.cancel(); legacy[RELEASE_TIMEOUT]?.();
+        } catch (error) {
+          if (error.code !== "client_outdated") throw error;
+          requiredVersion = /This origin requires Vecteur CLI (\d+\.\d+\.\d+)\./.exec(error.message)?.[1] ?? null;
+        }
+      }
+      return { contract, compatible, cli, requiredVersion };
+    } finally { response[RELEASE_TIMEOUT]?.(); }
+  }
+
+  async projectCreate(name, workspaceId, signal = undefined, idempotencyKey = undefined) {
     const value = await this.#json("POST", "/api/projects", {
-      body: { name, workspace_id: workspaceId }, signal,
+      body: { name, workspace_id: workspaceId }, signal, idempotencyKey,
     });
     if (!validateProject(value) || value.workspace_id !== workspaceId) {
       throw new CliError("project_invalid", "Server returned malformed project data");
@@ -469,6 +527,65 @@ export class VecteurClient {
     return value;
   }
 
+  async projectRename(projectId, name, signal = undefined) {
+    const value = await this.#json("PATCH", `/api/projects/${encodeURIComponent(projectId)}`, { body: { name }, signal });
+    if (!validateProject(value) || value.id !== projectId) throw new CliError("project_invalid", "Malformed renamed Project");
+    return value;
+  }
+
+  /** Body and key are frozen by the caller before any admission I/O. */
+  async runAdmit(projectId, body, idempotencyKey, signal = undefined) {
+    const value = await this.#json("POST", `/api/projects/${encodeURIComponent(projectId)}/runs`, {
+      body, idempotencyKey, signal,
+    });
+    if (!validateRunAck(value)) throw new CliError("run_ack_invalid", "Server returned malformed run acknowledgement");
+    return value;
+  }
+
+  async runCancel(runId, signal = undefined) {
+    const value = await this.#json("POST", `/api/runs/${encodeURIComponent(runId)}/cancel`, { signal });
+    if (!validateRunAck(value) || value.run_id !== runId) throw new CliError("run_ack_invalid", "Malformed cancellation acknowledgement");
+    return value;
+  }
+
+  async runControl(runId, control, signal = undefined) {
+    const value = await this.#json("POST", `/api/runs/${encodeURIComponent(runId)}/controls`, { body: control, signal });
+    if (!validateRunControl(value) || value.id !== control.id) throw new CliError("control_invalid", "Malformed control acknowledgement");
+    return value;
+  }
+
+  async clarificationAnswer(runId, questionId, answers, signal = undefined) {
+    const value = await this.#json("POST", `/api/runs/${encodeURIComponent(runId)}/clarifications/${encodeURIComponent(questionId)}/answer`,
+      { body: { answers }, signal });
+    if (!validateRunAck(value) || value.run_id !== runId) throw new CliError("run_ack_invalid", "Malformed answer acknowledgement");
+    return value;
+  }
+
+  async inputAdd(projectId, bytes, contentType, signal = undefined) {
+    const value = await this.#json("POST", `/api/projects/${encodeURIComponent(projectId)}/inputs`, {
+      rawBody: bytes, contentType, signal,
+    });
+    const digest = createHash("sha256").update(bytes).digest("hex");
+    if (!validateSource(value) || value.sha256 !== digest || value.cas_ref !== `sha256:${digest}`
+        || value.size !== bytes.byteLength) throw new CliError("source_invalid", "Uploaded source identity differs from the selected bytes");
+    if (value.offer) this.validateOffer(projectId, value, value.offer);
+    return value;
+  }
+
+  async inputOffer(projectId, source, signal = undefined) {
+    const query = new URLSearchParams({ cas_ref: source.cas_ref, acquisition_ref: source.acquisition_ref });
+    const offer = await this.#json("GET", `/api/projects/${encodeURIComponent(projectId)}/inputs/extraction-offer?${query}`, { signal });
+    return this.validateOffer(projectId, source, offer);
+  }
+
+  validateOffer(projectId, source, offer) {
+    if (!validateSourceOffer(offer) || offer.project_id !== projectId
+        || offer.source_handle.cas_ref !== source.cas_ref || offer.source_handle.acquisition_ref !== source.acquisition_ref) {
+      throw new CliError("source_offer_invalid", "Extraction offer differs from the selected source");
+    }
+    return offer;
+  }
+
   async deviceMint(signal = undefined) {
     const value = await this.#json("POST", "/api/auth/device", { body: {}, signal });
     if (!validateDeviceAuthorization(value)) {
@@ -612,21 +729,30 @@ export class VecteurClient {
    * Project, so it refuses rather than let the caller guess null.
    */
   async projectNewestRun(projectId, signal = undefined) {
-    const page = await this.#json("GET",
-      `/api/projects/${encodeURIComponent(projectId)}/runs?limit=1`, { signal });
+    const page = await this.projectHistory(projectId, { limit: 1, signal });
     const newest = page?.runs?.[0];
-    if (!exactKeys(page, ["runs", "next_before"]) || !Array.isArray(page.runs) || page.runs.length > 1
-        || (page.next_before !== null && typeof page.next_before !== "string")
-        || (newest !== undefined && (newest?.request?.project_id !== projectId
-          || !validateAdmitted(newest.response) || !isStateHash(newest.response.state_hash)))) {
-      throw new CliError("project_runs_invalid", "Server returned malformed Project run history");
-    }
     if (!newest && page.next_before !== null) {
       throw new CliError("project_head_hidden",
         `the newest Run in Project ${projectId} is not visible to this login; nothing was submitted; `
         + "next: continue in the web app, or pass --parent <state-hash>");
     }
-    return newest?.response ?? null;
+    // Client-local presentation overlay, as in the web transcript. Never write this
+    // timestamp into the immutable RunWire response or send it back to the server.
+    return newest ? { ...newest.response, accepted_at: newest.accepted_at } : null;
+  }
+
+  async projectHistory(projectId, { limit = 25, before, signal } = {}) {
+    if (!Number.isInteger(limit) || limit < 1 || limit > 25) throw new CliError("limit_invalid", "History page must contain 1–25 Runs");
+    const query = new URLSearchParams({ limit: String(limit), ...(before ? { before } : {}) });
+    const page = await this.#json("GET", `/api/projects/${encodeURIComponent(projectId)}/runs?${query}`, { signal });
+    if (!exactKeys(page, ["runs", "next_before"]) || !Array.isArray(page.runs) || page.runs.length > limit
+        || (page.next_before !== null && typeof page.next_before !== "string")
+        || page.runs.some(row => row?.request?.project_id !== projectId || typeof row.request.ask !== "string"
+          || !validateAdmitted(row.response) || !isStateHash(row.response.state_hash))) {
+      throw new CliError("project_runs_invalid", "Server returned malformed Project run history");
+    }
+    for (const row of page.runs) row.response.events.forEach((event, seq) => validateEvent(event, row.response.run_id, seq));
+    return page;
   }
 
   /**
@@ -642,11 +768,8 @@ export class VecteurClient {
       : parentStateHash;
     let value;
     try {
-      value = await this.#json("POST", `/api/projects/${encodeURIComponent(projectId)}/runs`, {
-        body: { ask, attachments: [], parent_state_hash: parent, ui_context: null },
-        idempotencyKey: randomUUID(),
-        signal,
-      });
+      value = await this.runAdmit(projectId,
+        { ask, attachments: [], parent_state_hash: parent, ui_context: null }, randomUUID(), signal);
     } catch (error) {
       if (error instanceof CliError && (error.code === "state_fork" || error.code === "state_busy")) {
         throw await this.#admissionRefused(error.code, projectId, parent, signal);
@@ -693,10 +816,20 @@ export class VecteurClient {
     return value;
   }
 
-  async runEvents(runId, onEvent = null, signal = undefined) {
+  async runEvents(runId, onEvent = null, signal = undefined, priorEvents = []) {
+    priorEvents.forEach((event, seq) => validateEvent(event, runId, seq));
+    if (priorEvents.length > MAX_EVENTS) throw new CliError("response_too_large", "Event count exceeds limit");
+    if (priorEvents.at(-1)?.kind === "terminal") {
+      const direct = await this.runGet(runId, signal);
+      if (JSON.stringify(priorEvents) !== JSON.stringify(direct.events)) {
+        throw new CliError("record_mismatch", "Event stream disagrees with direct replay");
+      }
+      return direct;
+    }
     const response = await this.request("GET", `/api/runs/${encodeURIComponent(runId)}/events`, {
       accept: "text/event-stream",
       signal,
+      lastEventId: priorEvents.length ? priorEvents.length - 1 : undefined,
     });
     let events;
     try {
@@ -704,12 +837,14 @@ export class VecteurClient {
       if (type !== "text/event-stream") {
         throw new CliError("sse_invalid", "Event route is not an SSE stream");
       }
-      events = await parseSse(response, runId, onEvent);
+      events = [...priorEvents, ...await parseSse(response, runId, onEvent, priorEvents.length)];
     } catch (error) {
       if (error?.name === "AbortError") {
+        if (signal?.aborted) throw new CliError("request_cancelled", "Following the Run was detached");
         throw new CliError("request_timeout",
           `origin ${this.config.origin}; cause=timeout; next: check the network and retry`);
       }
+      if (error instanceof TypeError) throw new CliError("request_failed", "Event connection lost; reconnect to the same Run");
       throw error;
     } finally {
       response[RELEASE_TIMEOUT]?.();

package/src/commands.js

@@ -0,0 +1,161 @@
+import { CliError } from "./errors.js";
+import { runView } from "./blocks.js";
+import { openBrowser } from "./browser.js";
+import { diagnose } from "./diagnostics.js";
+import { humanCost } from "./format.js";
+import { preferences, savePreferences } from "./preferences.js";
+
+export const SHORTCUTS = `Enter sends when ready; while running it offers steering or keeps the draft.
+Alt+Enter / Ctrl+J newline; backslash then Enter is the portable fallback.
+Paste never sends. Tab completes commands; arrows select; Esc closes a menu.
+Home/End or Ctrl+A/E: line boundaries. Alt+B/F: words. Ctrl+W: cut word.
+Ctrl+K/U: cut line tail/head. Ctrl+Y: restore cut. Ctrl+_: undo edit.
+Up/Down: multiline movement, then history at its boundary. Ctrl+R: search history.
+? on empty input: shortcuts. Ctrl+O: step details. Ctrl+L: redraw.
+Ctrl+C with text clears it (Ctrl+_ restores). Empty idle Ctrl+C twice exits.
+Esc twice or empty Ctrl+C twice requests cancellation of the same cloud Run.
+Ctrl+D on empty input saves and detaches; the cloud Run continues. /quit also exits.`;
+
+const rows = [];
+const add = (name, description, run, options = {}) => rows.push({ name, description, run, ...options });
+add("help", "Find commands and their purpose", (s, query) => s.message(help(query, s)), { argument: "[query]" });
+add("shortcuts", "All editing, navigation and Run keys", s => s.message(SHORTCUTS));
+add("status", "Account, Project, connection and current state", s => s.message(s.statusDetails()));
+add("login", "Sign in through your browser", s => s.initialize({ login: true }));
+add("logout", "Sign out here; preserve account drafts", s => s.logout(), { requires: "login" });
+add("offline", "Draft without any network activity", s => {
+  if (s.busy && !s.loginController) throw new CliError("session_busy", "Wait for this action to finish before disconnecting; your draft is kept");
+  s.workOffline();
+});
+add("resume", "Reconnect or reconcile an interrupted ask", s => s.resume());
+add("quit", "Save draft and detach; cloud Run continues", s => s.close(), { aliases: ["exit"] });
+add("drafts", "Recover a saved draft", s => s.recoverDraft());
+add("clear", "Clear this draft; Ctrl+_ restores the edit", s => { s.lastClearedDraft = s.draft; s.setDraft(""); });
+add("mode", "Lead, model, execution location and payer", s => s.message(s.modeDetails()));
+add("model", "Choose the next Run's server model or route", s => s.modelChoice(), { requires: "login" });
+add("usage", "Read the Project's server-authored usage", async s => {
+  if (!s.project) throw new CliError("project_unavailable", "Choose a Project first with /project");
+  const client = s.client, project = s.project;
+  const value = await client.customerCost(project.id);
+  if (s.client === client && s.project === project) s.message(humanCost(value));
+}, { requires: "login" });
+add("settings", "Plain display, reduced motion and updates", async s => {
+  const key = await s.choose("Settings", [
+    { label: "Display: rich or plain", value: "plain" }, { label: "Reduced motion", value: "reducedMotion" },
+    { label: "Automatic updates for this installation", value: "updates" },
+  ]);
+  if (key === "updates") { const { updatePreference } = await import("./update.js"); return updatePreference(s); }
+  const value = await s.choose(key === "plain" ? "Display" : "Reduced motion", [
+    { label: key === "plain" ? "Rich terminal" : "Enabled", value: key !== "plain" },
+    { label: key === "plain" ? "Plain / screen reader" : "Disabled", value: key === "plain" },
+  ]);
+  savePreferences({ [key]: value }, s.env); s.emit("preferences", preferences(s.env)); s.message("Preference saved.");
+});
+add("update", "Check or update this exact installation", async (s, argument) => {
+  if (argument && argument !== "check") throw new CliError("usage_invalid", "Use /update or /update check");
+  const { interactiveUpdate } = await import("./update.js"); return interactiveUpdate(s, { check: argument === "check" });
+}, { argument: "[check]" });
+add("project", "Choose a Project or start a new study draft", async (s, argument) => {
+  if (argument === "list") {
+    const client = s.client, account = s.account;
+    const projects = await client.projectList();
+    if (s.client === client && s.account === account) s.message(projects.map(p => `${p.name} · ${p.role} · ${p.id}`).join("\n") || "No Projects yet.");
+    return;
+  }
+  if (argument) throw new CliError("usage_invalid", "Use /project or /project list");
+  const action = await s.choose("Project", [
+    { label: "Open an existing Project without linking", value: "open" },
+    { label: "Link an existing Project to this folder", value: "link" },
+    { label: "Start a new study on next send", value: "new" },
+  ]);
+  if (action !== "new") return s.link({ persist: action === "link" });
+  if (s.run?.open || s.registry.state().pendingRun || s.registry.state().pendingCreate) throw new CliError("run_busy", "Resolve or finish the current Run before starting a new study");
+  s.registry.unlink(); s.binding = null; s.project = null; s.run = null; s.attachments = []; s.status = "New Project on first send"; s.change();
+}, { argument: "[list]", requires: "login" });
+add("link", "Link an existing Project to this folder", s => s.link(), { requires: "login" });
+add("unlink", "Remove this folder's Project binding", s => {
+  if (s.run?.open || s.busy || s.registry.state().pendingRun || s.registry.state().pendingCreate) throw new CliError("run_busy", "Resolve or finish the current Run before unlinking");
+  s.followController?.abort(); s.generation++; s.registry.unlink(); s.binding = null; s.project = null; s.run = null; s.status = "Folder unlinked"; s.change();
+}, { requires: "login" });
+add("history", "Read earlier Runs in this Project", s => s.history(), { requires: "login" });
+add("name", "Name the Project", (s, value) => s.transition(async () => {
+  if (s.project) { s.requireLogin(); s.project = await s.client.projectRename(s.project.id, value); } else s.projectName = value;
+  s.change();
+}), { argument: "<name>", required: true });
+add("attach", "Select one file; preview its upload destination", async (s, path) => {
+  if (!path) path = await s.choose("File path (only this file is read; blank cancels)", [], { typed: true });
+  if (path.trim()) return s.attach(path.replace(/^(['"])(.*)\1$/, "$2"));
+}, { argument: "<path>" });
+add("clear-files", "Remove pending attachments", s => {
+  if (s.busy || s.registry?.state().pendingRun) throw new CliError("session_busy", "Resolve the pending action before clearing files");
+  s.attachments = []; s.change();
+});
+add("files", "Selected inputs and downloadable results", s => s.message([
+  ...s.attachments.map(item => `Pending: ${item.path} (${item.bytes.length} bytes; not uploaded)`),
+  ...runView(s.run).artifacts.map((item, i) => `${i + 1}. ${item.filename} · ${item.kind} · /download ${i + 1} · /web`),
+].join("\n") || "No selected files or artifacts."));
+add("download", "Save and verify a result file", (s, argument) => {
+  const match = /^(\d+)(?:\s+(.+))?$/.exec(argument);
+  if (!match) throw new CliError("usage_invalid", "Use /download <artifact number> [output path]");
+  return s.download(Number(match[1]), match[2]);
+}, { argument: "<number> [path]", required: true, requires: "login" });
+add("export", "Export the answer, Run record and verified files to a new folder", (s, path) => s.exportRun(path || undefined), { argument: "[folder]", requires: "login" });
+add("copy", "Copy the exact answer or save it to a new file", (s, path) => s.copy(path || undefined), { argument: "[path]" });
+add("answer", "Answer the current clarification", s => s.answer(), { requires: "question" });
+add("steer", "Send an instruction to the running Run", (s, text) => s.steer(text), { argument: "<instruction>", required: true, requires: "run" });
+add("answer-now", "Ask the running Run to conclude", s => s.steer(""), { requires: "run" });
+add("cancel", "Request cancellation; keep completed work", s => s.cancel(), { requires: "run" });
+add("details", "Read the current or numbered step", (s, argument) => {
+  const steps = runView(s.run).steps;
+  const event = argument ? steps[Number(argument) - 1] : steps.at(-1);
+  s.message(event ? JSON.stringify(event.payload, null, 2) : "No step details yet.");
+}, { argument: "[number]" });
+add("handoff", "Open your Claude Code or Codex here with Vecteur attached", (s, vendor) => {
+  if (!["claude", "codex"].includes(vendor)) throw new CliError("usage_invalid", "Use /handoff claude or /handoff codex");
+  if (s.busy) throw new CliError("session_busy", "Wait for this action to finish before handing off");
+  s.emit("handoff", vendor);
+}, { argument: "<claude|codex>", required: true });
+add("web", "Open this Project in the browser", s => {
+  const url = s.project ? `${s.origin}/dashboard/${encodeURIComponent(s.project.id)}` : s.origin;
+  s.message(url); if (!s.noBrowser && !s.offline) void openBrowser(url);
+});
+add("doctor", "Diagnose connection and installation", async s => {
+  const client = s.client, account = s.account;
+  const result = await diagnose({ env: s.env, origin: s.origin, client, offline: s.offline });
+  if (s.client === client && s.account === account) s.message(result.text);
+});
+export const COMMANDS = Object.freeze(rows.map(Object.freeze));
+export function unavailable(row, session) {
+  if (!row.requires) return "";
+  if (session.offline) return "Offline — /resume";
+  if (!session.account) return "Sign in — /login";
+  if (row.requires === "login") return "";
+  if (session.project?.role === "VIEWER") return "Read-only Project";
+  if (row.requires === "question") return runView(session.run).question ? "" : "No pending question";
+  return session.run?.open ? "" : "No running Run";
+}
+export function completions(query = "", session) {
+  const text = query.replace(/^\//, "").toLowerCase();
+  return COMMANDS.filter(row => `${row.name} ${row.description}`.toLowerCase().includes(text))
+    .map(row => ({ ...row, disabled: session ? unavailable(row, session) : "" }))
+    .sort((a, b) => Number(Boolean(a.disabled)) - Number(Boolean(b.disabled)) || Number(b.name === text) - Number(a.name === text));
+}
+export function help(query = "", session) {
+  return completions(query, session).map(row => `/${row.name}${row.argument ? " " + row.argument : ""} — ${row.description}${row.disabled ? ` (${row.disabled})` : ""}`).join("\n") + "\n/shortcuts lists every key. Esc twice cancels the current Run.";
+}
+export const HELP = help();
+export async function command(session, input) {
+  if (input.startsWith("//")) return session.submit(input.slice(1));
+  const match = /^\/(\S+)(?:\s+([\s\S]*))?$/.exec(input);
+  if (!match) return session.submit(input);
+  const [, name, argument = ""] = match;
+  if (name === "device") { session.message("Computer connection is not available in this version."); return; }
+  const row = COMMANDS.find(row => row.name === name || row.aliases?.includes(name));
+  if (!row) throw new CliError("command_unknown", `Unknown /${name}; /help searches commands. Use // to send literal text starting with /.`);
+  const reason = unavailable(row, session);
+  if (reason) throw new CliError("action_unavailable", reason);
+  let value = argument;
+  if (row.required && !value.trim()) value = await session.choose(`/${row.name} ${row.argument} (blank cancels)`, [], { typed: true });
+  if (row.required && !value.trim()) return;
+  return row.run(session, value);
+}