@gleapai/kai-bridge 0.2.9 → 0.6.0

package/runner/tools/verify-mcp.mjs

@@ -0,0 +1,442 @@
+#!/usr/bin/env node
+// Minimal stdio MCP server for the `kai-verifier` persona (Kai Code
+// "Verify"). Two tools, zero dependencies; speaks newline-delimited
+// JSON-RPC 2.0 per the MCP stdio transport (same skeleton as todo-mcp.mjs
+// / ask-user-mcp.mjs).
+//
+//   report_verification — the verdict channel. The verifier drives the
+//     running preview with the Playwright MCP, records a video +
+//     screenshots, and must hand the host a STRUCTURED result — pass/fail
+//     checks, what stayed untested, and the local path of every artifact
+//     the browser tools wrote. Prose in the final message can't be
+//     uploaded or rendered as an evidence card. The runner's mapper
+//     (lib/acp/mapper.mjs) sniffs calls to this tool into the
+//     `verify_report` contract event; the host (kai-bridge daemon) uploads
+//     the artifacts and replaces the paths with URLs. The tool itself is a
+//     signalling no-op — the INPUT is the product. Not turn-ending: the
+//     persona wraps up normally after reporting.
+//
+//   http_request — the ONLY HTTP path for API changes (no curl). Performs
+//     the call in-process against the preview / external origins the host
+//     allows, appends one JSON line per call to
+//     `<evidence dir>/requests.jsonl` (the transcript IS the evidence — the
+//     host uploads it as a `requests` artifact) and refuses writes when the
+//     run is read-only. The host derives an auth header from the app's own
+//     sign-in and hands it over by env — the model never sees the value.
+//
+// Env (all set by the host; every one optional):
+//   KAI_VERIFY_READ_ONLY=1        non-GET/HEAD/OPTIONS refused, recorded as `refused: "read_only"`
+//   KAI_VERIFY_ORIGINS            allowed origins, `;`/`,`/space separated (`http://localhost:*` = any port)
+//   KAI_VERIFY_AUTH_HEADER        `Header-Name: value` (bare value = Authorization); sent to LOCAL origins only, masked everywhere
+//   KAI_VERIFY_EVIDENCE_DIR       where `requests.jsonl` is appended (no dir → nothing written)
+
+import { appendFileSync, mkdirSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { createInterface } from "node:readline";
+import { fileURLToPath } from "node:url";
+
+const CHECK_STATUS = ["passed", "failed"];
+export const BLOCKED_CODES = ["needs_login", "preview_unreachable", "not_verifiable", "other"];
+export const READ_METHODS = new Set(["GET", "HEAD", "OPTIONS"]);
+export const RESPONSE_BODY_CAP = 8 * 1024;
+export const REQUEST_TIMEOUT_MS = 30_000;
+export const REQUESTS_FILE = "requests.jsonl";
+const MASKED = "[masked]";
+const MASKED_REQUEST_HEADERS = new Set(["authorization", "cookie", "proxy-authorization", "x-api-key"]);
+const LOCAL_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]", "::1"]);
+
+const REPORT_TOOL = {
+  name: "report_verification",
+  description:
+    "File the verification report for this run. Call it EXACTLY ONCE, as " +
+    "the last thing you do: list every check you performed with its " +
+    "result, everything you could not test, and the path of EVERY " +
+    "artifact (video, screenshots, traces) the browser tools returned. " +
+    "A `passed` report needs at least one check. " +
+    "Status `blocked` = you could not verify (preview unreachable, a login " +
+    "wall, nothing to exercise from the app, …) — explain why in `reason`, " +
+    "classify it in `blockedCode` and still list the partial evidence you " +
+    "have. Never include cookies, tokens, response bodies or other secret " +
+    "values anywhere in the report.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      status: {
+        type: "string",
+        enum: ["passed", "failed", "blocked"],
+        description:
+          "Overall verdict: passed = every check passed (at least one check); failed = at least " +
+          "one check failed; blocked = verification could not be carried out.",
+      },
+      scope: {
+        type: "string",
+        description: "One line: what was tested (feature / flow / pages / endpoints).",
+      },
+      reason: {
+        type: "string",
+        description: "For failed/blocked: the explanation in one or two sentences.",
+      },
+      blockedCode: {
+        type: "string",
+        enum: BLOCKED_CODES,
+        description:
+          "For blocked only: `needs_login` = a sign-in wall stopped you, or an API answered 401/403 without credentials (set " +
+          "`loginPath`; do NOT ask the user for credentials — the host " +
+          "arranges the sign-in and re-runs you); `preview_unreachable` = " +
+          "the preview never answered / the page never loaded; `not_verifiable` = " +
+          "the change has nothing a tester can exercise from the running app (build tooling, " +
+          "comments, types only) — never fabricate a check instead; `other` = anything else (explain in `reason`).",
+      },
+      loginPath: {
+        type: "string",
+        description:
+          "With blockedCode needs_login: the URL path of the login wall or the endpoint that refused you " +
+          "(e.g. `/login`, `/api/v1/me`) — never the full URL with tokens, never credentials.",
+      },
+      checks: {
+        type: "array",
+        items: {
+          type: "object",
+          properties: {
+            label: { type: "string", description: "What was checked, in plain words." },
+            status: { type: "string", enum: CHECK_STATUS },
+          },
+          required: ["label", "status"],
+        },
+        description: "Every check performed, in order. Only checks you actually performed.",
+      },
+      untested: {
+        type: "array",
+        items: { type: "string" },
+        description: "What was NOT verified and why (honest gaps — a 404 on a guessed API path belongs here, not in checks).",
+      },
+      artifacts: {
+        type: "array",
+        items: {
+          type: "object",
+          properties: {
+            label: { type: "string", description: "Short caption shown under the artifact." },
+            path: { type: "string", description: "Local file path exactly as the browser tool returned it." },
+            kind: { type: "string", enum: ["screenshot", "video", "trace"] },
+          },
+          required: ["label", "path", "kind"],
+        },
+        description: "Every recording, screenshot and trace produced in this run (the HTTP transcript is collected by the host — do not list it).",
+      },
+    },
+    required: ["status", "checks", "artifacts"],
+  },
+};
+
+const HTTP_TOOL = {
+  name: "http_request",
+  description:
+    "Perform ONE HTTP request against the running preview (or an external origin the task lists) and record it " +
+    "in the verification transcript. This is the only way to call an API in a verification run — never use curl. " +
+    "The host adds the app's own authentication automatically when it has one; never guess or paste tokens. " +
+    "In a read-only run (shared database) anything but GET/HEAD/OPTIONS is refused and recorded as skipped — " +
+    "put such endpoints in `untested`. A 401/403 without credentials is a `needs_login` block, never a failed check; " +
+    "a 404 on a path you guessed is `untested`. Resolve real paths from the OpenAPI spec first.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      method: { type: "string", description: "HTTP method (GET, HEAD, OPTIONS, POST, PUT, PATCH, DELETE). Default GET." },
+      url: { type: "string", description: "Absolute URL on an allowed origin, or a path (`/api/v1/tickets`) resolved against the first allowed origin." },
+      headers: { type: "object", additionalProperties: { type: "string" }, description: "Extra request headers (Accept, Content-Type, …). Authentication is added by the host." },
+      body: { description: "Request body: a string is sent as-is; an object is sent as JSON." },
+      check: { type: "string", description: "What this request verifies, in plain words (shown next to the row in the transcript)." },
+    },
+    required: ["url"],
+  },
+};
+
+export const TOOLS = [REPORT_TOOL, HTTP_TOOL];
+
+/** `KAI_VERIFY_ORIGINS` → normalised origins (`http://localhost:*` kept as a wildcard). */
+export function parseOrigins(raw) {
+  const out = [];
+  for (const part of String(raw || "").split(/[;,\s]+/)) {
+    const text = part.trim();
+    if (!text) continue;
+    const wildcard = /^(https?):\/\/([^/:]+):\*$/i.exec(text);
+    if (wildcard) {
+      out.push(`${wildcard[1].toLowerCase()}://${wildcard[2].toLowerCase()}:*`);
+      continue;
+    }
+    try {
+      out.push(new URL(text).origin.toLowerCase());
+    } catch {
+      /* junk entry */
+    }
+  }
+  return [...new Set(out)];
+}
+
+/** Is `url`'s origin one of the allowed ones (wildcard ports included)? */
+export function isAllowedOrigin(url, allowed) {
+  let u;
+  try {
+    u = new URL(url);
+  } catch {
+    return false;
+  }
+  if (u.protocol !== "http:" && u.protocol !== "https:") return false;
+  const origin = u.origin.toLowerCase();
+  for (const a of allowed || []) {
+    if (a === origin) return true;
+    if (a.endsWith(":*") && origin.startsWith(a.slice(0, -1))) return true;
+    if (a.endsWith(":*")) {
+      const [proto, host] = a.slice(0, -2).split("://");
+      if (u.protocol === `${proto}:` && u.hostname.toLowerCase() === host) return true;
+    }
+  }
+  return false;
+}
+
+/** Absolute URL for the request: paths resolve against the first allowed origin. */
+export function resolveRequestUrl(raw, allowed) {
+  const text = String(raw || "").trim();
+  if (!text) return null;
+  if (/^https?:\/\//i.test(text)) return text;
+  const base = (allowed || []).find((o) => !o.endsWith(":*"));
+  if (!base) return null;
+  try {
+    return new URL(text.startsWith("/") ? text : `/${text}`, base).toString();
+  } catch {
+    return null;
+  }
+}
+
+/** `Authorization: Bearer x` → { name, value }; a bare value is an Authorization header. Null when empty. */
+export function parseAuthHeader(raw) {
+  const text = String(raw || "").trim();
+  if (!text) return null;
+  const m = /^([A-Za-z0-9-]+):\s*(.+)$/.exec(text);
+  if (m) return { name: m[1], value: m[2].trim() };
+  return { name: "Authorization", value: text };
+}
+
+/** The host-derived auth header only ever goes to the preview itself, never to an external origin. */
+export function isLocalOrigin(url) {
+  try {
+    return LOCAL_HOSTS.has(new URL(url).hostname.toLowerCase());
+  } catch {
+    return false;
+  }
+}
+
+/** Request headers as recorded: credentials masked, names lower-cased. */
+export function maskHeaders(headers) {
+  const out = {};
+  for (const [k, v] of Object.entries(headers || {})) {
+    const key = String(k).toLowerCase();
+    out[key] = MASKED_REQUEST_HEADERS.has(key) ? MASKED : String(v);
+  }
+  return out;
+}
+
+/** Response body capped at 8 KB for the transcript. */
+export function capBody(text) {
+  const body = String(text ?? "");
+  if (body.length <= RESPONSE_BODY_CAP) return { body, truncated: false };
+  return { body: body.slice(0, RESPONSE_BODY_CAP), truncated: true };
+}
+
+/**
+ * Pure: decide what to do with an `http_request` call. Returns
+ * `{ refused: "origin" | "read_only" | "invalid", url, method, headers }`
+ * or `{ url, method, headers, body }` ready for fetch. `headers` already
+ * carries the host auth header when it applies.
+ */
+export function planRequest(args, { readOnly = false, allowed = [], auth = null } = {}) {
+  const method = String(args?.method || "GET").trim().toUpperCase() || "GET";
+  const url = resolveRequestUrl(args?.url, allowed);
+  const userHeaders = {};
+  for (const [k, v] of Object.entries(args?.headers && typeof args.headers === "object" ? args.headers : {})) {
+    if (typeof v === "string" || typeof v === "number") userHeaders[String(k)] = String(v);
+  }
+  if (!url) return { refused: "invalid", method, url: String(args?.url || ""), headers: userHeaders, reason: "not a valid URL (absolute http(s) URL or a path on the preview)" };
+  if (!isAllowedOrigin(url, allowed)) return { refused: "origin", method, url, headers: userHeaders, reason: `origin not allowed for this run (allowed: ${allowed.join(", ") || "none"})` };
+  if (readOnly && !READ_METHODS.has(method)) return { refused: "read_only", method, url, headers: userHeaders, reason: "this is a read-only run — writes are skipped; list the endpoint under untested" };
+  const headers = { ...userHeaders };
+  let body = args?.body;
+  if (body !== undefined && body !== null && !READ_METHODS.has(method)) {
+    if (typeof body !== "string") {
+      body = JSON.stringify(body);
+      if (!Object.keys(headers).some((h) => h.toLowerCase() === "content-type")) headers["Content-Type"] = "application/json";
+    }
+  } else {
+    body = undefined;
+  }
+  if (auth && isLocalOrigin(url)) {
+    // The host's header wins: a guessed Authorization from the model would
+    // only ever hide the real sign-in state.
+    for (const k of Object.keys(headers)) if (k.toLowerCase() === auth.name.toLowerCase()) delete headers[k];
+    headers[auth.name] = auth.value;
+  }
+  return { method, url, headers, body };
+}
+
+/** One transcript row (`requests.jsonl` line). Credentials are masked, never the row's URL query (the model chose it). */
+export function buildRequestRow({ plan, check, status = null, ms = null, responseHeaders = null, responseBody = null, truncated = false, error = null, now = new Date() }) {
+  const row = {
+    t: now.toISOString(),
+    method: plan.method,
+    url: plan.url,
+    status,
+    ms,
+    requestHeaders: maskHeaders(plan.headers),
+    requestBody: plan.body === undefined ? null : capBody(plan.body).body,
+    responseHeaders,
+    responseBody,
+    truncated: !!truncated,
+    check: typeof check === "string" && check.trim() ? check.trim().slice(0, 300) : null,
+  };
+  if (plan.refused) row.refused = plan.refused;
+  if (error) row.error = String(error).slice(0, 300);
+  return row;
+}
+
+function appendRow(dir, row) {
+  if (!dir) return;
+  try {
+    mkdirSync(dir, { recursive: true });
+    appendFileSync(join(dir, REQUESTS_FILE), `${JSON.stringify(row)}\n`);
+  } catch {
+    /* the transcript is best-effort; the tool result still reaches the model */
+  }
+}
+
+/** What the model sees for a refused call — plain words, an action to take. */
+function describeRefusal(plan) {
+  if (plan.refused === "read_only") return `Skipped: ${plan.method} ${plan.url} — ${plan.reason}. Recorded as skipped in the transcript.`;
+  if (plan.refused === "origin") return `Refused: ${plan.method} ${plan.url} — ${plan.reason}.`;
+  return `Refused: ${plan.url || "(empty)"} — ${plan.reason}.`;
+}
+
+/**
+ * Perform the call (injectable fetch for tests). Returns the tool result
+ * text + the transcript row; the auth header value never appears in either.
+ */
+export async function performHttpRequest(args, { readOnly, allowed, auth, evidenceDir, fetchImpl = fetch, now = () => new Date(), timeoutMs = REQUEST_TIMEOUT_MS } = {}) {
+  const plan = planRequest(args, { readOnly, allowed, auth });
+  if (plan.refused) {
+    const row = buildRequestRow({ plan, check: args?.check, now: now() });
+    appendRow(evidenceDir, row);
+    return { text: describeRefusal(plan), row, isError: plan.refused !== "read_only" };
+  }
+  const startedAt = Date.now();
+  try {
+    const res = await fetchImpl(plan.url, {
+      method: plan.method,
+      headers: plan.headers,
+      body: plan.body,
+      redirect: "manual",
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    const ms = Date.now() - startedAt;
+    const responseHeaders = {};
+    for (const [k, v] of res.headers?.entries?.() ?? []) responseHeaders[k.toLowerCase()] = v;
+    const raw = plan.method === "HEAD" ? "" : await res.text().catch(() => "");
+    const { body, truncated } = capBody(raw);
+    const row = buildRequestRow({ plan, check: args?.check, status: res.status, ms, responseHeaders, responseBody: body, truncated, now: now() });
+    appendRow(evidenceDir, row);
+    const headLine = `HTTP ${res.status}${res.statusText ? ` ${res.statusText}` : ""} (${ms} ms) ${plan.method} ${plan.url}`;
+    const shown = ["content-type", "content-length", "location"].filter((h) => responseHeaders[h]).map((h) => `${h}: ${responseHeaders[h]}`);
+    const text = [headLine, ...shown, "", body || "(empty body)", truncated ? `\n[response truncated to ${RESPONSE_BODY_CAP} bytes in the transcript]` : ""].join("\n").trimEnd();
+    return { text, row, isError: false };
+  } catch (err) {
+    const ms = Date.now() - startedAt;
+    const message = err?.name === "TimeoutError" ? `timed out after ${Math.round(timeoutMs / 1000)}s` : err?.cause?.code || err?.message || String(err);
+    const row = buildRequestRow({ plan, check: args?.check, ms, error: message, now: now() });
+    appendRow(evidenceDir, row);
+    return { text: `Request failed: ${plan.method} ${plan.url} — ${message}. If the preview never answers, report blocked (preview_unreachable).`, row, isError: true };
+  }
+}
+
+/** Env → the request policy for this run. */
+export function policyFromEnv(env = process.env) {
+  return {
+    readOnly: env.KAI_VERIFY_READ_ONLY === "1" || env.KAI_VERIFY_READ_ONLY === "true",
+    allowed: parseOrigins(env.KAI_VERIFY_ORIGINS),
+    auth: parseAuthHeader(env.KAI_VERIFY_AUTH_HEADER),
+    evidenceDir: env.KAI_VERIFY_EVIDENCE_DIR || null,
+  };
+}
+
+function send(message) {
+  process.stdout.write(`${JSON.stringify(message)}\n`);
+}
+
+function reply(id, result) {
+  send({ jsonrpc: "2.0", id, result });
+}
+
+function replyError(id, code, message) {
+  send({ jsonrpc: "2.0", id, error: { code, message } });
+}
+
+function serve() {
+  const policy = policyFromEnv();
+  const rl = createInterface({ input: process.stdin, terminal: false });
+  rl.on("line", (line) => {
+    const trimmed = line.trim();
+    if (!trimmed) return;
+    let msg;
+    try {
+      msg = JSON.parse(trimmed);
+    } catch {
+      return;
+    }
+    const { id, method } = msg ?? {};
+    if (typeof method !== "string") return;
+
+    if (method === "initialize") {
+      reply(id, {
+        protocolVersion: msg.params?.protocolVersion ?? "2025-06-18",
+        capabilities: { tools: {} },
+        serverInfo: { name: "kai-verify", version: "1.1.0" },
+      });
+      return;
+    }
+    if (method === "notifications/initialized" || id == null) {
+      return; // notifications need no response
+    }
+    if (method === "tools/list") {
+      reply(id, { tools: TOOLS });
+      return;
+    }
+    if (method === "tools/call") {
+      const name = msg.params?.name;
+      const args = msg.params?.arguments ?? {};
+      if (name === REPORT_TOOL.name) {
+        // Loose validation: the host normalises the report; a malformed call
+        // must not stall the turn with an error the model then retries.
+        const checks = Array.isArray(args.checks) ? args.checks.length : 0;
+        const artifacts = Array.isArray(args.artifacts) ? args.artifacts.length : 0;
+        reply(id, {
+          content: [
+            {
+              type: "text",
+              text: `Verification report received (${args.status ?? "unknown"}, ${checks} check${checks === 1 ? "" : "s"}, ${artifacts} artifact${artifacts === 1 ? "" : "s"}). You are done — end your turn with a one-paragraph summary.`,
+            },
+          ],
+        });
+        return;
+      }
+      if (name === HTTP_TOOL.name) {
+        void performHttpRequest(args, policy).then(
+          ({ text, isError }) => reply(id, { content: [{ type: "text", text }], ...(isError ? { isError: true } : {}) }),
+          (err) => reply(id, { content: [{ type: "text", text: `Request failed: ${err?.message || err}` }], isError: true }),
+        );
+        return;
+      }
+      replyError(id, -32602, `unknown tool: ${name}`);
+      return;
+    }
+    replyError(id, -32601, `unknown method: ${method}`);
+  });
+}
+
+// Runs as a server when spawned directly; importable for its pure helpers.
+if (process.argv[1] && fileURLToPath(import.meta.url) === resolve(process.argv[1])) serve();

package/src/api.mjs

@@ -6,8 +6,19 @@
 //   POST   /gleapcode/bridge/devices/me/heartbeat  { running: [turnIds] }
 //   POST   /gleapcode/bridge/turns/:id/events      { events: [contract lines] }
 //   POST   /gleapcode/bridge/turns/:id/result      { result, changes, status }
+//   POST   /gleapcode/bridge/turns/:id/artifacts   multipart `file`            → { url }   (verify evidence)
+//   POST   /gleapcode/bridge/turns/:id/verification{ status, scope, reason, checks, untested, artifacts, evidence?, revisions? }
+//   PUT    /gleapcode/bridge/turns/:id/verification/artifacts { artifacts, evidence }   (evidence retry — union by URL, clears evidenceMissing)
+//   POST   /gleapcode/bridge/turns/:id/verification/stage { stage, note? }   (setup|booting|login|verifying|fixing|saving)
+//   GET    /gleapcode/bridge/turns/:id/preview-login → the saved sign-in record for this verify turn (one GET per turn)
+//   POST   /gleapcode/bridge/preview-logins/:requestId          { storageState, origins, services, landingUrl, loginPaths }  (capture upload)
+//   POST   /gleapcode/bridge/preview-logins/:requestId/status   { status: opened|waiting_signin|detected|failed|cancelled, error? }
+//   PUT    /gleapcode/bridge/preview-logins/:id                 { storageState, basedOnVersion } → 409 on a stale version
 //   POST   /users/me/pusher                        { socket_id, channel_name }   (channel auth)
 
+import { readFile } from "node:fs/promises";
+import { basename } from "node:path";
+
 export class BridgeApi {
   constructor({ apiBase, token, fetchImpl = fetch }) {
     this.apiBase = String(apiBase).replace(/\/+$/, "");
@@ -105,7 +116,97 @@ export class BridgeApi {
     );
   }
 
-  /** Turns the server still believes this device is running. */
+  /**
+   * Upload one verify artifact (recording / screenshot / trace) as
+   * multipart `file`; resolves the Server's `{ url }`. Separate from the
+   * JSON-only `request()`: the body is a FormData (fetch sets the boundary
+   * header itself — never set content-type here), a video can take a
+   * while (5-min cap), and it retries transient failures 3× — a dropped
+   * screenshot is missing evidence, not a broken turn.
+   */
+  async uploadArtifact(turnId, filePath, contentType, { tries = 3, timeoutMs = 5 * 60_000, onRetry } = {}) {
+    const bytes = await readFile(filePath);
+    const path = `/gleapcode/bridge/turns/${encodeURIComponent(turnId)}/artifacts`;
+    let delay = 1_000;
+    for (let attempt = 1; ; attempt += 1) {
+      try {
+        const form = new FormData();
+        form.append("file", new Blob([bytes], { type: contentType }), basename(filePath));
+        const res = await this.fetch(`${this.apiBase}${path}`, {
+          method: "POST",
+          headers: { ...(this.token ? { authorization: `Bearer ${this.token}` } : {}) },
+          body: form,
+          signal: AbortSignal.timeout(timeoutMs),
+        });
+        const text = await res.text();
+        let data = null;
+        try {
+          data = text ? JSON.parse(text) : null;
+        } catch {
+          data = { raw: text };
+        }
+        if (!res.ok) {
+          const err = new Error(`POST ${path} → ${res.status}: ${data?.message ?? data?.error ?? text.slice(0, 200)}`);
+          err.status = res.status;
+          err.data = data;
+          throw err;
+        }
+        if (typeof data?.url !== "string" || !data.url) throw new Error(`POST ${path} → no url in response`);
+        return data;
+      } catch (err) {
+        const permanent = err.status >= 400 && err.status < 500 && err.status !== 429;
+        if (permanent || attempt >= tries) throw err;
+        onRetry?.(err, attempt, delay);
+        await new Promise((r) => setTimeout(r, delay));
+        delay = Math.min(delay * 2, 30_000);
+      }
+    }
+  }
+
+  /** The verification report for a verify turn (artifacts already uploaded → URLs). */
+  turnVerification(turnId, payload, opts) {
+    return this.requestWithRetry("POST", `/gleapcode/bridge/turns/${encodeURIComponent(turnId)}/verification`, payload, opts);
+  }
+
+  /** Late evidence (`bridge.verify.evidence.retry`): the Server unions by URL and clears `evidenceMissing`. */
+  putVerificationArtifacts(turnId, payload, opts) {
+    return this.requestWithRetry("PUT", `/gleapcode/bridge/turns/${encodeURIComponent(turnId)}/verification/artifacts`, payload, opts);
+  }
+
+  /** Stage transition of a running verify turn (best-effort UI state — callers swallow errors). */
+  turnVerificationStage(turnId, payload) {
+    return this.request("POST", `/gleapcode/bridge/turns/${encodeURIComponent(turnId)}/verification/stage`, payload);
+  }
+  /**
+   * The saved sign-in for this verify turn: `{ id, version, storageState,
+   * origins, services, landingUrl, loginPaths, optional }` (or `null` —
+   * a 404 is "no record", not an error). The Server allows ONE successful
+   * GET per turn and never caches it.
+   */
+  async turnPreviewLogin(turnId) {
+    try {
+      const data = await this.request("GET", `/gleapcode/bridge/turns/${encodeURIComponent(turnId)}/preview-login`);
+      const record = data && typeof data === "object" && "record" in data ? data.record : data;
+      return record && typeof record === "object" && record.storageState ? record : null;
+    } catch (err) {
+      if (err?.status === 404) return null;
+      throw err;
+    }
+  }
+  /** Capture upload against a pending login request (the ONLY thing a device may upload a sign-in against). */
+  uploadPreviewLogin(requestId, payload, opts) {
+    return this.requestWithRetry("POST", `/gleapcode/bridge/preview-logins/${encodeURIComponent(requestId)}`, payload, opts);
+  }
+  /** Capture progress for the dashboard's sign-in card. */
+  previewLoginStatus(requestId, payload) {
+    return this.request("POST", `/gleapcode/bridge/preview-logins/${encodeURIComponent(requestId)}/status`, payload);
+  }
+  /** Refresh a record after a verify run (CAS on `basedOnVersion`; 409 = someone else refreshed first → discard). */
+  refreshPreviewLogin(recordId, payload) {
+    return this.request("PUT", `/gleapcode/bridge/preview-logins/${encodeURIComponent(recordId)}`, payload);
+  }
+
+  /** Turns (and pending sign-in requests) the server still believes this device is running. */
   pendingTurns() {
     return this.request("GET", "/gleapcode/bridge/devices/me/pending");
   }

package/src/companions.mjs

@@ -0,0 +1,101 @@
+// Companion repos for a preview (kai-bridge 0.5.0) — the pure parts.
+//
+// A frontend's dev.yaml names the API it needs (`companions:`), that API
+// may name a worker, and so on: a BFS up to depth 3 with a visited set
+// collects them all; boot order is deepest-first so `${port:x}` references
+// and `requires:` checks find their targets running. Cloning a missing
+// companion needs a remote: the Server resolves one per key from the
+// connected repository (`companionRemotes`) — the daemon never guesses
+// `https://github.com/<key>` for a non-github host — and the clone scheme
+// follows the machine's existing checkouts (SSH when any of them is).
+
+/** `https://github.com/o/n(.git)` ↔ `git@github.com:o/n.git`, by preference. */
+export function withCloneScheme(remote, { useSsh = false } = {}) {
+  const text = String(remote || "").trim();
+  if (!text) return null;
+  const https = /^https?:\/\/([^/]+)\/([^/]+)\/([^/]+?)(?:\.git)?\/?$/i.exec(text);
+  const ssh = /^(?:ssh:\/\/)?git@([^:/]+)[:/]([^/]+)\/([^/]+?)(?:\.git)?$/i.exec(text);
+  const parts = https ? { host: https[1], owner: https[2], name: https[3] } : ssh ? { host: ssh[1], owner: ssh[2], name: ssh[3] } : null;
+  if (!parts) return text; // a local path or an exotic remote — as given
+  return useSsh ? `git@${parts.host}:${parts.owner}/${parts.name}.git` : `https://${parts.host}/${parts.owner}/${parts.name}.git`;
+}
+
+/**
+ * The remote to clone `key` from: the Server-resolved `remotes[key]`
+ * (any provider), else — for github.com keys only — the key itself.
+ * Null means the daemon cannot know (→ `companion_missing`).
+ */
+export function resolveCompanionRemote({ key, remotes = {}, useSsh = false } = {}) {
+  const lc = String(key || "").toLowerCase();
+  const given = remotes?.[key] ?? remotes?.[lc] ?? null;
+  if (given) return withCloneScheme(given, { useSsh });
+  const [host, owner, name] = lc.split("/");
+  if (host === "github.com" && owner && name) return withCloneScheme(`https://github.com/${owner}/${name}.git`, { useSsh });
+  return null;
+}
+
+/** Do the machine's checkouts use SSH remotes? (`repoGroups[].checkouts[].remote`) */
+export function prefersSsh(repoGroups) {
+  for (const g of repoGroups || []) {
+    for (const c of g?.checkouts || [g?.primary]) {
+      if (c?.remote && /^(?:ssh:\/\/)?git@/i.test(String(c.remote))) return true;
+    }
+  }
+  return false;
+}
+
+/** The exact command shown on the `companion_clone_failed` card (copyable). */
+export function buildCloneCommand({ remote, target }) {
+  const q = (s) => (/[\s"']/.test(String(s)) ? JSON.stringify(String(s)) : String(s));
+  return `git clone ${q(remote)} ${q(target)}`;
+}
+
+/**
+ * Boot order for a resolved companion set: deepest dependencies first,
+ * stable within a depth (insertion order). `entries` = `[{ key, depth }]`.
+ */
+export function orderCompanions(entries) {
+  return [...entries].sort((a, b) => b.depth - a.depth || a.index - b.index).map((e) => e.key);
+}
+
+/**
+ * BFS over companion declarations. `roots` = `[{ key, config }]` (the
+ * session repos); `loadConfig(key)` resolves a companion's config
+ * (`{ config }`, `{ missing: true }` when not on the device and not
+ * clonable, `{ unconfigured: true }` when checked out but without a dev
+ * config, `{ error }`). Async because loading may clone. Returns
+ * `{ companions: [{ key, optional, depth, requiredBy, config?, missing?, unconfigured?, error? }] }`
+ * in BOOT order (deepest first). Session repos are never companions; a
+ * repo required by any config is required overall; depth is capped at
+ * `maxDepth`; a visited set keeps cycles harmless.
+ */
+export async function collectCompanions({ roots, loadConfig, maxDepth = 3 } = {}) {
+  const sessionKeys = new Set((roots || []).map((r) => String(r.key).toLowerCase()));
+  const seen = new Map(); // key → entry
+  let queue = (roots || []).map((r) => ({ key: String(r.key).toLowerCase(), config: r.config, depth: 0 }));
+  let index = 0;
+  for (let depth = 1; depth <= maxDepth && queue.length > 0; depth += 1) {
+    const next = [];
+    for (const node of queue) {
+      for (const c of node.config?.companions || []) {
+        const key = String(c.repo).toLowerCase();
+        if (sessionKeys.has(key)) continue; // already part of the session
+        const prev = seen.get(key);
+        if (prev) {
+          // Required by any → required overall; keep the shallowest depth.
+          prev.optional = prev.optional && !!c.optional;
+          if (!prev.requiredBy.includes(node.key)) prev.requiredBy.push(node.key);
+          continue;
+        }
+        const entry = { key, optional: !!c.optional, depth, requiredBy: [node.key], index: index++ };
+        seen.set(key, entry);
+        const loaded = await loadConfig(key, entry);
+        Object.assign(entry, loaded && typeof loaded === "object" ? loaded : {});
+        if (entry.config) next.push({ key, config: entry.config, depth });
+      }
+    }
+    queue = next;
+  }
+  const entries = [...seen.values()];
+  return { companions: orderCompanions(entries).map((key) => seen.get(key)) };
+}