runbios-mcp 0.2.1-dev.62

package/README.md

@@ -0,0 +1,363 @@
+# Run BiOS MCP server
+
+The MCP server exposes the authenticated Run BiOS training and model-serving
+control planes to MCP-compatible automation clients. This build registers **42
+tools**; `get_platform_guide` lists all of them and a test fails if that
+inventory drifts from what is actually registered, so the count in the guide is
+always the count on the wire (`tools/list`).
+
+PRE-LAUNCH: while the coming-soon gates are on (the default — see
+`src/config.ts`), the three creation tools (`create_training_job`,
+`upload_dataset`, `import_huggingface_dataset`) are not registered at all, so
+the wire count is **39** and the guide lists only the live tools. Read and
+lifecycle tools are unaffected. Set `RUNBIOS_TRAINING_COMING_SOON=false` /
+`RUNBIOS_DATASETS_COMING_SOON=false` at launch and the registrations return.
+
+Set these environment variables in the MCP client configuration:
+
+```json
+{
+  "command": "npx",
+  "args": ["-y", "runbios-mcp"],
+  "env": {
+    "RUNBIOS_API_KEY": "bios-...",
+    "RUNBIOS_BASE_URL": "https://api.runbios.ai",
+    "RUNBIOS_WORKSPACE_ID": "workspace-id",
+    "RUNBIOS_INFERENCE_KEY": "sk-bios-deployment-key"
+  }
+}
+```
+
+`RUNBIOS_*` is the canonical environment prefix. API keys start with `bios-`;
+legacy `usf-` keys are still accepted.
+The legacy `BIOS_*` variable names are still accepted as fallbacks.
+
+`https://api.runbios.ai` is the canonical production hostname. Use
+`https://api-dev.runbios.ai` explicitly during dev.
+
+For interactive JWT authentication, omit `RUNBIOS_API_KEY` and set
+`RUNBIOS_ACCESS_TOKEN`. The server never guesses credential type from a prefix:
+API keys use `X-API-Key`, while access tokens use `Authorization: Bearer`.
+
+`chat_with_inference` reads the deployment key only from
+`RUNBIOS_INFERENCE_KEY`; a model cannot place it in a tool argument or expose it
+in a transcript. Set `RUNBIOS_INFERENCE_BASE_URL=https://api-dev.runbios.ai`
+explicitly for dev. The tool validates function schemas and matching tool
+response messages, propagates MCP cancellation to the HTTP request, makes one
+non-streaming OpenAI-compatible request, and never retries a dispatched
+inference POST automatically. `RUNBIOS_INFERENCE_TIMEOUT_MS` defaults to
+`900000` (15 minutes). Its idempotency header is propagated, but replay/dedup is
+not claimed without an explicit acknowledgement from the endpoint.
+
+## What the platform derives (never a tool input)
+
+An MCP client acts on the schema it is given, so the schema must not offer a
+choice the control plane will reject. These serving settings are SERVER-DERIVED
+and immutable, and are therefore absent from `create_inference` /
+`preflight_inference`:
+
+- `serving_mode` (`full` / `adapter` / `merged`) — from the verified
+  checkpoint's lineage; a catalog base model is served whole.
+- `model_task` — from the resolved model: `chat` for an instruct or
+  vision-language model, `completion` for a base model with no chat template,
+  `embedding`/`rerank` for those architectures. Every model in the current
+  catalog resolves to `chat`, so there is nothing to select.
+- `supports_images` — from the model's own config, never a caller claim.
+
+They are reported back on the preflight/create/status responses, which is where
+a caller reads them. Copying `canonical_request` from preflight into create
+still works: the echoed derived fields are dropped rather than rejected.
+
+`context_length` is the one window a caller may narrow. The policy the server
+enforces is: default `min(native max, 262144)`, falling back to `32768` when the
+native window is unknown (a model with a smaller native window keeps its own),
+and the hard ceiling is always the model's OWN native max. No static JSON Schema
+can express a per-model ceiling, so the tool advertises a `1024`-`1048576` sanity
+range and its description names the real authority —
+`model.native_max_context` from `preflight_inference`. An out-of-range value is
+rejected with the whole policy in the message, not a bare bounds error.
+
+`max_seq_length` (training) follows the same rule: the platform default is
+`2048`, the hard ceiling is the base model's OWN window, and the authoritative
+field bounds live in `get_training_capabilities` (`max_length`), so the tool
+advertises the contract's `128` floor and the same `1048576` sanity ceiling
+instead of the meaningless `10000000` it used to. `chat_with_inference`'s
+`max_tokens` is bounded the same way — the real ceiling is the served window
+minus the prompt.
+
+## Spend consent is bounded by what the platform can charge
+
+`max_price_hour_cents` is the one field that authorizes money: the maximum
+accepted TOTAL hourly price for the complete GPU count. The control plane has no
+ceiling of its own — it only refuses a cap BELOW the primary placement's
+verified price — so `z.number().int()` alone advertised `9007199254740991`, i.e.
+told an agent that consenting to nine quadrillion cents an hour is a legal
+request. All five money-bearing tools (`preflight_inference`, `create_inference`,
+`update_inference_policy`, `preflight_training_job`, `create_training_job`) now
+cap it at **100000 cents ($1,000/hour)**: the dearest configuration the GPU
+catalog can book is 8 x B300 at 8280 cents/hour, and the beta serving cap
+(models up to ~130B total parameters) keeps a deployment inside that ladder, so
+the bound has an order of magnitude of headroom and still reads as a limit
+rather than a blank cheque. It is a sanity bound on consent, never a price
+quote: `get_gpu_pricing` and the preflight response carry the real numbers, and
+the rejection message says all of this.
+
+## Error text an agent can act on
+
+- A capacity rejection stays the structured compact JSON below.
+- A model id outside the Run BiOS catalog answers `MODEL_NOT_HOSTED` and names every
+  route to a valid id (`list_models`, `search_models`, ids already returned by
+  `list_inferences`/`list_training_jobs`, the console Models page) plus what to
+  do when none of them answer — recovery advice never dead-ends on one tool.
+- A model-resolution failure answers `MODEL_NOT_RESOLVED` /
+  `MODEL_REVISION_UNRESOLVED` in the platform's own terms. The upstream mirror's
+  transport error is never forwarded: an agent cannot act on a vendor's 404, and
+  the vendor is not the answer to "why can this not be sized".
+- A workspace-scoped read with no workspace context answers
+  `WORKSPACE_CONTEXT_REQUIRED` and says the fix is configuration
+  (`RUNBIOS_WORKSPACE_ID` or a workspace-bound API key), not a retry.
+- An unknown id answers a structured `<THING>_NOT_FOUND`
+  (`INFERENCE_NOT_FOUND`, `TRAINING_JOB_NOT_FOUND`, `CHECKPOINT_NOT_FOUND`,
+  `DATASET_NOT_FOUND`, `INTEGRATION_NOT_FOUND`, `BOOKING_NOT_FOUND`, or
+  `RESOURCE_NOT_FOUND` for a path with no id) carrying the id, the resource, the
+  upstream code, and the read that hands out valid ids — never the bare sentence
+  ("Deployment not found") an agent would have to string-match. A 404 on a static
+  endpoint under the same prefix (`/api/inference/gpu-options`) is never reported
+  as an id that does not exist.
+- FastAPI-shaped bodies (`{"detail": ...}`) are read as well as
+  `{"error":{"message"}}`, and a response with no message at all reports the
+  status, the path, and what to do — never a bare `BIOS API error 400`.
+- No tool result is ever a bare `null`.
+- `get_inference_status` adds a derived `status_summary` (phase, `count x SKU`
+  GPU, `endpoint_usable`, queue/GPU state) built only from fields in the same
+  response, so a field that is null before the pod reports is not read as "no
+  GPU" or "no phase".
+- `list_supported_architectures` labels its rows as manifest provenance. Which
+  build published a row is registry provenance, never the image the platform is
+  running, and the control plane no longer publishes it at all: the public
+  projection drops `image_tag`, `bios_version` and `manifest_sha256` at the
+  boundary. Internal build references are additionally removed **by content**
+  from every string of every scope, not by field name: dropping the `image_tag`
+  key alone left the identical `<registry>/<engine>@sha256:<digest>` in the
+  free-text `notes` of 194 training-scope rows, and a rule that matches only a
+  key is defeated the moment the value moves. `manifest_provenance` reports how
+  many references were redacted and how many rows came from a published manifest
+  — counted from `source`, the one provenance field that survives the
+  projection. It publishes no build-version or digest counts, because after the
+  projection those could only ever report 0, and a standing 0 reads as "the
+  registry records no build" rather than "this response cannot see one".
+
+## Safe inference workflow
+
+1. `get_inference_gpu_options` returns inference-fit configurations joined to
+   authoritative deployment prices and stock. Prefer the MODEL-ADDRESSED form
+   (`model=<catalog_model_id>` — an id from `list_models`/`search_models`,
+   optionally `revision`): the server resolves the model facts (vision-aware)
+   and answers with computed
+   `min_gpus`, `valid_counts`, and `bookable_counts` — the exact minimums the
+   create gate enforces, so client-supplied facts can never understate a
+   minimum. `unknown` is not treated as available; never offer a count below
+   `min_gpus` or outside `bookable_counts`.
+2. `preflight_inference` validates the exact source, model, GPU, queue, price
+   cap, and wallet-hold terms without creating a deployment or mutating funds.
+3. `create_inference` uses the same request contract, self-validates the
+   selection against the model-addressed minimums before submitting, and
+   follows BOOK-BEFORE-REVEAL: a non-queued create answers `202` with a
+   booking handle while the GPU is secured on real capacity (30-40 s typical); the
+   tool polls the handle and returns the full payload — including the ONE-TIME
+   `inference_key` — only after the GPU is confirmed. A definitive miss
+   returns the standard `CAPACITY_UNAVAILABLE` stock-miss error with fresh
+   alternatives and NO deployment exists (nothing charged). A selection that
+   can never run at all is refused up front with a permanent code instead
+   (see below). Queueing is opt-in, a maximum
+   total hourly price is explicit, and a GPU alternative is never selected
+   without approval. `gpu_priorities` backups (1-5 ranked choices) may be
+   supplied on ANY create — they form the after-start replacement ladder;
+   the queue itself stays opt-in.
+4. `get_inference_booking` polls a booking handle from a long-running
+   `create_inference` (pending → revealed payload → or the standard 409).
+5. `get_inference_status` reports durable queue state, provisioning/loading,
+   endpoint readiness, price cap, notification summary, and wallet
+   authorization. An endpoint is live only when the returned status is
+   `running`. `queued_capacity` means waiting for stock at zero charge —
+   after a deployment has ever been booked, GPU loss never ends in a
+   capacity failure; it waits and auto-resumes.
+6. `get_inference_notifications` reports durable lifecycle-email delivery,
+   bounded retries, and operator-visible dead letters.
+7. `update_inference_policy`, `stop_inference`, `resume_inference`,
+   `restart_inference`, and `delete_inference` manage the lifecycle.
+
+## Standard GPU rejection contract
+
+Training and inference speak ONE GPU rejection shape, with a `code` that says
+whether waiting can ever help. The MCP transport serializes every code in the
+family as compact JSON in the tool-error text, even when zero alternatives
+exist, so an agent can act on it directly.
+
+| `reason` | `code` | HTTP | `queue_offered` |
+| --- | --- | --- | --- |
+| `insufficient_stock` | `CAPACITY_UNAVAILABLE` | 409 | `true` |
+| `model_too_large` | `GPU_TYPE_TOO_SMALL` | 400 | `false` |
+| `below_model_minimum` | `GPU_COUNT_BELOW_MINIMUM` | 400 | `false` |
+| `invalid_gpu_count` | `GPU_COUNT_INVALID` | 400 | `false` |
+| `gpu_unsupported` | `GPU_TYPE_UNSUPPORTED` | 400 | `false` |
+
+`CAPACITY_UNAVAILABLE` is the ONLY transient one: the GPU is not free right
+now, so retrying later or joining the queue can succeed (training also echoes
+the deprecated `SELECTED_GPU_UNAVAILABLE` as `legacy_code` for one release).
+The four `400` codes are permanent facts about the request itself, so the queue
+is never offered for them and resending the same `gpu_type`/`gpu_count` can
+never succeed. Branch on `retryable_as_submitted` (or `queue_offered`) rather
+than on the message text.
+
+```json
+{
+  "code": "GPU_TYPE_TOO_SMALL",
+  "status": 400,
+  "reason": "model_too_large",
+  "message": "This model does not fit on L40_48GB, at any GPU count.",
+  "recoverable": true,
+  "retryable_as_submitted": false,
+  "instruction": "This GPU cannot run the request as submitted, and free capacity will never change that. Retry the same call with gpu_type and gpu_count set to one of available_gpus, never below that entry's min_gpus. 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.",
+  "available_gpus": [
+    { "gpu_type": "H100_80GB", "gpu_count": 2, "min_gpus": 2, "valid_counts": [2, 4, 8],
+      "tier": "secure", "price_hour_cents": 598, "available_count": 6 }
+  ],
+  "minimum_requirement": {
+    "selected_gpu_min": 2, "selected_valid_counts": [2, 4, 8],
+    "per_type": [{ "gpu_type": "H100_80GB", "min_gpus": 2, "valid_counts": [2, 4, 8] }]
+  },
+  "selected": { "gpu_type": "L40_48GB", "gpu_count": 2, "availability_status": "available" },
+  "queue_offered": false,
+  "queue_eligible": false,
+  "gpu_priorities_entry": 1,
+  "checked_at": "2026-07-19T00:00:00Z"
+}
+```
+
+`available_alternatives` is the deprecated alias of `available_gpus`, and
+`gpu_priorities_entry` is the 1-based rank of the refused `gpu_priorities`
+entry when the rejection belongs to one. A stock miss carries the same shape
+with `code: "CAPACITY_UNAVAILABLE"`, `queue_offered: true`,
+`retryable_as_submitted: true`, and an `instruction` that does offer
+`allow_capacity_queue=true`.
+
+A `503 ADMISSION_UNAVAILABLE` is a transient market outage, never a capacity
+verdict. Retry shortly, and never conclude out-of-stock from it. See
+`get_platform_guide` topic `capacity_errors` for the recovery playbook.
+
+Models are selectable only from the platform's own catalog: `list_models`
+and `search_models` read the hosted registry, and `create_training_job`,
+`preflight_training_job`, `create_inference`, and `preflight_inference`
+validate the model id against it, answering `MODEL_NOT_HOSTED` — never a
+live Hugging Face lookup. Catalog models are pre-mirrored, so raw access
+tokens are intentionally excluded from MCP tool inputs and no integration is
+needed for models; Hugging Face integrations remain for dataset imports via
+`import_huggingface_dataset`.
+
+`create_training_job` and `resume_training_job` accept an optional
+`idempotency_key`. Reuse the same value after a timeout so the API replays the
+original acknowledgement instead of creating another job, wallet hold, queue
+entry, or GPU request. The MCP server generates a fresh key when it is omitted.
+
+## Training lifecycle (book-before-reveal)
+
+Like inference, `create_training_job` books a GPU before it reveals a job.
+The call blocks while the ranked ladder is booked (~40s typical); a job id and
+the "training started" email exist only once a real pod is secured. Read
+`status` on the response and from `get_training_status`:
+
+- `booked` — a GPU is secured (booked == secured); the job then provisions,
+  downloads, and runs on its own. Money is captured only after this point.
+- `securing` — still booking at the deadline; the async tail continues.
+  Poll `get_training_status` until `booked`/`running` (or a terminal state).
+  Nothing is charged while securing.
+- `queued` — returned only with explicit queue consent; waits for stock at
+  zero charge and books via the same path.
+- A booking-time stock miss returns the standard `CAPACITY_UNAVAILABLE`
+  (409) with fresh `available_gpus` and **no job exists** (nothing charged);
+  a selection that can never run returns one of the permanent `400` codes
+  above instead, and no queue is offered for it. A transient
+  `503 ADMISSION_UNAVAILABLE` is a retry, never out-of-stock, and the platform
+  never auto-substitutes a GPU.
+
+If a started job loses its pod, it rests at `interrupted` — a self-heal state
+distinct from `failed` in which billing is already stopped. Call
+`resume_training_job` to continue from the last checkpoint; resume re-books on
+secured capacity before reporting resumed, so the same guarantees apply.
+
+Training and deployment share one authoritative GPU-capacity broker. Server
+priority is evaluated first. Within an equal-priority class, the broker rotates
+across users and preserves FIFO order within each user's own requests. This
+anti-starvation policy prevents one user's large backlog from monopolizing GPU
+capacity; consequently, a newer request from another user can run before an
+older request in a busy user's backlog.
+
+For each eligible request, the broker selects the lowest-ranked approved GPU
+choice that is live, has enough cards, and remains within the accepted total
+hourly price cap. Thus an older request's third choice can receive capacity
+before a newer request's first choice. Unknown/stale provider inventory issues
+no grant. Every vendor mutation requires the broker's short-lived fenced grant,
+and atomic reservations prevent training and deployment replicas from booking
+the same cards.
+
+If capacity disappears before the vendor mutation, a queued request releases
+the grant and returns to its original global position. Expired worker leases
+are fenced and recovered with a new grant identity. Ambiguous provider results
+retain the same immutable provisioning request and grant fence until
+reconciliation proves success or definitive failure, so MCP clients should
+retry with the same idempotency key rather than submit a replacement request.
+
+## What never leaves the platform
+
+An MCP client is a program the customer runs, so every tool result is a
+customer-facing response. Two facts never appear in one:
+
+- **Container build identity** — any image name, version, tag, digest or path.
+  `list_supported_architectures` used to ship the engine image reference that
+  published each registry row (`image_tag`, `bios_version`, `manifest_sha256`,
+  and the same tag again inside the free-text `notes`), and
+  `get_training_capabilities` shipped `image_compatibility`, the engine image
+  VERSION range the contract was written against. Both are removed at the tool
+  boundary (`src/redaction.ts`), by CONTENT as well as by key — a key-only rule
+  is defeated the moment the same value moves one field over, which is exactly
+  what `notes` did. Architecture support is unchanged and still authoritative:
+  the deployment and training gates read those same rows, and the response says
+  so. Engine text that reaches an agent as an error (upstream bodies, serving
+  exceptions, training log lines) goes through the same content rule.
+- **Which supplier backs a placement** — the control plane already answers the
+  neutral `bios-cloud` / `global` placement labels, and the tools echo those
+  unchanged. Tool text describes what was bought ("the GPU is secured on real
+  capacity"), never who sold it.
+
+## Hosted (remote) connector — implemented, not planned
+
+Besides the stdio entry (`dist/index.js`), this package ships the hosted
+Streamable HTTP connector used by clients that only accept remote MCP servers
+(`dist/http/main.js`, ECS service `bios-mcp`, default port 7152). It is built and
+deployed, not a roadmap item:
+
+- `POST {PUBLIC_BASE_URL}/mcp` — stateless Streamable HTTP endpoint. `GET` and
+  `DELETE` answer `405`; an unauthenticated call answers `401` with the
+  RFC 9728 `WWW-Authenticate: Bearer resource_metadata=...` challenge.
+- OAuth 2.1 authorization server with dynamic client registration and PKCE,
+  advertised at `/.well-known/oauth-protected-resource`,
+  `/.well-known/oauth-authorization-server`, and
+  `/.well-known/openid-configuration` (each also under `/mcp`).
+- Consent is granted in the console (`CONSOLE_BASE_URL`); every request
+  re-validates the bearer token and re-checks scopes and workspace membership
+  through the internal api-gateway.
+- `chat_with_inference` is intentionally unavailable on the hosted connection:
+  a deployment's serving key is shown exactly once at create time and is never
+  retrievable, so the tool fails with that explanation instead of a
+  local-environment hint that does not apply.
+
+Any documentation still describing the hosted connector as "planned" is stale.
+
+## Verification
+
+```bash
+npm test
+npm run typecheck
+npm run build
+```

package/dist/api-client.d.ts

@@ -0,0 +1,147 @@
+/**
+ * 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 declare 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 declare 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 declare const PERMANENT_GPU_CODES: readonly ["GPU_TYPE_TOO_SMALL", "GPU_COUNT_BELOW_MINIMUM", "GPU_COUNT_INVALID", "GPU_TYPE_UNSUPPORTED"];
+/** Resolve the machine code for a rejection reason. */
+export declare function gpuRejectionCodeFor(reason?: string): string;
+/** True when this code can never be fixed by waiting for stock. */
+export declare function isPermanentGpuCode(code: unknown): boolean;
+/**
+ * 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 declare function gpuRejectionStatusFor(reason?: string): number;
+/** Every code whose body carries the standard GPU rejection fields. */
+export declare function isGpuRejectionCode(code: unknown): boolean;
+/**
+ * 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 declare function gpuRejectionInstruction(opts: {
+    permanent: boolean;
+    hasAlternatives: boolean;
+    /** How to name the retry, e.g. "create_inference". Defaults to "the same call". */
+    call?: string;
+}): string;
+export interface ApiOpts {
+    method?: string;
+    body?: unknown;
+    params?: Record<string, string | undefined>;
+    formData?: FormData;
+    headers?: Record<string, string>;
+}
+export interface BiosClientOptions {
+    /** Control-plane base URL; no trailing slash. */
+    baseUrl: string;
+    /** Control-plane auth headers: {"X-API-Key": k} or {"Authorization": "Bearer ..."}. */
+    authHeaders: Record<string, string>;
+    orgId?: string;
+    workspaceId?: string;
+    /** Base URL for inference calls; defaults to baseUrl. */
+    inferenceBaseUrl?: string;
+    /** Authorization header value for inference calls (may be empty). */
+    inferenceAuthHeader?: string;
+    /**
+     * Fallback Authorization header for /v1/chat/completions when no dedicated
+     * deployment key (inferenceAuthHeader) is set. A workspace platform key with
+     * serverless scope authenticates model-ID-routed serverless catalog calls;
+     * the unified /v1 gateway routes by the request's `model`. Dedicated
+     * deployment keys still take precedence when present.
+     */
+    serverlessAuthHeader?: string;
+    /** Inference request timeout in milliseconds; defaults to 900000. */
+    inferenceTimeoutMs?: number;
+    /** User-Agent header; defaults to "bios-mcp/<VERSION>". */
+    userAgent?: string;
+}
+/**
+ * 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 declare function formatApiError(status: number, text: string, path: string): string;
+export declare class BiosClient {
+    private readonly baseUrl;
+    private readonly authHeaders;
+    private readonly orgId;
+    private readonly workspaceId;
+    private readonly inferenceBaseUrl;
+    private readonly inferenceAuthHeader;
+    private readonly serverlessAuthHeader;
+    private readonly inferenceTimeoutMs;
+    private readonly userAgent;
+    constructor(opts: BiosClientOptions);
+    /**
+     * 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.
+     */
+    modelRegistryStatus(modelId: string): Promise<"hosted" | "not_hosted" | "unknown">;
+    api<T = unknown>(path: string, opts?: ApiOpts): Promise<T>;
+    /**
+     * 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.
+     */
+    private resolveInferenceAuth;
+    inferenceApi(body: Record<string, unknown>, idempotencyKey?: string, requestId?: string, callerSignal?: AbortSignal): Promise<unknown>;
+    /**
+     * 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.
+     */
+    streamInferenceApi(body: Record<string, unknown>, idempotencyKey?: string, requestId?: string, callerSignal?: AbortSignal): Promise<unknown>;
+}
+/**
+ * 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 declare function aggregateChatStream(stream: ReadableStream<Uint8Array>): Promise<Record<string, unknown>>;
+//# sourceMappingURL=api-client.d.ts.map

package/dist/api-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-client.d.ts","sourceRoot":"","sources":["../src/api-client.ts"],"names":[],"mappings":"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"}