@b3labs/b3iq-cli 0.0.0-stage → 0.0.1

package/dist/lib/inference.js

@@ -0,0 +1,272 @@
+import { fetchMediaDownload } from "./media-download.js";
+import { readFile, mkdir, writeFile, unlink, open, rename } from "node:fs/promises";
+import { constants } from "node:fs";
+import { isAbsolute } from "node:path";
+import { configDir, isLoopbackHost } from "./config.js";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { explainGatewayStatus, explainNetworkFailure } from "./diagnosis.js";
+import { CliError } from "./output.js";
+export const DEFAULT_GATEWAY_URL = "https://b3iq.org/v1/api";
+export const inferenceKeyPath = () => join(configDir(), "gateway-key");
+function validateGatewayKey(key) {
+    if (!key?.trim() || /[\r\n]/.test(key.trim()))
+        throw new CliError("Set B3IQ_GATEWAY_API_KEY or save a dashboard key with b3iq inference key-save (stdin).", "auth");
+    return key.trim();
+}
+export async function savedGatewayKey(path = inferenceKeyPath()) {
+    let key;
+    try {
+        key = await readFile(path, "utf8");
+    }
+    catch {
+        throw new CliError("Save the desktop API key first with b3iq inference key-save (stdin). Desktop setup and its helper use the saved file, not a terminal-only environment key.", "auth");
+    }
+    return validateGatewayKey(key);
+}
+export async function gatewayKey() {
+    return process.env.B3IQ_GATEWAY_API_KEY ? validateGatewayKey(process.env.B3IQ_GATEWAY_API_KEY) : savedGatewayKey();
+}
+export async function saveGatewayKey(input) {
+    const key = input.trim();
+    if (!key || key.length > 4096 || /[\r\n]/.test(key))
+        throw new CliError("Supply one dashboard API key on stdin.", "usage");
+    const path = inferenceKeyPath();
+    await mkdir(configDir(), { recursive: true, mode: 0o700 });
+    const temp = `${path}.${randomUUID()}`;
+    try {
+        await writeFile(temp, key + "\n", { flag: "wx", mode: 0o600 });
+        await rename(temp, path);
+    }
+    finally {
+        await unlink(temp).catch(() => { });
+    }
+}
+export async function clearGatewayKey() { await unlink(inferenceKeyPath()).catch(error => { if (error.code !== "ENOENT")
+    throw error; }); }
+export function gatewayURL(value = DEFAULT_GATEWAY_URL) {
+    const url = new URL(value);
+    if (url.username || url.password || url.search || url.hash || (url.protocol !== "https:" && !(url.protocol === "http:" && isLoopbackHost(url.hostname)))) {
+        throw new CliError("Gateway must be HTTPS (or loopback HTTP), without credentials, query or fragment.", "usage");
+    }
+    url.pathname = url.pathname.replace(/\/+$/, "");
+    return url;
+}
+export function nativeInputModalities(model) {
+    return model.b3iq?.input_modalities?.includes("image") && model.b3iq.capabilities?.includes("vision") ? ["text", "image"] : ["text"];
+}
+export class InferenceGateway {
+    base;
+    options;
+    constructor(options = {}) { this.base = gatewayURL(options.gateway ?? process.env.B3IQ_GATEWAY_URL); this.options = options; }
+    async request(path, body, signal) {
+        const url = new URL(this.base);
+        url.pathname += path;
+        if (this.options.machine)
+            url.searchParams.set("node_id", this.options.machine);
+        if (path === "/models")
+            url.searchParams.set("b3iq_metadata", "true");
+        const key = this.options.key ?? await gatewayKey();
+        let response;
+        try {
+            const fetcher = this.options.fetch ?? fetch;
+            const content = /^\/(?:media\/jobs|videos)\/[^/]+\/content$/.test(path);
+            const init = {
+                method: body === undefined ? "GET" : "POST", redirect: "error",
+                headers: { authorization: `Bearer ${key}`, ...(body === undefined ? {} : { "content-type": "application/json" }) },
+                ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+                signal: content ? signal : AbortSignal.any([...(signal ? [signal] : []), AbortSignal.timeout(120_000)]),
+            };
+            response = await (content ? fetchMediaDownload(fetcher, url, init) : fetcher(url, init));
+        }
+        catch (error) {
+            if (error instanceof CliError)
+                throw error;
+            throw explainNetworkFailure(error, "inference gateway");
+        }
+        if (!response.ok) {
+            await response.body?.cancel();
+            throw explainGatewayStatus(response.status, this.options.machine, response.headers.get("x-request-id") ?? undefined);
+        }
+        return response;
+    }
+    async json(path, body, signal, maxBytes = 1024 * 1024) {
+        const response = await this.request(path, body, signal);
+        const bytes = await boundedBytes(response, maxBytes);
+        try {
+            const value = JSON.parse(bytes.toString("utf8"));
+            if (!value || typeof value !== "object" || Array.isArray(value))
+                throw new Error();
+            return value;
+        }
+        catch {
+            throw new CliError("The inference gateway returned invalid JSON.", "api");
+        }
+    }
+    async models(signal) {
+        const result = await this.json("/models", undefined, signal);
+        if (!Array.isArray(result.data) || result.data.some(value => typeof value?.id !== "string"))
+            throw new CliError("Invalid model discovery response.", "api");
+        return result.data;
+    }
+    async requireModality(model, modality, signal) {
+        const models = await this.models(signal), selected = models.find(row => row.id === model);
+        if (!selected)
+            throw new CliError("That exact model ID is not served by the key's permitted machines. Run b3iq_models before selecting media models.", "usage");
+        if (!selected.b3iq?.modality)
+            throw new CliError("Serving modality metadata is unavailable. Update the gateway before selecting a media model.", "usage");
+        if (selected.b3iq.modality === modality)
+            return selected;
+        const compatible = models.filter(row => row.b3iq?.modality === modality).map(row => row.id);
+        throw new CliError(compatible.length
+            ? `The selected model does not generate ${modality}. Use an exact ${modality} model ID: ${compatible.join(", ")}.`
+            : `No ${modality}-generation model is served by the key's permitted machines. Install and serve a compatible ${modality} model first; do not retry with a text or other media model.`, "usage");
+    }
+    async image(model, prompt, signal, imagePath) {
+        const selected = await this.requireModality(model, "image", signal);
+        if (imagePath !== undefined && !selected.b3iq?.input_modalities?.includes("image"))
+            throw new CliError("That served image model does not advertise reference-image input. Choose an editing model from b3iq_models and update the host/gateway before retrying.", "usage");
+        const image = imagePath === undefined ? undefined : await referenceImage(imagePath);
+        const result = await this.json(image ? "/images/edits" : "/images/generations", { model, prompt, n: 1, response_format: "b64_json", async: true, ...(image ? { image } : {}) }, signal, 48 * 1024 * 1024);
+        if (Array.isArray(result.data))
+            return { status: "completed", ...await this.saveImage(result) };
+        if (typeof result.id !== "string" || !/^med_[a-f0-9-]{36}$/.test(result.id))
+            throw new CliError("The gateway did not return a media job. Update the gateway and inference plugin before retrying.", "api");
+        return result;
+    }
+    async imageStatus(id, signal) {
+        if (!/^med_[a-f0-9-]{36}$/.test(id))
+            throw new CliError("Invalid media job ID.", "usage");
+        const status = await this.json(`/media/jobs/${id}`, undefined, signal);
+        if (status.status !== "completed")
+            return status;
+        const result = await this.json(`/media/jobs/${id}/content`, undefined, signal, 48 * 1024 * 1024);
+        return { ...status, ...await this.saveImage(result) };
+    }
+    async saveImage(result) {
+        const row = Array.isArray(result.data) ? result.data[0] : undefined;
+        const encoded = row?.b64_json;
+        if (typeof encoded !== "string" || !/^[A-Za-z0-9+/]*={0,2}$/.test(encoded))
+            throw new CliError("The image response must contain inline base64 PNG data.", "api");
+        const image = Buffer.from(encoded, "base64");
+        if (!image.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10])))
+            throw new CliError("The image response is not a PNG.", "api");
+        const path = await this.artifactPath("png");
+        await writeFile(path, image, { flag: "wx", mode: 0o600 });
+        return { path, mimeType: "image/png" };
+    }
+    async video(model, prompt, seconds, signal) {
+        await this.requireModality(model, "video", signal);
+        return this.json("/videos", { model, prompt, seconds }, signal);
+    }
+    async videoStatus(id, signal) {
+        if (!/^vid_[a-f0-9-]{36}$/.test(id))
+            throw new CliError("Invalid video job ID.", "usage");
+        const result = await this.json(`/videos/${id}`, undefined, signal);
+        if (result.status !== "completed")
+            return result;
+        const response = await this.request(`/videos/${id}/content`, undefined, signal);
+        if (response.headers.get("content-type")?.split(";", 1)[0].trim().toLowerCase() !== "video/mp4") {
+            await response.body?.cancel();
+            throw new CliError("The video content type is not video/mp4.", "api");
+        }
+        const path = await this.artifactPath("mp4");
+        const handle = await open(path, "wx", 0o600);
+        const reader = response.body?.getReader();
+        if (!reader) {
+            await handle.close();
+            await unlink(path);
+            throw new CliError("Empty video content.", "api");
+        }
+        let size = 0, prefix = Buffer.alloc(0);
+        try {
+            for (;;) {
+                signal?.throwIfAborted();
+                const { value, done } = await reader.read();
+                if (done)
+                    break;
+                size += value.byteLength;
+                if (size > 256 * 1024 * 1024)
+                    throw new CliError("Video exceeds 256 MiB.", "api");
+                if (prefix.length < 12)
+                    prefix = Buffer.concat([prefix, value]).subarray(0, 12);
+                await handle.writeFile(value);
+            }
+            if (prefix.subarray(4, 8).toString("ascii") !== "ftyp")
+                throw new CliError("The video content is not MP4.", "api");
+            return { ...result, path, mimeType: "video/mp4" };
+        }
+        catch (error) {
+            await unlink(path).catch(() => { });
+            throw error;
+        }
+        finally {
+            await reader.cancel().catch(() => { });
+            reader.releaseLock();
+            await handle.close();
+        }
+    }
+    async artifactPath(extension) {
+        const dir = this.options.outputDir ?? join(configDir(), "media");
+        await mkdir(dir, { recursive: true, mode: 0o700 });
+        return join(dir, `${randomUUID()}.${extension}`);
+    }
+}
+async function boundedBytes(response, maximum) {
+    const reader = response.body?.getReader();
+    if (!reader)
+        throw new CliError("Empty inference response.", "api");
+    const chunks = [];
+    let total = 0;
+    try {
+        for (;;) {
+            const { value, done } = await reader.read();
+            if (done)
+                break;
+            total += value.byteLength;
+            if (total > maximum)
+                throw new CliError("Inference response exceeds the supported size.", "api");
+            chunks.push(value);
+        }
+        return Buffer.concat(chunks);
+    }
+    finally {
+        await reader.cancel().catch(() => { });
+        reader.releaseLock();
+    }
+}
+async function referenceImage(path) {
+    if (!isAbsolute(path))
+        throw new CliError("image_path must be the absolute path to the user's PNG, JPEG or WebP attachment.", "usage");
+    let handle;
+    try {
+        handle = await open(path, constants.O_RDONLY | constants.O_NONBLOCK);
+        const stat = await handle.stat();
+        const maxBytes = 5 * 1024 * 1024;
+        if (!stat.isFile() || stat.size <= 0 || stat.size > maxBytes)
+            throw new Error();
+        const buffer = Buffer.alloc(Math.min(stat.size + 1, maxBytes + 1));
+        let length = 0;
+        while (length < buffer.length) {
+            const { bytesRead } = await handle.read(buffer, length, buffer.length - length, null);
+            if (!bytesRead)
+                break;
+            length += bytesRead;
+        }
+        if (length !== stat.size)
+            throw new Error();
+        const bytes = buffer.subarray(0, length);
+        const mime = bytes.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10])) ? "image/png"
+            : bytes.subarray(0, 3).equals(Buffer.from([255, 216, 255])) ? "image/jpeg"
+                : bytes.subarray(0, 4).toString() === "RIFF" && bytes.subarray(8, 12).toString() === "WEBP" ? "image/webp" : null;
+        if (!mime)
+            throw new Error();
+        return `data:${mime};base64,${bytes.toString("base64")}`;
+    }
+    catch {
+        throw new CliError("Cannot read reference image. Supply a readable PNG, JPEG or WebP file of at most 5 MiB; directories, URLs and other formats are unsupported.", "usage");
+    }
+    finally {
+        await handle?.close();
+    }
+}

package/dist/lib/machines.js

@@ -0,0 +1,120 @@
+import { createInterface } from "node:readline";
+import { api, whoAmI } from "./api.js";
+import { resolveSettings } from "./config.js";
+import { explainAmbiguousMachine, explainMachineNotVisible, explainMissingMachineSelector, readAccountBestEffort, shellArg, withDeadline, } from "./diagnosis.js";
+import { CliError, plain, warn } from "./output.js";
+export const machineLabel = (n) => (plain(n.name ?? "").replace(/\s+/g, " ").trim() || `${n.node_id.slice(0, 8)}…`);
+export function matchMachines(nodes, selector) {
+    const sel = selector.trim();
+    const lower = sel.toLowerCase();
+    const isExactIdOrName = (n) => n.node_id === sel || n.name?.toLowerCase() === lower;
+    const isIdPrefixOrLabelSubstring = (n) => n.node_id.startsWith(sel) || machineLabel(n).toLowerCase().includes(lower);
+    const exactMatches = nodes.filter(isExactIdOrName);
+    return exactMatches.length ? exactMatches : nodes.filter(isIdPrefixOrLabelSubstring);
+}
+async function accountForMiss() {
+    return readAccountBestEffort(() => withDeadline(whoAmI(), 4_000));
+}
+export async function resolveMachine(selector) {
+    const sel = (selector ?? resolveSettings().defaultMachine ?? "").trim();
+    if (!sel)
+        throw explainMissingMachineSelector();
+    const { nodes, org_context } = await api.nodes();
+    const matches = matchMachines(nodes, sel);
+    if (matches.length === 0) {
+        throw explainMachineNotVisible({
+            selector: sel,
+            machinesListed: nodes.length,
+            account: await accountForMiss(),
+            orgIdSet: Boolean(resolveSettings().orgId),
+            orgContext: org_context ?? null,
+        });
+    }
+    if (matches.length > 1)
+        throw explainAmbiguousMachine(sel, matches.map((node) => ({ node_id: node.node_id, label: machineLabel(node) })));
+    return matches[0];
+}
+export function noteReportedOffline(node) {
+    if (node.liveness !== "offline")
+        return;
+    warn(`${machineLabel(node)} (${node.node_id}) was reported offline. The command is still being submitted. If this wait ends first, run \`b3iq commands get <id> --machine ${shellArg(node.node_id)}\` before submitting another.`);
+}
+export async function resolveMachineOrRental(selector) {
+    const sel = (selector ?? resolveSettings().defaultMachine ?? "").trim();
+    if (!sel)
+        throw explainMissingMachineSelector();
+    const { nodes, org_context } = await api.nodes();
+    const orgId = org_context ?? null;
+    const owned = matchMachines(nodes, sel);
+    if (owned.length > 1)
+        throw explainAmbiguousMachine(sel, owned.map((node) => ({ node_id: node.node_id, label: machineLabel(node) })));
+    if (owned.length === 1)
+        return { kind: "machine", node: owned[0], orgId };
+    const { guests } = await api.rentedGuests();
+    const rentals = guests.map((rental) => ({ node_id: rental.node_id, name: rental.name, rental }));
+    const matches = matchMachines(rentals, sel);
+    if (matches.length === 0) {
+        throw explainMachineNotVisible({
+            selector: sel,
+            machinesListed: nodes.length,
+            rentalsListed: guests.length,
+            account: await accountForMiss(),
+            orgIdSet: Boolean(resolveSettings().orgId),
+            orgContext: orgId,
+        });
+    }
+    if (matches.length > 1)
+        throw explainAmbiguousMachine(sel, matches.map((node) => ({ node_id: node.node_id, label: machineLabel(node) })));
+    const { rental, ...node } = matches[0];
+    return { kind: "rental", node, rental, orgId };
+}
+export async function pickMachineOrRental(io = { input: process.stdin, output: process.stderr }) {
+    const [{ nodes, org_context }, { guests }] = await Promise.all([api.nodes(), api.rentedGuests()]);
+    const orgId = org_context ?? null;
+    const choices = [
+        ...nodes.map((node) => ({ kind: "machine", node, orgId })),
+        ...guests.map((rental) => ({ kind: "rental", node: { node_id: rental.node_id, name: rental.name }, rental, orgId })),
+    ];
+    if (choices.length === 0) {
+        throw explainMachineNotVisible({
+            selector: "",
+            machinesListed: 0,
+            rentalsListed: 0,
+            account: await accountForMiss(),
+            orgIdSet: Boolean(resolveSettings().orgId),
+            orgContext: orgId,
+        });
+    }
+    if (choices.length === 1)
+        return choices[0];
+    const width = String(choices.length).length;
+    const lines = choices.map((choice, i) => {
+        const note = choice.kind === "rental" ? "your rented guest" : (choice.node.liveness ?? "");
+        return `  ${String(i + 1).padStart(width)}) ${machineLabel(choice.node)}  ${choice.node.node_id.slice(0, 8)}${note ? `  ${note}` : ""}`;
+    });
+    io.output.write(`Which machine?\n${lines.join("\n")}\n`);
+    const rl = createInterface({ input: io.input, terminal: false });
+    const answers = rl[Symbol.asyncIterator]();
+    try {
+        for (;;) {
+            io.output.write(`Number or name [1-${choices.length}]: `);
+            const answer = await answers.next();
+            if (answer.done)
+                throw new CliError("No machine chosen.", "usage", 1);
+            const text = answer.value.trim();
+            if (!text)
+                continue;
+            const index = /^\d+$/.test(text) ? Number(text) - 1 : -1;
+            if (choices[index])
+                return choices[index];
+            const matched = new Set(matchMachines(choices.map((choice) => choice.node), text));
+            const matches = choices.filter((choice) => matched.has(choice.node));
+            if (matches.length === 1)
+                return matches[0];
+            io.output.write(matches.length ? `"${text}" matches ${matches.length} machines. Pick a number.\n` : `No machine matches "${text}".\n`);
+        }
+    }
+    finally {
+        rl.close();
+    }
+}

package/dist/lib/management-probe.js

@@ -0,0 +1,36 @@
+import { api, whoAmI } from "./api.js";
+import { resolveSettings } from "./config.js";
+import { readAccountBestEffort, withDeadline } from "./diagnosis.js";
+import { CliError } from "./output.js";
+import { matchMachines } from "./machines.js";
+export async function probeManagement(machine) {
+    const { token, orgId } = resolveSettings();
+    const org_id_set = Boolean(orgId);
+    if (!token)
+        return { checked: false, reason: "no_management_token", org_id_set, account_lookup: "no_token", account: null };
+    const account = await readAccountBestEffort(() => withDeadline(whoAmI(), 4_000));
+    try {
+        const { nodes } = await withDeadline(api.nodes(), 4_000);
+        const matches = machine ? matchMachines(nodes, machine) : [];
+        return {
+            checked: true,
+            org_id_set,
+            account_lookup: account.lookup,
+            account: account.account,
+            machines_listed: nodes.length,
+            ...(machine
+                ? { machine_visible: matches.length === 1, machine_ambiguous: matches.length > 1 }
+                : {}),
+        };
+    }
+    catch (error) {
+        const org = error instanceof CliError && error.diagnosis?.diagnostic === "org_scope_unsupported";
+        return {
+            checked: false,
+            reason: org ? "org_scope_unsupported" : "lookup_failed",
+            org_id_set,
+            account_lookup: account.lookup,
+            account: account.account,
+        };
+    }
+}

package/dist/lib/media-download.js

@@ -0,0 +1,50 @@
+export async function fetchMediaDownload(fetcher, url, init) {
+    const controller = new AbortController();
+    const abort = () => controller.abort(init.signal?.reason);
+    if (init.signal?.aborted)
+        abort();
+    else
+        init.signal?.addEventListener("abort", abort, { once: true });
+    let timer;
+    const progress = () => {
+        clearTimeout(timer);
+        timer = setTimeout(() => controller.abort(new DOMException("Media download stalled. Check the same job again to download its saved result.", "TimeoutError")), 120_000);
+    };
+    const cleanup = () => { clearTimeout(timer); init.signal?.removeEventListener("abort", abort); };
+    progress();
+    try {
+        const response = await fetcher(url, { ...init, signal: controller.signal });
+        if (!response.body) {
+            cleanup();
+            return response;
+        }
+        progress();
+        const reader = response.body.getReader();
+        return new Response(new ReadableStream({
+            async pull(output) {
+                try {
+                    const { value, done } = await reader.read();
+                    if (done) {
+                        cleanup();
+                        reader.releaseLock();
+                        output.close();
+                        return;
+                    }
+                    if (value.byteLength)
+                        progress();
+                    output.enqueue(value);
+                }
+                catch (error) {
+                    cleanup();
+                    void reader.cancel(error).catch(() => { });
+                    output.error(error);
+                }
+            },
+            cancel(reason) { cleanup(); const cancelled = reader.cancel(reason); controller.abort(reason); return cancelled; },
+        }), { status: response.status, statusText: response.statusText, headers: response.headers });
+    }
+    catch (error) {
+        cleanup();
+        throw error;
+    }
+}

package/dist/lib/output.js

@@ -0,0 +1,151 @@
+import { resolveSettings } from "./config.js";
+let jsonMode = false;
+let quietMode = false;
+export function configureOutput(flags) {
+    quietMode = flags.quiet ?? false;
+    if (flags.json && flags.pretty) {
+        fail(new CliError("--json and --pretty cannot be used together", "usage", 1));
+    }
+    const stdoutIsPipedToAnAgentOrFile = !process.stdout.isTTY;
+    if (flags.json)
+        jsonMode = true;
+    else if (flags.pretty)
+        jsonMode = false;
+    else
+        jsonMode = stdoutIsPipedToAnAgentOrFile;
+}
+export const isJSON = () => jsonMode;
+export const isQuiet = () => quietMode;
+const glyph = { info: "›", ok: "✓", warn: "!", err: "✗" };
+const color = (code, s) => process.stderr.isTTY && !process.env.NO_COLOR ? `\x1b[${code}m${s}\x1b[0m` : s;
+export function plain(text) {
+    return text
+        .replace(/\u001b\[[0-?]*[ -\/]*[@-~]/g, "")
+        .replace(/\u001b\][^\u0007\u001b]*(?:\u0007|\u001b\\)?/g, "")
+        .replace(/[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/g, "");
+}
+const cell = (text) => plain(text ?? "").replace(/[\t\n]/g, " ");
+export const log = (msg) => void process.stderr.write(`${color(2, glyph.info)} ${plain(msg)}\n`);
+export const success = (msg) => void process.stderr.write(`${color(32, glyph.ok)} ${plain(msg)}\n`);
+export const warn = (msg) => void process.stderr.write(`${color(33, glyph.warn)} ${plain(msg)}\n`);
+export const errline = (msg) => void process.stderr.write(`${color(31, glyph.err)} ${plain(msg)}\n`);
+export function emit(data, render) {
+    if (jsonMode) {
+        process.stdout.write(JSON.stringify(data, null, process.stdout.isTTY ? 2 : 0) + "\n");
+        return;
+    }
+    render();
+}
+export function emitIds(ids) {
+    process.stdout.write(ids.filter(Boolean).join("\n") + (ids.length ? "\n" : ""));
+}
+export function kv(rows, width = 12) {
+    for (const [k, v] of rows)
+        process.stdout.write(`  ${k.padEnd(width)} ${cell(v)}\n`);
+}
+export function table(headers, rows) {
+    const clean = rows.map((r) => r.map(cell));
+    const widths = headers.map((h, i) => Math.max(h.length, ...clean.map((r) => (r[i] ?? "").length)));
+    const line = (cells) => cells.map((c, i) => (c ?? "").padEnd(widths[i])).join("  ").trimEnd();
+    process.stdout.write("  " + color(1, line(headers)) + "\n");
+    for (const r of clean)
+        process.stdout.write("  " + line(r) + "\n");
+}
+export const EXIT_CODE = { success: 0, usage: 1, api: 2, auth: 3, ratelimited: 4 };
+export class CliError extends Error {
+    code;
+    exitCode;
+    requestId;
+    diagnosis;
+    constructor(message, code, exitCode, requestId, diagnosis) {
+        super(message);
+        this.code = code;
+        this.exitCode = exitCode ?? EXIT_CODE[code in EXIT_CODE ? code : "api"];
+        this.requestId = requestId;
+        this.diagnosis = diagnosis;
+    }
+}
+const SECRET_PATTERNS = [/Bearer\s+\S+/gi, /b3iq_(?:pat|key)_[A-Za-z0-9._-]+/g, /sk-[A-Za-z0-9._-]{8,}/g];
+export function redact(text) {
+    let out = text;
+    const secrets = new Set();
+    for (const value of [process.env.B3IQ_TOKEN, process.env.B3IQ_GATEWAY_API_KEY]) {
+        if (value && value.length >= 8)
+            secrets.add(value);
+    }
+    try {
+        const token = resolveSettings().token;
+        if (token && token.length >= 8)
+            secrets.add(token);
+    }
+    catch {
+    }
+    for (const secret of secrets)
+        out = out.split(secret).join("[redacted]");
+    for (const pattern of SECRET_PATTERNS) {
+        pattern.lastIndex = 0;
+        out = out.replace(pattern, "[redacted]");
+    }
+    return out;
+}
+function redactObserved(observed) {
+    if (!observed)
+        return undefined;
+    const out = {};
+    for (const [key, value] of Object.entries(observed))
+        out[key] = typeof value === "string" ? redact(value) : value;
+    return out;
+}
+export function formatFailureLines(error) {
+    const lines = [redact(error.message)];
+    const diagnosis = error.diagnosis;
+    if (diagnosis) {
+        lines.push(`Cause: ${redact(diagnosis.cause)}`);
+        if (diagnosis.limitation)
+            lines.push(redact(diagnosis.limitation));
+        if (diagnosis.recovery.length) {
+            lines.push("Next:");
+            for (const step of diagnosis.recovery)
+                lines.push(`  ${redact(step)}`);
+        }
+        if (diagnosis.command_id)
+            lines.push(`command_id: ${redact(diagnosis.command_id)}`);
+    }
+    if (error.requestId)
+        lines.push(`request_id: ${redact(error.requestId)}`);
+    return lines;
+}
+export function failureRecord(error) {
+    const diagnosis = error.diagnosis;
+    const observed = redactObserved(diagnosis?.observed);
+    return {
+        error: redact(error.message),
+        code: error.code,
+        request_id: error.requestId ? redact(error.requestId) : null,
+        ...(diagnosis
+            ? {
+                diagnostic: diagnosis.diagnostic,
+                cause: redact(diagnosis.cause),
+                ...(observed ? { observed } : {}),
+                recovery: diagnosis.recovery.map(redact),
+                ...(diagnosis.limitation ? { limitation: redact(diagnosis.limitation) } : {}),
+                ...(diagnosis.command_id ? { command_id: redact(diagnosis.command_id) } : {}),
+            }
+            : {}),
+    };
+}
+export function fail(err) {
+    const e = err instanceof CliError
+        ? err
+        : new CliError(err instanceof Error ? err.message : String(err), "api");
+    if (jsonMode) {
+        process.stderr.write(JSON.stringify(failureRecord(e)) + "\n");
+    }
+    else {
+        const [first, ...rest] = formatFailureLines(e);
+        errline(first ?? e.message);
+        for (const line of rest)
+            process.stderr.write(`${plain(line)}\n`);
+    }
+    process.exit(e.exitCode);
+}