impel-cli 0.18.12 → 0.18.13

package/README.md

@@ -103,6 +103,12 @@ impel claude
 impel codex
 ```
 
+Before spawning the vendor CLI, Impel verifies that the selected tenant's live
+model catalogue has a healthy, routable provider pool. A short-lived successful
+check is reused for one minute. If a provider is unavailable, the command stops
+with an actionable gateway message instead of opening a client that cannot
+complete inference.
+
 Arguments after the command are passed to the vendor CLI:
 
 ```sh

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "impel-cli",
-  "version": "0.18.12",
+  "version": "0.18.13",
   "description": "Prepare isolated Claude and Codex workspaces for every accessible Impel tenant",
   "type": "module",
   "bin": {

package/src/commands/launch.js

@@ -12,6 +12,7 @@ import {
   normalizeGatewayUrl,
   redactSecretText,
   resolveDefaultGateway,
+  saveConfig,
 } from "../config.js";
 import { impelClaudeBaseUrl, impelCrossAppClaudeBaseUrl } from "../claudeSetup.js";
 import { withGitEnvironment } from "../skills.js";
@@ -22,6 +23,12 @@ import {
   resolveNativeBinary,
 } from "../nativeProcess.js";
 import { RUNTIME_BRAND } from "../runtimeBrand.js";
+import {
+  cacheProviderReadiness,
+  cachedProviderReadiness,
+  probeGatewayProviderReadiness,
+  providerAvailable,
+} from "../providerReadiness.js";
 
 const CLAUDE_DIRECT_AUTH_ENV = [
   "ANTHROPIC_API_KEY",
@@ -81,6 +88,32 @@ function childExitCode(code, signal) {
   return Number.isInteger(signalNumber) ? 128 + signalNumber : 1;
 }
 
+function localInformationRequest(argv) {
+  return argv.length === 1 && ["--help", "-h", "--version", "-V", "-v", "help"].includes(argv[0]);
+}
+
+async function assertLiveProviderReadiness({ config, gatewayUrl, credential, tenantId, tool, crossAppModels }) {
+  let readiness = cachedProviderReadiness(config, tenantId);
+  if (!readiness) {
+    readiness = await probeGatewayProviderReadiness(gatewayUrl, credential, tenantId);
+    if (cacheProviderReadiness(config, tenantId, readiness)) saveConfig(config);
+  }
+  const label = tool === "claude" ? "Claude" : "Codex";
+  if (!readiness.reachable) {
+    throw new Error(`could not verify live ${label} availability for tenant "${tenantId}" (${readiness.error || "gateway unreachable"})`);
+  }
+  if (readiness.rejected) throw new Error(`gateway credential was rejected (HTTP ${readiness.status})`);
+  if (!readiness.healthy) {
+    throw new Error(`could not verify live ${label} availability for tenant "${tenantId}" (${readiness.error || `HTTP ${readiness.status}`})`);
+  }
+  if (!providerAvailable(tool, readiness.providers, { crossAppModels })) {
+    throw new Error(
+      `${label} is currently unavailable for tenant "${tenantId}": the gateway advertises no ${label} models. `
+      + `Ask a gateway administrator to restore the ${label} provider pool, then rerun \`${RUNTIME_BRAND.cli.command} setup\`.`,
+    );
+  }
+}
+
 function runNativeCli(tool, argv, environment) {
   const binary = resolveNativeBinary(tool, environment);
   let invocation;
@@ -141,6 +174,22 @@ export async function cmdLaunch(tool, argv) {
     return;
   }
   const gatewayCredential = tenantCredential(config.pat, tenantId);
+  if (!localInformationRequest(argv)) {
+    try {
+      await assertLiveProviderReadiness({
+        config,
+        gatewayUrl,
+        credential: gatewayCredential,
+        tenantId,
+        tool,
+        crossAppModels,
+      });
+    } catch (error) {
+      console.error(`${RUNTIME_BRAND.cli.command} ${tool}: ${redactSecretText(error?.message || error)}`);
+      process.exitCode = 1;
+      return;
+    }
+  }
   const environment = { ...process.env };
   environment.IMPEL_TENANT_ID = tenantId;
   let agentProfile;

package/src/commands/setup.js

@@ -23,6 +23,11 @@ import { runInstallRecovery } from "../installRecovery/engine.js";
 import { refreshUpdateCache, updateNoticeLine } from "../updates.js";
 import { restoreNativeProfiles } from "./use.js";
 import { brandedEnvironmentName, brandedText, RUNTIME_BRAND } from "../runtimeBrand.js";
+import {
+  cacheProviderReadiness,
+  probeGatewayProviderReadiness,
+  providerAvailable,
+} from "../providerReadiness.js";
 
 const HELP = brandedText(`impel setup - prepare every accessible Impel tenant
 
@@ -52,52 +57,33 @@ export function resolveTenantChoice(listing, { requested = null, answer = null,
   return selectDefaultTenant(listing, { currentTenantId });
 }
 
-async function probeGatewayOnce(gatewayUrl, pat, tenantId, fetchImpl, timeoutMs) {
-  const controller = new AbortController();
-  const timeout = setTimeout(() => controller.abort(), timeoutMs);
-  try {
-    const response = await fetchImpl(`${gatewayUrl}/v1/models`, {
-      headers: {
-        accept: "application/json",
-        authorization: `Bearer ${tenantCredential(pat, tenantId)}`,
-      },
-      signal: controller.signal,
-    });
-    return {
-      reachable: true,
-      healthy: response.ok,
-      status: response.status,
-      rejected: [401, 403].includes(response.status),
-    };
-  } catch (error) {
-    return {
-      reachable: false,
-      error: error?.name === "AbortError"
-        ? `timed out after ${Math.round(timeoutMs / 1000)}s`
-        : redactSecretText(error?.message || error),
-    };
-  } finally {
-    clearTimeout(timeout);
-  }
-}
-
-// A single short probe misreports a cold gateway (serverless cold start plus
-// long-haul latency) as unreachable, and that transient verdict gets baked
-// into the convergence failure message. Retry once with a longer deadline
-// before concluding the gateway is down.
 export async function probeGateway(gatewayUrl, pat, tenantId, fetchImpl = fetch, timeoutsMs = [5_000, 10_000]) {
-  let probe = { reachable: false, error: "not probed" };
-  for (const timeoutMs of timeoutsMs) {
-    probe = await probeGatewayOnce(gatewayUrl, pat, tenantId, fetchImpl, timeoutMs);
-    if (probe.reachable) return probe;
-  }
-  return probe;
+  return probeGatewayProviderReadiness(
+    gatewayUrl,
+    tenantCredential(pat, tenantId),
+    tenantId,
+    fetchImpl,
+    timeoutsMs,
+  );
 }
 
-function markProbeFailures(report, probes) {
+function markProbeFailures(report, probes, { crossAppModels = false } = {}) {
   probes.forEach((probe, index) => {
-    if (probe.reachable && !probe.rejected && probe.healthy !== false) return;
     const tenant = report.tenants[index];
+    if (probe.reachable && !probe.rejected && probe.healthy !== false) {
+      if (!Array.isArray(probe.providers)) return;
+      for (const client of ["claude", "codex"]) {
+        if (tenant.clients[client].cli !== "ready") continue;
+        if (!providerAvailable(client, probe.providers, { crossAppModels })) {
+          tenant.clients[client].cli = "unavailable";
+        }
+      }
+      const states = [tenant.clients.claude.cli, tenant.clients.codex.cli];
+      tenant.cli = states.includes("failed")
+        ? "failed"
+        : states.includes("ready") ? "ready" : "unavailable";
+      return;
+    }
     tenant.cli = "failed";
     tenant.status = "failed";
     for (const client of Object.values(tenant.clients)) {
@@ -344,7 +330,12 @@ export async function cmdSetup(argv, overrides = {}) {
   ) => {
     const nextReport = await runConvergence(includeApps, tenants, confirmInstall);
     const probes = await Promise.all(tenants.map((tenant) => io.probe(gatewayUrl, pat, tenant.id)));
-    return markProbeFailures(nextReport, probes);
+    let cacheChanged = false;
+    probes.forEach((probe, index) => {
+      cacheChanged = cacheProviderReadiness(config, tenants[index].id, probe) || cacheChanged;
+    });
+    if (cacheChanged) io.saveConfig(config);
+    return markProbeFailures(nextReport, probes, { crossAppModels: config.experimental?.crossAppModels === true });
   };
   let report = await verifyConvergence();
   if (sharedFailure) report.passed = false;
@@ -476,7 +467,13 @@ export async function cmdSetup(argv, overrides = {}) {
   printReconciliationSummary(report);
   console.log(`CLI tenant: ${selected.id}`);
   if (!RUNTIME_BRAND.tenant.defaultId) console.log("Change it: impel tenant use <tenant>");
-  console.log("Launch: impel claude | impel codex");
+  const selectedReport = report.tenants.find((tenant) => tenant.tenantId === selected.id);
+  const launchable = ["claude", "codex"]
+    .filter((client) => selectedReport?.clients?.[client]?.cli === "ready")
+    .map((client) => `${RUNTIME_BRAND.cli.command} ${client}`);
+  console.log(launchable.length
+    ? `Launch: ${launchable.join(" | ")}`
+    : "Launch: no provider CLI is currently available for this tenant");
   if (!report.passed || sharedFailure) {
     if (sharedFailure) console.error(`Shared setup failure: ${sharedFailure}`);
     console.error("Setup is incomplete. Fix the reported issue or rerun `impel setup`.");

package/src/commands/status.js

@@ -3,7 +3,7 @@ import os from "node:os";
 import path from "node:path";
 
 import { appPaths, CLAUDE_CONFIG_ID, readTenantManifest } from "../apps.js";
-import { loadConfig, maskSecret } from "../config.js";
+import { crossAppModelsEnabled, loadConfig, maskSecret } from "../config.js";
 import { environmentValue, findNativeBinary } from "../nativeProcess.js";
 import { tenantCliClientReadiness } from "../provisioning.js";
 import { windowsTenantShortcutName } from "../shellEntries.js";
@@ -16,6 +16,7 @@ import {
 import { installedVersion, maybePrintUpdateNotice } from "../updates.js";
 import { windowsClaudeUserData } from "../windowsApps.js";
 import { RUNTIME_BRAND } from "../runtimeBrand.js";
+import { cachedProviderReadiness, providerAvailable } from "../providerReadiness.js";
 
 function readShellManifest(paths) {
   try {
@@ -72,8 +73,9 @@ function desktopReadiness(tenant, {
   return states;
 }
 
-function cliState({ supported, profileReady, binaryReady }) {
+function cliState({ supported, available = true, profileReady, binaryReady }) {
   if (!supported) return "unsupported";
+  if (!available) return "unavailable";
   return profileReady && binaryReady ? "ready" : "missing";
 }
 
@@ -126,13 +128,18 @@ export async function cmdStatus(overrides = {}) {
   for (const tenant of [...selected.tenants].sort((left, right) => left.id.localeCompare(right.id))) {
     const profiles = io.cliReadiness(tenant.id);
     const desktop = io.desktopReadiness(tenant, overrides);
+    const providerReadiness = cachedProviderReadiness(config, tenant.id);
     const claudeCli = cliState({
       supported: !scopeKnown || scopes.has(PAT_SCOPE_CLAUDE),
+      available: !providerReadiness || providerAvailable("claude", providerReadiness.providers, {
+        crossAppModels: crossAppModelsEnabled(config),
+      }),
       profileReady: profiles.claude,
       binaryReady: binaries.claude,
     });
     const codexCli = cliState({
       supported: !scopeKnown || scopes.has(PAT_SCOPE_CODEX),
+      available: !providerReadiness || providerAvailable("codex", providerReadiness.providers),
       profileReady: profiles.codex,
       binaryReady: binaries.codex,
     });

package/src/providerReadiness.js

@@ -0,0 +1,122 @@
+import { redactSecretText } from "./config.js";
+
+const PROVIDERS = new Set(["claude", "codex"]);
+const POOL_STATES = new Set(["healthy", "exhausted", "rate_limited", "expired", "no_seat"]);
+export const PROVIDER_READINESS_CACHE_MS = 60_000;
+
+function providersFromPayload(payload) {
+  if (!Array.isArray(payload?.data)) return { error: "gateway model catalog has no model data array" };
+  const statuses = {};
+  if (Object.hasOwn(payload, "provider_status")) {
+    const raw = payload.provider_status;
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+      return { error: "gateway model catalog has malformed provider status metadata" };
+    }
+    for (const provider of PROVIDERS) {
+      if (!Object.hasOwn(raw, provider)) continue;
+      const status = raw[provider];
+      if (!status
+          || typeof status !== "object"
+          || Array.isArray(status)
+          || !POOL_STATES.has(status.state)
+          || typeof status.routable !== "boolean") {
+        return { error: "gateway model catalog has malformed provider status metadata" };
+      }
+      statuses[provider] = status;
+    }
+  }
+  const providers = [...new Set(payload.data
+    .filter((model) => model?.available !== false && model?.ready !== false && model?.readiness?.ready !== false)
+    .map((model) => model?.provider)
+    .filter((provider) => PROVIDERS.has(provider))
+    .filter((provider) => !statuses[provider]
+      || (statuses[provider].state === "healthy" && statuses[provider].routable === true)))]
+    .sort();
+  return { providers };
+}
+
+async function probeGatewayOnce(gatewayUrl, credential, tenantId, fetchImpl, timeoutMs) {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const response = await fetchImpl(`${gatewayUrl}/v1/models`, {
+      headers: {
+        accept: "application/json",
+        authorization: `Bearer ${credential}`,
+      },
+      signal: controller.signal,
+    });
+    const result = {
+      reachable: true,
+      healthy: response.ok,
+      status: response.status,
+      rejected: [401, 403].includes(response.status),
+    };
+    if (!response.ok || typeof response.json !== "function") return result;
+
+    let payload;
+    try {
+      payload = await response.json();
+    } catch {
+      return { ...result, healthy: false, error: "gateway model catalog was not valid JSON" };
+    }
+    const catalog = providersFromPayload(payload);
+    if (catalog.error) {
+      return { ...result, healthy: false, error: catalog.error };
+    }
+    if (payload.org_id && payload.org_id !== tenantId) {
+      return { ...result, healthy: false, error: "gateway model catalog tenant did not match the selected tenant" };
+    }
+    return { ...result, providers: catalog.providers };
+  } catch (error) {
+    return {
+      reachable: false,
+      error: error?.name === "AbortError"
+        ? `timed out after ${Math.round(timeoutMs / 1000)}s`
+        : redactSecretText(error?.message || error),
+    };
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+// Retry one cold/unreachable gateway probe with a longer deadline, but never
+// retry an authoritative HTTP or model-catalog response.
+export async function probeGatewayProviderReadiness(
+  gatewayUrl,
+  credential,
+  tenantId,
+  fetchImpl = fetch,
+  timeoutsMs = [5_000, 10_000],
+) {
+  let probe = { reachable: false, error: "not probed" };
+  for (const timeoutMs of timeoutsMs) {
+    probe = await probeGatewayOnce(gatewayUrl, credential, tenantId, fetchImpl, timeoutMs);
+    if (probe.reachable) return probe;
+  }
+  return probe;
+}
+
+export function cacheProviderReadiness(config, tenantId, probe, checkedAt = new Date()) {
+  if (!probe?.healthy || !Array.isArray(probe.providers)) return false;
+  config.providerReadiness ||= {};
+  config.providerReadiness[tenantId] = {
+    checkedAt: checkedAt.toISOString(),
+    providers: [...new Set(probe.providers.filter((provider) => PROVIDERS.has(provider)))].sort(),
+  };
+  return true;
+}
+
+export function cachedProviderReadiness(config, tenantId, now = Date.now()) {
+  const record = config?.providerReadiness?.[tenantId];
+  const checkedAt = Date.parse(record?.checkedAt || "");
+  if (!Number.isFinite(checkedAt) || checkedAt > now || now - checkedAt > PROVIDER_READINESS_CACHE_MS) return null;
+  if (!Array.isArray(record.providers) || record.providers.some((provider) => !PROVIDERS.has(provider))) return null;
+  return { healthy: true, reachable: true, providers: [...new Set(record.providers)].sort(), cached: true };
+}
+
+export function providerAvailable(tool, providers, { crossAppModels = false } = {}) {
+  if (!Array.isArray(providers)) return false;
+  if (tool === "claude" && crossAppModels) return providers.length > 0;
+  return providers.includes(tool);
+}