impel-cli 0.7.0

package/src/commands/doctor.js

@@ -0,0 +1,215 @@
+import { parseFlags } from "../args.js";
+import { loadConfig, normalizeGatewayUrl, resolveDefaultGateway } from "../config.js";
+import {
+  DEFAULT_TTFT_BUDGET_MS,
+  DOCTOR_PROVIDERS,
+  probeTenant,
+  recordSucceeded,
+} from "../doctor.js";
+import {
+  assertProviderScopes,
+  fetchTenants,
+  normalizeTenantId,
+  productAccessLabel,
+} from "../tenants.js";
+
+const HELP = `impel doctor - run synthetic, billable end-to-end gateway checks
+
+Usage:
+  impel doctor [--tenant <org> | --all-tenants] [options]
+
+Options:
+  --gateway <url>           Invocation-only gateway (flag > IMPEL_GATEWAY_URL > saved config).
+  --providers claude,codex   Providers to check. Default: both.
+  --attempts <n>             Requests per provider (1-5). Default: 1.
+  --timeout-ms <n>           Per-request timeout. Default: 120000.
+  --claude-ttft-ms <n>       Claude TTFT warning budget. Default: 6000.
+  --codex-ttft-ms <n>        Codex TTFT warning budget. Default: 5000.
+  --strict-latency           Fail when any successful request misses its budget.
+  --json                     Print one sanitized JSON report.
+
+The probe sends a synthetic marker only. It never prints your PAT or real prompt content.
+`;
+
+const DOCTOR_FLAGS = new Set([
+  "tenant",
+  "all-tenants",
+  "gateway",
+  "providers",
+  "attempts",
+  "timeout-ms",
+  "claude-ttft-ms",
+  "codex-ttft-ms",
+  "strict-latency",
+  "json",
+]);
+const MAX_TOTAL_PROBES = 50;
+
+function integerFlag(value, label, { min, max }) {
+  if (value === undefined) return null;
+  if (!/^\d+$/u.test(String(value))) throw new Error(`${label} must be an integer`);
+  const number = Number(value);
+  if (!Number.isSafeInteger(number) || number < min || number > max) {
+    throw new Error(`${label} must be between ${min} and ${max}`);
+  }
+  return number;
+}
+
+function parseProviders(value) {
+  if (value === undefined) return [...DOCTOR_PROVIDERS];
+  const providers = [...new Set(String(value).split(",").map((item) => item.trim()).filter(Boolean))];
+  if (!providers.length || providers.some((provider) => !DOCTOR_PROVIDERS.includes(provider))) {
+    throw new Error("--providers must be claude, codex, or claude,codex");
+  }
+  return providers;
+}
+
+function doctorGatewayUrl(value) {
+  const normalized = normalizeGatewayUrl(value);
+  let parsed;
+  try {
+    parsed = new URL(normalized);
+  } catch {
+    throw new Error("--gateway must be an absolute HTTP or HTTPS origin");
+  }
+  if (!["http:", "https:"].includes(parsed.protocol)
+      || !parsed.hostname
+      || parsed.username
+      || parsed.password
+      || parsed.pathname !== "/"
+      || parsed.search
+      || parsed.hash) {
+    throw new Error("--gateway must be an absolute HTTP or HTTPS origin without credentials, path, query, or fragment");
+  }
+  return parsed.origin;
+}
+
+function printHuman(report) {
+  for (const tenant of report.tenants) {
+    console.log(`Tenant:  ${tenant.tenantId}`);
+    console.log(`Access:  ${productAccessLabel(tenant.productAccess)}`);
+    console.log(`Catalog: ${tenant.catalog.status ?? "network error"} (${tenant.catalog.models} ready models, ${tenant.catalog.durationMs ?? "?"}ms)`);
+    if (tenant.catalog.error) console.log(`  ERROR ${tenant.catalog.error}`);
+    for (const record of tenant.records) {
+      const ok = recordSucceeded(record);
+      const latency = record.ttftMs === null ? "TTFT n/a" : `TTFT ${record.ttftMs}ms, total ${record.totalMs}ms`;
+      console.log(
+        `  ${record.provider} #${record.attempt}: ${ok ? "PASS" : "FAIL"} `
+        + `(HTTP ${record.status ?? "n/a"}, ${latency}, account ${record.accountId ? "selected" : "missing"})`,
+      );
+      if (record.error) console.log(`    ${record.error}`);
+      else if (!record.exactAck) console.log("    response did not exactly acknowledge the synthetic request marker");
+      else if (!record.responseId) console.log("    provider stream did not include a response id");
+      else if (!record.terminalEvent) console.log("    provider stream did not finish successfully");
+      else if (!record.requestId) console.log("    response did not include a gateway-owned request id");
+      else if (record.echoedClientRequestId !== record.clientRequestId) console.log("    response did not preserve the client correlation id");
+      else if (record.orgId !== tenant.tenantId) console.log("    response tenant attribution did not match the selected tenant");
+      else if (!record.contentType.toLowerCase().includes("text/event-stream")) console.log("    response was not a streaming event stream");
+    }
+    for (const [provider, summary] of Object.entries(tenant.providers)) {
+      if (summary.skipped) {
+        console.log(`  ${provider}: SKIP (no subscription seat is available for this tenant)`);
+        continue;
+      }
+      console.log(
+        `  ${provider} latency: p50 ${summary.ttftP50Ms ?? "n/a"}ms / p95 ${summary.ttftP95Ms ?? "n/a"}ms `
+        + `(budget ${summary.ttftBudgetMs}ms; ${summary.withinLatencyBudget}/${summary.attempted} within)`,
+      );
+    }
+    console.log(`Result:  ${tenant.passed ? "PASS" : "FAIL"}${tenant.latencyPassed === false ? " (latency warning)" : ""}`);
+    console.log("");
+  }
+  console.log(`Overall: ${report.passed ? "PASS" : "FAIL"}`);
+}
+
+export async function cmdDoctor(argv) {
+  if (argv.some((arg) => ["help", "--help", "-h"].includes(arg))) {
+    console.log(HELP);
+    return;
+  }
+  const { flags, positionals } = parseFlags(argv, {
+    tenant: { type: "string" },
+    "all-tenants": { type: "boolean" },
+    gateway: { type: "string" },
+    providers: { type: "string" },
+    attempts: { type: "string" },
+    "timeout-ms": { type: "string" },
+    "claude-ttft-ms": { type: "string" },
+    "codex-ttft-ms": { type: "string" },
+    "strict-latency": { type: "boolean" },
+    json: { type: "boolean" },
+  });
+  const unknownFlag = Object.keys(flags).find((flag) => !DOCTOR_FLAGS.has(flag));
+  if (unknownFlag) throw new Error(`unknown doctor option "--${unknownFlag}"`);
+  for (const flag of ["tenant", "gateway", "providers", "attempts", "timeout-ms", "claude-ttft-ms", "codex-ttft-ms"]) {
+    if (argv.includes(`--${flag}`) && flags[flag] === undefined) {
+      throw new Error(`--${flag} requires a value`);
+    }
+  }
+  for (const flag of ["all-tenants", "strict-latency", "json"]) {
+    if (flags[flag] !== undefined && flags[flag] !== true) {
+      throw new Error(`--${flag} does not take a value`);
+    }
+  }
+  if (positionals.length) throw new Error(`unexpected doctor argument "${positionals[0]}"`);
+  if (flags.tenant && flags["all-tenants"]) throw new Error("use --tenant or --all-tenants, not both");
+
+  const config = loadConfig();
+  if (!config?.pat) throw new Error("not authenticated; run `impel setup` (or `impel auth`) first");
+  const gatewayUrl = doctorGatewayUrl(
+    flags.gateway !== undefined
+      ? flags.gateway
+      : process.env.IMPEL_GATEWAY_URL || config.gatewayUrl || resolveDefaultGateway(),
+  );
+  const doctorConfig = { ...config, gatewayUrl };
+  const listing = await fetchTenants(config);
+  if (!listing.productAccess) {
+    throw new Error("the control plane did not return a live product access entitlement; retry after it is upgraded");
+  }
+
+  const requestedTenant = flags.tenant ? normalizeTenantId(flags.tenant) : null;
+  const selectedTenant = requestedTenant
+    ? listing.tenants.find((tenant) => tenant.id === requestedTenant || tenant.slug === requestedTenant)
+    : listing.tenants.find((tenant) => tenant.id === config.tenantId) || listing.tenants.find((tenant) => tenant.id === listing.defaultTenantId);
+  if (requestedTenant && !selectedTenant) throw new Error(`tenant "${requestedTenant}" is not available to this user`);
+  const tenants = flags["all-tenants"] ? listing.tenants : [selectedTenant];
+
+  const providers = parseProviders(flags.providers);
+  assertProviderScopes(listing.scopes, providers, { requireLive: true });
+  const attempts = integerFlag(flags.attempts, "--attempts", { min: 1, max: 5 }) ?? 1;
+  const timeoutMs = integerFlag(flags["timeout-ms"], "--timeout-ms", { min: 1_000, max: 300_000 }) ?? 120_000;
+  const ttftBudgets = {
+    claude: integerFlag(flags["claude-ttft-ms"], "--claude-ttft-ms", { min: 100, max: 300_000 }) ?? DEFAULT_TTFT_BUDGET_MS.claude,
+    codex: integerFlag(flags["codex-ttft-ms"], "--codex-ttft-ms", { min: 100, max: 300_000 }) ?? DEFAULT_TTFT_BUDGET_MS.codex,
+  };
+  const totalProbes = tenants.length * providers.length * attempts;
+  if (totalProbes > MAX_TOTAL_PROBES) {
+    throw new Error(
+      `doctor would send ${totalProbes} billable requests; narrow the tenants/providers/attempts to at most ${MAX_TOTAL_PROBES}`,
+    );
+  }
+
+  const tenantReports = [];
+  for (const tenant of tenants) {
+    tenantReports.push(await probeTenant({
+      config: doctorConfig,
+      tenantId: tenant.id,
+      productAccess: listing.productAccess,
+      providers,
+      attempts,
+      timeoutMs,
+      ttftBudgets,
+      strictLatency: Boolean(flags["strict-latency"]),
+    }));
+  }
+  const report = {
+    generatedAt: new Date().toISOString(),
+    synthetic: true,
+    strictLatency: Boolean(flags["strict-latency"]),
+    tenants: tenantReports,
+    passed: tenantReports.length > 0 && tenantReports.every((tenant) => tenant.passed),
+  };
+  if (flags.json) console.log(JSON.stringify(report, null, 2));
+  else printHuman(report);
+  if (!report.passed) process.exitCode = 1;
+}

package/src/commands/experimental.js

@@ -0,0 +1,60 @@
+import { crossAppModelsEnabled, loadConfig, saveConfig } from "../config.js";
+import { assertProviderScopes, ensureTenantSelection } from "../tenants.js";
+
+const HELP = `impel experimental cross-app-models enable|disable|status
+
+Hidden experiment for Impel-managed desktop apps and isolated CLI launchers.
+When enabled, Impel Claude/\`impel claude\` can use tenant-routable GPT models
+and Impel ChatGPT/Codex/\`impel codex\` can use tenant-routable Claude models.
+It does not modify native profiles or support the consumer ChatGPT app
+(com.openai.chat).
+
+Run \`impel app refresh all\` to refresh desktop configs. Reopen an Impel app
+or isolated CLI to apply the experiment.`;
+
+export async function cmdExperimental(argv, dependencies = {}) {
+  const read = dependencies.loadConfig || loadConfig;
+  const write = dependencies.saveConfig || saveConfig;
+  const select = dependencies.ensureTenantSelection || ensureTenantSelection;
+  const log = dependencies.log || console.log;
+  const [experiment, action, ...extra] = argv;
+
+  if ((experiment === "help" || experiment == null) && action == null && extra.length === 0) {
+    log(HELP);
+    return;
+  }
+  if (experiment !== "cross-app-models" || !["enable", "disable", "status"].includes(action) || extra.length > 0) {
+    throw new Error("usage: impel experimental cross-app-models enable|disable|status");
+  }
+
+  const config = read();
+  if (action === "status") {
+    log(`Cross-app models: ${crossAppModelsEnabled(config) ? "enabled" : "disabled"}`);
+    return;
+  }
+  if (action === "disable") {
+    if (config && crossAppModelsEnabled(config)) {
+      delete config.experimental.crossAppModels;
+      if (Object.keys(config.experimental).length === 0) delete config.experimental;
+      write(config);
+    }
+    log(
+      "Cross-app models disabled. Reopen an Impel app or isolated CLI; run `impel app refresh all` to refresh desktop configs.",
+    );
+    return;
+  }
+
+  if (!config?.pat) throw new Error("run `impel auth` before enabling cross-app models");
+  const selected = await select(config, { refresh: true });
+  assertProviderScopes(selected.scopes, ["claude", "codex"], { requireLive: true });
+  selected.config.experimental = {
+    ...(selected.config.experimental && typeof selected.config.experimental === "object"
+      ? selected.config.experimental
+      : {}),
+    crossAppModels: true,
+  };
+  write(selected.config);
+  log(
+    "Cross-app models enabled for Impel-managed apps and isolated CLIs. Reopen one or run `impel app refresh all` to refresh desktop configs.",
+  );
+}

package/src/commands/launch.js

@@ -0,0 +1,161 @@
+import { spawn } from "node:child_process";
+import os from "node:os";
+
+import {
+  ensureImpelClaudeProfile,
+  ensureImpelCodexProfile,
+} from "../cliProfiles.js";
+import {
+  crossAppModelsEnabled,
+  loadConfig,
+  normalizeGatewayUrl,
+  redactSecretText,
+  resolveDefaultGateway,
+} from "../config.js";
+import { impelClaudeBaseUrl, impelCrossAppClaudeBaseUrl } from "../claudeSetup.js";
+import { assertProviderScopes, ensureTenantSelection, tenantCredential } from "../tenants.js";
+import { maybePrintUpdateNotice } from "../updates.js";
+import {
+  nativeSpawnInvocation,
+  resolveNativeBinary,
+} from "../nativeProcess.js";
+
+const CLAUDE_DIRECT_AUTH_ENV = [
+  "ANTHROPIC_API_KEY",
+  "ANTHROPIC_AUTH_TOKEN",
+  "CLAUDE_CODE_USE_BEDROCK",
+  "CLAUDE_CODE_USE_FOUNDRY",
+  "CLAUDE_CODE_USE_VERTEX",
+];
+
+const CODEX_DIRECT_AUTH_ENV = ["CODEX_ACCESS_TOKEN", "CODEX_API_KEY", "OPENAI_API_KEY", "OPENAI_BASE_URL"];
+export { escapeWindowsBatchArgument, nativeSpawnInvocation, resolveNativeBinary } from "../nativeProcess.js";
+
+export const IMPEL_SPECIALIST_DELEGATION_INSTRUCTIONS = `You are running in an Impel tenant-scoped session. Before starting any non-trivial task, call the Impel MCP tool list_specialists. If exactly one available specialist clearly matches the user's request, its capabilities and its exclusions, delegate the complete request by calling start_specialist_run exactly once with a stable idempotency key, then call read_specialist_run until it reaches a terminal state. When the run succeeds, use the specialist's result as your response instead of redoing the work. If no specialist clearly matches, the tools are unavailable, or the run fails, continue normally yourself. Do not delegate trivial requests, do not call a specialist excluded from the request, and never invent a specialist result.`;
+
+export const IMPEL_CODEX_SPECIALIST_DELEGATION_INSTRUCTIONS =
+  `${IMPEL_SPECIALIST_DELEGATION_INSTRUCTIONS} ` +
+  `Codex can defer MCP tools behind tool_search. If an Impel specialist tool is not directly visible, call tool_search for its exact name before treating it as unavailable: impel_specialists-list_specialists for discovery, impel_specialists-start_specialist_run to delegate, and impel_specialists-read_specialist_run to poll the result. Use the returned tool for the same one-run delegation flow.`;
+
+const IMPEL_CODEX_RUNTIME_OVERRIDES = [
+  // Codex models may select code mode even when the standalone
+  // `codex-code-mode-host` companion is not present in the vendor install.
+  // The embedded runtime is the vendor-supported equivalent and is scoped to
+  // this Impel invocation, so the user's native Codex profile is unaffected.
+  "features.code_mode_host=false",
+];
+
+export function impelLaunchArguments(tool, argv) {
+  if (tool === "claude") {
+    return ["--append-system-prompt", IMPEL_SPECIALIST_DELEGATION_INSTRUCTIONS, ...argv];
+  }
+  if (tool === "codex") {
+    // `-c` is a Codex global option, so it must precede subcommands such as
+    // `exec`, `resume`, and `mcp`. JSON strings are valid TOML basic strings.
+    return [
+      "-c",
+      `developer_instructions=${JSON.stringify(IMPEL_CODEX_SPECIALIST_DELEGATION_INSTRUCTIONS)}`,
+      ...IMPEL_CODEX_RUNTIME_OVERRIDES.flatMap((override) => ["-c", override]),
+      ...argv,
+    ];
+  }
+  throw new Error(`unsupported CLI launcher: ${tool}`);
+}
+
+function deleteEnvironmentKeys(environment, keys) {
+  for (const key of keys) delete environment[key];
+}
+
+function childExitCode(code, signal) {
+  if (Number.isInteger(code)) return code;
+  const signalNumber = signal ? os.constants.signals[signal] : null;
+  return Number.isInteger(signalNumber) ? 128 + signalNumber : 1;
+}
+
+function runNativeCli(tool, argv, environment) {
+  const binary = resolveNativeBinary(tool, environment);
+  let invocation;
+  try {
+    invocation = nativeSpawnInvocation(binary, argv, environment);
+  } catch (error) {
+    console.error(`impel ${tool}: ${redactSecretText(error?.message || error)}`);
+    return Promise.resolve(1);
+  }
+
+  return new Promise((resolve) => {
+    const child = spawn(invocation.command, invocation.args, {
+      cwd: process.cwd(),
+      env: environment,
+      stdio: "inherit",
+      windowsVerbatimArguments: invocation.windowsVerbatimArguments,
+    });
+    let settled = false;
+    child.once("error", (error) => {
+      if (settled) return;
+      settled = true;
+      console.error(
+        `impel ${tool}: could not launch \`${redactSecretText(binary)}\`: ${redactSecretText(error.message)}`,
+      );
+      resolve(127);
+    });
+    child.once("exit", (code, signal) => {
+      if (settled) return;
+      settled = true;
+      resolve(childExitCode(code, signal));
+    });
+  });
+}
+
+export async function cmdLaunch(tool, argv) {
+  const config = loadConfig();
+  if (!config?.pat) {
+    console.error(`impel ${tool}: not authenticated. Run \`impel auth\` first.`);
+    process.exitCode = 1;
+    return;
+  }
+  maybePrintUpdateNotice();
+
+  const gatewayUrl = normalizeGatewayUrl(config.gatewayUrl || resolveDefaultGateway());
+  const crossAppModels = tool === "claude" && crossAppModelsEnabled(config);
+  let tenantId;
+  try {
+    // PAT scopes are immutable. Refresh legacy configs once, then use the
+    // locally persisted scope list so launching the native CLI stays fast.
+    const selection = await ensureTenantSelection(config, { refresh: !Array.isArray(config.scopes) });
+    assertProviderScopes(selection.scopes, crossAppModels ? ["claude", "codex"] : [tool], {
+      requireLive: true,
+    });
+    tenantId = selection.tenantId;
+  } catch (error) {
+    console.error(`impel ${tool}: ${error.message}`);
+    process.exitCode = 1;
+    return;
+  }
+  const gatewayCredential = tenantCredential(config.pat, tenantId);
+  const environment = { ...process.env };
+  environment.IMPEL_TENANT_ID = tenantId;
+
+  if (tool === "claude") {
+    const profile = ensureImpelClaudeProfile(gatewayUrl, tenantId, { crossAppModels });
+    deleteEnvironmentKeys(environment, CLAUDE_DIRECT_AUTH_ENV);
+    delete environment.CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY;
+    environment.CLAUDE_CONFIG_DIR = profile.configDir;
+    environment.ANTHROPIC_BASE_URL = crossAppModels
+      ? impelCrossAppClaudeBaseUrl(gatewayUrl)
+      : impelClaudeBaseUrl(gatewayUrl);
+    if (crossAppModels) environment.CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY = "1";
+    // Claude's external apiKeyHelper path validates Anthropic-shaped API keys.
+    // Impel PATs are bearer tokens, so keep the token process-scoped instead of
+    // writing it into Claude's isolated profile.
+    environment.ANTHROPIC_AUTH_TOKEN = gatewayCredential;
+  } else if (tool === "codex") {
+    const profile = ensureImpelCodexProfile(gatewayUrl, tenantId);
+    deleteEnvironmentKeys(environment, CODEX_DIRECT_AUTH_ENV);
+    environment.CODEX_HOME = profile.codexHome;
+  } else {
+    throw new Error(`unsupported CLI launcher: ${tool}`);
+  }
+
+  const exitCode = await runNativeCli(tool, impelLaunchArguments(tool, argv), environment);
+  if (exitCode !== 0) process.exitCode = exitCode;
+}

package/src/commands/mcp.js

@@ -0,0 +1,94 @@
+import readline from "node:readline";
+
+import { loadConfig, resolveDefaultGateway } from "../config.js";
+import { parseFlags } from "../args.js";
+import { ensureTenantSelection, normalizeTenantId, tenantCredential } from "../tenants.js";
+
+function rpcError(id, message) {
+  return JSON.stringify({
+    jsonrpc: "2.0",
+    id: id ?? null,
+    error: { code: -32000, message },
+  });
+}
+
+function responseLines(contentType, body) {
+  if (!contentType.toLowerCase().includes("text/event-stream")) {
+    return body.trim() ? [JSON.stringify(JSON.parse(body))] : [];
+  }
+  return body
+    .split(/\r?\n/)
+    .filter((line) => line.startsWith("data:"))
+    .map((line) => line.slice(5).trim())
+    .filter((line) => line && line !== "[DONE]")
+    .map((line) => JSON.stringify(JSON.parse(line)));
+}
+
+export async function cmdMcp(argv = []) {
+  const { flags } = parseFlags(argv, { tenant: { type: "string" } });
+  const config = loadConfig();
+  if (!config?.pat) {
+    throw new Error("not authenticated; run `impel setup` (or `impel auth`) first");
+  }
+  const gatewayUrl = config.gatewayUrl || resolveDefaultGateway();
+  const tenantId = flags.tenant
+    ? normalizeTenantId(flags.tenant)
+    : (await ensureTenantSelection(config)).tenantId;
+  const gatewayCredential = tenantCredential(config.pat, tenantId);
+  const endpoint = `${gatewayUrl}/mcp`;
+  const input = readline.createInterface({ input: process.stdin, crlfDelay: Infinity });
+  let sessionId;
+
+  for await (const line of input) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    let message;
+    try {
+      message = JSON.parse(trimmed);
+    } catch {
+      process.stdout.write(`${rpcError(null, "Invalid JSON-RPC request.")}\n`);
+      continue;
+    }
+
+    try {
+      const controller = new AbortController();
+      const timeout = setTimeout(() => controller.abort(), 70_000);
+      let response;
+      try {
+        response = await fetch(endpoint, {
+          method: "POST",
+          headers: {
+            Authorization: `Bearer ${gatewayCredential}`,
+            "Content-Type": "application/json",
+            Accept: "application/json, text/event-stream",
+            ...(sessionId ? { "Mcp-Session-Id": sessionId } : {}),
+          },
+          body: JSON.stringify(message),
+          signal: controller.signal,
+        });
+      } finally {
+        clearTimeout(timeout);
+      }
+      sessionId = response.headers.get("mcp-session-id") || sessionId;
+      const body = await response.text();
+      if (!response.ok) {
+        process.stdout.write(
+          `${rpcError(message.id, `Impel MCP gateway returned HTTP ${response.status}.`)}\n`
+        );
+        continue;
+      }
+      for (const output of responseLines(
+        response.headers.get("content-type") || "application/json",
+        body
+      )) {
+        process.stdout.write(`${output}\n`);
+      }
+    } catch (error) {
+      const messageText =
+        error?.name === "AbortError"
+          ? "Impel MCP gateway timed out."
+          : `Impel MCP gateway request failed: ${error?.message || error}`;
+      process.stdout.write(`${rpcError(message.id, messageText)}\n`);
+    }
+  }
+}