runbios-mcp 0.2.1-dev.62

package/dist/api-client.js

@@ -0,0 +1,806 @@
+import { randomUUID } from "node:crypto";
+import { redactBuildIdentity, redactBuildIdentityDeep } from "./redaction.js";
+import { VERSION } from "./version.js";
+/* ─── Standard GPU rejection contract ─── */
+/**
+ * The ONE transient GPU rejection code: the GPU is not in stock right now.
+ * Stock changes, so retrying later or joining the capacity queue is a real
+ * answer here (and ONLY here).
+ */
+export const CAPACITY_UNAVAILABLE_CODE = "CAPACITY_UNAVAILABLE";
+/**
+ * Deprecated training-side alias of CAPACITY_UNAVAILABLE, still echoed for one
+ * release. It means the same transient thing.
+ */
+export const LEGACY_CAPACITY_UNAVAILABLE_CODE = "SELECTED_GPU_UNAVAILABLE";
+/**
+ * Permanent GPU rejection codes. Each one is a fixed fact about the request
+ * itself: the model does not fit on that GPU, the GPU count is below what the
+ * model needs, the count cannot be used for this model, or that GPU cannot run
+ * the model at all. Free stock never changes any of them, so waiting and the
+ * capacity queue can never turn one of these into a booking. Callers MUST NOT
+ * offer the queue for these.
+ */
+export const PERMANENT_GPU_CODES = [
+    "GPU_TYPE_TOO_SMALL",
+    "GPU_COUNT_BELOW_MINIMUM",
+    "GPU_COUNT_INVALID",
+    "GPU_TYPE_UNSUPPORTED",
+];
+/**
+ * reason discriminator to machine code, mirroring the server-side table. An
+ * unknown or missing reason resolves to the transient code, which is also what
+ * a plain stock miss carries.
+ */
+const GPU_REJECTION_CODE_BY_REASON = {
+    insufficient_stock: CAPACITY_UNAVAILABLE_CODE,
+    model_too_large: "GPU_TYPE_TOO_SMALL",
+    below_model_minimum: "GPU_COUNT_BELOW_MINIMUM",
+    invalid_gpu_count: "GPU_COUNT_INVALID",
+    gpu_unsupported: "GPU_TYPE_UNSUPPORTED",
+};
+/** Resolve the machine code for a rejection reason. */
+export function gpuRejectionCodeFor(reason) {
+    return GPU_REJECTION_CODE_BY_REASON[reason ?? ""] ?? CAPACITY_UNAVAILABLE_CODE;
+}
+/** True when this code can never be fixed by waiting for stock. */
+export function isPermanentGpuCode(code) {
+    return typeof code === "string" && PERMANENT_GPU_CODES.includes(code);
+}
+/**
+ * HTTP status for a rejection reason: 409 for a stock miss (a retry can resolve
+ * it), 400 for a permanent rejection the request itself has to change.
+ */
+export function gpuRejectionStatusFor(reason) {
+    return isPermanentGpuCode(gpuRejectionCodeFor(reason)) ? 400 : 409;
+}
+/** Every code whose body carries the standard GPU rejection fields. */
+export function isGpuRejectionCode(code) {
+    return code === CAPACITY_UNAVAILABLE_CODE
+        || code === LEGACY_CAPACITY_UNAVAILABLE_CODE
+        || isPermanentGpuCode(code);
+}
+/**
+ * The recovery instruction handed to the calling agent. It branches on whether
+ * the rejection is permanent, because "wait for stock" is actively harmful
+ * advice on a request that can never book: the agent would park a deployment
+ * that no amount of capacity can satisfy.
+ */
+export function gpuRejectionInstruction(opts) {
+    const call = opts.call || "the same call";
+    if (opts.permanent) {
+        const fix = opts.hasAlternatives
+            ? `Retry ${call} with gpu_type and gpu_count set to one of available_gpus, never below that entry's min_gpus.`
+            : `Read minimum_requirement.per_type for the GPU types that fit this model and the GPU count each one needs, then retry ${call} with one of those.`;
+        return `This GPU cannot run the request as submitted, and free capacity will never change that. ${fix} `
+            + "Do not set allow_capacity_queue, and do not send the same gpu_type and gpu_count again: "
+            + "neither waiting nor the queue can make this request fit.";
+    }
+    return opts.hasAlternatives
+        ? `The selected GPU is not bookable for this request. Retry ${call} with gpu_type/gpu_count set to one of available_gpus (never below its min_gpus).`
+        : "No alternative GPUs are in stock right now. Retry shortly, or resubmit with allow_capacity_queue=true to wait for stock (nothing is charged while waiting).";
+}
+/* ─── Error text an agent can act on ─── */
+/**
+ * What a caller should DO about a status when the API sent no usable message.
+ * An MCP client is an AI agent: "Run BiOS API error 400" tells it nothing, so it
+ * either retries blindly or reports a dead end to the user. These sentences say
+ * what class of problem it is and what the next move is — without inventing a
+ * cause the response did not state.
+ */
+function statusGuidance(status) {
+    if (status === 400)
+        return "the API rejected the request as invalid but sent no reason. Re-read the tool's input schema; do not retry the identical payload.";
+    if (status === 401)
+        return "the credential was not accepted. Check the API key/token configured for this MCP server, then call introspect_api_key.";
+    if (status === 403)
+        return "the credential is authenticated but not allowed to do this. Call introspect_api_key to see the scopes and workspace it is bound to.";
+    if (status === 404)
+        return "no such resource in this workspace. List the parent collection to get a valid id instead of guessing one.";
+    if (status === 409)
+        return "the request conflicts with current state. Re-read the resource's status before retrying.";
+    if (status === 413)
+        return "the payload is too large for this endpoint.";
+    if (status === 429)
+        return "rate limited. Wait and retry; do not loop.";
+    if (status >= 500)
+        return "a server-side failure, not a verdict about the request. Retry shortly; if it persists, report it rather than changing the payload.";
+    return "no error message was returned.";
+}
+/**
+ * Pull the human-readable message out of an error body. The platform speaks
+ * several shapes: Go services answer `{error:{code,message}}` or `{message}`,
+ * the Python dataset service answers FastAPI's `{detail: "..."}` (or a
+ * validation array of `{loc,msg}`). Only the first two were read before, so
+ * every dataset-service rejection — list_integrations' missing-workspace 400
+ * among them — degraded to a bare "Run BiOS API error 400".
+ */
+function extractApiMessage(err) {
+    const nested = typeof err.error === "object" && err.error !== null ? err.error : {};
+    if (typeof nested.message === "string" && nested.message.trim())
+        return nested.message.trim();
+    if (typeof err.error === "string" && err.error.trim())
+        return err.error.trim();
+    if (typeof err.message === "string" && err.message.trim())
+        return err.message.trim();
+    const detail = err.detail;
+    if (typeof detail === "string" && detail.trim())
+        return detail.trim();
+    if (Array.isArray(detail)) {
+        const parts = detail
+            .map((entry) => {
+            if (!entry || typeof entry !== "object")
+                return String(entry);
+            const item = entry;
+            const where = Array.isArray(item.loc) ? item.loc.filter((p) => p !== "body").join(".") : "";
+            const msg = typeof item.msg === "string" ? item.msg : typeof item.message === "string" ? item.message : "";
+            return where && msg ? `${where}: ${msg}` : msg || where;
+        })
+            .filter(Boolean);
+        if (parts.length > 0)
+            return parts.join("; ");
+    }
+    if (typeof err.title === "string" && err.title.trim())
+        return err.title.trim();
+    return "";
+}
+const NOT_FOUND_ROUTES = [
+    {
+        test: /^\/api\/inference\/bookings\/([^/]+)/,
+        idFrom: 1,
+        resource: {
+            code: "BOOKING_NOT_FOUND",
+            resource: "booking_handle",
+            // A booking handle is minted by ONE create_inference 202 and expires; it
+            // is not listable, so "list the collection" would be wrong advice here.
+            recovery: "A booking handle exists only for the create_inference call that minted it, and it expires. Nothing was charged and no deployment exists for an unknown handle. "
+                + "Call list_inferences to see whether the deployment was in fact created; if it was not, re-issue create_inference with the SAME idempotency_key rather than polling this handle again.",
+        },
+    },
+    {
+        test: /^\/api\/training\/jobs\/([^/]+)\/checkpoints\/([^/]+)/,
+        idFrom: 2,
+        resource: {
+            code: "CHECKPOINT_NOT_FOUND",
+            resource: "checkpoint_id",
+            recovery: "Call get_training_checkpoints with the same job_id to list the checkpoints that actually exist, and copy an id from that response.",
+        },
+    },
+    {
+        test: /^\/api\/training\/jobs\/([^/]+)/,
+        idFrom: 1,
+        resource: {
+            code: "TRAINING_JOB_NOT_FOUND",
+            resource: "job_id",
+            recovery: "Call list_training_jobs to get the job ids in this workspace and copy one from that response. A job id from another workspace is never visible here.",
+        },
+    },
+    {
+        test: /^\/api\/datasets\/integrations\/([^/]+)/,
+        idFrom: 1,
+        resource: {
+            code: "INTEGRATION_NOT_FOUND",
+            resource: "integration_id",
+            recovery: "Call list_integrations to get the connected accounts in this workspace and copy an id from that response.",
+        },
+    },
+    {
+        // The negative lookahead keeps a 404 from a STATIC endpoint under the same
+        // prefix (a collection read, an upload, a validate) from being reported as
+        // "no dataset with id 'upload'".
+        test: /^\/api\/datasets\/(?!integrations|uploads?|validate|register-hf|storage-usage|storage-billing|format-specs|hub-search|hub-preview)([^/]+)/,
+        idFrom: 1,
+        resource: {
+            code: "DATASET_NOT_FOUND",
+            resource: "dataset_id",
+            recovery: "Call list_datasets to get the dataset ids in this workspace and copy one from that response. A dataset that is still importing is listed but not yet previewable — read its status there before concluding it is missing.",
+        },
+    },
+    {
+        test: /^\/api\/inference\/(?!bookings|preflight|gpu-options|gpu-availability|validate-model)([^/]+)/,
+        idFrom: 1,
+        resource: {
+            code: "INFERENCE_NOT_FOUND",
+            resource: "deployment_id",
+            recovery: "Call list_inferences to get the deployment ids in this workspace and copy one from that response. A deleted deployment is gone permanently — it does not come back.",
+        },
+    },
+];
+/**
+ * Structured answer for a 404. Deliberately NOT gated on the upstream message
+ * text: whichever service answered and in whatever prose, a 404 on an
+ * id-bearing path means the same thing and needs the same next move.
+ */
+function notFoundError(status, message, path, upstreamCode) {
+    for (const route of NOT_FOUND_ROUTES) {
+        const match = route.test.exec(path);
+        if (!match)
+            continue;
+        const id = decodeURIComponent(match[route.idFrom] ?? "");
+        return JSON.stringify({
+            code: route.resource.code,
+            message: `${message || "Not found"} — no ${route.resource.resource} "${id}" exists in this workspace (an id from another workspace is never visible, and a deleted one never returns).`,
+            recoverable: true,
+            instruction: `${route.resource.recovery} Do NOT retry this call with the same id, and do not treat this as an outage — the platform answered definitively.`,
+            resource: route.resource.resource,
+            id,
+            path,
+            upstream_code: upstreamCode,
+        });
+    }
+    // An unmapped path: still structured, still says what to do, but never
+    // invents a collection to list.
+    return JSON.stringify({
+        code: "RESOURCE_NOT_FOUND",
+        message: `${message || "Not found"} — ${statusGuidance(status)}`,
+        recoverable: true,
+        instruction: "The platform answered definitively that this resource does not exist in this workspace. List the parent collection to obtain a valid id instead of retrying, and do not treat this as an outage.",
+        path,
+        upstream_code: upstreamCode,
+    });
+}
+/**
+ * Format a failed control-plane response as error text an agent can act on.
+ *
+ * Four shapes come out of here:
+ *   1. Capacity-class rejections stay the structured compact JSON of the
+ *      standard capacity contract (book-first §3) — unchanged.
+ *   2. A missing-workspace 400 becomes a structured, self-recoverable error
+ *      naming the exact fix, because "Workspace context required" alone does
+ *      not tell an agent where workspace context comes from.
+ *   3. A 404 becomes a structured `<THING>_NOT_FOUND` naming the id, the
+ *      resource, and the read that hands out valid ids — the same shape as
+ *      MODEL_NOT_HOSTED, so an unknown id never has to be string-matched out
+ *      of a bare sentence.
+ *   4. Everything else keeps the API's own prose (so a real message is never
+ *      paraphrased), and a response with NO message gets the status, the path,
+ *      and what to do about it instead of a bare error code.
+ *
+ * CUSTOMER BOUNDARY: whichever shape comes out, it is redacted before it is
+ * returned. Every one of the four carries text the platform did not author —
+ * an upstream message, a proxy body, an engine exception — so build identity
+ * (image name/tag/digest/version) can ride any of them out to an MCP client.
+ * The redaction is applied HERE rather than at the single throw site so the
+ * exported helper cannot be reused later without it.
+ */
+export function formatApiError(status, text, path) {
+    const formatted = buildApiErrorText(status, text, path);
+    // Redact structurally when the shape is JSON, so a replacement can never
+    // land inside a string and corrupt the payload the agent has to parse.
+    try {
+        const parsed = JSON.parse(formatted);
+        if (parsed && typeof parsed === "object") {
+            return JSON.stringify(redactBuildIdentityDeep(parsed));
+        }
+    }
+    catch {
+        /* not JSON — plain prose, redacted as text below */
+    }
+    return redactBuildIdentity(formatted);
+}
+function buildApiErrorText(status, text, path) {
+    let err;
+    try {
+        const parsed = JSON.parse(text);
+        if (parsed && typeof parsed === "object")
+            err = parsed;
+    }
+    catch {
+        /* non-JSON body handled below */
+    }
+    if (!err) {
+        // A non-JSON 404 (a proxy's own page, an empty body) is still an unknown
+        // id as far as the caller is concerned, so it gets the structured answer.
+        // An HTML error page is not a message: quoting it would bury the
+        // instruction, so only a short plain body is carried through.
+        if (status === 404) {
+            const body = text.trim();
+            const usable = body.length <= 200 && !body.startsWith("<") ? body : "";
+            return notFoundError(status, usable, path, undefined);
+        }
+        const body = text.trim();
+        return body || `Run BiOS API error ${status} on ${path} — ${statusGuidance(status)}`;
+    }
+    const message = extractApiMessage(err);
+    const nested = typeof err.error === "object" && err.error !== null ? err.error : {};
+    // Availability rejections are SELF-RECOVERABLE: the API includes the machine
+    // code plus the currently bookable GPU alternatives. An MCP client is an AI
+    // agent — hand it the structured payload as compact JSON in the error text so
+    // it can pick a listed gpu_type and retry the same call, instead of a prose
+    // sentence it can only show a human.
+    //
+    // Standard capacity contract (book-first §3): the fields may live nested
+    // under `error` or at the top level; a capacity-class code is ALWAYS
+    // serialized structured — even with ZERO alternatives (the zero-alternative
+    // miss must still carry the minimum block and the queue option, not degrade
+    // to prose).
+    const alternatives = nested.available_gpus ?? nested.available_alternatives
+        ?? err.available_gpus ?? err.available_alternatives;
+    const code = (nested.code || err.code);
+    const isCapacityClass = code === "CAPACITY_UNAVAILABLE" || code === "SELECTED_GPU_UNAVAILABLE";
+    if (isCapacityClass || (Array.isArray(alternatives) && alternatives.length > 0)) {
+        const alternativeList = Array.isArray(alternatives) ? alternatives : [];
+        return JSON.stringify({
+            code: code || `HTTP_${status}`,
+            reason: nested.reason ?? err.reason,
+            message: message || `Run BiOS API error ${status}`,
+            recoverable: true,
+            instruction: alternativeList.length > 0
+                ? "The selected GPU is not bookable for this request. Retry the same call with gpu_type/gpu_count set to one of available_gpus (never below its min_gpus)."
+                : "No alternative GPUs are in stock right now. Retry shortly, or resubmit with allow_capacity_queue=true to wait for stock (nothing is charged while waiting).",
+            available_gpus: alternativeList,
+            minimum_requirement: nested.minimum_requirement ?? err.minimum_requirement,
+            selected: nested.selected ?? err.selected,
+            queue_eligible: nested.queue_eligible ?? err.queue_eligible,
+            checked_at: nested.checked_at ?? err.checked_at,
+        });
+    }
+    // Workspace context is not something the model can put in a tool argument —
+    // it comes from the MCP server's configuration (RUNBIOS_WORKSPACE_ID) or from
+    // the workspace an API key is bound to. Say that, or the agent retries the
+    // same call forever.
+    if (status === 400 && /workspace (context|id) (is )?required|workspace context required/i.test(message)) {
+        return JSON.stringify({
+            code: "WORKSPACE_CONTEXT_REQUIRED",
+            message: `${message} — this call is workspace-scoped and the request carried no workspace.`,
+            recoverable: false,
+            instruction: "The workspace cannot be passed as a tool argument. Either set RUNBIOS_WORKSPACE_ID in this MCP server's environment or use an API key bound to a workspace, then restart the MCP client. Call introspect_api_key to see which workspace (if any) the current credential is bound to. Tell the user this is a configuration fix, not a retry.",
+            path,
+        });
+    }
+    // An unknown id is a verdict about the ARGUMENT, so it must arrive as
+    // structured data with the route back to a valid id — never as a sentence the
+    // caller has to parse.
+    if (status === 404)
+        return notFoundError(status, message, path, code);
+    return message || `Run BiOS API error ${status} on ${path} — ${statusGuidance(status)}`;
+}
+export class BiosClient {
+    baseUrl;
+    authHeaders;
+    orgId;
+    workspaceId;
+    inferenceBaseUrl;
+    inferenceAuthHeader;
+    serverlessAuthHeader;
+    inferenceTimeoutMs;
+    userAgent;
+    constructor(opts) {
+        this.baseUrl = opts.baseUrl.replace(/\/+$/, "");
+        this.authHeaders = { ...opts.authHeaders };
+        this.orgId = opts.orgId ?? "";
+        this.workspaceId = opts.workspaceId ?? "";
+        this.inferenceBaseUrl = (opts.inferenceBaseUrl || this.baseUrl).replace(/\/+$/, "");
+        this.inferenceAuthHeader = opts.inferenceAuthHeader ?? "";
+        this.serverlessAuthHeader = opts.serverlessAuthHeader ?? "";
+        this.inferenceTimeoutMs = opts.inferenceTimeoutMs ?? 900_000;
+        this.userAgent = opts.userAgent ?? `bios-mcp/${VERSION}`;
+    }
+    /**
+     * Tri-state probe against the public model registry (model-service):
+     * "hosted" — the exact author/name id is a verified catalog model;
+     * "not_hosted" — the registry definitively answered 404; "unknown" — the
+     * registry could not answer (network/5xx). Callers must treat "unknown" as
+     * advisory only and let the server-side gate enforce: never fail closed.
+     */
+    async modelRegistryStatus(modelId) {
+        const id = modelId.trim();
+        // Catalog ids are exactly "author/name" with safe segments; anything else
+        // can never resolve, so answer without a network call.
+        const segments = id.split("/");
+        if (segments.length !== 2
+            || !segments.every((s) => /^[A-Za-z0-9._-]+$/.test(s) && s !== "." && s !== "..")) {
+            return "not_hosted";
+        }
+        let res;
+        try {
+            res = await fetch(`${this.baseUrl}/api/models/${id}`, {
+                headers: { "User-Agent": this.userAgent },
+            });
+        }
+        catch {
+            return "unknown";
+        }
+        // Drain the body so the connection can be reused; only the status matters.
+        await res.text().catch(() => "");
+        if (res.ok)
+            return "hosted";
+        if (res.status === 404)
+            return "not_hosted";
+        return "unknown";
+    }
+    async api(path, opts = {}) {
+        const { method = "GET", body, params, formData, headers: extraHeaders } = opts;
+        const url = new URL(path, this.baseUrl);
+        if (params) {
+            for (const [k, v] of Object.entries(params)) {
+                if (v !== undefined)
+                    url.searchParams.set(k, v);
+            }
+        }
+        const headers = {
+            "User-Agent": this.userAgent,
+        };
+        if (this.orgId)
+            headers["X-Org-ID"] = this.orgId;
+        Object.assign(headers, this.authHeaders);
+        if (extraHeaders)
+            Object.assign(headers, extraHeaders);
+        if (this.workspaceId)
+            headers["X-Workspace-ID"] = this.workspaceId;
+        let reqBody;
+        if (formData) {
+            reqBody = formData;
+        }
+        else if (body) {
+            headers["Content-Type"] = "application/json";
+            reqBody = JSON.stringify(body);
+        }
+        const res = await fetch(url.toString(), { method, headers, body: reqBody });
+        const text = await res.text();
+        if (!res.ok) {
+            // GPU rejections are SELF-RECOVERABLE: the API includes the machine
+            // code plus the GPUs that can actually run this request. An MCP client
+            // is an AI agent, so hand it the structured payload as compact JSON in
+            // the error text and it can pick a listed gpu_type and retry, instead
+            // of a prose sentence it can only show a human.
+            //
+            // Standard GPU rejection contract (book-first §3): the fields may live
+            // nested under `error` or at the top level; EVERY code in the family is
+            // ALWAYS serialized structured, even with ZERO alternatives (the
+            // zero-alternative body still carries the minimum block, and for a
+            // stock miss the queue option, so it must not degrade to prose).
+            //
+            // The family is two classes and the difference is load-bearing:
+            // CAPACITY_UNAVAILABLE is "not in stock right now" and the queue can
+            // fix it, while every PERMANENT_GPU_CODES member is a fixed fact about
+            // the request that no amount of stock can fix. Both get the structured
+            // payload; only the transient one gets pointed at the queue.
+            //
+            // Every text field the payload carries (message, reason, the nested
+            // selection) can be raw upstream prose, so the whole structured object
+            // is run through redactBuildIdentityDeep before it is stringified — the
+            // same boundary formatApiError applies to every other failed call. A
+            // non-GPU error falls through to formatApiError, which redacts too.
+            let structuredError;
+            try {
+                const err = JSON.parse(text);
+                const nested = typeof err.error === 'object' && err.error !== null ? err.error : {};
+                const alternatives = nested.available_gpus ?? nested.available_alternatives
+                    ?? err.available_gpus ?? err.available_alternatives;
+                const code = nested.code || err.code;
+                if (isGpuRejectionCode(code) || (Array.isArray(alternatives) && alternatives.length > 0)) {
+                    let baseMsg = `Run BiOS API error ${res.status}`;
+                    if (err.message)
+                        baseMsg = err.message;
+                    if (err.error) {
+                        if (typeof err.error === 'object' && err.error.message) {
+                            baseMsg = err.error.message;
+                        }
+                        else if (typeof err.error === 'string') {
+                            baseMsg = err.error;
+                        }
+                    }
+                    const alternativeList = Array.isArray(alternatives) ? alternatives : [];
+                    const queueOffered = nested.queue_offered ?? err.queue_offered;
+                    const priorityEntry = nested.gpu_priorities_entry ?? err.gpu_priorities_entry;
+                    // queue_offered === false is the server saying the queue is not on the
+                    // table, which is exactly the permanent classes. Reading the code and
+                    // the flag keeps this right even if one of them is missing.
+                    const permanent = isPermanentGpuCode(code) || queueOffered === false;
+                    const structured = {
+                        code: code || `HTTP_${res.status}`,
+                        status: res.status,
+                        reason: nested.reason ?? err.reason,
+                        message: baseMsg,
+                        // Recoverable by the agent on its own, either way. What differs is
+                        // HOW: a stock miss can resend the same body later, a permanent
+                        // rejection has to change gpu_type/gpu_count first.
+                        recoverable: true,
+                        retryable_as_submitted: !permanent,
+                        instruction: gpuRejectionInstruction({
+                            permanent,
+                            hasAlternatives: alternativeList.length > 0,
+                        }),
+                        available_gpus: alternativeList,
+                        minimum_requirement: nested.minimum_requirement ?? err.minimum_requirement,
+                        selected: nested.selected ?? err.selected,
+                        queue_offered: queueOffered,
+                        queue_eligible: nested.queue_eligible ?? err.queue_eligible,
+                        checked_at: nested.checked_at ?? err.checked_at,
+                    };
+                    // 1-based rank of the gpu_priorities entry that was refused, so a
+                    // caller with a ranked ladder knows which entry to change.
+                    if (priorityEntry !== undefined)
+                        structured.gpu_priorities_entry = priorityEntry;
+                    structuredError = JSON.stringify(redactBuildIdentityDeep(structured));
+                }
+            }
+            catch {
+                /* not a GPU rejection body — fall through to formatApiError */
+            }
+            // formatApiError is the single redaction exit for every failed
+            // control-plane call: the text it returns can be raw upstream prose (an
+            // engine exception, a body we could not parse) that would otherwise reach
+            // the MCP client verbatim as the tool error.
+            throw new Error(structuredError ?? formatApiError(res.status, text, path));
+        }
+        // A body of literally `null` (or an empty body) must never reach a tool
+        // result as a bare `null`: an agent that reads "null" learns nothing about
+        // whether the call succeeded, failed, or returned no rows. Normalize the
+        // empty answer to an empty object; every tool then renders a JSON object.
+        const parsed = text ? JSON.parse(text) : null;
+        return (parsed ?? {});
+    }
+    /**
+     * Select the Authorization header for /v1/chat/completions. A dedicated
+     * deployment key (inferenceAuthHeader) wins when present; otherwise a
+     * serverless-scoped platform key (serverlessAuthHeader) authenticates
+     * model-ID-routed serverless catalog calls on the unified endpoint.
+     */
+    resolveInferenceAuth() {
+        const auth = this.inferenceAuthHeader || this.serverlessAuthHeader;
+        if (!auth) {
+            throw new Error("chat_with_inference requires a key: set RUNBIOS_INFERENCE_KEY for a dedicated deployment, "
+                + "or provide a workspace platform key (RUNBIOS_API_KEY with serverless scope) to call catalog models by id");
+        }
+        return auth;
+    }
+    async inferenceApi(body, idempotencyKey, requestId, callerSignal) {
+        // Route streaming requests through the SSE aggregator so reasoning +
+        // content deltas surface exactly as produced, collapsed to one result.
+        if (body.stream === true) {
+            return this.streamInferenceApi(body, idempotencyKey, requestId, callerSignal);
+        }
+        const headers = {
+            Authorization: this.resolveInferenceAuth(),
+            Accept: "application/json",
+            "Content-Type": "application/json",
+            "X-Request-ID": requestId || randomUUID(),
+            "User-Agent": this.userAgent,
+        };
+        if (idempotencyKey)
+            headers["Idempotency-Key"] = idempotencyKey;
+        // Inference POSTs are intentionally dispatched once. An MCP caller that
+        // retries can reuse idempotency_key; this client never replays implicitly.
+        const controller = new AbortController();
+        const relayAbort = () => controller.abort(callerSignal?.reason);
+        if (callerSignal?.aborted)
+            relayAbort();
+        else
+            callerSignal?.addEventListener("abort", relayAbort, { once: true });
+        const timeout = setTimeout(() => controller.abort(new Error(`Inference timed out after ${this.inferenceTimeoutMs}ms`)), this.inferenceTimeoutMs);
+        let response;
+        let text;
+        try {
+            response = await fetch(`${this.inferenceBaseUrl}/v1/chat/completions`, {
+                method: "POST",
+                headers,
+                body: JSON.stringify(body),
+                signal: controller.signal,
+            });
+            text = await response.text();
+        }
+        finally {
+            clearTimeout(timeout);
+            callerSignal?.removeEventListener("abort", relayAbort);
+        }
+        if (!response.ok) {
+            // Serving errors are engine output; redact any build identity before the
+            // MCP client sees them as the tool error.
+            try {
+                const parsed = JSON.parse(text);
+                throw new Error(redactBuildIdentity(parsed?.error?.message || parsed?.message || `Inference API error ${response.status}`));
+            }
+            catch (error) {
+                if (error instanceof SyntaxError)
+                    throw new Error(redactBuildIdentity(text || `Inference API error ${response.status}`));
+                throw error;
+            }
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch {
+            throw new Error("Inference endpoint returned invalid JSON");
+        }
+        // `null` is not a completion. Returning it verbatim would hand the caller a
+        // bare "null" tool result that reads as "the model answered nothing".
+        if (parsed === null || typeof parsed !== "object") {
+            throw new Error("Inference endpoint returned an empty body (no completion object). Nothing was generated; retry the call.");
+        }
+        return parsed;
+    }
+    /**
+     * POST a streaming /v1/chat/completions request, consume the SSE, and
+     * aggregate the deltas into ONE OpenAI-shaped completion. Content and
+     * reasoning_content are concatenated in arrival order (so reasoning surfaces
+     * as produced), tool-call fragments are reassembled by index, and the final
+     * usage row (requested via stream_options.include_usage) is attached. The
+     * MCP transport returns a single tool result, so streaming is used for
+     * on-the-wire liveness/real-TTFT parity while the caller receives the
+     * assembled message.
+     */
+    async streamInferenceApi(body, idempotencyKey, requestId, callerSignal) {
+        const headers = {
+            Authorization: this.resolveInferenceAuth(),
+            Accept: "text/event-stream",
+            "Content-Type": "application/json",
+            "X-Request-ID": requestId || randomUUID(),
+            "User-Agent": this.userAgent,
+        };
+        if (idempotencyKey)
+            headers["Idempotency-Key"] = idempotencyKey;
+        const controller = new AbortController();
+        const relayAbort = () => controller.abort(callerSignal?.reason);
+        if (callerSignal?.aborted)
+            relayAbort();
+        else
+            callerSignal?.addEventListener("abort", relayAbort, { once: true });
+        const timeout = setTimeout(() => controller.abort(new Error(`Inference timed out after ${this.inferenceTimeoutMs}ms`)), this.inferenceTimeoutMs);
+        try {
+            const response = await fetch(`${this.inferenceBaseUrl}/v1/chat/completions`, {
+                method: "POST",
+                headers,
+                body: JSON.stringify(body),
+                signal: controller.signal,
+            });
+            if (!response.ok) {
+                const text = await response.text().catch(() => "");
+                try {
+                    const parsed = JSON.parse(text);
+                    throw new Error(redactBuildIdentity(parsed?.error?.message || parsed?.message || `Inference API error ${response.status}`));
+                }
+                catch (error) {
+                    if (error instanceof SyntaxError)
+                        throw new Error(redactBuildIdentity(text || `Inference API error ${response.status}`));
+                    throw error;
+                }
+            }
+            if (!response.body)
+                throw new Error("Inference stream returned no body");
+            return await aggregateChatStream(response.body);
+        }
+        finally {
+            clearTimeout(timeout);
+            callerSignal?.removeEventListener("abort", relayAbort);
+        }
+    }
+}
+/**
+ * Parse the OpenAI chat-completion SSE from `stream` and fold its deltas into a
+ * single non-streaming-shaped response. Content and reasoning_content are
+ * concatenated in arrival order; tool-call fragments are merged by index;
+ * finish_reason, role, id, model, and the final usage row are captured.
+ */
+export async function aggregateChatStream(stream) {
+    const reader = stream.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    let content = "";
+    let reasoning = "";
+    let role = "assistant";
+    let finishReason = null;
+    let id;
+    let model;
+    let created;
+    let usage;
+    const toolCalls = [];
+    const consume = (payload) => {
+        const data = payload.trim();
+        if (!data || data === "[DONE]")
+            return;
+        let event;
+        try {
+            event = JSON.parse(data);
+        }
+        catch {
+            return; // ignore non-JSON keepalive frames
+        }
+        if (event.error) {
+            const err = event.error;
+            const msg = typeof err === "string" ? err : String(err?.message ?? "stream error");
+            throw new Error(redactBuildIdentity(msg));
+        }
+        if (typeof event.id === "string")
+            id = event.id;
+        if (typeof event.model === "string")
+            model = event.model;
+        if (typeof event.created === "number")
+            created = event.created;
+        if (event.usage)
+            usage = event.usage;
+        const choices = Array.isArray(event.choices) ? event.choices : [];
+        for (const rawChoice of choices) {
+            const choice = rawChoice;
+            if (typeof choice.finish_reason === "string")
+                finishReason = choice.finish_reason;
+            const delta = (choice.delta ?? {});
+            if (typeof delta.role === "string")
+                role = delta.role;
+            if (typeof delta.content === "string")
+                content += delta.content;
+            if (typeof delta.reasoning_content === "string")
+                reasoning += delta.reasoning_content;
+            const deltaCalls = Array.isArray(delta.tool_calls) ? delta.tool_calls : [];
+            for (const rawCall of deltaCalls) {
+                const call = rawCall;
+                const index = typeof call.index === "number" ? call.index : toolCalls.length;
+                const slot = toolCalls[index] ?? (toolCalls[index] = { function: { arguments: "" } });
+                if (typeof call.id === "string")
+                    slot.id = call.id;
+                if (typeof call.type === "string")
+                    slot.type = call.type;
+                const fn = (call.function ?? {});
+                if (typeof fn.name === "string")
+                    slot.function.name = fn.name;
+                if (typeof fn.arguments === "string")
+                    slot.function.arguments += fn.arguments;
+            }
+        }
+    };
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            buffer += decoder.decode(value, { stream: true });
+            for (;;) {
+                const match = /\r\n\r\n|\n\n|\r\r/.exec(buffer);
+                if (!match || match.index === undefined)
+                    break;
+                const frame = buffer.slice(0, match.index);
+                buffer = buffer.slice(match.index + match[0].length);
+                emitFrame(frame, consume);
+            }
+        }
+        buffer += decoder.decode();
+        if (buffer.trim())
+            emitFrame(buffer, consume);
+    }
+    finally {
+        await reader.cancel().catch(() => undefined);
+        reader.releaseLock();
+    }
+    const message = { role, content: content || null };
+    if (reasoning)
+        message.reasoning_content = reasoning;
+    const assembledCalls = toolCalls.filter((c) => c !== undefined);
+    if (assembledCalls.length > 0) {
+        message.tool_calls = assembledCalls.map((c, i) => ({
+            id: c.id ?? `call_${i}`,
+            type: c.type ?? "function",
+            function: { name: c.function.name ?? "", arguments: c.function.arguments },
+        }));
+    }
+    const result = {
+        id: id ?? "",
+        object: "chat.completion",
+        model: model ?? "",
+        choices: [{ index: 0, message, finish_reason: finishReason }],
+    };
+    if (created !== undefined)
+        result.created = created;
+    if (usage !== undefined)
+        result.usage = usage;
+    return result;
+}
+/** Extract the joined `data:` payload from one SSE frame and consume it. */
+function emitFrame(frame, consume) {
+    const data = [];
+    for (const line of frame.replace(/\r\n/g, "\n").replace(/\r/g, "\n").split("\n")) {
+        if (!line || line.startsWith(":"))
+            continue;
+        const colon = line.indexOf(":");
+        const field = colon < 0 ? line : line.slice(0, colon);
+        let value = colon < 0 ? "" : line.slice(colon + 1);
+        if (value.startsWith(" "))
+            value = value.slice(1);
+        if (field === "data")
+            data.push(value);
+    }
+    if (data.length > 0)
+        consume(data.join("\n"));
+}
+//# sourceMappingURL=api-client.js.map