@b3labs/b3iq-cli 0.0.0-stage → 0.0.1

package/dist/lib/diagnosis.js

@@ -0,0 +1,678 @@
+import { configPath, resolveSettings } from "./config.js";
+import { CliError } from "./output.js";
+const CONTEXT_MINIMUM = { codex: 32_768, opencode: 32_768, claude: 100_000 };
+export function shellArg(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+export function b3iqLine(parts) {
+    return parts.map((part) => (typeof part === "string" ? part : shellArg(part.arg))).join(" ");
+}
+export function withDeadline(work, ms) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(Object.assign(new Error("diagnostic lookup timed out"), { name: "DiagnosticTimeout" })), ms);
+        work.then((value) => {
+            clearTimeout(timer);
+            resolve(value);
+        }, (error) => {
+            clearTimeout(timer);
+            reject(error);
+        });
+    });
+}
+export async function readAccountBestEffort(load) {
+    if (!resolveSettings().token)
+        return { lookup: "no_token", account: null };
+    try {
+        const { user } = await load();
+        const account = [user.email, user.displayName, user.id].find((value) => typeof value === "string" && value.trim())?.trim() ?? null;
+        return { lookup: "ok", account: account ? account.slice(0, 200) : null };
+    }
+    catch {
+        return { lookup: "failed", account: null };
+    }
+}
+function observed(entries) {
+    const out = {};
+    for (const [key, value] of Object.entries(entries))
+        if (value !== undefined)
+            out[key] = value;
+    return out;
+}
+function diagnosed(message, code, diagnosis, exitCode, requestId) {
+    return new CliError(message, code, exitCode, requestId, diagnosis);
+}
+export function explainNotLoggedIn() {
+    return diagnosed("Not logged in. Run `b3iq login` or set B3IQ_TOKEN.", "auth", {
+        diagnostic: "auth_missing",
+        cause: `No token was present in B3IQ_TOKEN or ${configPath()}.`,
+        observed: { token_present: false },
+        recovery: ["b3iq login", "Set B3IQ_TOKEN to a Machines & SSH API key from the dashboard (Keys, API keys)."],
+        limitation: "An inference-only API key does not log this CLI in for machine-management commands.",
+    }, 3);
+}
+export function explainNetworkFailure(error, target) {
+    const name = error instanceof Error && error.name ? error.name : "Error";
+    const timedOut = name === "TimeoutError" || name === "AbortError" || name === "DiagnosticTimeout";
+    return diagnosed(timedOut ? `The ${target} request ended before a response (${name}).` : `The ${target} request did not complete (${name}).`, "api", {
+        diagnostic: timedOut ? "request_timeout" : "network_failed",
+        cause: timedOut
+            ? "No HTTP status was received. This timeout is the client stopping, not a report that remote work failed."
+            : `No HTTP response was received (${name}). This was not an API refusal.`,
+        observed: { error_name: name, target },
+        recovery: target === "inference gateway"
+            ? ["Retry the command. A rejected API key returns HTTP 401 or 403, which this failure did not."]
+            : ["b3iq doctor", "Retry the command. Check B3IQ_API_URL only if you set one."],
+        limitation: "The transport error text is omitted so a URL or credential inside it is not printed.",
+    }, 2);
+}
+function safeDetail(detail) {
+    if (!detail)
+        return undefined;
+    const trimmed = detail.replace(/\s+/g, " ").trim();
+    if (!trimmed || trimmed.length > 300)
+        return undefined;
+    return trimmed;
+}
+export function explainAuthFailure(detail, status, requestId, orgId, savedExpiresAt) {
+    const text = safeDetail(detail);
+    const personalScope = Boolean(text && /personal-scope/i.test(text));
+    const shownOrgId = orgId && /^[A-Za-z0-9_-]{1,80}$/.test(orgId) ? orgId : orgId ? "set" : null;
+    if (personalScope) {
+        return diagnosed("The control plane refused organization scope for this personal key (HTTP 403).", "auth", {
+            diagnostic: "org_scope_unsupported",
+            cause: "The response said a personal key is personal-scope. B3IQ_ORG_ID or org_id in the CLI config was sent as x-org-id.",
+            observed: observed({ http_status: status, org_id_set: Boolean(orgId), org_id: shownOrgId }),
+            recovery: [
+                `Unset B3IQ_ORG_ID and remove org_id from ${configPath()} if it is set, then retry the personal-account command.`,
+                "b3iq whoami",
+                "b3iq machines list",
+                "For an organization's machines: b3iq login, and choose the organization in the browser",
+            ],
+            limitation: "A personal key cannot take organization scope, and setting an organization id on it will not list organization machines. An organization's machines need a token bound to that organization: run `b3iq login` and choose it on the approval page.",
+        }, 3, requestId);
+    }
+    if (text && /bound to a different organization/i.test(text)) {
+        return diagnosed("This CLI's API key is bound to another organization (HTTP 403).", "auth", {
+            diagnostic: "org_token_mismatch",
+            cause: "The login was approved for one organization and its API key reaches only that one. B3IQ_ORG_ID or org_id in the CLI config named a different one.",
+            observed: observed({ http_status: status, org_id_set: Boolean(orgId), org_id: shownOrgId }),
+            recovery: ["Unset B3IQ_ORG_ID, then retry.", "b3iq whoami", "b3iq login, and choose the other organization in the browser"],
+            limitation: "One login reaches one organization. Sign in again and choose the other one.",
+        }, 3, requestId);
+    }
+    if (status === 401 && text && /CLI tokens were retired/i.test(text)) {
+        return diagnosed("This CLI token was retired. Run `b3iq login` to sign in again.", "auth", {
+            diagnostic: "token_retired",
+            cause: "HTTP 401. CLI tokens (b3iq_pat_) were retired; a login now saves an API key.",
+            observed: { http_status: 401 },
+            recovery: ["b3iq login", "Set B3IQ_TOKEN to a Machines & SSH API key from the dashboard (Keys, API keys)."],
+            limitation: "No CLI token can be renewed. The new login replaces the saved token.",
+        }, 3, requestId);
+    }
+    if (status === 401 && savedExpiresAt && Date.parse(savedExpiresAt) <= Date.now()) {
+        return diagnosed(`This login expired on ${savedExpiresAt.slice(0, 10)}. Run \`b3iq login\` to sign in again.`, "auth", {
+            diagnostic: "login_expired",
+            cause: `HTTP 401. The saved login's API key expired at ${savedExpiresAt}.`,
+            observed: { http_status: 401, expired: true },
+            recovery: ["b3iq login"],
+            limitation: "A login's key lasts 90 days. Logging in again saves a new one.",
+        }, 3, requestId);
+    }
+    if (status === 401) {
+        return diagnosed("The control plane rejected this credential (HTTP 401).", "auth", {
+            diagnostic: "auth_rejected",
+            cause: text
+                ? `HTTP 401. The control plane detail was: ${text}`
+                : "HTTP 401. The token was not accepted. No response body is included.",
+            observed: { http_status: 401, detail_included: Boolean(text) },
+            recovery: orgId
+                ? ["b3iq login, and choose the organization again in the browser"]
+                : ["b3iq login", "Set B3IQ_TOKEN to a Machines & SSH API key from the dashboard (Keys, API keys)."],
+            limitation: orgId
+                ? "An organization login's API key stops working when it expires (90 days), is revoked, or its creator leaves the organization. An inference-only API key does not authenticate machine-management commands. The response body is not printed."
+                : "A login's API key stops working when it expires (90 days) or is revoked. An inference-only API key does not authenticate machine-management commands. The response body is not printed.",
+        }, 3, requestId);
+    }
+    return diagnosed(`The control plane refused this request (HTTP ${status}).`, "auth", {
+        diagnostic: "auth_forbidden",
+        cause: text
+            ? `HTTP ${status}. The control plane detail was: ${text}`
+            : `HTTP ${status}. No response body is included. This was an authorization refusal, not a usage error.`,
+        observed: observed({ http_status: status, org_id_set: Boolean(orgId), detail_included: Boolean(text) }),
+        recovery: ["b3iq whoami"],
+        limitation: orgId
+            ? "An organization id is set, but this 403 did not include the personal-scope refusal, so it is not classified as that. Do not retry with a different organization id as a guess."
+            : "Do not retry with B3IQ_ORG_ID as a guess. A personal key cannot take organization scope; run `b3iq login` and choose the organization in the browser.",
+    }, 3, requestId);
+}
+export function explainApiStatus(detail, status, requestId) {
+    const text = safeDetail(detail);
+    if (status === 429) {
+        return diagnosed("The control plane rate-limited this request (HTTP 429).", "ratelimited", {
+            diagnostic: "rate_limited",
+            cause: "HTTP 429 after the one automatic retry. No further retry was made.",
+            observed: { http_status: 429 },
+            recovery: ["Wait, then retry the same command once."],
+            limitation: "A 429 does not say the machine, model, or token is wrong.",
+        }, 4, requestId);
+    }
+    return diagnosed(text ? `The control plane returned HTTP ${status}: ${text}` : `The control plane returned HTTP ${status}.`, "api", {
+        diagnostic: "api_rejected",
+        cause: text
+            ? `HTTP ${status}. The control plane detail was: ${text}`
+            : `HTTP ${status}. The body was not JSON with a detail field, so it is not included.`,
+        observed: { http_status: status, detail_included: Boolean(text) },
+        recovery: ["Retry the command. If it keeps failing, include request_id when you contact support."],
+        limitation: "The raw response body is not printed.",
+    }, 2, requestId);
+}
+export function explainGatewayStatus(status, machine, requestId) {
+    const auth = status === 401 || status === 403;
+    const limited = status === 429;
+    if (auth) {
+        return diagnosed(`B3IQ inference returned HTTP ${status}.`, auth ? "auth" : "api", {
+            diagnostic: "gateway_auth_rejected",
+            cause: "The gateway rejected the credential. The response body is not included.",
+            observed: observed({ http_status: status, machine: machine ?? null }),
+            recovery: [
+                "Set B3IQ_GATEWAY_API_KEY, or save a dashboard key with b3iq inference key-save (stdin).",
+                "The management token (B3IQ_TOKEN or a `b3iq login`) does not authenticate inference.",
+            ],
+        }, undefined, requestId);
+    }
+    if (limited) {
+        return diagnosed("B3IQ inference returned HTTP 429.", "ratelimited", {
+            diagnostic: "gateway_rate_limited",
+            cause: "The gateway rate-limited this request. This gateway call was not retried.",
+            observed: observed({ http_status: 429, machine: machine ?? null }),
+            recovery: ["Wait and retry the same command. A 429 does not say the model or machine is wrong."],
+        }, undefined, requestId);
+    }
+    if (status === 404 && machine) {
+        return diagnosed("B3IQ inference returned HTTP 404 for the selected machine.", "api", {
+            diagnostic: "gateway_machine_not_found",
+            cause: `The gateway returned HTTP 404 for node_id ${JSON.stringify(machine)}. This status does not establish whether the machine exists or whether the key's scope excludes it.`,
+            observed: { http_status: 404, machine },
+            recovery: ["b3iq inference models", "b3iq machines list"],
+            limitation: "b3iq machines list uses the management token, not the inference API key. A machine can answer inference and still be absent from that list.",
+        }, undefined, requestId);
+    }
+    return diagnosed(`B3IQ inference returned HTTP ${status}.`, "api", {
+        diagnostic: "gateway_http_error",
+        cause: "The gateway returned a non-success status. The response body is not included.",
+        observed: observed({ http_status: status, machine: machine ?? null }),
+        recovery: ["b3iq inference models"],
+        limitation: "This status is not a measured serving-window or tool-calling result.",
+    }, undefined, requestId);
+}
+export function explainMachineNotVisible(input) {
+    const shown = JSON.stringify(input.selector);
+    const checkedRentals = input.rentalsListed !== undefined;
+    const accountBit = input.account.lookup === "ok" && input.account.account
+        ? ` Settings returned account ${input.account.account}.`
+        : input.account.lookup === "failed"
+            ? " The account lookup failed, so this message does not name the account."
+            : " No management token was configured, so no account was read.";
+    const org = input.orgContext ?? null;
+    const listName = org ? `The machine list for organization ${org}` : "The personal machine list";
+    const listBit = checkedRentals
+        ? `${listName} returned ${input.machinesListed} machines and rented guests returned ${input.rentalsListed}. None matched ${shown}.`
+        : `${listName} returned ${input.machinesListed} machines and none matched ${shown}. This command does not search rented guests.`;
+    return diagnosed(`No machine visible to this CLI account matches ${shown}.`, "usage", {
+        diagnostic: "machine_not_visible",
+        cause: `${listBit}${accountBit} That result does not establish whether the machine exists.`,
+        observed: observed({
+            selector: input.selector,
+            machines_listed: input.machinesListed,
+            rentals_listed: input.rentalsListed,
+            account_lookup: input.account.lookup,
+            account: input.account.account,
+            org_id_set: input.orgIdSet,
+            org_context: org,
+        }),
+        recovery: ["b3iq whoami", "b3iq machines list"],
+        limitation: org ? [
+            "This CLI's API key is bound to one organization and lists only that organization's machines.",
+            "A machine owned by you personally or by another organization is not in it: run `b3iq login` and choose your personal account or that organization in the browser.",
+            "A missing match does not establish whether the machine exists.",
+        ].join(" ") : [
+            "If another account manages the machine, ask B3IQ support (hello@b3iq.org) to grant this account owner access.",
+            "A missing match does not prove an owner grant is what is missing: the selector may be wrong, or the machine may belong to another account.",
+            "Organization ownership alone does not make a machine visible to a personal key. For an organization's machines, run `b3iq login` and choose the organization in the browser.",
+            input.orgIdSet
+                ? `B3IQ_ORG_ID or org_id in ${configPath()} is set. Unset it. A personal key cannot use that selector, and unsetting it does not grant the machine.`
+                : "Do not set B3IQ_ORG_ID. The control plane refuses that header on a personal key, and it is not a way to see organization machines.",
+        ].join(" "),
+    }, 1);
+}
+export function explainAmbiguousMachine(selector, matches) {
+    const labels = matches.map((match) => `${match.label} (${match.node_id})`).join(", ");
+    const recovery = matches.length <= 5
+        ? ["Pass one full node id.", ...matches.map((match) => b3iqLine(["b3iq machines get", { arg: match.node_id }]))]
+        : ["b3iq machines list", "Pass one full node id."];
+    return diagnosed(`${JSON.stringify(selector)} matches ${matches.length} machines in this account.`, "usage", {
+        diagnostic: "machine_ambiguous",
+        cause: `The personal machine list matched ${matches.length} machines: ${labels}.`,
+        observed: { selector, match_count: matches.length },
+        recovery,
+        limitation: "No single machine was selected, so no command was sent.",
+    }, 1);
+}
+export function explainMissingMachineSelector() {
+    return diagnosed("No machine given and no default set.", "usage", {
+        diagnostic: "machine_selector_missing",
+        cause: `The command had no machine argument and ${configPath()} has no default_machine.`,
+        observed: { selector_present: false, default_machine_present: false },
+        recovery: ["b3iq machines list", "b3iq config default-machine <id>"],
+    }, 1);
+}
+function nativeFacts(model, client) {
+    const profile = model.b3iq;
+    const raw = profile?.context_window_tokens;
+    let contextKind = "absent";
+    if (profile && Object.prototype.hasOwnProperty.call(profile, "context_window_tokens")) {
+        if (raw === null)
+            contextKind = "null";
+        else if (typeof raw === "number" && Number.isSafeInteger(raw))
+            contextKind = "integer";
+        else
+            contextKind = "not_integer";
+    }
+    return {
+        modality: typeof profile?.modality === "string" ? profile.modality : null,
+        modalityReported: typeof profile?.modality === "string",
+        context: contextKind === "integer" && typeof raw === "number" ? raw : null,
+        contextKind,
+        toolCalling: profile?.capabilities?.includes("tool_calling") === true,
+        capabilitiesReported: Array.isArray(profile?.capabilities),
+        inputModalities: Array.isArray(profile?.input_modalities) ? profile.input_modalities.join(",") : null,
+        required: CONTEXT_MINIMUM[client],
+    };
+}
+function baseObserved(model, client, machine, desktop, facts) {
+    return observed({
+        model_id: model.id,
+        client,
+        machine: machine ?? null,
+        desktop: desktop ?? null,
+        modality: facts.modality,
+        modality_reported: facts.modalityReported,
+        context_window_tokens: facts.context,
+        context_kind: facts.contextKind,
+        required_context_window_tokens: facts.required,
+        tool_calling: facts.toolCalling,
+        capabilities_reported: facts.capabilitiesReported,
+        input_modalities: facts.inputModalities,
+    });
+}
+function toolNote(facts) {
+    if (!facts.capabilitiesReported)
+        return "capabilities was absent, so tool_calling was not advertised.";
+    return facts.toolCalling ? "capabilities included tool_calling." : "capabilities was present and did not include tool_calling.";
+}
+function imageNote(facts) {
+    if (!facts.inputModalities?.split(",").includes("image"))
+        return "";
+    return " input_modalities included image. That field is not the modality check.";
+}
+export function assessNativeContext(model, options = {}) {
+    const client = options.client ?? "codex";
+    const facts = nativeFacts(model, client);
+    const fields = baseObserved(model, client, options.machine, options.desktop, facts);
+    const shown = JSON.stringify(model.id);
+    if (!facts.modalityReported) {
+        return { ok: false, error: diagnosed(`Native setup refused ${shown} for ${client}: modality was absent from gateway discovery.`, "usage", {
+                diagnostic: "modality_metadata_missing",
+                cause: `The served profile had no modality. The ${facts.required}-token window check and the tool_calling check were not applied.${imageNote(facts)}`,
+                observed: fields,
+                recovery: [inferenceModels(options.machine)],
+                limitation: "Native setup does not fill modality from the model name. This is missing metadata, not a measured window.",
+            }, 1) };
+    }
+    if (facts.modality !== "text") {
+        return { ok: false, error: diagnosed(`Native setup refused ${shown} for ${client}: modality was ${JSON.stringify(facts.modality)}, not text.`, "usage", {
+                diagnostic: "modality_unsupported",
+                cause: `Gateway discovery reported modality ${JSON.stringify(facts.modality)}. Native setup accepts text only.${imageNote(facts)} ${toolNote(facts)}`,
+                observed: fields,
+                recovery: [inferenceModels(options.machine)],
+                limitation: "b3iq models context does not change modality. This refusal is the modality check, not a serving-window check.",
+            }, 1) };
+    }
+    if (facts.contextKind !== "integer") {
+        const why = facts.contextKind === "absent"
+            ? "context_window_tokens was absent"
+            : facts.contextKind === "null"
+                ? "context_window_tokens was null"
+                : "context_window_tokens was not a safe integer";
+        return { ok: false, error: diagnosed(`Native setup refused ${shown} for ${client}: ${why}. This is missing metadata, not a window under ${facts.required}.`, "usage", {
+                diagnostic: "context_metadata_missing",
+                cause: `Gateway discovery reported modality text. ${why}. ${toolNote(facts)}${imageNote(facts)} The ${facts.required}-token minimum was not applied because there is no integer window to compare.`,
+                observed: fields,
+                recovery: [inferenceModels(options.machine)],
+                limitation: "Native setup does not substitute a model-card maximum. Discovery can lag a context command that already finished; this reading is only the current gateway report, and it is not labeled stale.",
+            }, 1) };
+    }
+    if (facts.context !== null && facts.context < facts.required) {
+        const also = facts.toolCalling ? "" : ` ${toolNote(facts)}`;
+        return { ok: false, error: diagnosed(`Native setup refused ${shown} for ${client}: the verified profile window is ${facts.context} tokens, below the ${facts.required} tokens ${client} requires.`, "usage", {
+                diagnostic: "context_window_insufficient",
+                cause: `Gateway discovery reported modality text, context_window_tokens ${facts.context}, and ${facts.toolCalling ? "tool_calling" : "no tool_calling"}. ${client} requires at least ${facts.required}.${imageNote(facts)}${also} Native setup does not change the serving window.`,
+                observed: fields,
+                recovery: [inferenceModels(options.machine)],
+                limitation: "The reported integer is below the minimum. It is not missing metadata and it is not labeled stale. Discovery can still lag a context command that already finished; compare b3iq inference models before treating this number as the saved window.",
+            }, 1) };
+    }
+    if (!facts.toolCalling) {
+        return { ok: false, error: diagnosed(`Native setup refused ${shown} for ${client}: the live profile did not advertise tool_calling.`, "usage", {
+                diagnostic: "tool_calling_missing",
+                cause: `Gateway discovery reported modality text and context_window_tokens ${facts.context}, which meets ${facts.required}. ${toolNote(facts)}${imageNote(facts)} A text window alone does not establish coding-tool support.`,
+                observed: fields,
+                recovery: [inferenceModels(options.machine)],
+                limitation: "b3iq models context changes the serving window. It does not add tool_calling. Native setup does not install another model.",
+            }, 1) };
+    }
+    return { ok: true, context: facts.context };
+}
+function inferenceModels(machine) {
+    return machine ? b3iqLine(["b3iq inference models --machine", { arg: machine }]) : "b3iq inference models";
+}
+function setupLine(client, model, machine, desktop) {
+    const parts = ["b3iq inference setup", client];
+    if (desktop)
+        parts.push("--desktop");
+    parts.push("--model", { arg: model });
+    if (machine)
+        parts.push("--machine", { arg: machine });
+    return b3iqLine(parts);
+}
+function contextCommand(model, machine) {
+    return b3iqLine(["b3iq models context", { arg: model }, "--machine", { arg: machine }]);
+}
+export function withManagementGuidance(error, model, options, management) {
+    const diagnostic = error.diagnosis?.diagnostic;
+    if (diagnostic !== "context_window_insufficient" && diagnostic !== "context_metadata_missing")
+        return error;
+    const client = options.client ?? "codex";
+    const machine = options.machine;
+    const account = management.account_lookup === "ok" && management.account ? ` Settings returned account ${management.account}.` : "";
+    const later = `After the window is in discovery, rerun ${setupLine(client, model.id, machine, options.desktop)}. This check did not record --install or --activate; add those only if that was the command you ran.`;
+    let recovery;
+    let limitation;
+    if (!management.checked && management.reason === "no_management_token") {
+        recovery = ["b3iq login", "b3iq whoami", "b3iq machines list"];
+        limitation = `No management token was configured, so machine visibility was not listed.${account} b3iq models context needs that token and a machine this account can manage. The API key used for setup cannot run it. Do not set B3IQ_ORG_ID on a personal token. ${later}`;
+    }
+    else if (!management.checked && management.reason === "org_scope_unsupported") {
+        recovery = [`Unset B3IQ_ORG_ID and org_id in ${configPath()}, then retry.`, "b3iq whoami", "b3iq machines list"];
+        limitation = `The management lookup was refused because a personal key cannot take an organization id.${account} Unsetting it restores personal scope. It does not grant organization machines; run \`b3iq login\` and choose the organization in the browser. ${later}`;
+    }
+    else if (!management.checked) {
+        recovery = ["b3iq whoami", "b3iq machines list"];
+        limitation = `The management lookup did not complete, so this message does not say whether the machine is visible and does not recommend b3iq models context yet. The gateway result above is unchanged.${account}`;
+    }
+    else if (!machine) {
+        recovery = ["b3iq machines list", "b3iq inference models"];
+        limitation = `No --machine was passed, so a specific machine was not looked up.${account} b3iq models context needs a machine from that list. Native setup will not run it. ${later}`;
+    }
+    else if (management.machine_ambiguous) {
+        recovery = ["b3iq machines list"];
+        limitation = `The selector matched more than one machine in this account (${management.machines_listed ?? "unknown"} listed).${account} Pass a full node id before b3iq models context. No context command was sent.`;
+    }
+    else if (management.machine_visible) {
+        recovery = [contextCommand(model.id, machine), inferenceModels(machine)];
+        limitation = `The personal machine list included exactly one match. The context command below is how to set the window. Native setup does not run it. It uses the management token, not the API key. Gateway discovery can lag after that command completes; rerun inference models before setup. ${later}`;
+    }
+    else {
+        recovery = ["b3iq whoami", "b3iq machines list"];
+        limitation = [
+            `The personal machine list (${management.machines_listed ?? 0} machines) did not include ${JSON.stringify(machine)}, so this message does not recommend b3iq models context as the next command.${account}`,
+            "That does not establish whether the machine exists.",
+            "If another account manages it, ask B3IQ support (hello@b3iq.org) to grant this account owner access.",
+            "A missing match does not prove an owner grant is what is missing.",
+            "Organization ownership alone is not enough for a personal token. Do not set B3IQ_ORG_ID: run `b3iq login` and choose the organization in the browser.",
+            later,
+        ].join(" ");
+    }
+    const prior = error.diagnosis;
+    return new CliError(error.message, error.code, error.exitCode, error.requestId, {
+        diagnostic: prior?.diagnostic ?? "context_window_insufficient",
+        cause: prior?.cause ?? error.message,
+        observed: observed({
+            ...prior?.observed,
+            management_checked: management.checked,
+            management_reason: management.reason ?? (management.checked ? "listed" : null),
+            org_id_set: management.org_id_set,
+            account_lookup: management.account_lookup,
+            account: management.account,
+            machines_listed: management.machines_listed,
+            machine_visible: management.machine_visible,
+            machine_ambiguous: management.machine_ambiguous,
+        }),
+        recovery,
+        limitation,
+    });
+}
+export function requireContext(model, options = {}) {
+    const result = assessNativeContext(model, options);
+    if (!result.ok) {
+        if (options.management && (result.error.diagnosis?.diagnostic === "context_window_insufficient" || result.error.diagnosis?.diagnostic === "context_metadata_missing")) {
+            throw withManagementGuidance(result.error, model, options, options.management);
+        }
+        throw result.error;
+    }
+    return result.context;
+}
+export function explainModelNotServed(modelId, discovered, machine) {
+    return diagnosed(`That exact model ID is not in this gateway discovery response (${discovered} model(s) returned).`, "usage", {
+        diagnostic: "model_not_served",
+        cause: `${JSON.stringify(modelId)} was not among the ${discovered} id(s) returned for this API key${machine ? ` with node_id ${JSON.stringify(machine)}` : ""}. This does not establish whether the model is installed on a machine.`,
+        observed: observed({ model_id: modelId, models_returned: discovered, machine: machine ?? null }),
+        recovery: [inferenceModels(machine)],
+        limitation: "Discovery uses the API key. b3iq models list uses the management token and only sees machines that account can manage. This check did not call that list.",
+    }, 1);
+}
+export function explainProfileRefusal(input) {
+    const offline = input.liveness === "offline";
+    const offlineBit = offline ? ` The machine list reported liveness offline for ${input.nodeId}.` : "";
+    if (input.matches.length === 0) {
+        return diagnosed(`No model matches ${JSON.stringify(input.selector)} on ${input.nodeId}.`, "usage", {
+            diagnostic: offline && input.catalogSize === 0 ? "model_catalog_offline" : "model_not_on_machine",
+            cause: input.catalogSize === 0
+                ? `The machine catalog returned no profiles.${offlineBit} This does not establish that the model id is wrong.`
+                : `The catalog had ${input.catalogSize} profile(s) and none matched ${JSON.stringify(input.selector)}.${offlineBit}`,
+            observed: observed({
+                selector: input.selector,
+                catalog_size: input.catalogSize,
+                node_id: input.nodeId,
+                liveness: input.liveness ?? null,
+            }),
+            recovery: [b3iqLine(["b3iq models list --machine", { arg: input.nodeId }]), b3iqLine(["b3iq machines get", { arg: input.nodeId }])],
+            limitation: offline
+                ? "No install, removal, or context command was sent. An offline catalog is not a failed install. Do not submit a duplicate until machines get shows the machine online and models list shows the profile."
+                : "No command was sent. The catalog match is the only check this error used.",
+        }, 1);
+    }
+    const eligible = input.matches.filter((profile) => profile.status === input.wantStatus);
+    if (eligible.length > 1) {
+        return diagnosed(`${JSON.stringify(input.selector)} matches ${eligible.length} ${input.wantStatus} profiles.`, "usage", {
+            diagnostic: "model_ambiguous",
+            cause: `Eligible profile ids: ${eligible.map((profile) => profile.id ?? profile.model ?? "unknown").join(", ")}.`,
+            observed: { selector: input.selector, match_count: eligible.length, node_id: input.nodeId },
+            recovery: ["Pass the full profile id."],
+            limitation: "No command was sent.",
+        }, 1);
+    }
+    const statuses = [...new Set(input.matches.map((profile) => profile.status ?? "unknown"))];
+    const status = statuses[0] ?? "unknown";
+    const recovery = profileRecovery(status, input.wantStatus, input.selector, input.nodeId);
+    return diagnosed(`${JSON.stringify(input.selector)} is ${statuses.join(", ")} on ${input.nodeId}, so it cannot ${input.verb}.`, "usage", {
+        diagnostic: profileDiagnostic(status, input.wantStatus),
+        cause: `The catalog status was ${statuses.join(", ")}. This command accepts ${input.wantStatus}.${offlineBit}`,
+        observed: observed({
+            selector: input.selector,
+            status: statuses.join(","),
+            want_status: input.wantStatus,
+            node_id: input.nodeId,
+            liveness: input.liveness ?? null,
+            match_count: input.matches.length,
+        }),
+        recovery,
+        limitation: offline
+            ? "No command was sent. The machine was reported offline as well as the catalog status above."
+            : statusLimitation(status, input.wantStatus),
+    }, 1);
+}
+function profileDiagnostic(status, want) {
+    if (status === "runtime_missing")
+        return "runtime_missing";
+    if (status === "hardware_unsupported")
+        return "hardware_unsupported";
+    if (status === "modality_unsupported")
+        return "modality_unsupported";
+    if (want === "installed" && status === "ready_to_install")
+        return "model_not_installed";
+    if (want === "ready_to_install" && status === "installed")
+        return "model_already_installed";
+    return "model_not_ready";
+}
+function profileRecovery(status, want, selector, nodeId) {
+    const list = b3iqLine(["b3iq models list --machine", { arg: nodeId }]);
+    if (want === "installed" && status === "ready_to_install") {
+        return [b3iqLine(["b3iq models install", { arg: selector }, "--machine", { arg: nodeId }]), list];
+    }
+    if (status === "runtime_missing")
+        return [b3iqLine(["b3iq runtimes list --machine", { arg: nodeId }]), list];
+    if (status === "installed")
+        return [list, "The profile is already installed, so install is the wrong command."];
+    return [list, b3iqLine(["b3iq machines get", { arg: nodeId }])];
+}
+function statusLimitation(status, want) {
+    if (status === "hardware_unsupported")
+        return "No command in this CLI changes the machine's hardware. The catalog status is hardware_unsupported.";
+    if (status === "modality_unsupported")
+        return "The catalog status is modality_unsupported. This CLI did not choose a different model.";
+    if (status === "runtime_missing")
+        return "The catalog status is runtime_missing. This CLI did not install a runtime as a side effect.";
+    if (want === "installed" && status !== "installed")
+        return "Context and removal accept an installed profile only. Nothing was queued.";
+    return "Nothing was queued. The catalog status is the only readiness fact this error used.";
+}
+export function explainRuntimeMissing(selector, nodeId, label) {
+    return diagnosed(`No runtime ${JSON.stringify(selector)} on ${label}.`, "usage", {
+        diagnostic: "runtime_not_on_machine",
+        cause: `The machine's runtime list had no id or kind equal to ${JSON.stringify(selector)}.`,
+        observed: { selector, node_id: nodeId },
+        recovery: [b3iqLine(["b3iq runtimes list --machine", { arg: nodeId }])],
+        limitation: "No restart was sent.",
+    }, 1);
+}
+export function explainCommandTimeout(input) {
+    const waited = input.timeoutMs >= 60_000 ? `${Math.round(input.timeoutMs / 60_000)} min` : `${Math.round(input.timeoutMs / 1000)} s`;
+    const saw = input.lastStatus !== undefined;
+    const lookup = b3iqLine(["b3iq commands get", { arg: input.commandId }, "--machine", { arg: input.nodeId }]);
+    return diagnosed(saw
+        ? `${input.describe} was still ${input.lastStatus} when this CLI stopped waiting (${waited}).`
+        : `${input.describe} produced no command status before this CLI stopped waiting (${waited}).`, "api", {
+        diagnostic: "command_timeout",
+        command_id: input.commandId,
+        cause: saw
+            ? `The last observed status was ${JSON.stringify(input.lastStatus)}. It was not completed, failed, or cancelled.`
+            : "No row for this command id was observed before the deadline. The wait ending is not a report that the work failed.",
+        observed: {
+            command_id: input.commandId,
+            node_id: input.nodeId,
+            last_status: input.lastStatus ?? null,
+            timeout_ms: input.timeoutMs,
+            status_observed: saw,
+        },
+        recovery: [lookup],
+        limitation: "The work may still be queued or running. Do not submit the same install, upgrade, or context change again until that status is completed, failed, or cancelled.",
+    }, 2);
+}
+export function explainCommandEnded(describe, status, serverError, commandId, nodeId) {
+    const detail = serverError?.trim() ? serverError.trim().replace(/\s+/g, " ").slice(0, 300) : "";
+    const lookup = b3iqLine(["b3iq commands get", { arg: commandId }, "--machine", { arg: nodeId }]);
+    const headline = status === "cancelled"
+        ? `${describe} was cancelled${detail ? `: ${detail}` : ""}`
+        : `${describe} failed${detail ? `: ${detail}` : ""}`;
+    return diagnosed(headline, "api", {
+        diagnostic: status === "failed" ? "command_failed" : "command_cancelled",
+        command_id: commandId,
+        cause: detail
+            ? `The command status was ${status}. The control plane included this error text: ${detail}`
+            : `The command status was ${status}. No error text was included.`,
+        observed: { command_id: commandId, node_id: nodeId, status },
+        recovery: [lookup],
+        limitation: status === "failed"
+            ? "Failed means this command did not complete. Do not start a duplicate until you have read that status. This CLI did not add a cause beyond the status and error text it received."
+            : "Cancelled means the command was cancelled. Read it before submitting another.",
+    }, 2);
+}
+export function explainSshLane(nodeId, enabled, hostnamePresent) {
+    return diagnosed(`SSH is not enabled for ${nodeId}.`, "usage", {
+        diagnostic: "ssh_lane_disabled",
+        cause: `Machine detail reported ssh_lane.enabled=${enabled} and hostname ${hostnamePresent ? "present" : "absent"}.`,
+        observed: { node_id: nodeId, ssh_lane_enabled: enabled, ssh_hostname_present: hostnamePresent },
+        recovery: ["Enable the SSH lane on the machine's dashboard page, then retry b3iq ssh."],
+        limitation: "This CLI does not enable the lane. The hostname value is not printed.",
+    }, 1);
+}
+export function explainDirectSshNotEnabled(feature) {
+    return diagnosed("Direct SSH is not turned on for this account.", "usage", {
+        diagnostic: "ssh_direct_not_enabled",
+        cause: `--direct was given and /v1/public/features did not include ${feature}. It answers a b3iq login's API key as signed out, so a per-account grant does not reach the CLI yet.`,
+        observed: { feature, feature_on: false },
+        recovery: ["b3iq ssh <machine>", "b3iq ssh <machine> --tunnel"],
+        limitation: "No ssh process was started.",
+    }, 1);
+}
+export function explainNoDirectAddress(nodeId, guest, addressesTried = 0) {
+    const message = guest
+        ? "A rented guest is only reachable over its host's Cloudflare Tunnel."
+        : addressesTried > 0
+            ? `None of the ${addressesTried} direct address${addressesTried === 1 ? "" : "es"} ${nodeId} reported answered with sshd.`
+            : `${nodeId} has not reported an address you can SSH to directly.`;
+    return diagnosed(message, "usage", {
+        diagnostic: guest ? "ssh_direct_not_for_guests" : addressesTried > 0 ? "ssh_direct_unreachable" : "ssh_direct_unavailable",
+        cause: guest
+            ? "--direct was given for a rented guest."
+            : addressesTried > 0
+                ? "--direct was given and no reported address completed a TCP connect with an SSH banner."
+                : "--direct was given and machine detail had no ssh_direct addresses.",
+        observed: { node_id: nodeId, direct_addresses_tried: addressesTried },
+        recovery: [`b3iq ssh ${shellArg(nodeId)}`],
+        limitation: "No ssh process was started. Without --direct, b3iq ssh uses the Cloudflare Tunnel.",
+    }, 1);
+}
+export function explainSshMissing() {
+    return diagnosed("ssh is required to reach this machine, and it was not found on PATH.", "usage", {
+        diagnostic: "ssh_missing",
+        cause: "Starting `ssh` failed with ENOENT.",
+        observed: { ssh_on_path: false },
+        recovery: ["Install an OpenSSH client (it ships with macOS and most Linux distributions)", "b3iq doctor"],
+        limitation: "No ssh process was started.",
+    }, 1);
+}
+export function explainCloudflaredMissing() {
+    return diagnosed("cloudflared is required to reach this machine, and it was not found on PATH.", "usage", {
+        diagnostic: "cloudflared_missing",
+        cause: "`cloudflared --version` did not exit 0.",
+        observed: { cloudflared_on_path: false },
+        recovery: ["brew install cloudflared", "b3iq doctor"],
+        limitation: "No ssh process was started.",
+    }, 1);
+}
+export function contextSavedLines(model, nodeId, label, result) {
+    const record = result && typeof result === "object" ? result : {};
+    const verified = record.verified === true;
+    const tokens = typeof record.context_window_tokens === "number" ? record.context_window_tokens : null;
+    const lines = [
+        verified
+            ? `Context verified and saved for ${model} on ${label}${tokens !== null ? ` (${tokens} tokens)` : ""}.`
+            : `The context command completed for ${model} on ${label}, but the result did not report verified: true. Read the result before setup.`,
+        "Gateway discovery can lag this save.",
+        `Check: ${b3iqLine(["b3iq inference models --machine", { arg: nodeId }])}`,
+        "Native setup does not apply the window. Rerun your setup command after discovery shows the verified window.",
+    ];
+    return lines;
+}