impel-cli 0.18.15 → 0.18.17

package/src/commands/apps.js

@@ -76,7 +76,7 @@ export function selectCatalogAppTargets(
   requestedTargets,
   models,
   config,
-  { log = console.log } = {},
+  { log = console.log, allowNone = false } = {},
 ) {
   const supported = appTargetsSupportedByModels(
     requestedTargets,
@@ -87,6 +87,14 @@ export function selectCatalogAppTargets(
   const unavailable = requestedTargets.filter((target) => !supportedSet.has(target));
   if (unavailable.length === 0) return supported;
 
+  if (allowNone && supported.length === 0) {
+    for (const target of unavailable) {
+      const capability = APP_CAPABILITIES[target];
+      log(`Skipping ${capability.label}: the selected tenant has no ${capability.provider} models.`);
+    }
+    return supported;
+  }
+
   if (requestedTargets.length === 1 || supported.length === 0) {
     const target = unavailable[0];
     const capability = APP_CAPABILITIES[target];
@@ -297,9 +305,9 @@ export function openManagedLauncher(launcher, {
   return false;
 }
 
-async function fetchWindowsCatalog(config, io) {
+async function fetchWindowsCatalog(config, io, { allowEmpty = false } = {}) {
   try {
-    return await io.fetchModels(config);
+    return await io.fetchModels(config, undefined, { allowEmpty });
   } catch (error) {
     throw new Error(`tenant model catalog is unavailable (${redactSecretText(error.message)}); the Impel app profiles were not changed`);
   }
@@ -374,12 +382,25 @@ export async function reconcileWindowsTenantApps({
     ...overrides,
   };
   const config = explicitTenantAppConfig(baseConfig, tenant, targets);
-  const catalog = await fetchWindowsCatalog(config, io);
-  const actionTargets = selectCatalogAppTargets(targets, catalog.models, config, { log: io.log });
+  const catalog = await fetchWindowsCatalog(config, io, { allowEmpty: true });
+  const actionTargets = selectCatalogAppTargets(targets, catalog.models, config, {
+    log: io.log,
+    allowNone: true,
+  });
   const supported = new Set(actionTargets);
   const unsupported = targets.filter((target) => !supported.has(target));
   const userData = io.claudeUserData(environment, config.tenantId);
   const paths = appPaths(homeDir, config.tenantId, { claudeUserData: userData, tenantName: config.tenantName });
+  if (actionTargets.length === 0) {
+    return {
+      tenantId: config.tenantId,
+      targets: [],
+      unsupported,
+      paths,
+      verification: {},
+      failed: [],
+    };
+  }
   const vendorPaths = {};
   const preparedTargets = new Set(skipVendor ? actionTargets : skipVendorTargets);
 
@@ -501,13 +522,28 @@ export async function reconcileMacTenantApps({
   const config = explicitTenantAppConfig(baseConfig, tenant, targets);
   let catalog;
   try {
-    catalog = await io.fetchModels(config);
+    catalog = await io.fetchModels(config, undefined, { allowEmpty: true });
   } catch (error) {
     throw new Error(`tenant model catalog is unavailable (${redactSecretText(error?.message || error)}); no Impel app files were changed`);
   }
-  const actionTargets = selectCatalogAppTargets(targets, catalog.models, config, { log: io.log });
+  const actionTargets = selectCatalogAppTargets(targets, catalog.models, config, {
+    log: io.log,
+    allowNone: true,
+  });
   const supported = new Set(actionTargets);
   const unsupported = targets.filter((target) => !supported.has(target));
+  const paths = appPaths(homeDir, config.tenantId, { tenantName: config.tenantName });
+  if (actionTargets.length === 0) {
+    return {
+      tenantId: config.tenantId,
+      targets: [],
+      unsupported,
+      paths,
+      verification: {},
+      installed: [],
+      failed: [],
+    };
+  }
   const vendorPaths = {};
   const statuses = io.status(actionTargets, homeDir, config.tenantId, config.tenantName);
   for (const status of statuses) vendorPaths[status.target] ||= status.vendorPath;
@@ -549,7 +585,6 @@ export async function reconcileMacTenantApps({
     vendorPaths,
     writeBundles: staleTargets,
   }) : [];
-  const paths = appPaths(homeDir, config.tenantId, { tenantName: config.tenantName });
   const agentItems = [];
   for (const item of installed) {
     const { client, env, label } = appSkillTarget(item.target, paths);

package/src/commands/converge.js

@@ -13,6 +13,8 @@ import { promptText } from "../prompt.js";
 import { describeCliFailure, preparePlatformClis } from "../platformSetup.js";
 import { restoreNativeProfiles } from "./use.js";
 
+const RETRYABLE_TENANT_DISCOVERY_ERROR = /could not reach|request timed out|fetch failed|ECONNRESET|ECONNABORTED|ETIMEDOUT|EAI_AGAIN|ENETUNREACH|network error|socket/iu;
+
 function confirmed(answer) {
   return /^(?:y|yes)$/iu.test(String(answer || "").trim());
 }
@@ -44,6 +46,7 @@ export async function cmdConverge(argv = [], overrides = {}) {
     platform: process.platform,
     environment: process.env,
     preparePlatformClis,
+    discoveryLogger: console,
     ...overrides,
   };
   if (overrides.prepareWindowsClis && !overrides.preparePlatformClis) {
@@ -58,10 +61,22 @@ export async function cmdConverge(argv = [], overrides = {}) {
   let listing;
   try {
     listing = await io.fetchTenants(config);
+    // Tenant discovery is the entry gate for the whole convergence. A single
+    // transient timeout should not force a human to rerun every update step.
   } catch (error) {
-    console.error(`impel update: tenant discovery failed (${redactSecretText(error?.message || error)})`);
-    process.exitCode = 1;
-    return false;
+    if (!RETRYABLE_TENANT_DISCOVERY_ERROR.test(String(error?.message || error))) {
+      console.error(`impel update: tenant discovery failed (${redactSecretText(error?.message || error)})`);
+      process.exitCode = 1;
+      return false;
+    }
+    io.discoveryLogger.log("Tenants: discovery request failed transiently; retrying once…");
+    try {
+      listing = await io.fetchTenants(config);
+    } catch (retryError) {
+      console.error(`impel update: tenant discovery failed (${redactSecretText(retryError?.message || retryError)})`);
+      process.exitCode = 1;
+      return false;
+    }
   }
   const selected = selectDefaultTenant(listing, { currentTenantId: config.tenantId });
   config.tenantId = selected.id;

package/src/commands/cursorExperimental.js

@@ -0,0 +1,192 @@
+import os from "node:os";
+
+import {
+  cursorLaunchSpec,
+  ensureCursorManagedAuthentication,
+  ensureCursorManagedModels,
+  launchManagedCursor,
+  managedCursorStatus,
+  prepareManagedCursor,
+  reusePreparedManagedCursor,
+} from "../cursorLocal.js";
+import { fetchHttp1 } from "../http1.js";
+import { loadConfig, normalizeGatewayUrl, redactSecretText, resolveDefaultGateway } from "../config.js";
+import { assertProviderScopes, ensureTenantSelection, tenantCredential } from "../tenants.js";
+
+export const CURSOR_EXPERIMENT_HELP = `impel experimental cursor prepare|open|status
+
+Prepare, open, and inspect a tenant-isolated Cursor desktop runtime experiment.
+Agent inference uses the selected tenant's Impel gateway and an isolated,
+non-secret Cursor smoke identity. The signed stable Cursor.app in /Applications
+keeps updating normally; Impel mirrors and revalidates each compatible update
+without modifying the vendor app or the user's personal Cursor profile.
+
+Usage:
+  impel experimental cursor prepare
+  impel experimental cursor open [workspace-or-Cursor-args...]
+  impel experimental cursor status`;
+
+async function cursorGatewayCatalog(options, dependencies = {}) {
+  const fetchImpl = dependencies.fetch || fetchHttp1;
+  let response;
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 7_000);
+    try {
+      response = await fetchImpl(
+        `${options.gatewayUrl}/experimental/openai/v1/models`,
+        {
+          headers: {
+            accept: "application/json",
+            authorization: `Bearer ${options.credential}`,
+          },
+          signal: controller.signal,
+        },
+      );
+      break;
+    } catch (error) {
+      if (error?.name === "AbortError" && attempt === 0) continue;
+      const detail = error?.name === "AbortError" ? "request timed out" : error?.message || error;
+      throw new Error(`could not read the Cursor model catalog: ${redactSecretText(detail)}`);
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+  let payload;
+  try {
+    payload = await response.json();
+  } catch {
+    throw new Error(
+      `Cursor model catalog endpoint returned non-JSON (HTTP ${response.status}); deploy the matching impel-gateway Cursor catalog route`,
+    );
+  }
+  if (!response.ok) {
+    const detail = payload?.error?.message || payload?.error || `Cursor model catalog returned HTTP ${response.status}`;
+    throw new Error(redactSecretText(typeof detail === "string" ? detail : JSON.stringify(detail)));
+  }
+  if (payload?.org_id !== options.tenantId) {
+    throw new Error("Cursor model catalog tenant did not match the selected tenant");
+  }
+  if (!Array.isArray(payload.data) || payload.data.length === 0) {
+    throw new Error("Cursor model catalog returned no routable models");
+  }
+  const invalid = payload.data.find((model) => (
+    typeof model?.id !== "string"
+    || !Array.isArray(model.api_types)
+    || !model.api_types.includes("responses")
+    || model?.capabilities?.supports_tool_use !== true
+    || model?.capabilities?.supports_streaming !== true
+    || (
+      model?.capabilities?.supports_reasoning === true
+      && (
+        !Array.isArray(model.capabilities.reasoning_effort)
+        || model.capabilities.reasoning_effort.length === 0
+        || model.capabilities.reasoning_effort.some((effort) => typeof effort !== "string")
+        || (
+          model.capabilities.default_reasoning_effort !== undefined
+          && !model.capabilities.reasoning_effort.includes(model.capabilities.default_reasoning_effort)
+        )
+      )
+    )
+  ));
+  if (invalid) throw new Error("Cursor model catalog did not advertise the required Responses/tool contract");
+  return payload;
+}
+
+function statusLines(status, tenantId) {
+  const vendorLabel = status.vendor
+    ? `${status.vendor.version} (${status.vendor.commit.slice(0, 12)})`
+    : "incompatible";
+  const managedLabel = status.manifest?.vendor?.version || "not prepared";
+  return [
+    `Managed Cursor tenant: ${tenantId}`,
+    `Installed stable Cursor: ${vendorLabel}`,
+    `Managed runtime: ${managedLabel}`,
+    `Managed bundle contract: ${status.ready ? "ready" : "needs prepare"}`,
+    `Local Agent UI contract: ${status.ready ? "ready" : "needs prepare"}`,
+    ...(status.compatibilityError ? [`Compatibility: blocked — ${status.compatibilityError}`] : []),
+    ...(status.runtimeError ? [`Managed signature: invalid — ${status.runtimeError}`] : []),
+  ];
+}
+
+export async function cmdCursorExperimental(argv, dependencies = {}) {
+  const [action, ...args] = argv;
+  const log = dependencies.log || console.log;
+  if (action == null || action === "help") {
+    if (args.length) throw new Error("usage: impel experimental cursor prepare|open|status");
+    log(CURSOR_EXPERIMENT_HELP);
+    return;
+  }
+  if (!["prepare", "open", "status"].includes(action) || (action !== "open" && args.length)) {
+    throw new Error("usage: impel experimental cursor prepare|open|status");
+  }
+
+  const config = (dependencies.loadConfig || loadConfig)();
+  if (!config?.pat) throw new Error("run `impel setup` before preparing managed Cursor");
+  const selection = await (dependencies.ensureTenantSelection || ensureTenantSelection)(config, {
+    refresh: !Array.isArray(config.scopes),
+  });
+  assertProviderScopes(selection.scopes, ["claude", "codex"], { requireLive: true });
+  const tenantId = selection.tenantId;
+  const homeDir = dependencies.homeDir || os.homedir();
+  const gatewayUrl = normalizeGatewayUrl(config.gatewayUrl || resolveDefaultGateway());
+  const common = {
+    tenantId,
+    homeDir,
+    appRoot: dependencies.appRoot,
+    ...(dependencies.vendorPath ? { vendorPath: dependencies.vendorPath } : {}),
+  };
+  const credential = tenantCredential(config.pat, tenantId);
+
+  if (action === "status") {
+    const status = (dependencies.managedCursorStatus || managedCursorStatus)(common, dependencies);
+    for (const line of statusLines(status, tenantId)) log(line);
+    try {
+      const catalog = await cursorGatewayCatalog({ gatewayUrl, credential, tenantId }, dependencies);
+      log(`Gateway Cursor catalog: ready (${catalog.data.length} model${catalog.data.length === 1 ? "" : "s"})`);
+      return { ...status, gatewayReady: true, catalog };
+    } catch (error) {
+      const gatewayError = redactSecretText(error?.message || error);
+      log(`Gateway Cursor catalog: unavailable — ${gatewayError}`);
+      return { ...status, gatewayReady: false, gatewayError };
+    }
+  }
+
+  let prepared;
+  try {
+    prepared = (dependencies.prepareManagedCursor || prepareManagedCursor)(common, dependencies);
+  } catch (error) {
+    if (action !== "open") throw error;
+    prepared = (dependencies.reusePreparedManagedCursor || reusePreparedManagedCursor)(common, dependencies);
+    log(`Installed Cursor update was not imported; reusing the last verified managed runtime — ${redactSecretText(error?.message || error)}`);
+  }
+  const updateLabel = prepared.updated ? "Prepared" : "Reused";
+  log(`${updateLabel} managed Cursor ${prepared.source.version} for tenant ${tenantId}.`);
+  if (action === "prepare") return prepared;
+  const catalog = await cursorGatewayCatalog({ gatewayUrl, credential, tenantId }, dependencies);
+  const managedModels = (dependencies.ensureCursorManagedModels || ensureCursorManagedModels)(
+    prepared.paths.userData,
+    catalog.data,
+    `${gatewayUrl}/experimental/openai/v1`,
+    dependencies,
+  );
+  const authentication = (dependencies.ensureCursorManagedAuthentication || ensureCursorManagedAuthentication)(
+    prepared.paths.userData,
+    dependencies,
+  );
+  const spec = (dependencies.cursorLaunchSpec || cursorLaunchSpec)({
+    paths: prepared.paths,
+    gatewayUrl,
+    credential,
+    tenantId,
+    cursorAuthToken: authentication.token,
+    argv: args,
+    environment: dependencies.environment || process.env,
+  });
+  await (dependencies.launchManagedCursor || launchManagedCursor)(spec, dependencies);
+  log(`Opened managed Cursor for tenant ${tenantId} with ${catalog.data.length} gateway model${catalog.data.length === 1 ? "" : "s"}.`);
+  return { ...prepared, catalog, managedModels, launched: true };
+
+}
+
+export { cursorGatewayCatalog };

package/src/commands/experimental.js

@@ -1,5 +1,6 @@
 import { crossAppModelsEnabled, loadConfig, saveConfig } from "../config.js";
 import { assertProviderScopes, ensureTenantSelection } from "../tenants.js";
+import { cmdCursorExperimental, CURSOR_EXPERIMENT_HELP } from "./cursorExperimental.js";
 
 const HELP = `impel experimental cross-app-models enable|disable|status
 
@@ -10,7 +11,9 @@ 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.`;
+or isolated CLI to apply the experiment.
+
+${CURSOR_EXPERIMENT_HELP}`;
 
 export async function cmdExperimental(argv, dependencies = {}) {
   const read = dependencies.loadConfig || loadConfig;
@@ -23,8 +26,11 @@ export async function cmdExperimental(argv, dependencies = {}) {
     log(HELP);
     return;
   }
+  if (experiment === "cursor") {
+    return cmdCursorExperimental([action, ...extra], dependencies);
+  }
   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");
+    throw new Error("usage: impel experimental cross-app-models enable|disable|status | impel experimental cursor prepare|open|status");
   }
 
   const config = read();

package/src/commands/launch.js

@@ -20,8 +20,9 @@ import { assertProviderScopes, ensureTenantSelection, tenantCredential } from ".
 import { maybePrintUpdateNotice } from "../updates.js";
 import {
   nativeSpawnInvocation,
-  resolveNativeBinary,
 } from "../nativeProcess.js";
+import { resolveReviewedVendorCliBinary } from "../vendorCliBinaries.js";
+import { PINNED_VENDOR_CLI_VERSIONS } from "../vendorCliVersions.js";
 import { RUNTIME_BRAND } from "../runtimeBrand.js";
 import {
   cacheProviderReadiness,
@@ -115,7 +116,15 @@ async function assertLiveProviderReadiness({ config, gatewayUrl, credential, ten
 }
 
 function runNativeCli(tool, argv, environment) {
-  const binary = resolveNativeBinary(tool, environment);
+  const binary = resolveReviewedVendorCliBinary(tool, environment);
+  if (!binary) {
+    const version = PINNED_VENDOR_CLI_VERSIONS[tool];
+    console.error(
+      `impel ${tool}: reviewed ${tool === "claude" ? "Claude Code" : "Codex"} CLI `
+      + `v${version} is not installed. Run \`impel update\` to repair it.`,
+    );
+    return Promise.resolve(127);
+  }
   let invocation;
   try {
     invocation = nativeSpawnInvocation(binary, argv, environment);

package/src/commands/status.js

@@ -4,8 +4,9 @@ import path from "node:path";
 
 import { appPaths, CLAUDE_CONFIG_ID, readTenantManifest } from "../apps.js";
 import { crossAppModelsEnabled, loadConfig, maskSecret } from "../config.js";
-import { environmentValue, findNativeBinary } from "../nativeProcess.js";
+import { environmentValue } from "../nativeProcess.js";
 import { tenantCliClientReadiness } from "../provisioning.js";
+import { findReviewedVendorCliBinary } from "../vendorCliBinaries.js";
 import { windowsTenantShortcutName } from "../shellEntries.js";
 import {
   ensureTenantSelection,
@@ -86,7 +87,7 @@ export async function cmdStatus(overrides = {}) {
     cliReadiness: tenantCliClientReadiness,
     desktopReadiness,
     installedVersion,
-    findNativeBinary,
+    findNativeBinary: findReviewedVendorCliBinary,
     maybePrintUpdateNotice,
     platform: process.platform,
     environment: process.env,

package/src/commands/update.js

@@ -18,6 +18,7 @@ import {
   isNewerVersion,
   refreshUpdateCache,
   updateInstallSpec,
+  updateTagForVersion,
   writeUpdateCache,
 } from "../updates.js";
 
@@ -200,30 +201,41 @@ export async function cmdUpdate(argv, overrides = {}) {
   }
 
   const current = io.installedVersion();
-  const remote = await io.progress("Checking npm for impel-cli updates", () => io.fetchRemoteVersion());
+  const updateTag = updateTagForVersion(current);
+  const installSpec = updateInstallSpec(updateTag);
+  const remote = await io.progress(
+    "Checking npm for impel-cli updates",
+    () => io.fetchRemoteVersion({ tag: updateTag }),
+  );
   if (remote) io.writeCache({ remoteVersion: remote, checkedAt: Date.now() });
 
   console.log(`impel-cli v${current ?? "?"}`);
-  console.log(`npm latest: ${remote ? `v${remote}` : "unknown — registry check failed"}`);
+  console.log(`npm ${updateTag}: ${remote ? `v${remote}` : "unknown — registry check failed"}`);
 
   const updateAvailable = Boolean(current && remote && isNewerVersion(remote, current));
   const upToDate = Boolean(current && remote && !updateAvailable);
   if (flags.check) {
-    console.log(upToDate ? "Up to date." : "Update available: run `impel update`.");
-    if (!remote) process.exitCode = 1;
+    if (!remote) {
+      console.log("Update status unavailable; the installed CLI was not changed.");
+      process.exitCode = 1;
+    } else {
+      console.log(upToDate ? "Up to date." : "Update available: run `impel update`.");
+    }
     return;
   }
 
   // ── CLI ────────────────────────────────────────────────────────────────
-  if (upToDate) {
+  if (!remote) {
+    console.warn("CLI: npm update check unavailable; keeping the installed build.");
+  } else if (upToDate) {
     console.log("CLI: already up to date.");
   } else {
-    console.log("CLI: installing the latest build…");
-    if (!await io.progress("Installing the latest impel-cli build", () => io.selfUpdate(updateInstallSpec()))) {
+    console.log(`CLI: installing the npm ${updateTag} build…`);
+    if (!await io.progress(`Installing the npm ${updateTag} impel-cli build`, () => io.selfUpdate(installSpec))) {
       console.error("impel update: `npm install -g` failed; the CLI was not updated.");
       if (io.platform === "win32") {
         console.error("  Verify `npm --version` in PowerShell, then retry `impel update`.");
-        console.error("  Manual recovery: `npm install --global impel-cli@latest`.");
+        console.error(`  Manual recovery: \`npm install --global ${installSpec}\`.`);
       }
       const config = io.loadConfig();
       let recovered = false;
@@ -239,7 +251,7 @@ export async function cmdUpdate(argv, overrides = {}) {
                 platform: io.platform,
                 architecture: process.arch,
                 step: "install.impel_cli",
-                command: `npm install --global ${RUNTIME_BRAND.cli.packageName}@latest`,
+                command: `npm install --global ${installSpec}`,
                 message: `The npm-verified global ${RUNTIME_BRAND.cli.packageName} update failed.`,
               },
               config,
@@ -265,7 +277,7 @@ export async function cmdUpdate(argv, overrides = {}) {
                   }
                 },
                 retryStep: async () => {
-                  updateState.ok = io.selfUpdate(updateInstallSpec()) === true;
+                  updateState.ok = io.selfUpdate(installSpec) === true;
                   return updateState.ok;
                 },
               },
@@ -294,7 +306,7 @@ export async function cmdUpdate(argv, overrides = {}) {
       console.error(`impel update: npm reported success but the running CLI still resolves v${postInstall ?? "?"} (expected v${remote}).`);
       console.error(`  Running CLI: ${CLI_BIN}`);
       console.error("  This usually means the `impel` on PATH belongs to a different npm prefix than `npm prefix -g`.");
-      console.error("  Fix: run `npm prefix -g`, confirm it owns the `impel` shim on PATH, then `npm install --global impel-cli@latest` there.");
+      console.error(`  Fix: run \`npm prefix -g\`, confirm it owns the \`impel\` shim on PATH, then \`npm install --global ${installSpec}\` there.`);
       process.exitCode = 1;
       return;
     }