impel-cli 0.20.56 → 0.20.57

package/src/modelSync.js

@@ -0,0 +1,197 @@
+// The async half of the CLI Codex catalog layering (D13): fetch the tenant's
+// live gateway catalog and atomically replace the models.json that
+// ensureImpelCodexProfile pinned, recording provenance in
+// models-manifest.json so the synchronous floor writer and the TTL machinery
+// can tell a synced catalog from the offline floor.
+//
+// Layering contract:
+//   - ensureImpelCodexProfile (cliProfiles.js) stays synchronous and offline;
+//     it writes the FALLBACK_MODELS floor unless the manifest proves the
+//     on-disk catalog is the last synced one for the same bindings.
+//   - syncCodexModelsSafe runs AFTER it — at launch (the syncAgentProfilesSafe
+//     idiom), from `impel models sync`, from the detached stale-only app
+//     refresh, and from the `impel token` heartbeat repair. It never throws
+//     and never blocks a launch on the network.
+//   - A gateway catalog replaces the floor only when valid and non-empty:
+//     fetchGatewayModels validates org/product attribution and fails closed
+//     on empty data (isExplicitNoSeatCatalog only relaxes lifecycle
+//     reconciliation, not this sync), and gatewayCodexCliCatalog reconstructs
+//     every entry from validated fields — raw gateway JSON never flows into
+//     models.json (D15).
+
+import fs from "node:fs";
+
+import { normalizeGatewayUrl, redactSecretText } from "./config.js";
+import { tenantCliProfilePaths } from "./cliProfiles.js";
+import { fetchGatewayModels } from "./gatewayModels.js";
+import { gatewayCodexCliCatalog } from "./modelCatalog.js";
+import {
+  catalogDigest,
+  codexCatalogIsFresh,
+  codexModelsManifestPath,
+  CODEX_MODELS_MANIFEST_SCHEMA_VERSION,
+  readCodexModelsManifest,
+  writeAtomicPrivateFile,
+  writeCodexModelsManifest,
+} from "./modelsManifest.js";
+import { normalizeTenantId } from "./tenants.js";
+
+/**
+ * One catalog sync for one tenant's isolated CLI Codex profile. Throws on
+ * failure (callers that must not fail use syncCodexModelsSafe). Returns
+ * { synced, skipped?, reason?, catalogPath, models? }.
+ */
+export async function syncCodexModels({
+  gatewayUrl,
+  credential,
+  tenantId,
+  crossAppModels = false,
+  staleOnly = false,
+  now = Date.now(),
+  fetchModels = fetchGatewayModels,
+}) {
+  if (process.env.IMPEL_SKIP_MODEL_SYNC === "1" || process.env.IMPEL_SKIP_MODEL_SYNC === "true") {
+    return { synced: false, skipped: true, reason: "disabled" };
+  }
+  const normalizedTenant = normalizeTenantId(tenantId);
+  const normalizedGateway = normalizeGatewayUrl(gatewayUrl);
+  const { codexHome, codexCatalog } = tenantCliProfilePaths(normalizedTenant);
+  const bindings = {
+    tenantId: normalizedTenant,
+    gatewayUrl: normalizedGateway,
+    crossAppModels,
+  };
+  if (!fs.existsSync(codexCatalog)) {
+    // Never conjure a half-initialized profile just to sync models into it;
+    // the profile writer owns directory creation and hardening.
+    return { synced: false, skipped: true, reason: "uninitialized", catalogPath: codexCatalog };
+  }
+  if (staleOnly && codexCatalogIsFresh(codexHome, codexCatalog, { ...bindings, now })) {
+    return { synced: false, skipped: true, reason: "fresh", catalogPath: codexCatalog };
+  }
+
+  const fetched = await fetchModels({
+    gatewayUrl: normalizedGateway,
+    pat: credential,
+    tenantId: normalizedTenant,
+  });
+  const catalog = gatewayCodexCliCatalog(fetched.models, {
+    crossAppModels,
+    now: new Date(now),
+  });
+  if (!catalog) {
+    // Valid-and-non-empty gate: a tenant with zero projectable Codex-picker
+    // models keeps its current catalog (floor or last sync) rather than
+    // shipping Codex an empty picker.
+    throw new Error("gateway returned no models projectable into the Codex picker");
+  }
+  const text = `${JSON.stringify(catalog, null, 2)}\n`;
+  writeAtomicPrivateFile(codexCatalog, text);
+  writeCodexModelsManifest(codexHome, {
+    schemaVersion: CODEX_MODELS_MANIFEST_SCHEMA_VERSION,
+    syncedAt: new Date(now).toISOString(),
+    catalogVersion: fetched.version ?? null,
+    digest: catalogDigest(text),
+    tenantId: normalizedTenant,
+    gatewayUrl: normalizedGateway,
+    experiments: { crossAppModels: Boolean(crossAppModels) },
+  });
+  return {
+    synced: true,
+    catalogPath: codexCatalog,
+    models: catalog.models.length,
+    catalogVersion: fetched.version ?? null,
+  };
+}
+
+/**
+ * The launch-safe wrapper (the syncAgentProfilesSafe idiom): never throws,
+ * never blocks a launch outcome. A network/catalog failure leaves the last
+ * good models.json — floor or previously synced — in place.
+ */
+export async function syncCodexModelsSafe(options) {
+  try {
+    return await syncCodexModels(options);
+  } catch (error) {
+    const logger = options?.logger || console;
+    logger.warn(`impel: model catalog sync failed (${redactSecretText(error?.message || error)}); keeping the last good Codex model catalog.`);
+    return {
+      synced: false,
+      reason: "error",
+      error: redactSecretText(error?.message || error),
+    };
+  }
+}
+
+/**
+ * The `catalogIsFresh` gate for the TTL machinery (heartbeat repair, detached
+ * stale-only refresh): true only when an initialized CLI Codex catalog exists
+ * and is NOT provably fresh for these bindings. Uninitialized profiles are
+ * never stale — a sync would skip them anyway. Never throws.
+ */
+export function cliCodexCatalogStale(tenantId, {
+  gatewayUrl,
+  crossAppModels = false,
+  now = Date.now(),
+} = {}) {
+  try {
+    const normalizedTenant = normalizeTenantId(tenantId);
+    const { codexHome, codexCatalog } = tenantCliProfilePaths(normalizedTenant);
+    if (!fs.existsSync(codexCatalog)) return false;
+    return !codexCatalogIsFresh(codexHome, codexCatalog, {
+      tenantId: normalizedTenant,
+      gatewayUrl: normalizeGatewayUrl(gatewayUrl),
+      crossAppModels,
+      now,
+    });
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Staleness report for diagnostics (`impel models list`, `impel doctor`).
+ * Read-only and offline.
+ */
+export function codexCatalogStatus(tenantId, {
+  gatewayUrl = null,
+  crossAppModels = false,
+  now = Date.now(),
+} = {}) {
+  const normalizedTenant = normalizeTenantId(tenantId);
+  const { codexHome, codexCatalog } = tenantCliProfilePaths(normalizedTenant);
+  const manifest = readCodexModelsManifest(codexHome);
+  let catalog = null;
+  let catalogError = null;
+  try {
+    catalog = JSON.parse(fs.readFileSync(codexCatalog, "utf8"));
+  } catch (error) {
+    catalogError = error?.code === "ENOENT" ? "missing" : "unreadable";
+  }
+  const models = Array.isArray(catalog?.models)
+    ? catalog.models.filter((model) => model && typeof model.slug === "string")
+    : [];
+  const digestMatches = Boolean(manifest && catalog)
+    && catalogDigest(fs.readFileSync(codexCatalog, "utf8")) === manifest.digest;
+  const syncedAt = manifest ? Date.parse(manifest.syncedAt) : NaN;
+  const fresh = gatewayUrl !== null
+    ? codexCatalogIsFresh(codexHome, codexCatalog, {
+      tenantId: normalizedTenant,
+      gatewayUrl,
+      crossAppModels,
+      now,
+    })
+    : false;
+  return {
+    tenantId: normalizedTenant,
+    catalogPath: codexCatalog,
+    manifestPath: codexModelsManifestPath(codexHome),
+    catalogError,
+    models,
+    source: digestMatches ? "gateway" : "floor",
+    manifest,
+    syncedAt: Number.isFinite(syncedAt) ? new Date(syncedAt).toISOString() : null,
+    ageMs: Number.isFinite(syncedAt) ? Math.max(0, now - syncedAt) : null,
+    fresh,
+  };
+}

package/src/modelsManifest.js

@@ -0,0 +1,132 @@
+// Freshness record for the isolated CLI Codex model catalog (models.json):
+// models-manifest.json, written beside the catalog in the tenant CODEX_HOME.
+//
+// Leaf module (node builtins + other leaf modules only). Both the synchronous
+// profile writer in cliProfiles.js — which must decide floor-vs-keep with
+// zero network I/O — and the async gateway sync in modelSync.js consult the
+// same record, so this logic must sit below both without importing either.
+//
+// The manifest pins the exact catalog bytes the last sync wrote (sha256
+// digest) plus the bindings that make a synced catalog valid for a launch:
+// tenant, gateway origin, and the cross-app experiment state. A digest or
+// binding mismatch means the catalog on disk is NOT the one the last sync
+// produced — the floor writer then reasserts the offline floor, and the TTL
+// machinery treats the catalog as stale regardless of syncedAt.
+
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+import { normalizeGatewayUrl } from "./config.js";
+import { renameWithWindowsRetry } from "./windowsFs.js";
+
+export const CODEX_MODELS_MANIFEST_BASENAME = "models-manifest.json";
+export const CODEX_MODELS_MANIFEST_SCHEMA_VERSION = 1;
+/** Same 6h cadence as the agent-profile and desktop-app refresh machinery. */
+export const MODEL_SYNC_TTL_MS = 6 * 60 * 60 * 1000;
+
+export function codexModelsManifestPath(codexHome) {
+  return path.join(codexHome, CODEX_MODELS_MANIFEST_BASENAME);
+}
+
+export function catalogDigest(text) {
+  return crypto.createHash("sha256").update(text, "utf8").digest("hex");
+}
+
+/** Atomic private write (write-temp-rename, 0600), matching the CLI's other config writers. */
+export function writeAtomicPrivateFile(target, contents) {
+  fs.mkdirSync(path.dirname(target), { recursive: true, mode: 0o700 });
+  const temporaryPath = `${target}.tmp-${process.pid}`;
+  try {
+    fs.writeFileSync(temporaryPath, contents, { mode: 0o600 });
+    renameWithWindowsRetry(temporaryPath, target);
+    try {
+      fs.chmodSync(target, 0o600);
+    } catch {
+      // Best effort on platforms where chmod is unavailable.
+    }
+  } finally {
+    try {
+      fs.rmSync(temporaryPath, { force: true });
+    } catch {
+      // The rename already removed the temporary file in the normal case.
+    }
+  }
+}
+
+/** Parse and shape-validate the manifest; anything invalid reads as absent. */
+export function readCodexModelsManifest(codexHome) {
+  let raw;
+  try {
+    raw = fs.readFileSync(codexModelsManifestPath(codexHome), "utf8");
+  } catch {
+    return null;
+  }
+  let value;
+  try {
+    value = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  const valid = value
+    && typeof value === "object"
+    && !Array.isArray(value)
+    && value.schemaVersion === CODEX_MODELS_MANIFEST_SCHEMA_VERSION
+    && typeof value.syncedAt === "string"
+    && typeof value.digest === "string"
+    && /^[0-9a-f]{64}$/u.test(value.digest)
+    && typeof value.tenantId === "string"
+    && typeof value.gatewayUrl === "string"
+    && value.experiments
+    && typeof value.experiments === "object"
+    && !Array.isArray(value.experiments)
+    && typeof value.experiments.crossAppModels === "boolean";
+  return valid ? value : null;
+}
+
+export function writeCodexModelsManifest(codexHome, manifest) {
+  writeAtomicPrivateFile(
+    codexModelsManifestPath(codexHome),
+    `${JSON.stringify(manifest, null, 2)}\n`,
+  );
+}
+
+/**
+ * Whether the catalog on disk is exactly the one the last gateway sync wrote
+ * for these bindings. Deliberately TTL-free: a stale synced catalog still
+ * beats the offline floor (stale-beats-broken), so the synchronous profile
+ * writer keeps it; only the TTL gate below decides to refresh it.
+ */
+export function syncedCodexCatalogMatches(codexHome, catalogPath, {
+  tenantId,
+  gatewayUrl,
+  crossAppModels = false,
+} = {}) {
+  const manifest = readCodexModelsManifest(codexHome);
+  if (!manifest) return false;
+  if (manifest.tenantId !== tenantId) return false;
+  if (normalizeGatewayUrl(manifest.gatewayUrl) !== normalizeGatewayUrl(gatewayUrl)) return false;
+  if (manifest.experiments.crossAppModels !== Boolean(crossAppModels)) return false;
+  let text;
+  try {
+    text = fs.readFileSync(catalogPath, "utf8");
+  } catch {
+    return false;
+  }
+  return catalogDigest(text) === manifest.digest;
+}
+
+/** The TTL gate: an intact synced catalog whose last sync is inside the window. */
+export function codexCatalogIsFresh(codexHome, catalogPath, {
+  tenantId,
+  gatewayUrl,
+  crossAppModels = false,
+  now = Date.now(),
+  ttlMs = MODEL_SYNC_TTL_MS,
+} = {}) {
+  if (!syncedCodexCatalogMatches(codexHome, catalogPath, { tenantId, gatewayUrl, crossAppModels })) {
+    return false;
+  }
+  const syncedAt = Date.parse(readCodexModelsManifest(codexHome).syncedAt);
+  return Number.isFinite(syncedAt) && syncedAt <= now && now - syncedAt < ttlMs;
+}

package/src/platformSetup.js

@@ -29,8 +29,9 @@ export async function preparePlatformClis(options = {}, dependencies = {}) {
   };
   // Discovery-only probes must not write profiles either.
   if (options.inspectOnly) return result;
-  const claudeProfile = (dependencies.ensureClaudeProfile || ensureImpelClaudeProfile)(options.gatewayUrl, options.tenantId);
-  const codexProfile = (dependencies.ensureCodexProfile || ensureImpelCodexProfile)(options.gatewayUrl, options.tenantId);
+  const crossAppModels = options.crossAppModels === true;
+  const claudeProfile = (dependencies.ensureClaudeProfile || ensureImpelClaudeProfile)(options.gatewayUrl, options.tenantId, { crossAppModels });
+  const codexProfile = (dependencies.ensureCodexProfile || ensureImpelCodexProfile)(options.gatewayUrl, options.tenantId, { crossAppModels });
   return {
     ...result,
     profiles: { claude: claudeProfile.configDir, codex: codexProfile.codexHome },

package/src/provisioning.js

@@ -101,7 +101,9 @@ async function prepareTenantCli(config, tenant, io, binaries) {
     },
     codex: {
       supported: providerSupported(config.scopes, PAT_SCOPE_CODEX),
-      ensure: () => io.ensureCodex(config.gatewayUrl, tenant.id),
+      ensure: () => io.ensureCodex(config.gatewayUrl, tenant.id, {
+        crossAppModels: crossAppModelsEnabled(config),
+      }),
       root: (profile) => profile.codexHome,
       env: (profile) => ({
         CODEX_HOME: profile.codexHome,

package/src/runtimeBrand.js

@@ -11,7 +11,7 @@ const CONTROL_RE = /[\u0000-\u001F\u007F-\u009F]/u;
 const SUPPORTED_COMMANDS = new Set([
   "setup", "auth", "pat", "token", "mcp", "sessions", "claude", "codex",
   "status", "doctor", "report", "tasks", "tenant", "app", "nuke", "skills",
-  "agents", "update", "use", "experimental",
+  "models", "agents", "update", "use", "experimental",
 ]);
 
 const DEFAULT = Object.freeze({

package/src/updates.js

@@ -295,6 +295,16 @@ export function spawnDetachedAppRefresh(tenantId = null) {
   ]);
 }
 
+/** Background CLI Codex model-catalog sync; no-ops inside the TTL. */
+export function spawnDetachedModelSync(tenantId) {
+  spawnDetached([
+    "models",
+    "sync",
+    "--stale-only",
+    ...(tenantId ? ["--tenant", tenantId] : []),
+  ]);
+}
+
 /**
  * Background telemetry send. Lives here beside the other detached spawns so
  * `spawnDetached`'s Windows-console handling has exactly one implementation,

package/src/windowsSetup.js

@@ -143,6 +143,7 @@ export async function prepareWindowsClis({
   skipInstall = false,
   inspectOnly = false,
   installTools = ["claude", "codex"],
+  crossAppModels = false,
 } = {}, dependencies = {}) {
   const io = {
     environment: process.env,
@@ -238,8 +239,8 @@ export async function prepareWindowsClis({
     ? detectWindowsClis(io.find, io.environment, io.verify)
     : before;
   const drifted = detectDriftedWindowsClis(io.find, io.environment, binaries, { versionOf: io.versionOf });
-  const claudeProfile = io.ensureClaudeProfile(gatewayUrl, tenantId);
-  const codexProfile = io.ensureCodexProfile(gatewayUrl, tenantId);
+  const claudeProfile = io.ensureClaudeProfile(gatewayUrl, tenantId, { crossAppModels });
+  const codexProfile = io.ensureCodexProfile(gatewayUrl, tenantId, { crossAppModels });
 
   if (binaries.claude) {
     await io.syncSkills({