impel-cli 0.20.45 → 0.20.46-beta.2

package/src/doctor.js

@@ -10,6 +10,7 @@ const MAX_ERROR_BODY_BYTES = 64 * 1024;
 const MAX_OUTPUT_CHARS = 16 * 1024;
 const MAX_PENDING_SSE_CHARS = 1024 * 1024;
 const MAX_STREAM_BYTES = 4 * 1024 * 1024;
+const CLAUDE_PROBE_MAX_TOKENS = 1_024;
 const GATEWAY_REQUEST_ID_RE = /^impel-[a-f0-9]{32}$/u;
 const POOL_STATES = new Set(["healthy", "exhausted", "rate_limited", "expired", "no_seat"]);
 
@@ -86,6 +87,12 @@ function consumeSseBlock(provider, block, state, startedAt, now) {
     if (!state.responseId && typeof event?.message?.id === "string") {
       state.responseId = event.message.id.slice(0, 512) || null;
     }
+    if (event?.type === "message_delta" && typeof event?.delta?.stop_reason === "string") {
+      state.stopReason = event.delta.stop_reason.slice(0, 100);
+      if (state.stopReason !== "end_turn") {
+        state.error ||= `provider stopped the response with reason ${redactSecretText(state.stopReason)}`;
+      }
+    }
     if (event?.type === "message_stop") state.terminalEvent = event.type;
     if (event?.type === "content_block_delta" && event?.delta?.type === "text_delta") {
       delta = typeof event.delta.text === "string" ? event.delta.text : "";
@@ -131,7 +138,11 @@ async function streamProbe({ provider, url, bearer, model, tenantId, attempt, ti
   const body = provider === "claude"
     ? {
         model,
-        max_tokens: 96,
+        // Current reasoning-capable Claude models may spend part of this budget
+        // before emitting the tiny acknowledgement. Ninety-six tokens made a
+        // healthy route look broken when reasoning exhausted the response
+        // budget before the first text delta.
+        max_tokens: CLAUDE_PROBE_MAX_TOKENS,
         stream: true,
         messages: [{ role: "user", content: prompt }],
       }
@@ -192,6 +203,7 @@ async function streamProbe({ provider, url, bearer, model, tenantId, attempt, ti
         exactAck: false,
         outputChars: 0,
         outputTruncated: false,
+        stopReason: null,
         terminalEvent: null,
         doneSentinel: false,
         receivedBytes: 0,
@@ -204,6 +216,7 @@ async function streamProbe({ provider, url, bearer, model, tenantId, attempt, ti
       responseId: null,
       ttftMs: null,
       outputTruncated: false,
+      stopReason: null,
       terminalEvent: null,
       doneSentinel: false,
       error: null,
@@ -262,6 +275,7 @@ async function streamProbe({ provider, url, bearer, model, tenantId, attempt, ti
       exactAck,
       outputChars: state.answer.length,
       outputTruncated: state.outputTruncated,
+      stopReason: state.stopReason,
       terminalEvent: state.terminalEvent,
       doneSentinel: state.doneSentinel,
       receivedBytes,
@@ -283,6 +297,7 @@ async function streamProbe({ provider, url, bearer, model, tenantId, attempt, ti
       exactAck: false,
       outputChars: 0,
       outputTruncated: false,
+      stopReason: null,
       terminalEvent: null,
       doneSentinel: false,
       receivedBytes: 0,
@@ -488,6 +503,7 @@ export async function probeTenant({
           exactAck: false,
           outputChars: 0,
           outputTruncated: false,
+          stopReason: null,
           terminalEvent: null,
           doneSentinel: false,
           receivedBytes: 0,

package/src/exitCodes.js

@@ -0,0 +1,61 @@
+// Process exit codes that mean something specific.
+//
+// Three values are already spoken for and must never be reused:
+//
+//   1  — `bin/impel.js`'s catch-all for any escaped throw. A dedicated code
+//        that collides with this is indistinguishable from a crash.
+//   78 — `MANAGED_RUNTIME_PREFLIGHT_EXIT_CODE` (EX_CONFIG) in `src/apps.js`.
+//   127 — the shell's "command not found"; a CLI that returns it is claiming
+//        it was never invoked.
+//
+// Everything else follows sysexits.h, so an operator reading a bare number
+// gets the right intuition without a lookup.
+
+/** Codes an Impel-specific exit code must not reuse. Asserted by tests. */
+export const RESERVED_EXIT_CODES = Object.freeze([0, 1, 78, 127]);
+
+/**
+ * `impel _telemetry flush` could not deliver its batch (EX_TEMPFAIL): the
+ * spool is intact and a later flush retries.
+ *
+ * Nothing reads this in production — the sender is detached with stdio
+ * ignored, and the durable drop notice is the real observability surface. It
+ * exists because the send is an external call, and Law 6 wants every failure
+ * branch to have a distinct non-zero outcome that a test and a human running
+ * the command by hand can both see.
+ */
+export const TELEMETRY_FLUSH_FAILED_EXIT_CODE = 75;
+
+/**
+ * A gated command refused because the feature-flag state could not be
+ * established (EX_UNAVAILABLE): no fresh evaluation, no cached one for this
+ * account, and no way to reach the control plane.
+ *
+ * Distinct from the catch-all 1 on purpose. "I could not find out whether you
+ * are allowed to run this" and "I crashed" are different states, and only the
+ * first one is worth retrying once the machine is back online.
+ */
+export const FLAG_STATE_UNKNOWN_EXIT_CODE = 69;
+
+/**
+ * A gated command refused because the flag is off for this account
+ * (EX_NOPERM): the state *was* established, and the answer was no.
+ *
+ * Separate from `FLAG_STATE_UNKNOWN_EXIT_CODE` because the two say opposite
+ * things about retrying. "Not enabled for you" is a settled answer — running it
+ * again changes nothing until someone grants access. "Could not find out" is
+ * worth retrying the moment the machine is back online. A script that treats
+ * both as one number has to guess which it got.
+ */
+export const FEATURE_NOT_ENABLED_EXIT_CODE = 77;
+
+/**
+ * `impel report` could not deliver the bug report and wrote the envelope to
+ * disk instead (EX_IOERR): the route was unreachable, absent, or rate-limited.
+ *
+ * The report is user-initiated, so unlike telemetry someone is watching this
+ * exit code. It says "your report was not lost, and it was not sent either" —
+ * a state that deserves its own number, because the printed spool path is the
+ * next action and 1 would read as a crash that produced nothing.
+ */
+export const REPORT_SPOOLED_EXIT_CODE = 74;

package/src/featureFlags.js

@@ -0,0 +1,393 @@
+// Remote feature flags for the CLI: a disk cache in front of
+// `POST /api/cli/flags`, evaluated fail-closed.
+//
+// The only consumer today is the Cursor experiment gate, and that shapes every
+// decision here. A gate exists so an experiment can be turned off remotely for
+// one account; if a machine that cannot reach the control plane guessed a
+// value, the guess would be wrong exactly when the switch is being thrown. So
+// there is no default: `evaluateFlag` either returns an answer it can trace to
+// a real server evaluation — fresh, cached, or stale — or it throws
+// `FlagStateUnknownError` for the command to turn into a distinct exit code.
+//
+// Two timers, mirroring `src/updates.js`: `fetchedAt` decides whether the
+// cached answer is still current (6h), and `lastFailedAt` suppresses re-probing
+// after a failure (1h). Without the second one an offline machine would attempt
+// a fetch on every single invocation of the gated command.
+//
+// The cache records the principal it was fetched for. A read under a different
+// `{orgId, userId}` is a miss rather than a hit: serving the previous org's
+// answers for up to six hours after a tenant or PAT switch would defeat a kill
+// switch precisely when one org is being killed and another is not.
+//
+// Everything written here lives under `CONFIG_DIR`, so `impel nuke` erases it.
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import {
+  CONFIG_DIR,
+  loadConfig,
+  normalizeGatewayUrl,
+  resolveDefaultAppUrl,
+} from "./config.js";
+import { FLAG_STATE_UNKNOWN_EXIT_CODE } from "./exitCodes.js";
+import { fetchHttp1 } from "./http1.js";
+import { TELEMETRY_CONTRACT } from "./posthog.js";
+import { RUNTIME_BRAND } from "./runtimeBrand.js";
+import { managedMarkerPresent } from "./telemetryConsent.js";
+import { renameWithWindowsRetry } from "./windowsFs.js";
+
+/** The route this module posts to. */
+export const FLAGS_ENDPOINT_PATH = "/api/cli/flags";
+
+/** Beside `update-check.json`, and erased by the same `impel nuke` sweep. */
+export const FLAG_CACHE_PATH = path.join(CONFIG_DIR, "flags.json");
+
+/** How long an evaluation stays authoritative. The repo's cache default. */
+export const FLAG_CACHE_TTL_MS = 6 * 60 * 60 * 1000;
+
+/**
+ * How long a failed check suppresses the next attempt. Shorter than the TTL:
+ * a failure should heal within the session, but must not turn an offline
+ * machine into one request per gated command.
+ */
+export const FLAG_FETCH_BACKOFF_MS = 60 * 60 * 1000;
+
+/**
+ * The flag the managed-Cursor experiment is gated on.
+ *
+ * Declared as a literal rather than read out of `TELEMETRY_CONTRACT` by index;
+ * `test/feature-flags.test.js` pins it against `featureFlagKeys` so the two
+ * cannot drift while keeping the reference here readable.
+ */
+export const CURSOR_EXPERIMENT_FLAG = "cli-cursor-experiment";
+
+/** Long enough for a cold control-plane response, short enough to be a gate. */
+const REQUEST_TIMEOUT_MS = 10_000;
+
+/** Flag keys are bounded by the server schema; anything longer is not ours. */
+const MAX_FLAG_KEY_LENGTH = 128;
+
+/**
+ * The flag state could not be established, and no cached answer applies.
+ *
+ * Thrown rather than returned so a caller cannot accidentally treat it as a
+ * value. Commands catch it and set `exitCode` on `process.exitCode`: the
+ * `experimental` throw path always exits 1, so an escaping throw would be
+ * indistinguishable from a crash (see `src/exitCodes.js`).
+ */
+export class FlagStateUnknownError extends Error {
+  constructor(message, reason) {
+    super(message);
+    this.name = "FlagStateUnknownError";
+    /** Machine-readable cause; each maps to its own message. */
+    this.reason = reason;
+    this.exitCode = FLAG_STATE_UNKNOWN_EXIT_CODE;
+  }
+}
+
+/** Internal: a fetch that did not produce a usable evaluation. */
+class FlagFetchError extends Error {
+  constructor(message, reason) {
+    super(message);
+    this.name = "FlagFetchError";
+    this.reason = reason;
+  }
+}
+
+/* -------------------------------------------------------------------------- */
+/* Cache                                                                      */
+/* -------------------------------------------------------------------------- */
+
+export function readFlagCache() {
+  try {
+    const cache = JSON.parse(fs.readFileSync(FLAG_CACHE_PATH, "utf8"));
+    return cache && typeof cache === "object" && !Array.isArray(cache) ? cache : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Merge-and-replace, matching `writeUpdateCache`'s tmp+rename discipline. */
+export function writeFlagCache(patch) {
+  const next = { ...(readFlagCache() || {}), ...patch };
+  fs.mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
+  const temporaryPath = `${FLAG_CACHE_PATH}.tmp-${process.pid}`;
+  try {
+    fs.writeFileSync(temporaryPath, `${JSON.stringify(next, null, 2)}\n`, { mode: 0o600 });
+    renameWithWindowsRetry(temporaryPath, FLAG_CACHE_PATH);
+  } finally {
+    try {
+      fs.rmSync(temporaryPath, { force: true });
+    } catch {
+      // Cleanup must never mask the write/rename outcome.
+    }
+  }
+  return next;
+}
+
+/**
+ * Who the flags were evaluated for.
+ *
+ * `userId` comes from `config.user`, which U10 persists from the tenants
+ * response. Before that field exists it is `null` on both the write and the
+ * read, so the comparison stays consistent — an install that has never seen a
+ * `user` is one principal, not a permanent mismatch.
+ */
+function flagPrincipal(config) {
+  return {
+    orgId: typeof config?.tenantId === "string" ? config.tenantId : null,
+    userId: typeof config?.user?.id === "string" ? config.user.id : null,
+  };
+}
+
+function samePrincipal(cache, principal) {
+  return (cache?.orgId ?? null) === principal.orgId
+    && (cache?.userId ?? null) === principal.userId;
+}
+
+/** The cached evaluation, or null when there is none *for this principal*. */
+function cachedFlags(cache, principal) {
+  if (!cache || !samePrincipal(cache, principal)) return null;
+  const flags = cache.flags;
+  return flags && typeof flags === "object" && !Array.isArray(flags) ? flags : null;
+}
+
+function withinTtl(cache, now) {
+  return Number.isFinite(cache?.fetchedAt) && now - cache.fetchedAt < FLAG_CACHE_TTL_MS;
+}
+
+function backoffRemainingMs(cache, now) {
+  if (!Number.isFinite(cache?.lastFailedAt)) return 0;
+  return Math.max(0, cache.lastFailedAt + FLAG_FETCH_BACKOFF_MS - now);
+}
+
+/* -------------------------------------------------------------------------- */
+/* Evaluation                                                                 */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Read one flag out of an evaluation.
+ *
+ * A key the evaluation does not mention resolves to `enabled: false`. That is
+ * not a fabricated default: the server answered, and an answer that does not
+ * name the flag is an answer that the flag is not on for this principal. The
+ * fabricated case — no answer at all — throws instead. `known` lets a caller
+ * that cares tell the two apart.
+ */
+function resolveFlag(name, flags, source) {
+  const flag = flags?.[name];
+  return {
+    name,
+    enabled: flag?.enabled === true,
+    variant: typeof flag?.variant === "string" ? flag.variant : null,
+    payload: flag && Object.hasOwn(flag, "payload") ? flag.payload : null,
+    known: Boolean(flag),
+    source,
+  };
+}
+
+/**
+ * Validate a response into the shape the cache stores, or return null.
+ *
+ * One malformed flag rejects the whole response rather than being skipped: a
+ * partially-read evaluation is exactly the "some flags computed, some not"
+ * state the route already refuses to send (`flags_unavailable`), and a kill
+ * switch dropped by a lenient parser reads as "not killed".
+ */
+function normalizeFlagResponse(payload) {
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) return null;
+  const { flags } = payload;
+  if (!flags || typeof flags !== "object" || Array.isArray(flags)) return null;
+  const keys = Object.keys(flags);
+  if (keys.length > TELEMETRY_CONTRACT.limits.maxFlagsPerResponse) return null;
+
+  const normalized = {};
+  for (const key of keys) {
+    if (key.length === 0 || key.length > MAX_FLAG_KEY_LENGTH) return null;
+    const value = flags[key];
+    if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+    if (typeof value.enabled !== "boolean") return null;
+    normalized[key] = { enabled: value.enabled };
+    if (typeof value.variant === "string" && value.variant.length > 0) {
+      normalized[key].variant = value.variant;
+    }
+    if (value.payload !== undefined) normalized[key].payload = value.payload;
+  }
+  return {
+    flags: normalized,
+    evaluatedAt: typeof payload.evaluatedAt === "string" ? payload.evaluatedAt : null,
+  };
+}
+
+async function jsonBody(response) {
+  try {
+    return await response.json();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * One evaluation request.
+ *
+ * Server-supplied text is never echoed — only status codes and our own
+ * sentences — so no message can carry back something that needs redacting.
+ */
+async function fetchFlags({ config, fetchImpl, timeoutMs }) {
+  const appUrl = normalizeGatewayUrl(config.appUrl || resolveDefaultAppUrl());
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
+  let response;
+  try {
+    response = await fetchImpl(new URL(FLAGS_ENDPOINT_PATH, appUrl), {
+      method: "POST",
+      headers: {
+        accept: "application/json",
+        authorization: `Bearer ${config.pat}`,
+        "content-type": "application/json",
+      },
+      body: "{}",
+      signal: controller.signal,
+    });
+  } catch {
+    throw new FlagFetchError(
+      `could not reach ${appUrl} to check feature flags; reconnect and try again`,
+      "unreachable",
+    );
+  } finally {
+    clearTimeout(timeout);
+  }
+
+  if (!response.ok) {
+    // R16: a `next` deployment that predates the route. Named separately from
+    // every other failure because the remedy is a deployment, not a retry.
+    if (response.status === 404) {
+      throw new FlagFetchError(
+        `${appUrl} does not serve feature flags yet; update the ${RUNTIME_BRAND.product.displayName} control plane and try again`,
+        "absent_route",
+      );
+    }
+    const body = await jsonBody(response);
+    if (body?.code === "flags_unavailable") {
+      throw new FlagFetchError(
+        `${appUrl} cannot evaluate feature flags right now; try again in a few minutes`,
+        "unavailable",
+      );
+    }
+    throw new FlagFetchError(
+      `${appUrl} refused the feature-flag check (HTTP ${response.status}); try again later`,
+      "rejected",
+    );
+  }
+
+  const normalized = normalizeFlagResponse(await jsonBody(response));
+  if (!normalized) {
+    throw new FlagFetchError(
+      `${appUrl} returned a feature-flag response this CLI cannot read; update the CLI and try again`,
+      "malformed",
+    );
+  }
+  return normalized;
+}
+
+/**
+ * Why this process may not make the request, or null when it may.
+ *
+ * The managed-surface denial is the P1-8 egress boundary and is checked first:
+ * a managed vendor app profile may reach the gateway and nothing else, so a
+ * flag check from inside one presents as an unexpected call from a profile
+ * holding app credentials. Unlike analytics capture this is not a consent
+ * question — a kill switch that honors an opt-out is not a kill switch — but
+ * the context guard applies to every egress path without exception.
+ */
+function fetchBlocked({ config, env, homeDir, cache, now }) {
+  if (managedMarkerPresent(env, homeDir)) {
+    return {
+      reason: "managed_surface",
+      message: "feature flags cannot be checked from inside a managed Impel app profile; run this from a terminal",
+    };
+  }
+  if (!config?.pat) {
+    return {
+      reason: "unauthenticated",
+      message: `not authenticated; run \`${RUNTIME_BRAND.cli.command} setup\` before using a gated feature`,
+    };
+  }
+  const remaining = backoffRemainingMs(cache, now);
+  if (remaining > 0) {
+    const minutes = Math.max(1, Math.ceil(remaining / 60_000));
+    return {
+      reason: "backoff",
+      message: `a recent feature-flag check failed and no cached answer applies to this account; try again in ${minutes} minute${minutes === 1 ? "" : "s"}`,
+    };
+  }
+  return null;
+}
+
+/**
+ * Resolve one flag for the current principal.
+ *
+ * The state machine, in the order the branches are taken:
+ *
+ *   fresh cache                      -> use it, no request
+ *   blocked (managed/no PAT/backoff) -> stale cache if there is one, else refuse
+ *   fetch succeeds                   -> store and use
+ *   fetch fails, cache exists        -> stale value, failure stamped
+ *   fetch fails, no cache            -> refuse with that failure's own message
+ *
+ * "Cache" throughout means a cache written for *this* `{orgId, userId}`; one
+ * written for another principal is not a cache miss that degrades to stale, it
+ * is a miss that refuses.
+ */
+export async function evaluateFlag(name, options = {}) {
+  const {
+    config = loadConfig(),
+    fetchImpl = fetchHttp1,
+    env = process.env,
+    homeDir = os.homedir(),
+    now = Date.now(),
+    timeoutMs = REQUEST_TIMEOUT_MS,
+  } = options;
+
+  const principal = flagPrincipal(config);
+  const cache = readFlagCache();
+  const cached = cachedFlags(cache, principal);
+  if (cached && withinTtl(cache, now)) return resolveFlag(name, cached, "cache");
+
+  const blocked = fetchBlocked({ config, env, homeDir, cache, now });
+  if (blocked) {
+    if (cached) return resolveFlag(name, cached, "stale");
+    throw new FlagStateUnknownError(blocked.message, blocked.reason);
+  }
+
+  let evaluation;
+  try {
+    evaluation = await fetchFlags({ config, fetchImpl, timeoutMs });
+  } catch (error) {
+    // Stamp the failure even when a stale answer covers this call: the point of
+    // the second timer is that the *next* invocation does not re-probe either.
+    try {
+      writeFlagCache({ lastFailedAt: now });
+    } catch {
+      // The stamp is a request-rate limiter, not required state.
+    }
+    if (cached) return resolveFlag(name, cached, "stale");
+    throw new FlagStateUnknownError(error.message, error.reason || "unreachable");
+  }
+
+  try {
+    writeFlagCache({
+      ...principal,
+      flags: evaluation.flags,
+      evaluatedAt: evaluation.evaluatedAt,
+      fetchedAt: now,
+      lastFailedAt: 0,
+    });
+  } catch {
+    // An unwritable config dir costs a cache, not an answer: this evaluation is
+    // authoritative and is returned either way.
+  }
+  return resolveFlag(name, evaluation.flags, "network");
+}

package/src/managedProfileVersion.js

@@ -1,4 +1,6 @@
 // Fleet generation shared by managed-profile writers and upstream clients.
 // Keep this isolated from apps.js so latency-sensitive transports do not load
 // desktop bundle machinery just to identify their managed config contract.
-export const CURRENT_CONFIG_VERSION = 37;
+// v38 replaces the generated desktop MCP Apps host with the authenticated web
+// board and removes the desktop-only Codex renderer flag.
+export const CURRENT_CONFIG_VERSION = 38;