@corvio/cli 0.1.0-beta.10

package/dist/core.js

@@ -0,0 +1,1081 @@
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { chmod, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { homedir, platform } from "node:os";
+import { dirname, join, resolve } from "node:path";
+
+export const EXIT = Object.freeze({
+  OK: 0,
+  USAGE: 2,
+  AUTH: 3,
+  UNAVAILABLE: 4,
+  CONFLICT: 5,
+  RATE_LIMIT: 6,
+  REMOTE: 7,
+});
+
+export class CliError extends Error {
+  constructor(message, { code = "cli_error", exitCode = EXIT.USAGE, status = null, details = null } = {}) {
+    super(message);
+    this.name = "CliError";
+    this.code = code;
+    this.exitCode = exitCode;
+    this.status = status;
+    this.details = details;
+  }
+}
+
+function exitCodeForStatus(status) {
+  if (status === 401 || status === 403) return EXIT.AUTH;
+  if (status === 409) return EXIT.CONFLICT;
+  if (status === 429) return EXIT.RATE_LIMIT;
+  return EXIT.REMOTE;
+}
+
+const DEFAULT_REQUEST_TIMEOUT_MS = 60_000;
+const MAX_REQUEST_TIMEOUT_MS = 10 * 60_000;
+const RETRYABLE_HTTP_STATUSES = new Set([408, 429, 502, 503, 504]);
+
+function normalizeRequestTimeout(value, fallback = DEFAULT_REQUEST_TIMEOUT_MS) {
+  const raw = value === undefined || value === null || value === "" ? fallback : Number(value);
+  if (!Number.isSafeInteger(raw) || raw < 1 || raw > MAX_REQUEST_TIMEOUT_MS) {
+    throw new CliError(
+      `Request timeout must be an integer between 1 and ${MAX_REQUEST_TIMEOUT_MS} milliseconds.`,
+      { code: "invalid_request_timeout" },
+    );
+  }
+  return raw;
+}
+
+function networkFailureDetails({
+  cause,
+  url,
+  method,
+  requestHeaders = {},
+  body = undefined,
+  retrySafe = false,
+}) {
+  const nested = cause && typeof cause === "object" ? cause.cause : null;
+  const causeCode = String(nested?.code || cause?.code || "").trim() || null;
+  const syscall = String(nested?.syscall || cause?.syscall || "").trim() || null;
+  const normalizedMethod = String(method || "GET").toUpperCase();
+  const operationKey = String(requestHeaders["idempotency-key"] || requestHeaders["Idempotency-Key"] || "").trim();
+  const revision = body?.expected_content_revision;
+  const revisionGuarded = normalizedMethod === "PUT" && Number.isSafeInteger(revision) && revision >= 0;
+  const safeToRetry = retrySafe || ["GET", "HEAD"].includes(normalizedMethod) || Boolean(operationKey) || revisionGuarded;
+  const timedOut = cause?.name === "TimeoutError" || cause?.name === "AbortError";
+  return {
+    method: normalizedMethod,
+    origin: new URL(String(url)).origin,
+    response_received: false,
+    timed_out: timedOut,
+    safe_to_retry: safeToRetry,
+    retry_safety: operationKey
+      ? "idempotency_key"
+      : revisionGuarded
+        ? "revision_guard"
+        : retrySafe
+          ? "operation_contract"
+          : safeToRetry
+            ? "read_only"
+            : "unknown_commit_state",
+    ...(operationKey ? { idempotency_key: operationKey } : {}),
+    ...(causeCode ? { cause_code: causeCode } : {}),
+    ...(syscall ? { syscall } : {}),
+  };
+}
+
+export function parseArgv(argv) {
+  const options = Object.create(null);
+  const positionals = [];
+  const booleanOptions = new Set([
+    "json",
+    "no-input",
+    "yes",
+    "allow-actions",
+    "private-link",
+    "force",
+    "once",
+    "include-revoked",
+    "recover-credential",
+    "no-listen",
+    "start-new-chain",
+    "help",
+    "version",
+  ]);
+  for (let index = 0; index < argv.length; index += 1) {
+    const value = argv[index];
+    if (value === "--") {
+      positionals.push(...argv.slice(index + 1));
+      break;
+    }
+    if (!value.startsWith("--")) {
+      positionals.push(value);
+      continue;
+    }
+    const separator = value.indexOf("=");
+    const name = value.slice(2, separator === -1 ? undefined : separator);
+    if (!name) throw new CliError("Option name must not be empty.", { code: "invalid_option" });
+    if (Object.hasOwn(options, name)) {
+      throw new CliError(`Option --${name} was provided more than once.`, { code: "duplicate_option" });
+    }
+    if (booleanOptions.has(name)) {
+      const booleanValue = separator === -1 ? "true" : value.slice(separator + 1);
+      if (booleanValue !== "true" && booleanValue !== "false") {
+        throw new CliError(`Option --${name} must be true or false.`, { code: "invalid_boolean_option" });
+      }
+      options[name] = booleanValue === "true";
+      continue;
+    }
+    if (separator !== -1) {
+      options[name] = value.slice(separator + 1);
+      continue;
+    }
+    const next = argv[index + 1];
+    if (next === undefined || next.startsWith("--")) {
+      throw new CliError(`Option --${name} requires a value.`, { code: "missing_option_value" });
+    }
+    options[name] = next;
+    index += 1;
+  }
+  return { options, positionals };
+}
+
+export function assertKnownOptions(options, allowed) {
+  const allowedSet = new Set(allowed);
+  for (const name of Object.keys(options)) {
+    if (!allowedSet.has(name)) {
+      throw new CliError(`Unknown option --${name}.`, { code: "unknown_option" });
+    }
+  }
+}
+
+export function assertPositionalCount(positionals, maximum) {
+  if (positionals.length > maximum) {
+    throw new CliError(`Unexpected argument: ${positionals[maximum]}`, { code: "unexpected_argument" });
+  }
+}
+
+export function option(options, name, { required = false, fallback = undefined } = {}) {
+  const value = options[name] ?? fallback;
+  if (required && (value === undefined || String(value).trim() === "")) {
+    throw new CliError(`Missing required option --${name}.`, { code: "missing_required_option" });
+  }
+  return value;
+}
+
+export function listOption(options, name, fallback = []) {
+  const value = options[name];
+  if (value === undefined) return fallback;
+  return String(value).split(",").map((item) => item.trim()).filter(Boolean);
+}
+
+export function numberOption(options, name, fallback, { minimum = 1, maximum = Number.MAX_SAFE_INTEGER } = {}) {
+  const value = options[name];
+  if (value === undefined) return fallback;
+  const normalized = String(value).trim();
+  const parsed = /^\d+$/.test(normalized) ? Number(normalized) : Number.NaN;
+  if (!Number.isSafeInteger(parsed) || parsed < minimum || parsed > maximum) {
+    throw new CliError(
+      `Option --${name} must be an integer between ${minimum} and ${maximum}.`,
+      { code: "invalid_number_option" },
+    );
+  }
+  return parsed;
+}
+
+export function normalizeApiBase(value, fallback) {
+  const raw = String(value || fallback).trim().replace(/\/+$/, "");
+  let parsed;
+  try {
+    parsed = new URL(raw);
+  } catch {
+    throw new CliError("Corvio API base must be a valid URL.", { code: "invalid_api_base" });
+  }
+  const localhost = parsed.hostname === "localhost" || parsed.hostname === "127.0.0.1" || parsed.hostname === "[::1]";
+  if (parsed.username || parsed.password || (parsed.protocol !== "https:" && !(parsed.protocol === "http:" && localhost))) {
+    throw new CliError("Corvio API base must use HTTPS (localhost is allowed for development).", {
+      code: "insecure_api_base",
+    });
+  }
+  if (parsed.search || parsed.hash) {
+    throw new CliError("Corvio API base must not include a query string or fragment.", { code: "invalid_api_base" });
+  }
+  const normalized = parsed.toString().replace(/\/+$/, "");
+  return normalized.endsWith("/v1") ? normalized : `${normalized}/v1`;
+}
+
+function parseSemver(value) {
+  const match = String(value || "").trim().match(/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/);
+  if (!match) return null;
+  return {
+    core: match.slice(1, 4).map((item) => Number.parseInt(item, 10)),
+    pre: match[4] ? match[4].split(".") : [],
+  };
+}
+
+export function compareVersions(left, right) {
+  const a = parseSemver(left);
+  const b = parseSemver(right);
+  if (!a || !b) return 0;
+  for (let index = 0; index < 3; index += 1) {
+    if (a.core[index] !== b.core[index]) return a.core[index] > b.core[index] ? 1 : -1;
+  }
+  if (a.pre.length === 0 && b.pre.length > 0) return 1;
+  if (b.pre.length === 0 && a.pre.length > 0) return -1;
+  for (let index = 0; index < Math.max(a.pre.length, b.pre.length); index += 1) {
+    if (a.pre[index] === undefined) return -1;
+    if (b.pre[index] === undefined) return 1;
+    if (a.pre[index] === b.pre[index]) continue;
+    const aNumber = /^\d+$/.test(a.pre[index]) ? Number.parseInt(a.pre[index], 10) : null;
+    const bNumber = /^\d+$/.test(b.pre[index]) ? Number.parseInt(b.pre[index], 10) : null;
+    if (aNumber !== null && bNumber !== null) return aNumber > bNumber ? 1 : -1;
+    if (aNumber !== null) return -1;
+    if (bNumber !== null) return 1;
+    return a.pre[index] > b.pre[index] ? 1 : -1;
+  }
+  return 0;
+}
+
+export async function resolveNpmUpdateStatus({
+  currentVersion,
+  policy,
+  userAgent,
+  allowRegistryFailure = false,
+  fetchImpl = globalThis.fetch,
+  registryBase = process.env.CORVIO_NPM_REGISTRY_BASE || "https://registry.npmjs.org",
+}) {
+  const packageName = String(policy?.package || "").trim();
+  const distTag = String(policy?.dist_tag || "beta").trim();
+  if (!packageName) throw new CliError("The API did not advertise an npm package.", { code: "update_policy_invalid" });
+  const encoded = encodeURIComponent(packageName).replace("%40", "@");
+  let latestVersion = null;
+  let registryError = null;
+  try {
+    const registry = String(registryBase).replace(/\/+$/, "");
+    const response = await fetchImpl(`${registry}/${encoded}`, {
+      headers: { accept: "application/json", "user-agent": userAgent },
+      signal: AbortSignal.timeout(2500),
+    });
+    if (!response.ok) throw new Error(`npm registry returned ${response.status}`);
+    const metadata = await response.json();
+    latestVersion = String(metadata?.["dist-tags"]?.[distTag] || "").trim() || null;
+  } catch (error) {
+    registryError = error instanceof Error ? error.message : String(error);
+    if (!allowRegistryFailure) {
+      throw new CliError(`Unable to check npm for updates: ${registryError}`, {
+        code: "update_check_failed",
+        exitCode: EXIT.REMOTE,
+      });
+    }
+  }
+  const minimum = String(policy.minimum_supported_version || "").trim() || null;
+  return {
+    package: packageName,
+    channel: String(policy.channel || distTag),
+    dist_tag: distTag,
+    current_version: currentVersion,
+    latest_published_version: latestVersion,
+    reviewed_version: String(policy.reviewed_version || "").trim() || null,
+    minimum_supported_version: minimum,
+    update_available: Boolean(latestVersion && compareVersions(latestVersion, currentVersion) > 0),
+    supported: minimum ? compareVersions(currentVersion, minimum) >= 0 : true,
+    install_command: String(policy.install_command || `npm install --global ${packageName}@${distTag}`),
+    automatic_install: false,
+    ...(registryError ? { registry_error: registryError } : {}),
+  };
+}
+
+export class ApiClient {
+  constructor({
+    baseUrl,
+    credential = null,
+    workspaceId = null,
+    userAgent,
+    fetchImpl = globalThis.fetch,
+    timeoutMs = process.env.CORVIO_REQUEST_TIMEOUT_MS,
+  }) {
+    this.baseUrl = baseUrl.replace(/\/+$/, "");
+    this.credential = credential;
+    this.workspaceId = String(workspaceId || "").trim() || null;
+    this.userAgent = userAgent;
+    this.fetchImpl = fetchImpl;
+    this.timeoutMs = normalizeRequestTimeout(timeoutMs);
+  }
+
+  async request(path, {
+    method = "GET",
+    body,
+    query,
+    headers = {},
+    auth = true,
+    retrySafe = false,
+    timeoutMs = this.timeoutMs,
+  } = {}) {
+    const url = new URL(`${this.baseUrl}${path.startsWith("/") ? path : `/${path}`}`);
+    for (const [key, value] of Object.entries(query || {})) {
+      if (value !== undefined && value !== null && value !== "") url.searchParams.set(key, String(value));
+    }
+    const requestHeaders = {
+      accept: "application/json",
+      "user-agent": this.userAgent,
+      ...headers,
+    };
+    if (body !== undefined) requestHeaders["content-type"] = "application/json";
+    if (auth) {
+      if (!this.credential) {
+        throw new CliError("Corvio authentication is required.", { code: "auth_required", exitCode: EXIT.AUTH });
+      }
+      requestHeaders.authorization = `Bearer ${this.credential}`;
+      if (this.workspaceId) {
+        requestHeaders["X-Corvio-Workspace-Id"] = this.workspaceId;
+        requestHeaders["X-Corvio-Workspace-Context-Contract"] = "required-v1";
+      }
+    }
+    const normalizedTimeout = normalizeRequestTimeout(timeoutMs, this.timeoutMs);
+    let response;
+    for (let attempt = 1; attempt <= 2; attempt += 1) {
+      try {
+        response = await this.fetchImpl(url, {
+          method,
+          headers: requestHeaders,
+          body: body === undefined ? undefined : JSON.stringify(body),
+          signal: AbortSignal.timeout(normalizedTimeout),
+        });
+        const safety = networkFailureDetails({
+          cause: null,
+          url,
+          method,
+          requestHeaders,
+          body,
+          retrySafe,
+        });
+        if (attempt === 1 && safety.safe_to_retry && RETRYABLE_HTTP_STATUSES.has(response.status)) {
+          await response.body?.cancel().catch(() => {});
+          const retryAfterValue = response.headers.get("retry-after");
+          const retryAfterSeconds = retryAfterValue === null ? Number.NaN : Number(retryAfterValue);
+          const delayMs = Number.isFinite(retryAfterSeconds)
+            ? Math.min(2_000, Math.max(0, retryAfterSeconds * 1000))
+            : 150;
+          await sleep(delayMs);
+          continue;
+        }
+        break;
+      } catch (cause) {
+        const details = networkFailureDetails({ cause, url, method, requestHeaders, body, retrySafe });
+        if (attempt === 1 && details.safe_to_retry) {
+          await sleep(150);
+          continue;
+        }
+        throw new CliError(
+          details.timed_out
+            ? `Corvio did not respond within ${normalizedTimeout} ms.`
+            : `Unable to reach Corvio: ${cause instanceof Error ? cause.message : String(cause)}`,
+          {
+          code: details.timed_out ? "request_timeout" : "network_error",
+          exitCode: EXIT.REMOTE,
+          details: {
+            ...details,
+            attempts: attempt,
+            automatic_retry_attempted: attempt > 1,
+          },
+          },
+        );
+      }
+    }
+    const text = await response.text();
+    let payload = null;
+    if (text) {
+      try {
+        payload = JSON.parse(text);
+      } catch {
+        payload = { message: text.slice(0, 500) };
+      }
+    }
+    if (!response.ok) {
+      const envelope = payload?.error || payload?.detail || payload || {};
+      throw new CliError(String(envelope.message || envelope.code || `Corvio request failed (${response.status}).`), {
+        code: String(envelope.code || `http_${response.status}`),
+        status: response.status,
+        exitCode: exitCodeForStatus(response.status),
+        details: {
+          ...(envelope.details || {}),
+          ...(envelope.request_id || response.headers.get("x-request-id")
+            ? { request_id: envelope.request_id || response.headers.get("x-request-id") }
+            : {}),
+        },
+      });
+    }
+    return payload;
+  }
+
+  async requestBytes(path, { query, headers = {}, auth = true, timeoutMs = this.timeoutMs } = {}) {
+    const url = new URL(`${this.baseUrl}${path.startsWith("/") ? path : `/${path}`}`);
+    for (const [key, value] of Object.entries(query || {})) {
+      if (value !== undefined && value !== null && value !== "") url.searchParams.set(key, String(value));
+    }
+    const requestHeaders = {
+      accept: "application/zip, application/octet-stream",
+      "user-agent": this.userAgent,
+      ...headers,
+    };
+    if (auth) {
+      if (!this.credential) {
+        throw new CliError("Corvio authentication is required.", { code: "auth_required", exitCode: EXIT.AUTH });
+      }
+      requestHeaders.authorization = `Bearer ${this.credential}`;
+      if (this.workspaceId) {
+        requestHeaders["X-Corvio-Workspace-Id"] = this.workspaceId;
+        requestHeaders["X-Corvio-Workspace-Context-Contract"] = "required-v1";
+      }
+    }
+    const normalizedTimeout = normalizeRequestTimeout(timeoutMs, this.timeoutMs);
+    let response;
+    for (let attempt = 1; attempt <= 2; attempt += 1) {
+      try {
+        response = await this.fetchImpl(url, {
+          method: "GET",
+          headers: requestHeaders,
+          signal: AbortSignal.timeout(normalizedTimeout),
+        });
+        if (attempt === 1 && RETRYABLE_HTTP_STATUSES.has(response.status)) {
+          await response.body?.cancel().catch(() => {});
+          await sleep(150);
+          continue;
+        }
+        break;
+      } catch (cause) {
+        const details = networkFailureDetails({ cause, url, method: "GET", requestHeaders });
+        if (attempt === 1) {
+          await sleep(150);
+          continue;
+        }
+        throw new CliError(
+          details.timed_out
+            ? `Corvio did not respond within ${normalizedTimeout} ms.`
+            : `Unable to reach Corvio: ${cause instanceof Error ? cause.message : String(cause)}`,
+          {
+            code: details.timed_out ? "request_timeout" : "network_error",
+            exitCode: EXIT.REMOTE,
+            details: { ...details, attempts: attempt, automatic_retry_attempted: true },
+          },
+        );
+      }
+    }
+    const bytes = new Uint8Array(await response.arrayBuffer());
+    if (!response.ok) {
+      const text = new TextDecoder().decode(bytes);
+      let payload = {};
+      try {
+        payload = JSON.parse(text);
+      } catch {
+        payload = { message: text.slice(0, 500) };
+      }
+      const envelope = payload?.error || payload?.detail || payload || {};
+      throw new CliError(String(envelope.message || envelope.code || `Corvio request failed (${response.status}).`), {
+        code: String(envelope.code || `http_${response.status}`),
+        status: response.status,
+        exitCode: exitCodeForStatus(response.status),
+        details: {
+          ...(envelope.details || {}),
+          ...(envelope.request_id || response.headers.get("x-request-id")
+            ? { request_id: envelope.request_id || response.headers.get("x-request-id") }
+            : {}),
+        },
+      });
+    }
+    return bytes;
+  }
+
+  async putUrl(url, content, { headers = {}, timeoutMs = this.timeoutMs } = {}) {
+    const normalizedTimeout = normalizeRequestTimeout(timeoutMs, this.timeoutMs);
+    let response;
+    for (let attempt = 1; attempt <= 2; attempt += 1) {
+      try {
+        response = await this.fetchImpl(String(url), {
+          method: "PUT",
+          headers,
+          body: content,
+          signal: AbortSignal.timeout(normalizedTimeout),
+        });
+        if (attempt === 1 && RETRYABLE_HTTP_STATUSES.has(response.status)) {
+          await response.body?.cancel().catch(() => {});
+          await sleep(150);
+          continue;
+        }
+        break;
+      } catch (cause) {
+        const details = networkFailureDetails({
+          cause,
+          url,
+          method: "PUT",
+          requestHeaders: headers,
+          retrySafe: true,
+        });
+        if (attempt === 1) {
+          await sleep(150);
+          continue;
+        }
+        throw new CliError(
+          details.timed_out
+            ? `The file upload did not respond within ${normalizedTimeout} ms.`
+            : `Unable to upload the file: ${cause instanceof Error ? cause.message : String(cause)}`,
+          {
+            code: details.timed_out ? "upload_timeout" : "upload_network_error",
+            exitCode: EXIT.REMOTE,
+            details: { ...details, attempts: attempt, automatic_retry_attempted: true },
+          },
+        );
+      }
+    }
+    if (!response.ok) {
+      const message = (await response.text()).slice(0, 500);
+      throw new CliError(message || `File upload failed (${response.status}).`, {
+        code: "upload_failed",
+        status: response.status,
+        exitCode: EXIT.REMOTE,
+      });
+    }
+    return { ok: true, status: response.status };
+  }
+}
+
+function configRoot(env = process.env) {
+  if (env.CORVIO_CONFIG_DIR) return resolve(env.CORVIO_CONFIG_DIR);
+  if (env.XDG_CONFIG_HOME) return join(resolve(env.XDG_CONFIG_HOME), "corvio");
+  return join(homedir(), ".config", "corvio");
+}
+
+export function workspaceCredentialPath(env = process.env) {
+  return join(configRoot(env), "credentials.json");
+}
+
+export function workspaceContextPath(env = process.env) {
+  return join(configRoot(env), "workspace-context.json");
+}
+
+export function adminCredentialPath(env = process.env) {
+  return join(configRoot(env), "admin-credentials.json");
+}
+
+export function agentCredentialPath(env = process.env) {
+  return join(configRoot(env), "agent-credentials.json");
+}
+
+export function conversationRoutingPath(env = process.env) {
+  return join(configRoot(env), "conversation-routing.json");
+}
+
+export async function readWorkspaceCredential(env = process.env) {
+  const environmentKey = String(env.CORVIO_API_KEY || "").trim();
+  if (environmentKey) {
+    if (!environmentKey.startsWith("cvu_") && !environmentKey.startsWith("cvk_")) {
+      throw new CliError("CORVIO_API_KEY must be a user cvu_ key or legacy Workspace cvk_ key.", {
+        code: "invalid_workspace_key",
+        exitCode: EXIT.AUTH,
+      });
+    }
+    return { key: environmentKey, source: "environment", profile: null, metadata: null };
+  }
+  const path = workspaceCredentialPath(env);
+  let parsed;
+  try {
+    parsed = JSON.parse(await readFile(path, "utf8"));
+  } catch (cause) {
+    if (cause?.code === "ENOENT") return null;
+    throw new CliError("Stored Corvio credentials are unreadable.", { code: "credential_store_invalid", exitCode: EXIT.AUTH });
+  }
+  const profileName = String(parsed.active_profile || "default");
+  const profile = parsed.profiles?.[profileName];
+  const metadata = String(parsed.api_key || "").trim() ? parsed : profile;
+  const key = String(metadata?.api_key || "").trim();
+  if (!key.startsWith("cvu_") && !key.startsWith("cvk_")) {
+    throw new CliError("Stored Corvio credentials are invalid; run `corvio auth login` again.", {
+      code: "credential_store_invalid",
+      exitCode: EXIT.AUTH,
+    });
+  }
+  return { key, source: "device_link", profile: profileName, metadata };
+}
+
+export async function readAgentCredential(
+  env = process.env,
+  {
+    required = true,
+    bindingId = null,
+    agentId = null,
+    projectRoot = null,
+    fallbackToActive = true,
+  } = {},
+) {
+  const key = String(env.CORVIO_AGENT_API_KEY || "").trim();
+  if (key) {
+    if (!key.startsWith("cvg_")) {
+      throw new CliError("CORVIO_AGENT_API_KEY must be an Agent cvg_ key.", {
+        code: "invalid_agent_key",
+        exitCode: EXIT.AUTH,
+      });
+    }
+    return { key, source: "environment", profile: null, metadata: null };
+  }
+  const path = agentCredentialPath(env);
+  let parsed;
+  try {
+    parsed = JSON.parse(await readFile(path, "utf8"));
+  } catch (cause) {
+    if (cause?.code === "ENOENT" && !required) return null;
+    if (cause?.code === "ENOENT") {
+      throw new CliError(
+        "No Agent credential found. Run `corvio agents connect` or set CORVIO_AGENT_API_KEY.",
+        { code: "agent_auth_required", exitCode: EXIT.AUTH },
+      );
+    }
+    throw new CliError("Stored Agent credentials are unreadable.", {
+      code: "agent_credential_store_invalid",
+      exitCode: EXIT.AUTH,
+    });
+  }
+  let selected = parsed;
+  let selectedProfile = "default";
+  if (Number(parsed?.version) >= 2 && parsed?.credentials && typeof parsed.credentials === "object") {
+    const entries = Object.entries(parsed.credentials);
+    let match = null;
+    if (bindingId) {
+      match = entries.find(([key, value]) => key === bindingId || value?.binding_id === bindingId) || null;
+    }
+    if (!match && agentId) {
+      match = entries.find(([, value]) => String(value?.agent_id || "") === String(agentId)) || null;
+    }
+    if (!match && projectRoot) {
+      const normalizedRoot = resolve(String(projectRoot));
+      const candidates = entries
+        .filter(([, value]) => {
+          const storedRoot = String(value?.project_root || "").trim();
+          if (!storedRoot) return false;
+          const normalizedStored = resolve(storedRoot);
+          return normalizedRoot === normalizedStored || normalizedRoot.startsWith(`${normalizedStored}${process.platform === "win32" ? "\\" : "/"}`);
+        })
+        .sort((left, right) => String(right[1]?.project_root || "").length - String(left[1]?.project_root || "").length);
+      match = candidates[0] || null;
+    }
+    if (!match && fallbackToActive && parsed.active_binding_id) {
+      const value = parsed.credentials[parsed.active_binding_id];
+      if (value) match = [parsed.active_binding_id, value];
+    }
+    if (!match && fallbackToActive && entries.length === 1) match = entries[0];
+    if (!match) {
+      if (!required) return null;
+      throw new CliError(
+        "Multiple Agent project bindings are stored. Run from a connected project or pass --agent <id>.",
+        { code: "agent_routing_ambiguous", exitCode: EXIT.AUTH },
+      );
+    }
+    [selectedProfile, selected] = match;
+  }
+  const storedKey = String(selected?.api_key || "").trim();
+  if (!storedKey.startsWith("cvg_")) {
+    throw new CliError(
+      "Stored Agent credentials are invalid; run `corvio agents connect --recover-credential`.",
+      { code: "agent_credential_store_invalid", exitCode: EXIT.AUTH },
+    );
+  }
+  return { key: storedKey, source: "secure_store", profile: selectedProfile, metadata: selected };
+}
+
+export async function storeAgentCredential(payload, env = process.env) {
+  const secret = String(payload?.secret || "").trim();
+  if (!secret.startsWith("cvg_")) {
+    throw new CliError("Agent connection did not return a valid cvg_ credential.", {
+      code: "agent_credential_invalid",
+      exitCode: EXIT.AUTH,
+    });
+  }
+  const path = agentCredentialPath(env);
+  const root = dirname(path);
+  await mkdir(root, { recursive: true, mode: 0o700 });
+  await chmod(root, 0o700).catch(() => {});
+  const credential = {
+    api_key: secret,
+    agent_id: String(payload.agent_id || ""),
+    binding_id: String(payload.binding_id || "").trim() || null,
+    project_root: String(payload.project_root || "").trim() || null,
+    project_label: String(payload.project_label || "").trim() || null,
+    project_fingerprint: String(payload.project_fingerprint || "").trim() || null,
+    display_name: String(payload.display_name || ""),
+    provider: String(payload.provider || "custom"),
+    permission_profile: String(payload.permission_profile || "read_only"),
+    trigger_policy: String(payload.trigger_policy || "owner_only"),
+    skills_scope: String(payload.skills_scope || "project"),
+    memory_scope: String(payload.memory_scope || "off"),
+    connector_scope: String(payload.connector_scope || "off"),
+    display_prefix: String(payload.display_prefix || "cvg"),
+    created_at: payload.created_at || new Date().toISOString(),
+    source: "agent_connect",
+  };
+  let current = null;
+  try {
+    current = JSON.parse(await readFile(path, "utf8"));
+  } catch (error) {
+    if (error?.code !== "ENOENT") {
+      throw new CliError("Stored Agent credentials are unreadable.", {
+        code: "agent_credential_store_invalid",
+        exitCode: EXIT.AUTH,
+      });
+    }
+  }
+  const credentials = Number(current?.version) >= 2 && current?.credentials && typeof current.credentials === "object"
+    ? { ...current.credentials }
+    : {};
+  if (String(current?.api_key || "").startsWith("cvg_") && current?.agent_id) {
+    const legacyKey = String(current.binding_id || `legacy:${current.agent_id}`);
+    credentials[legacyKey] = { ...current, binding_id: current.binding_id || null };
+  }
+  const profile = credential.binding_id || `agent:${credential.agent_id}`;
+  credentials[profile] = credential;
+  const document = {
+    version: 2,
+    active_binding_id: profile,
+    credentials,
+  };
+  const temporary = `${path}.${randomUUID()}.tmp`;
+  await writeFile(temporary, `${JSON.stringify(document, null, 2)}\n`, { mode: 0o600, flag: "wx" });
+  await chmod(temporary, 0o600);
+  await rename(temporary, path);
+  await chmod(path, 0o600);
+  return { path, profile, metadata: credential };
+}
+
+export async function storeWorkspaceCredential(payload, env = process.env) {
+  const path = workspaceCredentialPath(env);
+  const root = dirname(path);
+  await mkdir(root, { recursive: true, mode: 0o700 });
+  await chmod(root, 0o700).catch(() => {});
+  const document = {
+    version: 2,
+    api_key: payload.secret,
+    key_id: payload.key_id,
+    audience: payload.audience || "user",
+    scopes: payload.scopes || [],
+    expires_at: payload.expires_at || null,
+    created_at: payload.created_at || new Date().toISOString(),
+    source: "device_link",
+  };
+  const temporary = `${path}.${randomUUID()}.tmp`;
+  await writeFile(temporary, `${JSON.stringify(document, null, 2)}\n`, { mode: 0o600, flag: "wx" });
+  await chmod(temporary, 0o600);
+  await rename(temporary, path);
+  await chmod(path, 0o600);
+  return { path, profile: "default" };
+}
+
+export async function readWorkspaceContext(env = process.env) {
+  const environmentWorkspaceId = String(env.CORVIO_WORKSPACE_ID || "").trim();
+  if (environmentWorkspaceId) {
+    return { workspaceId: environmentWorkspaceId, workspaceName: null, source: "environment" };
+  }
+  const path = workspaceContextPath(env);
+  try {
+    const parsed = JSON.parse(await readFile(path, "utf8"));
+    const workspaceId = String(parsed.active_workspace_id || "").trim();
+    if (!workspaceId) return null;
+    return {
+      workspaceId,
+      workspaceName: String(parsed.active_workspace_name || "").trim() || null,
+      source: "stored",
+      routingPreference: parsed.routing_preference || null,
+    };
+  } catch (cause) {
+    if (cause?.code === "ENOENT") return null;
+    throw new CliError("Stored Corvio Workspace selection is unreadable.", {
+      code: "workspace_context_store_invalid",
+      exitCode: EXIT.AUTH,
+    });
+  }
+}
+
+export async function storeWorkspaceContext({ workspaceId, workspaceName = null, routingPreference = null }, env = process.env) {
+  const normalizedId = String(workspaceId || "").trim();
+  if (!normalizedId) throw new CliError("Workspace ID is required.", { code: "workspace_selection_required" });
+  const path = workspaceContextPath(env);
+  const root = dirname(path);
+  await mkdir(root, { recursive: true, mode: 0o700 });
+  await chmod(root, 0o700).catch(() => {});
+  const document = {
+    version: 1,
+    active_workspace_id: normalizedId,
+    active_workspace_name: String(workspaceName || "").trim() || null,
+    routing_preference: routingPreference || {
+      workspace_id: normalizedId,
+      provenance: "user_confirmed_cli",
+      confidence: 1,
+      scope: "global",
+      expires_at: null,
+    },
+    updated_at: new Date().toISOString(),
+  };
+  const temporary = `${path}.${randomUUID()}.tmp`;
+  await writeFile(temporary, `${JSON.stringify(document, null, 2)}\n`, { mode: 0o600, flag: "wx" });
+  await chmod(temporary, 0o600);
+  await rename(temporary, path);
+  await chmod(path, 0o600);
+  return { path, workspaceId: normalizedId };
+}
+
+export async function readConversationRoutingReceipt(conversationId, env = process.env) {
+  const normalizedId = String(conversationId || "").trim();
+  if (!normalizedId) return null;
+  const path = conversationRoutingPath(env);
+  try {
+    const parsed = JSON.parse(await readFile(path, "utf8"));
+    const receipt = parsed?.receipts?.[normalizedId];
+    const workspaceId = String(receipt?.workspace_id || "").trim();
+    if (!workspaceId) return null;
+    return {
+      conversationId: normalizedId,
+      workspaceId,
+      agentId: String(receipt.agent_id || "").trim() || null,
+      apiBase: String(receipt.api_base || "").trim() || null,
+      recordedAt: String(receipt.recorded_at || "").trim() || null,
+    };
+  } catch (cause) {
+    if (cause?.code === "ENOENT") return null;
+    throw new CliError("Stored Corvio conversation routing receipts are unreadable.", {
+      code: "conversation_routing_store_invalid",
+      exitCode: EXIT.AUTH,
+    });
+  }
+}
+
+export async function storeConversationRoutingReceipt({ conversationId, workspaceId, agentId = null, apiBase = null }, env = process.env) {
+  const normalizedConversationId = String(conversationId || "").trim();
+  const normalizedWorkspaceId = String(workspaceId || "").trim();
+  if (!normalizedConversationId || !normalizedWorkspaceId) {
+    throw new CliError("Conversation and Workspace IDs are required for routing continuity.", {
+      code: "conversation_routing_receipt_invalid",
+    });
+  }
+  const path = conversationRoutingPath(env);
+  const root = dirname(path);
+  await mkdir(root, { recursive: true, mode: 0o700 });
+  await chmod(root, 0o700).catch(() => {});
+  let existing = {};
+  try {
+    const parsed = JSON.parse(await readFile(path, "utf8"));
+    if (parsed?.receipts && typeof parsed.receipts === "object" && !Array.isArray(parsed.receipts)) {
+      existing = parsed.receipts;
+    }
+  } catch (cause) {
+    if (cause?.code !== "ENOENT") {
+      throw new CliError("Stored Corvio conversation routing receipts are unreadable.", {
+        code: "conversation_routing_store_invalid",
+        exitCode: EXIT.AUTH,
+      });
+    }
+  }
+  const ordered = Object.entries({
+    ...existing,
+    [normalizedConversationId]: {
+      workspace_id: normalizedWorkspaceId,
+      agent_id: String(agentId || "").trim() || null,
+      api_base: String(apiBase || "").trim() || null,
+      recorded_at: new Date().toISOString(),
+    },
+  }).sort((left, right) => String(right[1]?.recorded_at || "").localeCompare(String(left[1]?.recorded_at || "")));
+  const document = { version: 1, receipts: Object.fromEntries(ordered.slice(0, 500)) };
+  const temporary = `${path}.${randomUUID()}.tmp`;
+  await writeFile(temporary, `${JSON.stringify(document, null, 2)}\n`, { mode: 0o600, flag: "wx" });
+  await chmod(temporary, 0o600);
+  await rename(temporary, path);
+  await chmod(path, 0o600);
+  return { path, conversationId: normalizedConversationId, workspaceId: normalizedWorkspaceId };
+}
+
+export async function clearWorkspaceContext(env = process.env) {
+  const path = workspaceContextPath(env);
+  await rm(path, { force: true });
+  return path;
+}
+
+export async function clearWorkspaceCredential(env = process.env) {
+  const path = workspaceCredentialPath(env);
+  await rm(path, { force: true });
+  return path;
+}
+
+export async function readAdminCredential(env = process.env) {
+  const key = String(env.CORVIO_ADMIN_API_KEY || "").trim();
+  if (key) {
+    if (!key.startsWith("cva_")) {
+      throw new CliError("CORVIO_ADMIN_API_KEY must be a platform administrator cva_ key.", {
+        code: "invalid_admin_key",
+        exitCode: EXIT.AUTH,
+      });
+    }
+    return { key, source: "environment", metadata: null };
+  }
+  const path = adminCredentialPath(env);
+  let parsed;
+  try {
+    parsed = JSON.parse(await readFile(path, "utf8"));
+  } catch (cause) {
+    if (cause?.code === "ENOENT") return null;
+    throw new CliError("Stored Corvio administrator credentials are unreadable.", {
+      code: "admin_credential_store_invalid",
+      exitCode: EXIT.AUTH,
+    });
+  }
+  const storedKey = String(parsed.api_key || "").trim();
+  if (!storedKey.startsWith("cva_")) {
+    throw new CliError("Stored Corvio administrator credentials are invalid; run `corvio-admin auth login` again.", {
+      code: "admin_credential_store_invalid",
+      exitCode: EXIT.AUTH,
+    });
+  }
+  return { key: storedKey, source: "device_link", metadata: parsed };
+}
+
+export async function storeAdminCredential(payload, env = process.env) {
+  const path = adminCredentialPath(env);
+  const root = dirname(path);
+  await mkdir(root, { recursive: true, mode: 0o700 });
+  await chmod(root, 0o700).catch(() => {});
+  const document = {
+    version: 1,
+    api_key: payload.secret,
+    key_id: payload.key_id,
+    audience: payload.audience,
+    api_base: payload.api_base,
+    scopes: payload.scopes || [],
+    expires_at: payload.expires_at,
+    created_at: payload.created_at || new Date().toISOString(),
+    source: "device_link",
+  };
+  const temporary = `${path}.${randomUUID()}.tmp`;
+  await writeFile(temporary, `${JSON.stringify(document, null, 2)}\n`, { mode: 0o600, flag: "wx" });
+  await chmod(temporary, 0o600);
+  await rename(temporary, path);
+  await chmod(path, 0o600);
+  return { path };
+}
+
+export async function clearAdminCredential(env = process.env) {
+  const path = adminCredentialPath(env);
+  await rm(path, { force: true });
+  return path;
+}
+
+export function writeResult(value, { json = false, stdout = process.stdout } = {}) {
+  if (json || typeof value !== "string") {
+    stdout.write(`${JSON.stringify(value, null, json ? 2 : 0)}\n`);
+  } else {
+    stdout.write(`${value}\n`);
+  }
+}
+
+export function writeError(error, { json = false, stderr = process.stderr } = {}) {
+  const safe = {
+    error: {
+      code: error instanceof CliError ? error.code : "unexpected_error",
+      message: error instanceof Error ? error.message : String(error),
+      ...(error instanceof CliError && error.status ? { status: error.status } : {}),
+      ...(error instanceof CliError && error.details ? { details: error.details } : {}),
+    },
+  };
+  if (json) {
+    stderr.write(`${JSON.stringify(safe)}\n`);
+    return;
+  }
+  stderr.write(`Error: ${safe.error.message}\n`);
+  if (safe.error.details?.request_id) stderr.write(`Request ID: ${safe.error.details.request_id}\n`);
+  if (safe.error.details?.safe_to_retry && safe.error.details?.idempotency_key) {
+    stderr.write(
+      `Safe retry: rerun the command with --idempotency-key ${safe.error.details.idempotency_key}\n`,
+    );
+  } else if (safe.error.details?.retry_safety === "revision_guard") {
+    stderr.write("Safe retry: rerun with the same --expected-revision; Corvio will reject an already-committed replacement.\n");
+  } else if (safe.error.details?.retry_safety === "unknown_commit_state") {
+    stderr.write("Retry state is unknown; read the remote object before repeating this mutation.\n");
+  }
+}
+
+export async function runMain(main, argv = process.argv.slice(2)) {
+  let json = argv.includes("--json");
+  try {
+    const parsed = parseArgv(argv);
+    json = Boolean(parsed.options.json);
+    await main(parsed);
+  } catch (error) {
+    writeError(error, { json });
+    process.exitCode = error instanceof CliError ? error.exitCode : 1;
+  }
+}
+
+export async function openBrowser(url) {
+  const target = String(url);
+  const command = platform() === "darwin" ? "open" : platform() === "win32" ? "rundll32.exe" : "xdg-open";
+  const args = platform() === "win32" ? ["url.dll,FileProtocolHandler", target] : [target];
+  return new Promise((resolvePromise) => {
+    let settled = false;
+    const finish = (opened) => {
+      if (settled) return;
+      settled = true;
+      resolvePromise(opened);
+    };
+    try {
+      const child = spawn(command, args, { detached: true, stdio: "ignore" });
+      child.once("error", () => finish(false));
+      child.once("spawn", () => {
+        child.unref();
+        finish(true);
+      });
+    } catch {
+      finish(false);
+    }
+  });
+}
+
+export async function sleep(milliseconds) {
+  await new Promise((resolvePromise) => setTimeout(resolvePromise, milliseconds));
+}
+
+export async function readTextFile(path) {
+  return readFile(resolve(String(path)), "utf8");
+}
+
+export async function writeTextFile(path, content) {
+  const target = resolve(String(path));
+  await mkdir(dirname(target), { recursive: true });
+  const temporary = `${target}.${randomUUID()}.tmp`;
+  try {
+    await writeFile(temporary, content, { encoding: "utf8", flag: "wx" });
+    await rename(temporary, target);
+  } catch (error) {
+    await rm(temporary, { force: true }).catch(() => {});
+    throw error;
+  }
+  return target;
+}
+
+export async function writeBinaryFile(path, content) {
+  const target = resolve(String(path));
+  await mkdir(dirname(target), { recursive: true });
+  const temporary = `${target}.${randomUUID()}.tmp`;
+  try {
+    await writeFile(temporary, content, { flag: "wx" });
+    await rename(temporary, target);
+  } catch (error) {
+    await rm(temporary, { force: true }).catch(() => {});
+    throw error;
+  }
+  return target;
+}
+
+export function requireConfirmation(options, action) {
+  if (!options.yes) {
+    throw new CliError(`${action} requires --yes.`, { code: "confirmation_required" });
+  }
+}
+
+export function idempotencyKey(options) {
+  return String(options["idempotency-key"] || randomUUID());
+}