runbios-mcp 0.2.1-dev.100

package/dist/server.js

@@ -0,0 +1,2239 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { readFile, stat } from "node:fs/promises";
+import { basename, resolve } from "node:path";
+import { randomUUID } from "node:crypto";
+import { buildGPUOptionsParams, buildTrainingCreateBody, TRAINING_ADAPTERS, TRAINING_METHODS, trimTrainingLogs, } from "./training-contract.js";
+import { buildDeploymentBody, buildDeploymentGPUOptionsParams, buildDeploymentPolicyBody, DEPLOYMENT_GPU_TIERS, DEPLOYMENT_SOURCE_TYPES, } from "./deployment-contract.js";
+import { buildInferenceBody } from "./inference-contract.js";
+import { redactBuildIdentity, redactBuildIdentityDeep, redactFreeTextFields, sanitizeArchitectureRegistry, stripBuildIdentity, } from "./redaction.js";
+import { gpuRejectionCodeFor, gpuRejectionInstruction, gpuRejectionStatusFor, isPermanentGpuCode, } from "./api-client.js";
+/**
+ * Job/deployment fields whose upstream value is RAW text rather than a curated
+ * sentence. `stop_last_error` is the proven one: the training stop saga stores
+ * the transport error from its last call to the machine verbatim, and that text
+ * is the request URL — a hostname that names the capacity supplier. The others
+ * are the same class (free text written from an upstream failure) and are
+ * covered so a future writer that stops curating cannot reopen the hole.
+ */
+const RAW_FAILURE_TEXT_FIELDS = [
+    "stop_last_error",
+    "error_message",
+    "last_error",
+    "stage_detail",
+];
+import { resolveLaunchGates } from "./config.js";
+import { VERSION } from "./version.js";
+export { VERSION };
+/**
+ * Wrap a tool handler so hooks.onToolCall observes the tool name, success
+ * flag, elapsed milliseconds, and on failure the error message string only
+ * (never tool arguments). The wrapper does not change what the handler
+ * returns or throws; without a hook the handler is registered untouched.
+ */
+function wrapToolHandler(name, handler, onToolCall) {
+    if (!onToolCall)
+        return handler;
+    const fn = handler;
+    const wrapped = async (...args) => {
+        const start = Date.now();
+        try {
+            const out = await fn(...args);
+            onToolCall({ tool: name, ok: true, ms: Date.now() - start });
+            return out;
+        }
+        catch (error) {
+            onToolCall({
+                tool: name,
+                ok: false,
+                ms: Date.now() - start,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            throw error;
+        }
+    };
+    return wrapped;
+}
+const SAFE_ID_RE = /^[a-zA-Z0-9_-]+$/;
+function validateId(value, label) {
+    if (!SAFE_ID_RE.test(value)) {
+        throw new Error(`Invalid ${label}: must contain only alphanumeric characters, hyphens, and underscores`);
+    }
+}
+function result(text) {
+    return { content: [{ type: "text", text }] };
+}
+function json(data) {
+    // A tool result of literally `null` is unreadable: an agent cannot tell an
+    // empty answer from a failure, and "null" is the one string that invites a
+    // wrong conclusion either way. The client already normalizes empty bodies;
+    // this is the last-resort guard for any other path.
+    if (data === null || data === undefined) {
+        return result(JSON.stringify({
+            code: "EMPTY_RESPONSE",
+            message: "The Run BiOS API answered this read with no JSON body. This is not an error verdict and nothing was changed.",
+            instruction: "Retry once; if it repeats, confirm the resource with the matching list/status tool before drawing a conclusion.",
+        }, null, 2));
+    }
+    return result(JSON.stringify(data, null, 2));
+}
+/* ─── Honest, actionable recovery text ───
+ * An MCP client ACTS on this text, so recovery advice must not dead-end on a
+ * single tool: list_models and search_models read the same registry through the
+ * same dependency, so one outage takes both down. Name every route the agent
+ * has, and tell it what to do when none of them answer, instead of pointing at
+ * one tool that may be unavailable. */
+const CATALOG_RECOVERY = "Pick an id from the Run BiOS catalog: call list_models (everything hosted) or search_models (filter by name/provider) — "
+    + "either one answers from the same registry. If BOTH are unavailable, do NOT guess another id: any id already returned "
+    + "by list_inferences or list_training_jobs is known-hosted, the same catalog is on the Models page of the Run BiOS console, "
+    + "and get_platform_guide (topic \"models\") states the rule. When nothing can confirm an id, report the catalog as "
+    + "unavailable instead of retrying with an unverified one.";
+/* ─── Context-length policy (owner-mandated, enforced server-side) ───
+ * The window is DERIVED unless the caller overrides it: the default is
+ * min(model native max, 262144), a model whose native window is unknown falls
+ * back to 32768, a genuinely small-context model keeps its own smaller window,
+ * and the hard ceiling is always the model's OWN native max — the server
+ * rejects anything above it. No static JSON Schema can express a per-model
+ * ceiling, so the bounds below are an honest sanity range and the description
+ * names the real authority (model.native_max_context from preflight). */
+const CONTEXT_DEFAULT_CEILING = 262_144;
+const CONTEXT_UNKNOWN_FALLBACK = 32_768;
+const CONTEXT_TOOL_MIN = 1_024;
+const CONTEXT_TOOL_MAX = 1_048_576;
+const CONTEXT_POLICY_TEXT = `Omit it to accept the platform default: min(model native max, ${CONTEXT_DEFAULT_CEILING}) tokens, `
+    + `falling back to ${CONTEXT_UNKNOWN_FALLBACK} when the model's native window is unknown (a model whose own window is `
+    + `smaller keeps its own). The hard ceiling is the model's OWN native window — a larger value is rejected. `
+    + `Read model.native_max_context from preflight_inference before proposing a value; `
+    + `the ${CONTEXT_TOOL_MIN}-${CONTEXT_TOOL_MAX} range accepted here is only a sanity bound, never a per-model ceiling.`;
+/**
+ * Context-length input with truthful bounds and self-contained rejection text.
+ * The MCP SDK renders a zod failure as its raw issue list, so the message on
+ * each bound has to carry the whole answer by itself — otherwise the caller
+ * gets a schema dump with no instruction.
+ */
+/* ─── Precision ───
+ * Precision is a sizing input, so it is a PRICE input: it sets the VRAM
+ * estimate, which sets the minimum GPU count, which sets the hourly total. An
+ * agent that writes "FP8" is asking for fp8, and must not be quoted the bf16
+ * price for it. Canonicalize case and whitespace before validating, then refuse
+ * anything outside the vocabulary BY NAME. bf16/fp16 are accepted spellings of
+ * "serve the checkpoint at its own precision", which is what none means.
+ */
+const QUANT_FORMATS = ["fp8", "awq", "gptq", "int4"];
+const NATIVE_PRECISION_ALIASES = ["none", "bf16", "bfloat16", "fp16", "float16"];
+function quantSchema(purpose) {
+    return z
+        .string()
+        .transform((v) => v.trim().toLowerCase())
+        .refine((v) => NATIVE_PRECISION_ALIASES.includes(v)
+        || QUANT_FORMATS.includes(v), {
+        error: (issue) => `${String(issue.input)} is not a precision this platform can serve. `
+            + `Use one of: ${QUANT_FORMATS.join(", ")}, or none.`,
+    })
+        .transform((v) => (NATIVE_PRECISION_ALIASES.includes(v) ? "none" : v))
+        .optional()
+        .describe(`${purpose} One of ${QUANT_FORMATS.join(", ")} or none. Case does not matter, `
+        + "and bf16/fp16 mean the same as none. Anything else is refused by name rather "
+        + "than sized at another precision.");
+}
+function contextLengthSchema(purpose) {
+    return z
+        .number()
+        .int({ error: "context_length must be a whole number of tokens." })
+        .min(CONTEXT_TOOL_MIN, {
+        error: (issue) => `context_length ${String(issue.input)} is below ${CONTEXT_TOOL_MIN} tokens, which cannot serve a request. `
+            + CONTEXT_POLICY_TEXT,
+    })
+        .max(CONTEXT_TOOL_MAX, {
+        error: (issue) => `context_length ${String(issue.input)} is above the ${CONTEXT_TOOL_MAX}-token sanity bound of this tool. `
+            + CONTEXT_POLICY_TEXT,
+    })
+        .optional()
+        .describe(`${purpose} ${CONTEXT_POLICY_TEXT}`);
+}
+/* ─── Spend-consent bounds (the one field that authorizes money) ───
+ * max_price_hour_cents is CONSENT, not a filter: it is the maximum total hourly
+ * price for the complete GPU count that the platform may charge without asking
+ * the user again. The server has no ceiling of its own — it only refuses a cap
+ * BELOW the primary placement's verified price (deployment-service
+ * validateInferenceGPUPriceContract, training-service validateTrainingRequest)
+ * — so `z.number().int()` alone advertised MAX_SAFE_INTEGER, i.e. told an agent
+ * that consenting to nine quadrillion cents an hour is a legal request. The
+ * ceiling below comes from what the platform can actually book: the most
+ * expensive placement in the GPU catalog is 8 x B300 at 1035 cents per GPU-hour
+ * = 8280 cents/hour total, and the beta serving cap (models up to ~130B total
+ * parameters) keeps a deployment inside that ladder. 100000 cents ($1,000/hour)
+ * is roughly twelve times the dearest bookable configuration: high enough that
+ * it can never reject a real cap, low enough that it is a limit rather than a
+ * blank cheque. It is a sanity bound, not a price quote — the authority is
+ * always the preflight response. */
+const PRICE_CAP_TOOL_MAX = 100_000;
+const priceCapPolicyText = (floor) => "This is SPEND CONSENT, not a filter: the maximum accepted TOTAL hourly price for the complete GPU count, in cents. "
+    + "Copy the cap the user approved from the preflight response (billing.max_price_hour_cents, or the chosen placement's "
+    + "total_price_hour_cents) — never invent one. The server rejects a cap BELOW the primary placement's current price, and "
+    + `omitting it accepts the verified price of the placements already approved. The ${floor}-${PRICE_CAP_TOOL_MAX} range here `
+    + "is a sanity bound on consent (the dearest configuration the GPU catalog can book is well under it), not a price quote and "
+    + "not a per-model ceiling; get_gpu_pricing and preflight give the real numbers.";
+/**
+ * Price-cap input with a defensible ceiling and self-contained rejection text.
+ * `allowZero` covers the training tools, where 0 is the documented "no explicit
+ * cap — accept the verified placement price" value; the deployment tools require
+ * a positive cap (deployment-contract.ts rejects <= 0).
+ */
+function priceCapSchema(allowZero) {
+    const floor = allowZero ? 0 : 1;
+    const policy = priceCapPolicyText(floor);
+    return z
+        .number()
+        .int({ error: "max_price_hour_cents must be a whole number of cents." })
+        .min(floor, {
+        error: (issue) => `max_price_hour_cents ${String(issue.input)} is below ${floor}. `
+            + (allowZero
+                ? "A cap cannot be negative; pass 0 (or omit it) to accept the verified placement price. "
+                : "Omit it instead of passing 0 or a negative number to accept the verified placement price. ")
+            + policy,
+    })
+        .max(PRICE_CAP_TOOL_MAX, {
+        error: (issue) => `max_price_hour_cents ${String(issue.input)} is above the ${PRICE_CAP_TOOL_MAX}-cent/hour ($1,000/hour) sanity bound `
+            + "of this tool. A cap that large is not a limit — it authorizes any price the platform could ever charge. "
+            + policy,
+    })
+        .optional()
+        .describe(policy);
+}
+/* ─── Training context window (max_seq_length) ───
+ * Same defect as context_length before #789: `max(10_000_000)` is not a policy,
+ * it is a number nothing enforces. The authoritative contract is
+ * get_training_capabilities, whose `max_length` field states the platform's
+ * default (2048) and its floor (128); the real ceiling is the base model's own
+ * position-embedding window, which no static JSON Schema can express. So the
+ * schema advertises the contract's floor and the same sanity ceiling serving
+ * uses, and the description names the real authority. */
+const TRAINING_SEQ_TOOL_MIN = 128;
+const TRAINING_SEQ_DEFAULT = 2_048;
+const TRAINING_SEQ_POLICY_TEXT = `Training sequence length in tokens (sent as config.max_length). Omit it to accept the platform default of ${TRAINING_SEQ_DEFAULT}. `
+    + "The hard ceiling is the BASE MODEL's own context window — a longer value wastes GPU memory on padding and can fail the fit "
+    + `check — and the authoritative field bounds live in get_training_capabilities (max_length). The ${TRAINING_SEQ_TOOL_MIN}-`
+    + `${CONTEXT_TOOL_MAX} range accepted here is only a sanity bound, never a per-model ceiling: read the model's window from `
+    + "get_model_config or preflight_training_job before proposing a value. Longer sequences raise memory use roughly linearly, "
+    + "so raise it deliberately, not by default.";
+const MAX_TOKENS_POLICY_TEXT = "Maximum tokens to GENERATE for this completion. Omit it to let the endpoint choose. The real ceiling is the deployment's "
+    + `served context window MINUS the prompt (read context_length from get_inference_status or the create response); the 1-`
+    + `${CONTEXT_TOOL_MAX} range accepted here is only a sanity bound, never the window of the model being called. Tokens are `
+    + "billed, so ask for what the answer needs rather than the maximum.";
+function trainingSeqLengthSchema() {
+    return z
+        .number()
+        .int({ error: "max_seq_length must be a whole number of tokens." })
+        .min(TRAINING_SEQ_TOOL_MIN, {
+        error: (issue) => `max_seq_length ${String(issue.input)} is below the ${TRAINING_SEQ_TOOL_MIN}-token floor of the training contract. `
+            + TRAINING_SEQ_POLICY_TEXT,
+    })
+        .max(CONTEXT_TOOL_MAX, {
+        error: (issue) => `max_seq_length ${String(issue.input)} is above the ${CONTEXT_TOOL_MAX}-token sanity bound of this tool. `
+            + TRAINING_SEQ_POLICY_TEXT,
+    })
+        .optional()
+        .describe(TRAINING_SEQ_POLICY_TEXT);
+}
+// Reuse this exact schema for preflight and create. The helper beneath it
+// performs the source-dependent checks that a flat MCP input schema cannot.
+const deploymentCreateToolSchema = {
+    name: z.string().min(1).max(255).describe("Deployment display name."),
+    source_type: z
+        .enum(DEPLOYMENT_SOURCE_TYPES)
+        .describe("Deploy a verified training checkpoint or a base model from the catalog."),
+    source_job_id: z
+        .string()
+        .optional()
+        .describe("Owning training job ID; required with source_type=checkpoint."),
+    source_checkpoint_id: z
+        .string()
+        .optional()
+        .describe("Verified checkpoint ID; required with source_type=checkpoint."),
+    hf_model_id: z
+        .string()
+        .optional()
+        .describe("Catalog model id (see list_models); required when deploying a hosted base model (source_type=hf_model, the legacy wire name). Must be hosted on Run BiOS."),
+    hf_model_revision: z
+        .string()
+        .regex(/^[0-9a-f]{40}$/)
+        .optional()
+        .describe("Exact model commit from preflight_inference canonical_request. Copy it unchanged into create_inference."),
+    hf_integration_id: z
+        .string()
+        .optional()
+        .describe("Legacy field kept for compatibility — catalog models are pre-mirrored and never gated, so no integration is needed. Raw tokens are not accepted by MCP."),
+    base_model_id: z
+        .string()
+        .optional()
+        .describe("Base model for an adapter checkpoint; normally resolved from training lineage."),
+    base_model_revision: z
+        .string()
+        .regex(/^[0-9a-f]{40}$/)
+        .optional()
+        .describe("Exact base-model commit from preflight_inference canonical_request. Copy it unchanged into create_inference."),
+    // serving_mode, model_task and supports_images are DELIBERATELY ABSENT.
+    // All three are derived server-side and immutable: the serving mode comes
+    // from the verified checkpoint's lineage, the OpenAI task from the resolved
+    // model (chat, or completion for a base model with no chat template, or
+    // embedding/rerank for those architectures), and image support from the
+    // model's own config. Advertising them as inputs invited exactly the 400s the
+    // create gate now returns ("configured automatically from the model itself
+    // ... and cannot be changed"). They are reported back on the
+    // preflight/create/status response, which is where a caller reads them.
+    gpu_type: z
+        .string()
+        .min(1)
+        .describe("Exact GPU SKU approved after reviewing authoritative deployment options."),
+    gpu_count: z
+        .number()
+        .int()
+        .min(1)
+        .max(8)
+        .describe("Tensor-parallel GPU count accepted by the model-fit option."),
+    gpu_priorities: z
+        .array(z.object({
+        gpu_type: z.string().min(1), gpu_count: z.number().int().min(1).max(8),
+        provider: z.string().min(1).max(30).optional(), region: z.string().min(1).max(64).optional(),
+        tier: z.literal("secure").optional(),
+    }))
+        .min(1)
+        .max(5)
+        .optional()
+        .describe("Ranked GPU placement choices. Copy these unchanged from the preflight response's accepted choices; the platform fills in and manages infrastructure placement automatically. Queueing requires 3-5 distinct entries; entry one must match gpu_type/gpu_count."),
+    gpu_tier: z
+        .enum(DEPLOYMENT_GPU_TIERS)
+        .optional()
+        .describe("Deployment serving supports secure capacity only; defaults to secure."),
+    allow_capacity_queue: z
+        .boolean()
+        .optional()
+        .describe("Explicit consent to wait up to seven days if this exact SKU is unavailable; defaults to false."),
+    max_price_hour_cents: priceCapSchema(false),
+    storage_gb: z.number().int().min(1).max(10000).optional(),
+    context_length: contextLengthSchema("Serving context window in tokens."),
+    quant: quantSchema("Runtime precision. Pre-quantized checkpoint precision may be locked."),
+    serving_config: z
+        .record(z.string(), z.unknown())
+        .optional()
+        .describe("Advanced serving arguments; the server applies its strict allowlist."),
+};
+const deploymentCreateMutationToolSchema = {
+    ...deploymentCreateToolSchema,
+    idempotency_key: z
+        .string()
+        .regex(/^[A-Za-z0-9._:-]{8,128}$/)
+        .describe("Stable retry key. Reuse the same value with the unchanged payload after timeouts to recover the same deployment and one-time inference key."),
+};
+/* ─── Response shaping that keeps provenance honest ─── */
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function nonEmptyString(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+/* ─── Internal build references never leave the platform ─── */
+/**
+ * Recursively redact every string in a JSON-shaped value, counting the fields
+ * that carried something.
+ *
+ * Redacting by KEY was defeated the moment the same value appeared under a
+ * different key: dropping `image_tag` left the identical
+ * `<registry>/<engine>@sha256:<digest>` in the free-text `notes` of 194
+ * training-scope rows, and the inference scope has the same shape waiting in
+ * the "dropped by engine <tag>" note its auto-disable pass writes. So the rule
+ * is content, not field name, and it runs over every string in the payload.
+ *
+ * The matching itself lives in redaction.ts and is NOT repeated here. An
+ * earlier revision of this module carried its own pattern list anchored on a
+ * plaintext array of the engine repositories Run BiOS builds — and `npm publish`
+ * ships dist/, so that array handed every customer the exact roster the
+ * redactor exists to protect (test/build-identity-leak.test.ts pins this, and
+ * the console hit the identical defect in its own leak guard). redaction.ts
+ * matches the same references by SHAPE plus salted hashes of the names, so it
+ * is strictly stronger AND publishes nothing.
+ */
+function redactDeep(value, counter) {
+    if (typeof value === "string") {
+        const out = redactBuildIdentity(value);
+        if (out !== value)
+            counter.hits += 1;
+        return out;
+    }
+    if (Array.isArray(value))
+        return value.map((entry) => redactDeep(entry, counter));
+    const record = asRecord(value);
+    if (!record)
+        return value;
+    const out = {};
+    for (const [key, entry] of Object.entries(record))
+        out[key] = redactDeep(entry, counter);
+    return out;
+}
+/**
+ * Label the architecture registry's provenance instead of shipping it bare.
+ *
+ * Each row in the registry TABLE records image_tag/bios_version/manifest_sha256
+ * from the serving image whose capability manifest last published it. That is
+ * REGISTRY PROVENANCE, not the image the platform is running now, and the two
+ * drift apart whenever a newer image has not re-published the manifest. An
+ * agent that reads a build reference next to a support list concludes "the
+ * platform runs this build" and tells the user a stale version — a wrong action
+ * caused purely by presentation. The support decision itself IS authoritative
+ * (the deploy gate reads these same rows), so the rows are preserved; the
+ * internal image reference is removed by CONTENT from every field of every
+ * scope (see redactBuildReferences) and replaced with an explicit provenance
+ * block. Fixing the underlying manifest staleness is a control-plane concern
+ * and is deliberately NOT duplicated here.
+ *
+ * Those three columns no longer REACH this function: the public endpoint
+ * projects them away before the response leaves the control plane. What arrives
+ * here is the customer projection, and this block must describe that.
+ *
+ * The block itself only asserts what the rows actually carry, and since the
+ * control plane started projecting this endpoint that is LESS than it once was:
+ * image_tag, bios_version and manifest_sha256 are dropped at the boundary now
+ * (publicArchRow in deployment-service), so no response can still see them.
+ * Counting them here would therefore report 0 forever and drive the block to
+ * announce "no row records a build version" about a registry whose rows do —
+ * narrating a field that is empty on every row is the same defect one level up,
+ * and asserting a fact about rows this layer can no longer inspect is worse.
+ * `source` is the discriminator that survives the projection, so it is the one
+ * this block counts on.
+ */
+export function annotateArchitectureProvenance(data) {
+    const payload = asRecord(data);
+    if (!payload || !Array.isArray(payload.architectures))
+        return data;
+    const counter = { hits: 0 };
+    let manifestRows = 0;
+    let lastPublished = "";
+    const architectures = payload.architectures.map((entry) => {
+        const row = asRecord(entry);
+        if (!row)
+            return redactDeep(entry, counter);
+        // Belt and braces: the boundary already omits image_tag, so this destructure
+        // only matters if the projection ever regresses. It is cheap and it is the
+        // reason this file carries a REVIEWED entry in the leak-gate allowlist —
+        // deleting it means deleting that entry too, or the gate fails on a stale one.
+        const { image_tag: _internalImageReference, ...rest } = row;
+        if (nonEmptyString(row.source) === "manifest")
+            manifestRows += 1;
+        const updated = nonEmptyString(row.updated_at);
+        if (updated && updated > lastPublished)
+            lastPublished = updated;
+        return redactDeep(rest, counter);
+    });
+    // Every OTHER field of the envelope goes through the same content rule: the
+    // whole point is that no field name is trusted, including one the control
+    // plane has not added yet.
+    const { architectures: _rows, ...envelope } = payload;
+    return {
+        ...redactDeep(envelope, counter),
+        architectures,
+        manifest_provenance: {
+            note: "Architecture support and the enabled flags are authoritative — the deployment gate reads these same rows. "
+                + "Some rows were published by an internal build's capability manifest, and the count below says how many. WHICH "
+                + "build is not part of this response at all: the platform does not publish it on this endpoint, so nothing here "
+                + "names or numbers an engine build. Do not report a platform version from this response, and do not infer from "
+                + "the absence that the registry is stale or current — this response cannot tell you either way. "
+                + "Build identity is removed by key AND by content from every field, so nothing here names the engine the platform runs.",
+            // The COUNTS are the honest signal; the VALUES are not. An earlier revision
+            // of this block also listed `recorded_bios_versions` — the distinct engine
+            // build versions read off the rows — which handed the caller the exact
+            // build identity every other rule here removes. Counting says as much about
+            // staleness and names nothing. Its siblings that counted build versions and
+            // manifest digests are gone for the opposite reason: after the boundary
+            // projection they could only ever have counted 0.
+            rows: architectures.length,
+            rows_from_a_published_manifest: manifestRows,
+            last_row_update: lastPublished || null,
+            // Counts FIELDS that carried a reference, not individual references: the
+            // matcher rewrites a whole string in one pass, so a per-occurrence tally
+            // would be a guess. Named for what it actually measures.
+            fields_with_build_references_redacted: counter.hits,
+        },
+    };
+}
+/** Say what the reported GPU means in the deployment's current lifecycle state. */
+function gpuState(status) {
+    switch (status) {
+        case "queued_capacity":
+            return "not held yet — waiting for stock, nothing charged";
+        case "running":
+        case "degraded":
+            return "held and serving";
+        case "provisioning":
+        case "downloading_weights":
+        case "loading_model":
+            return "being booked or booting — not serving yet";
+        case "stopped":
+        case "paused_insufficient_funds":
+        case "failed":
+        case "crash_loop":
+        case "deleting":
+        case "deleted":
+            return "not held — this is the SKU the deployment would resume on";
+        default:
+            return "unknown";
+    }
+}
+/**
+ * Summarize what a deployment detail payload ACTUALLY proves about the GPU and
+ * the lifecycle phase.
+ *
+ * The detail response is wide and reports several things as null until a pod
+ * callback lands, which reads to an agent as "no GPU" and "no phase" on a
+ * deployment that is demonstrably provisioning on a known SKU. Everything here
+ * is derived from fields the same payload returned — nothing is invented, and a
+ * value that cannot be derived stays "unknown" instead of being guessed.
+ */
+export function summarizeInferenceStatus(data) {
+    const payload = asRecord(data);
+    if (!payload)
+        return data;
+    const status = nonEmptyString(payload.status) ?? "unknown";
+    const gpuType = nonEmptyString(payload.gpu_type);
+    const gpuCount = typeof payload.gpu_count === "number" ? payload.gpu_count : undefined;
+    const gpu = gpuType ? `${gpuCount && gpuCount > 0 ? gpuCount : 1}x ${gpuType}` : "unknown";
+    const download = asRecord(payload.download_progress);
+    const boot = asRecord(payload.boot_progress);
+    // Phase precedence: the agent's own weight/load report is the most advanced
+    // signal, then the pre-agent boot report, then the durable lifecycle status.
+    const reportedPhase = nonEmptyString(download?.phase) ?? nonEmptyString(boot?.phase);
+    const phaseSource = nonEmptyString(download?.phase)
+        ? "agent_progress_report"
+        : nonEmptyString(boot?.phase)
+            ? "pre_agent_boot_report"
+            : "deployment_status";
+    const percent = typeof download?.percent === "number"
+        ? download.percent
+        : typeof boot?.percent === "number" ? boot.percent : null;
+    const endpoint = nonEmptyString(payload.endpoint_url);
+    const summary = {
+        status,
+        phase: reportedPhase ?? status,
+        phase_source: phaseSource,
+        phase_percent: percent,
+        gpu,
+        gpu_tier: nonEmptyString(payload.gpu_tier) ?? "unknown",
+        // What the GPU above MEANS right now: a queued or provisioning deployment
+        // does not hold the SKU yet, it is the one being waited/booked for.
+        gpu_state: gpuState(status),
+        endpoint_usable: status === "running" && Boolean(endpoint),
+        desired_state: nonEmptyString(payload.desired_state) ?? "unknown",
+        error_code: nonEmptyString(payload.error_code) ?? nonEmptyString(payload.status_reason) ?? null,
+        note: "Derived by the MCP server from the fields in this same response; the raw fields above are unchanged. "
+            + "Report the endpoint as live only when endpoint_usable is true.",
+    };
+    const shaped = { ...payload, status_summary: summary };
+    // A present-but-null `gpu`/`phase` reads as "there is none" even when the row
+    // proves otherwise. Fill from the derived value and say so, rather than
+    // passing a null the agent will misread.
+    for (const key of ["gpu", "phase"]) {
+        if (key in shaped && shaped[key] === null && summary[key] !== "unknown") {
+            shaped[key] = summary[key];
+            summary.filled_null_fields = [...(summary.filled_null_fields ?? []), key];
+        }
+    }
+    return shaped;
+}
+/* ─── Server setup ─── */
+export function createBiosMcpServer(client, hooks, deploymentCaps, 
+// Pre-launch surface gates (src/config.ts). While a gate is on, its creation
+// tools are NOT REGISTERED at all — hidden from tools/list so an agent never
+// learns they exist — and the platform guide stops teaching their workflows.
+// Defaults read the environment so a deployment with nothing set fails CLOSED
+// (gated) while pre-launch; tests that exercise creation pass
+// { training: false, datasets: false }.
+launchGates = resolveLaunchGates()) {
+    // `instructions` reaches the client at initialize, BEFORE any tool description
+    // is read, which is the only place to state the rules a tool schema cannot: an
+    // agent that learns the derived-settings and catalog rules up front never
+    // proposes a value the control plane must reject.
+    // While a creation surface is gated, the instructions must not present it as
+    // available: an agent reads these BEFORE any tool list, and a capability named
+    // here is a capability it will try. The gated wording names what is live and
+    // states — once, without naming tool names — that creation is not offered.
+    const gatedSurfaces = [
+        ...(launchGates.training ? ["fine-tuning"] : []),
+        ...(launchGates.datasets ? ["dataset upload/import"] : []),
+    ];
+    const prelaunchNote = gatedSurfaces.length
+        ? `${gatedSurfaces.join(" and ")} ${gatedSurfaces.length > 1 ? "are" : "is"} not available in this deployment yet — `
+            + "no creation tools for them are offered, so do not attempt to start one or look for a workaround. "
+            + "Existing jobs and datasets stay readable.\n"
+        : "";
+    const mcp = new McpServer({
+        name: "Run BiOS",
+        version: VERSION,
+    }, {
+        instructions: (launchGates.training
+            ? "Run BiOS serves models on its own GPU control plane. Call get_platform_guide first.\n"
+            : "Run BiOS trains and serves models on its own GPU control plane. Call get_platform_guide first.\n")
+            + prelaunchNote
+            + "Rules that no tool schema can express:\n"
+            + (launchGates.training
+                ? "1. Models: only ids in the Run BiOS catalog can be served (list_models / search_models). "
+                : "1. Models: only ids in the Run BiOS catalog can be trained or served (list_models / search_models). ")
+            + "This is not a Hugging Face lookup; an id outside the catalog is rejected, never mirrored on demand.\n"
+            + "2. Serving is platform-derived: serving mode (full/adapter/merged), the OpenAI task "
+            + "(chat, or completion for a base model with no chat template, or embedding/rerank), and image support are "
+            + "derived from the model and checkpoint lineage. They are not tool inputs — read them from the "
+            + "preflight/create/status response.\n"
+            + `3. Context window: the default is min(model native max, ${CONTEXT_DEFAULT_CEILING}) tokens, falling back to `
+            + `${CONTEXT_UNKNOWN_FALLBACK} when the native window is unknown, and the hard ceiling is the model's own native max. `
+            + "Read model.native_max_context from preflight_inference before proposing a value.\n"
+            + "4. GPUs and money: never substitute a GPU or exceed an approved price cap without asking. A capacity "
+            + "rejection arrives as compact JSON with bookable alternatives; a 503 is a transient outage, never an out-of-stock verdict.\n"
+            + "5. Report an endpoint as live only when the status says running.",
+    });
+    // The registrations below are moved verbatim from the original single-file
+    // entry and intentionally keep their original indentation. `server.tool(...)`
+    // is a thin delegate that adds the onToolCall hook around each handler.
+    const server = {
+        tool(name, description, paramsSchema, cb) {
+            mcp.tool(name, description, paramsSchema, wrapToolHandler(name, cb, hooks?.onToolCall));
+        },
+    };
+    /* ══════════════════════════════════════════════════════════════════════════ */
+    /*  TOOL: get_platform_guide                                                */
+    /* ══════════════════════════════════════════════════════════════════════════ */
+    server.tool("get_platform_guide", launchGates.training || launchGates.datasets
+        ? "Get a comprehensive guide to the Run BiOS platform. Call this FIRST to understand the available capabilities, the correct workflow order, supported models, GPU tiers, and best practices for serving models."
+        : "Get a comprehensive guide explaining how to use the Run BiOS fine-tuning platform. Call this FIRST to understand the available capabilities, the correct workflow order, supported models, training methods, GPU tiers, dataset formats, and best practices. This gives you all the context needed to help users fine-tune models effectively.", {
+        topic: z
+            .enum([
+            "overview",
+            "quick_start",
+            "models",
+            "datasets",
+            "training_methods",
+            "gpu_selection",
+            "inference",
+            "hyperparameters",
+            "monitoring",
+            "cost_optimization",
+            "capacity_errors",
+        ])
+            .optional()
+            .describe("Specific topic to learn about. Omit for the full platform overview."),
+    }, async ({ topic }) => {
+        /* PRE-LAUNCH GATES (src/config.ts): while a creation surface is gated, the
+           guide must not teach its workflow — an agent that reads "call
+           upload_dataset" will try a tool that is not registered. Gated topics get
+           a stand-in that says what launches soon and names only tools that ARE
+           registered (reads/lifecycle stay live). At launch the gates open and the
+           real topics return verbatim. */
+        // 42 tools with every creation tool registered; the gates hide three
+        // (create_training_job, upload_dataset, import_huggingface_dataset). The
+        // coming-soon gate test pins this claim to the wire count, so drift fails.
+        const liveToolCount = 42
+            - (launchGates.training ? 1 : 0)
+            - (launchGates.datasets ? 2 : 0);
+        const comingSoonNote = `# Coming soon
+
+${gatedSurfaces.join(" and ")} ${gatedSurfaces.length > 1 ? "are" : "is"} not available in this build yet — the creation tools are not registered, so no tool call (and no workaround) can start one today. Do not retry or search for one.
+
+What still works: every read and lifecycle tool for existing datasets and training jobs (list_datasets, preview_dataset, delete_dataset, list_training_jobs, get_training_status, get_training_metrics, get_training_logs, get_training_evals, stop_training_job, resume_training_job, get_training_checkpoints, get_checkpoint_download_manifest, delete_training_checkpoint), and the full inference surface (preflight_inference, create_inference, get_inference_status, chat_with_inference).`;
+        const gatedOverview = `# Run BiOS Platform
+
+Run BiOS serves models on its own GPU control plane: a curated catalog of verified models — mirrored in its own storage, never fetched live from Hugging Face — deployed to dedicated OpenAI-compatible endpoints.
+
+## Core workflow (serving, fully live)
+1. **Find a model** — search_models / list_models read the hosted catalog; these are the only models that can be deployed
+2. **Check GPU fit and price** — get_inference_gpu_options joins model-fit counts to live stock and total hourly prices
+3. **Preflight** — preflight_inference validates the exact request with no wallet, queue, database, or GPU side effects
+4. **Create the deployment** — create_inference books capacity book-before-reveal; a definitive miss returns CAPACITY_UNAVAILABLE and nothing exists
+5. **Run** — poll get_inference_status until status is running; call the endpoint with chat_with_inference
+6. **Control spend** — stop_inference / resume_inference / restart_inference / delete_inference
+
+## Launching soon — not offered in this build
+${gatedSurfaces.join(" and ")} ${gatedSurfaces.length > 1 ? "launch" : "launches"} soon: the creation tools are not registered, so no tool call — and no workaround — can start one today. Existing datasets and training jobs are unaffected: every read and lifecycle tool below still works.
+
+## What the PLATFORM decides for you (do not try to set these)
+Serving settings are derived from the model itself and are immutable. They are
+NOT tool inputs, and attempting to choose one is rejected:
+- **Serving mode** (full / adapter / merged) comes from the verified checkpoint's
+  lineage; a catalog base model is always served whole.
+- **OpenAI task** comes from the resolved model: an instruct/chat model and a
+  vision-language model serve as chat, a base model with no chat template serves
+  as text completion, and an embedding/reranker architecture serves as
+  embeddings/reranking. Every model in the current catalog resolves to chat.
+- **Image input** comes from the model's own config, never from a caller claim.
+- **Context window**: the default is min(model native max, 262144) tokens; a
+  model whose native window is unknown falls back to 32768, a model with a
+  smaller window keeps its own, and the hard ceiling is always the model's OWN
+  native max. You may pass a smaller context_length; a larger one is rejected.
+  Read model.native_max_context from preflight_inference before proposing a value.
+Read the actual values back from preflight_inference, create_inference, and
+get_inference_status instead of asserting them.
+
+## Billing
+- Per-second GPU billing (NOT hourly) — you only pay for actual compute time
+- Wallet-based prepaid system with auto top-up option
+- New accounts get a $1 welcome credit — enough to try inference, not to fund a deployment
+- First top-up earns a deposit match: 50% within 24h of signup, 30% to 48h, 10% to 72h (deposits of $10+, bonus capped at $100)
+
+## Authentication
+- API Key (recommended): Use \`X-API-Key: bios-...\` header — org and workspace are resolved automatically
+- JWT token: Use \`Authorization: Bearer <token>\` header with \`X-Org-ID\` and \`X-Workspace-ID\` headers
+- Call introspect_api_key to see your permissions, scopes, and which tools you can use
+
+## Available MCP Tools (${liveToolCount} in this build, listed in recommended order)
+1. get_platform_guide - You're reading this! Context for all capabilities
+2. introspect_api_key - Discover your API key's permissions, scopes, and bound workspace
+3. get_wallet_balance - Check your credits before creating a deployment
+4. search_models / list_models - Find a model from the hosted catalog
+5. get_model_config - Recommended settings for a chosen model
+6. list_supported_architectures - Which architectures can be served
+7. get_gpu_pricing / get_recommended_gpu - GPU options and pricing
+8. list_integrations - Connected Hugging Face accounts
+9. list_datasets / preview_dataset / delete_dataset - Read and clean up existing datasets
+10. get_training_capabilities - Read the authoritative training contract
+11. preflight_training_job - Validate a proposed job payload (no side effects)
+12. list_training_jobs / get_training_status - Monitor existing jobs
+13. get_training_metrics / get_training_evals / get_training_logs - Loss curves, benchmarks, logs
+14. stop_training_job / resume_training_job - Control existing jobs
+15. get_training_checkpoints / get_checkpoint_download_manifest / delete_training_checkpoint - Checkpoint access
+
+## Inference MCP Tools
+1. get_inference_gpu_options - Read model-fit choices joined to authoritative deployment stock and prices
+2. preflight_inference - Validate the exact request without wallet, queue, database, or GPU side effects
+3. create_inference - Create only after reviewing preflight alternatives, queue consent, and the price cap
+4. get_inference_booking - Poll a book-before-reveal booking handle from a long-running create_inference
+5. list_inferences / get_inference_status - Read durable lifecycle, queue expiry reason, and wallet-authorization state
+6. get_inference_metrics - Read request, token, latency, throughput, and GPU utilization metrics plus a recent time series
+7. get_inference_notifications - Inspect durable email delivery, retries, and dead letters
+8. update_inference_policy - Change explicit queue consent or the maximum accepted hourly price
+9. stop_inference / resume_inference / restart_inference - Control serving lifecycle
+10. chat_with_inference - Call a serverless catalog model by id or a dedicated deployment via the unified /v1 endpoint (optional streaming)
+11. delete_inference - Permanently remove a deployment after verified infrastructure teardown`;
+        const guides = {
+            overview: `# Run BiOS Fine-Tuning Platform
+
+Run BiOS is a cloud fine-tuning platform for large language models. It hosts a curated catalog of verified base models — mirrored in its own storage, never fetched live from Hugging Face — trained natively by the BIOS training engine (supervised fine-tuning and continued pre-training; vision-language models train through SFT).
+
+## Core Workflow
+1. **Upload a dataset** — JSONL, Parquet, or CSV. The platform auto-validates format, detects columns, and maps fields.
+2. **Choose a base model** — Search the hosted Run BiOS catalog (search_models / list_models); every listed model is verified end-to-end and these are the only models that can be trained or deployed
+3. **Pick a training method** — SFT for instruction tuning (including vision-language models), CPT for continued pre-training on raw domain text
+4. **Select adapter** — LoRA (fast, efficient), QLoRA (lower VRAM), or Full fine-tune (max quality)
+5. **Configure hyperparameters** — learning rate, batch size, epochs, LoRA rank, etc. Smart defaults provided.
+6. **Choose a GPU** — A100 80GB, H100, A6000 etc. Platform recommends based on model size.
+7. **Launch and monitor** — Real-time loss curves, eval metrics, training logs, checkpoint saving
+8. **Download or deploy** — Get your fine-tuned model weights or merged checkpoints
+
+## What the PLATFORM decides for you (do not try to set these)
+Serving settings are derived from the model itself and are immutable. They are
+NOT tool inputs, and attempting to choose one is rejected:
+- **Serving mode** (full / adapter / merged) comes from the verified checkpoint's
+  lineage; a catalog base model is always served whole.
+- **OpenAI task** comes from the resolved model: an instruct/chat model and a
+  vision-language model serve as chat, a base model with no chat template serves
+  as text completion, and an embedding/reranker architecture serves as
+  embeddings/reranking. Every model in the current catalog resolves to chat.
+- **Image input** comes from the model's own config, never from a caller claim.
+- **Context window**: the default is min(model native max, 262144) tokens; a
+  model whose native window is unknown falls back to 32768, a model with a
+  smaller window keeps its own, and the hard ceiling is always the model's OWN
+  native max. You may pass a smaller context_length; a larger one is rejected.
+  Read model.native_max_context from preflight_inference before proposing a value.
+Read the actual values back from preflight_inference, create_inference, and
+get_inference_status instead of asserting them.
+
+## Billing
+- Per-second GPU billing (NOT hourly) — you only pay for actual compute time
+- Wallet-based prepaid system with auto top-up option
+- New accounts get a $1 welcome credit — enough to try inference, not to fund a deployment
+- First top-up earns a deposit match: 50% within 24h of signup, 30% to 48h, 10% to 72h (deposits of $10+, bonus capped at $100)
+
+## Authentication
+- API Key (recommended): Use \`X-API-Key: bios-...\` header — org and workspace are resolved automatically
+- JWT token: Use \`Authorization: Bearer <token>\` header with \`X-Org-ID\` and \`X-Workspace-ID\` headers
+- Call introspect_api_key to see your permissions, scopes, and which tools you can use
+
+## Available MCP Tools (42 in this build, listed in recommended order)
+1. get_platform_guide - You're reading this! Context for all capabilities
+2. introspect_api_key - Discover your API key's permissions, scopes, and bound workspace
+3. get_wallet_balance - Check if you have enough credits before training
+4. search_models / list_models - Find the right base model from the hosted catalog
+5. get_model_config - Get recommended settings for your chosen model
+6. list_supported_architectures - Check which architectures can be trained or served
+7. get_training_capabilities - Read the authoritative training contract; call this before building automated payloads
+8. get_gpu_pricing - See GPU options and pricing
+9. get_recommended_gpu - Get the best GPU for your model + adapter combo
+10. list_integrations - See the Hugging Face accounts connected to your workspace
+11. list_datasets / upload_dataset / import_huggingface_dataset - Prepare training data
+12. preview_dataset - Verify dataset format before training
+13. delete_dataset - Remove a dataset you no longer need
+14. preflight_training_job - Validate the full job before creating it
+15. create_training_job - Launch the fine-tuning job
+16. list_training_jobs / get_training_status - Monitor progress
+17. get_training_metrics - View loss curves and eval results
+18. get_training_evals - Review benchmark scores and quality assessments
+19. get_training_logs - Read training output logs
+20. stop_training_job / resume_training_job - Control running jobs
+21. get_training_checkpoints - Access saved model checkpoints
+22. get_checkpoint_download_manifest - Per-file download URLs for a checkpoint (only where model weight downloads are enabled for the workspace)
+23. delete_training_checkpoint - Remove a checkpoint you no longer need
+
+## Inference MCP Tools
+1. get_inference_gpu_options - Read model-fit choices joined to authoritative deployment stock and prices
+2. preflight_inference - Validate the exact request without wallet, queue, database, or GPU side effects
+3. create_inference - Create only after reviewing preflight alternatives, queue consent, and the price cap
+4. get_inference_booking - Poll a book-before-reveal booking handle from a long-running create_inference
+5. list_inferences / get_inference_status - Read durable lifecycle, queue expiry reason, and wallet-authorization state
+6. get_inference_metrics - Read request, token, latency, throughput, and GPU utilization metrics plus a recent time series
+7. get_inference_notifications - Inspect durable email delivery, retries, and dead letters
+8. update_inference_policy - Change explicit queue consent or the maximum accepted hourly price
+9. stop_inference / resume_inference / restart_inference - Control serving lifecycle
+10. chat_with_inference - Call a serverless catalog model by id or a dedicated deployment via the unified /v1 endpoint (optional streaming)
+11. delete_inference - Permanently remove a deployment after verified infrastructure teardown`,
+            quick_start: `# Quick Start Guide
+
+## Fastest path to a fine-tuned model:
+
+### Step 1: Check your balance
+Call get_wallet_balance to confirm you have credits available.
+
+### Step 2: Search for a model
+Call search_models with a query like "llama 8B" or "mistral 7B".
+For beginners: start with meta-llama/Llama-3.1-8B-Instruct (good balance of quality and speed).
+
+### Step 3: Prepare your dataset
+Option A: Upload your own file — call upload_dataset with the file path
+Option B: Import from HuggingFace — call import_huggingface_dataset with a repo ID
+
+Dataset must be JSONL: {"messages": [...]} per line for SFT, or {"text": "..."} per line for CPT. Other layouts are refused with conversion guidance.
+
+### Step 4: Get recommended config
+Call get_model_config with your model name to see recommended GPU, adapter, and hyperparameters.
+
+### Step 5: Create the training job
+Call create_training_job with:
+- model: the model name from step 2
+- dataset_id: the ID from step 3
+- method: "sft" for instruction tuning (most common)
+- adapter: "lora" (fastest, recommended for first jobs)
+- Leave other params as defaults unless you have specific needs
+
+### Step 6: Monitor progress
+create_training_job books a GPU before returning (~40s). A 'booked' status means the GPU is secured (booked==secured) and training is starting; 'securing' means it is still booking — poll get_training_status until 'booked'/'running'. A booking-time capacity miss returns CAPACITY_UNAVAILABLE and no job is created.
+Call get_training_status periodically. Training typically takes 1-4 hours for small models.
+If a started job loses its pod it rests at 'interrupted' (billing already stopped, not 'failed') — call resume_training_job to continue from the last checkpoint.
+Call get_training_metrics to see loss curves — loss should decrease steadily.
+
+### Tips
+- Start with LoRA, not full fine-tune — it's 10x faster and 5x cheaper
+- 3 epochs is usually enough — more can overfit
+- If loss plateaus early, try increasing learning rate slightly
+- Use early stopping if loss increases for several steps`,
+            models: `# Model Catalog
+
+Run BiOS serves a curated catalog of models hosted in its own storage — every
+listed model is verified end-to-end for training and serving, and these are
+the ONLY models that can be trained or deployed. The catalog is the source of
+truth: call list_models for everything currently hosted, or search_models to
+filter by name, provider, or size. A model that is not in the catalog is not
+hosted yet — ask an admin to mirror it.
+
+list_models and search_models read the same registry, so either one answers.
+If BOTH are unavailable, do not guess an id: any id already returned by
+list_inferences or list_training_jobs is known-hosted, the same catalog is on
+the Models page of the console, and reporting the catalog as unavailable is the
+correct answer. An unverified id fails the create gate anyway.
+
+Hosted families typically include Llama, Mistral, Qwen, Gemma, and Phi across
+small (1B-4B), medium (7B-13B), and large (30B-70B+) sizes, plus vision-
+language models — but the live catalog always wins over any list.
+
+## Choosing a Model
+- For general tasks: a 7B-8B instruct model (good balance of quality and cost)
+- For coding: a code-specialized instruct model from the catalog
+- For multilingual: Qwen models
+- For low-resource: a 1B-4B mini model
+- For maximum quality: a 70B-class model (requires multi-GPU)
+
+Use search_models to find hosted models by name or provider.
+Use get_model_config to see what training methods and GPUs work with a specific model.`,
+            datasets: `# Dataset Format Guide
+
+## One file type, one shape per training method
+Run BiOS accepts exactly one container -- **JSONL** (.jsonl, one JSON object per line) -- and exactly
+one shape per training method -- the industry-standard chat-transcript convention. Files in any
+other layout or container are refused at upload with a message naming what was detected and the exact
+shape to convert to. There is no column mapping: convert before uploading.
+
+## SFT (Supervised Fine-Tuning)
+Each line: {"messages": [...]} -- an ordered list of {role, content} turns.
+Roles: "system" (optional, first), "user", "assistant", "tool". The last assistant turn is what the
+model learns to produce. Assistant turns may include "tool_calls". Vision models use the same shape
+with image content parts.
+
+Example JSONL:
+{"messages": [{"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "What is the capital of France?"}, {"role": "assistant", "content": "Paris."}]}
+{"messages": [{"role": "user", "content": "Translate to French: Hello world"}, {"role": "assistant", "content": "Bonjour le monde"}]}
+
+## CPT (Continued Pre-Training)
+Each line: {"text": "..."} -- one document of raw text per line. Documents are packed to the training
+sequence length.
+
+Example JSONL:
+{"text": "One document of plain text per line."}
+
+## Converting other layouts
+- instruction/input/output -> one user turn (instruction + input) and one assistant turn (output)
+- prompt/completion, question/answer -> user turn and assistant turn
+- ShareGPT conversations (from/value) -> role/content with human -> user, gpt -> assistant
+- Preference pairs (chosen/rejected) and prompt-only RL formats are not accepted for training.
+
+## Best Practices
+- Minimum 100 rows recommended (1,000+ for best results)
+- Maximum 500MB file size through this tool
+- Consistent formatting across all rows; remove duplicates and low-quality examples
+- Pick max_seq_length above your longest sample: samples longer than it are dropped and reported`,
+            training_methods: `# Training Methods
+
+## SFT — Supervised Fine-Tuning ⭐ Most Common
+Best for: Teaching a model to follow specific instructions or generate in a particular style.
+Input: JSONL of {"messages": [...]} chat transcripts.
+When to use: First fine-tuning job, domain-specific tasks, style transfer, format compliance.
+Vision-language models: the same messages shape with image content parts.
+
+## CPT — Continued Pre-Training
+Best for: Injecting domain knowledge into the base model before fine-tuning.
+Input: Raw text documents.
+When to use: Before SFT, when your domain has specialized vocabulary/knowledge.
+
+## Recommended Pipeline
+1. CPT (if domain-specific knowledge needed) → 2. SFT
+For most users: SFT alone is sufficient.`,
+            gpu_selection: `# GPU Selection Guide
+
+## Available GPUs
+
+| GPU | VRAM | Best For | Per-Second Cost |
+|-----|------|----------|-----------------|
+| A6000 | 48 GB | Models up to 13B with LoRA | ~$0.0007/sec |
+| A100 80GB | 80 GB | Models up to 70B with QLoRA, up to 13B full | ~$0.0007/sec |
+| H100 | 80 GB | Large models, fastest training | ~$0.0011/sec |
+
+## Model Size → GPU Recommendations
+
+### LoRA Fine-Tuning (most common)
+- 1B-3B models: A6000 (48GB) — plenty of headroom
+- 7B-13B models: A100 80GB ⭐ sweet spot
+- 30B-70B models: A100 80GB or H100 (may need multi-GPU)
+
+### QLoRA Fine-Tuning (4-bit quantized, uses less VRAM)
+- 7B-13B models: A6000 (48GB) — enough with quantization
+- 30B-70B models: A100 80GB
+- 70B+ models: H100 or multi-GPU A100
+
+### Full Fine-Tuning (no adapter, maximum quality)
+- 1B-3B models: A100 80GB
+- 7B models: 2-4x A100 80GB
+- 13B+ models: 4-8x A100 or H100
+
+## Cost Optimization Tips
+- Run BiOS bills per-SECOND, not per-hour — stop jobs early to save money
+- LoRA training is 5-10x cheaper than full fine-tune for comparable quality
+- QLoRA adds ~10% training time but halves VRAM needs
+- Start with fewer epochs (1-2) to validate, then train full if results look good
+- Use the get_recommended_gpu tool to get the optimal GPU for your specific setup
+
+## Multi-GPU
+For models that don't fit in a single GPU's VRAM, the platform automatically shards across GPUs.
+Specify gpu_count in create_training_job (default: 1).
+
+## Infrastructure and Price Caps
+The platform selects and manages the underlying infrastructure automatically. You choose only the GPU type, the GPU count, and a maximum total hourly price cap. Preflight returns ranked alternatives and the exact price that will be honored. A price above the approved cap is rejected rather than silently accepted.`,
+            inference: `# Model Inference Guide
+
+Deployments serve either a verified fine-tuning checkpoint or a base model from the catalog through an OpenAI-compatible endpoint.
+
+## Settings the platform derives (not tool inputs)
+serving_mode, model_task and supports_images are SERVER-DERIVED and immutable,
+so preflight_inference/create_inference do not accept them:
+- serving_mode (full / adapter / merged) follows the verified checkpoint's
+  lineage; a catalog base model is served whole.
+- model_task follows 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 choose.
+- supports_images follows the model's own config.
+Read all three from the preflight/create response and from get_inference_status.
+If you copy canonical_request from preflight into create, these fields are
+ignored rather than honored — the server derives them again either way.
+
+## Context window
+- Default: min(model native max, 262144) tokens. A model whose native window is
+  unknown falls back to 32768; a model with a smaller native window keeps it.
+- Hard ceiling: the model's OWN native max. A larger context_length is rejected
+  with the model's maximum in the message; there is no platform-wide maximum you
+  can rely on, so read model.native_max_context from preflight_inference.
+- Raising the window enlarges the KV cache and can raise min_gpus, so re-read
+  get_inference_gpu_options after changing it.
+
+## Safe automation workflow
+1. Call get_inference_gpu_options with model facts to obtain model-fit counts plus authoritative deployment stock and total hourly prices.
+2. Choose a concrete GPU type/count. Never infer availability from fit alone and never substitute a different SKU without user approval.
+3. Call preflight_inference. Review selected_gpu, alternatives, queue_required, billing.authorization_amount_cents, and billing.max_price_hour_cents.
+4. If the chosen SKU is unavailable, ask the user to choose an available alternative or explicitly consent to allow_capacity_queue. The queue can wait up to seven days.
+5. Copy canonical_request from preflight—including hf_model_revision/base_model_revision—into create_inference with the approved maximum total hourly price. Store the one-time inference_key securely.
+6. Poll get_inference_status for durable queue/provisioning/loading/running state. Do not report the endpoint as live until status is running.
+7. Stop or delete when no longer needed. Resume reauthorizes capacity under the saved price cap.
+
+## Billing and capacity semantics
+- Preflight is side-effect free.
+- Create authorizes two hours at the accepted maximum price without immediately reducing wallet balance.
+- One hour at the final confirmed price is captured only after capacity is accepted, and a price above the cap is rejected.
+- Deployment serving supports the secure inventory tier only. Unknown inventory is reported as unknown, never as zero or available.
+- Training and deployment use the shared capacity broker. It evaluates priority first, then rotates fairly across users at equal priority while preserving FIFO inside each user's own requests. This prevents a high-volume user from starving others; do not describe the queue as strict global FIFO.`,
+            hyperparameters: `# Hyperparameter Guide
+
+## Key Hyperparameters
+
+### Learning Rate
+- Default: 2e-4 (0.0002)
+- Range: 1e-5 to 5e-4
+- Higher = faster learning but risk of instability
+- Lower = more stable but slower convergence
+- Tip: Start with 2e-4 for LoRA, 2e-5 for full fine-tune
+
+### Batch Size (per_device_train_batch_size)
+- Default: 4
+- Range: 1-32 (limited by GPU VRAM)
+- Larger = smoother gradients, more stable training
+- Smaller = faster per-step but noisier
+- Use gradient_accumulation_steps to simulate larger batches
+
+### Epochs (num_train_epochs)
+- Default: 3
+- Range: 1-10
+- More epochs = more passes through data
+- Watch for overfitting: if eval loss starts increasing, you've trained too long
+- For small datasets (<1000 rows): 3-5 epochs
+- For large datasets (>10000 rows): 1-3 epochs
+
+### LoRA Rank (lora_r)
+- Default: 16
+- Range: 4-256
+- Higher = more trainable parameters, better quality, but slower
+- 8-16 is sufficient for most tasks
+- 32-64 for complex tasks requiring more model capacity
+- 128+ for near-full-fine-tune quality
+
+### LoRA Alpha (lora_alpha)
+- Default: 32 (typically 2x lora_rank)
+- Controls the scaling of LoRA updates
+- Rule of thumb: set to 2x your lora_rank
+
+### Max Sequence Length
+- Default: 2048
+- Range: 512-8192
+- Must cover your longest training example
+- Longer = more VRAM usage
+- Set to slightly above your longest example
+
+### LR Scheduler
+- cosine (default) — gradually decreases, good for most tasks
+- linear — constant decrease, predictable
+- constant_with_warmup — stays flat after warmup, good for short training
+
+### Warmup Ratio
+- Default: 0.03 (3% of total steps)
+- Prevents early instability by slowly ramping up learning rate
+
+## Recommended Defaults by Use Case
+| Parameter | Quick Test | Standard | High Quality |
+|-----------|-----------|----------|--------------|
+| Adapter | LoRA | LoRA | Full |
+| Learning Rate | 3e-4 | 2e-4 | 2e-5 |
+| Epochs | 1 | 3 | 5 |
+| Batch Size | 4 | 4 | 8 |
+| LoRA Rank | 8 | 16 | 64 |
+| Scheduler | cosine | cosine | cosine |`,
+            monitoring: `# Training Monitoring Guide
+
+## Key Metrics to Watch
+
+### Training Loss
+- Should decrease steadily during training
+- Sharp drops early are normal (learning basic patterns)
+- Gradual decrease later shows fine-grained learning
+- If loss plateaus: try higher learning rate or more LoRA rank
+- If loss spikes: learning rate is too high, reduce it
+
+### Eval Loss (if eval dataset provided)
+- Should track training loss but may be slightly higher
+- If eval loss increases while training loss decreases = OVERFITTING
+- Early sign of overfitting: gap between train and eval loss growing
+- Action: Stop training and use the last checkpoint before divergence
+
+### Learning Rate
+- Should follow your chosen schedule (cosine, linear, etc.)
+- Warmup period: LR starts low and ramps up
+- Main phase: LR follows the schedule downward
+
+## Monitoring Tools
+1. get_training_status — Progress %, current step, elapsed time, ETA
+2. get_training_metrics — Full loss curve data for analysis
+3. get_training_logs — Raw training output for debugging
+4. get_training_checkpoints — Saved model snapshots at intervals
+
+## When to Stop Early
+- Loss has plateaued for many steps (no improvement)
+- Eval loss is increasing (overfitting)
+- You've reached satisfactory quality and want to save GPU cost
+- The model is producing good outputs in eval samples
+
+## Checkpoints
+- Saved automatically at regular intervals during training
+- Each checkpoint is a complete model snapshot you can use
+- If training is interrupted, resume from the last checkpoint
+- Best practice: compare outputs from different checkpoints to pick the best one`,
+            cost_optimization: `# Cost Optimization Guide
+
+## Per-Second Billing
+Run BiOS charges per-SECOND of GPU usage, not per hour. This means:
+- You only pay for actual compute time
+- Stopping a job immediately stops billing
+- No wasted time rounding up to the next hour
+
+## Cost Estimation
+Before launching a job, estimate cost:
+1. Call get_recommended_gpu for your model — it includes a cost estimate
+2. Rough formula: (dataset_rows / batch_size) × epochs × seconds_per_step × gpu_price_per_second
+
+## Money-Saving Strategies
+
+### 1. Start Small
+- Train for 1 epoch first to validate your setup
+- Check if the loss is decreasing and outputs look reasonable
+- Only then train for the full 3-5 epochs
+
+### 2. Use LoRA
+- LoRA is 5-10x cheaper than full fine-tune
+- Quality is comparable for most tasks
+- QLoRA is even cheaper (uses 4-bit quantization)
+
+### 3. Optimize Batch Size
+- Larger batch sizes = fewer total steps = less time
+- Use gradient accumulation to simulate large batches on limited VRAM
+
+### 4. Choose the Right GPU
+- Don't pick H100 for a 7B LoRA job — A100 is plenty and cheaper
+- Use get_recommended_gpu to find the cost-optimal choice
+
+### 5. Monitor and Stop Early
+- Watch the loss curve via get_training_metrics
+- If loss has plateaued, stop early — more epochs won't help
+- Check wallet balance with get_wallet_balance before long jobs
+
+### 6. Check Your Balance First
+- Call get_wallet_balance before creating a job
+- Ensure you have enough credits for the estimated training time
+- Set up auto top-up to avoid interruptions mid-training`,
+            capacity_errors: `# Standard GPU Rejection Errors
+
+Training and inference speak ONE GPU rejection contract: one body shape, and a
+code that tells you whether waiting can ever help. This MCP server hands you
+that body as compact JSON in the tool-error text.
+
+## Two classes, and the difference matters
+- CAPACITY_UNAVAILABLE (HTTP 409, reason insufficient_stock) is the ONLY
+  transient one: the GPU is simply not free right now. Retrying later or
+  joining the queue can succeed. Training also echoes the deprecated alias
+  SELECTED_GPU_UNAVAILABLE as legacy_code for one release.
+- GPU_TYPE_TOO_SMALL (model_too_large), GPU_COUNT_BELOW_MINIMUM
+  (below_model_minimum), GPU_COUNT_INVALID (invalid_gpu_count) and
+  GPU_TYPE_UNSUPPORTED (gpu_unsupported) are HTTP 400 and PERMANENT: the
+  request as submitted can never run on that GPU, whatever frees up. Change
+  gpu_type or gpu_count. Do NOT wait and do NOT queue.
+
+Read retryable_as_submitted (false = permanent) or queue_offered instead of
+parsing the message.
+
+## Body fields
+- reason: insufficient_stock | model_too_large | below_model_minimum | invalid_gpu_count | gpu_unsupported
+- selected: the gpu_type/gpu_count/tier that was refused, with its live availability_status/available_count
+- minimum_requirement: selected_gpu_min + selected_valid_counts for the chosen type, plus the per_type table (min_gpus + valid_counts for every type that fits the model). NEVER submit below min_gpus or outside valid_counts.
+- available_gpus: ALL currently bookable alternatives, cheapest first, each at its minimum count with valid_counts, available_count and price_hour_cents (available_alternatives is the deprecated alias)
+- queue_offered: true only for a stock miss. When it is true, you may resubmit with allow_capacity_queue=true to wait for stock, and nothing is charged while waiting. When it is false the queue cannot help this request at all.
+- queue_eligible: whether THIS request already asked to queue (never true when queue_offered is false)
+- gpu_priorities_entry: 1-based rank of the gpu_priorities entry that was refused, when the rejection belongs to one
+- checked_at: when the market snapshot behind the verdict was read
+
+## How to recover
+1. Pick an entry from available_gpus and retry the SAME call with its gpu_type and a gpu_count >= its min_gpus (the listed gpu_count is that minimum). With zero alternatives, read minimum_requirement.per_type for the types that fit.
+2. Only when queue_offered is true: resubmit with allow_capacity_queue=true (explicit user consent required) to auto-deploy when stock frees.
+3. Never invent a GPU/count; never treat unknown availability as out-of-stock; never re-send an unchanged request that was refused as permanent.
+
+## Book-before-reveal (inference creates)
+A non-queued create_inference answers 202 with a booking handle while a
+GPU is secured on real capacity (30-40s typical). The deployment id and the
+ONE-TIME inference_key exist only after the booking is confirmed. A definitive
+miss returns this standard error with FRESH alternatives and NO deployment
+exists (nothing charged, nothing to clean up). Poll get_inference_booking for
+long bookings.
+
+## Transient outages are NOT capacity answers
+503 ADMISSION_UNAVAILABLE (market/broker unreadable) means retry shortly.
+Never conclude out-of-stock from it.
+
+## After start
+Once a deployment has ever been booked, losing its GPU NEVER ends in a
+capacity failure: the platform replaces it across the ranked backup ladder and,
+when no stock exists anywhere, parks it as queued_capacity (waiting, zero
+charge) until stock returns. gpu_priorities backups may be ranked on ANY
+create (1-5 choices), and the queue itself stays opt-in.`,
+        };
+        // The overview and quick_start teach both creation workflows, so either
+        // gate swaps them out; the single-surface topics follow their own gate.
+        if (launchGates.training || launchGates.datasets) {
+            guides.overview = gatedOverview;
+            guides.quick_start = comingSoonNote;
+        }
+        if (launchGates.training) {
+            guides.training_methods = comingSoonNote;
+            guides.gpu_selection = comingSoonNote;
+            guides.hyperparameters = comingSoonNote;
+            guides.cost_optimization = comingSoonNote;
+        }
+        if (launchGates.datasets) {
+            guides.datasets = comingSoonNote;
+        }
+        if (topic && guides[topic]) {
+            return result(guides[topic]);
+        }
+        return result(guides.overview);
+    });
+    /* ══════════════════════════════════════════════════════════════════════════ */
+    /*  TOOL: introspect_api_key                                                */
+    /* ══════════════════════════════════════════════════════════════════════════ */
+    server.tool("introspect_api_key", "Discover what this API key can do. Returns the key's permissions (scopes), the org and workspace it's bound to, allowed MCP tools and SDK methods, rate limits, and expiration. Call this first to understand your access level and available capabilities.", {}, async () => {
+        const data = await client.api("/api/api-keys/introspect");
+        return json(data);
+    });
+    /* ══════════════════════════════════════════════════════════════════════════ */
+    /*  TOOL: get_wallet_balance                                                */
+    /* ══════════════════════════════════════════════════════════════════════════ */
+    server.tool("get_wallet_balance", "Check your current wallet balance, available credits, and pending charges. Call this before creating a training job to make sure you have enough credits. Returns available balance in dollars, pending charges from running jobs, and auto top-up status.", {}, async () => {
+        const data = await client.api("/api/billing/wallet");
+        return json(data);
+    });
+    /* ══════════════════════════════════════════════════════════════════════════ */
+    /*  TOOL: search_models                                                     */
+    /* ══════════════════════════════════════════════════════════════════════════ */
+    server.tool("search_models", launchGates.training
+        ? "Search the Run BiOS model catalog — the platform's own hosted, verified models. These are the ONLY models that can be deployed on Run BiOS; a model that is not listed is not hosted yet (ask an admin to mirror it). Filter by name, provider, or parameter count. Returns model id, author, parameter counts, architecture, and downloads/likes for each result."
+        : "Search the Run BiOS model catalog — the platform's own hosted, verified models. These are the ONLY models that can be fine-tuned or deployed on Run BiOS; a model that is not listed is not hosted yet (ask an admin to mirror it). Filter by name, provider, or parameter count. Returns model id, author, parameter counts, architecture, and downloads/likes for each result.", {
+        query: z.string().optional().describe("Search by model name (e.g., 'llama', 'mistral', 'phi', 'qwen')"),
+        provider: z.string().optional().describe("Filter by provider/author (e.g., 'meta-llama', 'mistralai', 'microsoft', 'Qwen')"),
+        max_params: z.string().optional().describe("Maximum parameter count (e.g., '7B', '13B', '70B')"),
+    }, async ({ query, provider, max_params }) => {
+        // The registry matches query tokens against normalized repo ids
+        // ("author/name"), so folding the provider into q turns it into a real
+        // author filter instead of a silently ignored parameter.
+        const q = [provider, query].filter(Boolean).join(" ").trim() || undefined;
+        const data = await client.api("/api/public/model-search", {
+            params: { q, max_params },
+        });
+        return json(data);
+    });
+    /* ══════════════════════════════════════════════════════════════════════════ */
+    /*  TOOL: list_models                                                       */
+    /* ══════════════════════════════════════════════════════════════════════════ */
+    server.tool("list_models", launchGates.training
+        ? "List every model hosted on Run BiOS — the platform's own verified registry, mirrored in Run BiOS storage (never a live Hugging Face listing). These are the only models that can be deployed. Call this before create_inference to pick a valid model id; use search_models to filter the same catalog by text."
+        : "List every model hosted on Run BiOS — the platform's own verified registry, mirrored in Run BiOS storage (never a live Hugging Face listing). These are the only models that can be fine-tuned or deployed. Call this before create_training_job or create_inference to pick a valid model id; use search_models to filter the same catalog by text.", {
+        type: z.enum(["all", "llm", "vlm"]).optional().describe("Filter by model surface (default: all)."),
+        sort: z.enum(["downloads", "likes", "trending", "name"]).optional().describe("Sort order (default: downloads)."),
+        limit: z.number().int().min(1).max(60).optional().describe("Page size (default 24, max 60)."),
+        offset: z.number().int().min(0).optional().describe("Pagination offset (default 0)."),
+    }, async ({ type, sort, limit, offset }) => {
+        const data = await client.api("/api/public/model-search", {
+            params: {
+                type: type && type !== "all" ? type : undefined,
+                sort,
+                limit: limit !== undefined ? String(limit) : undefined,
+                offset: offset !== undefined ? String(offset) : undefined,
+            },
+        });
+        return json(data);
+    });
+    /**
+     * Registry gate for model selection: Run BiOS can only train and serve models it
+     * hosts in its own registry. A definitive registry miss gets a clear,
+     * actionable error pointing at the catalog; any failure to ANSWER (registry
+     * unreachable) stays advisory — the server-side gate re-validates
+     * authoritatively and unknown never fails closed.
+     */
+    async function assertModelHosted(modelId, tool) {
+        const status = await client.modelRegistryStatus(modelId);
+        if (status === "not_hosted") {
+            // Same compact-JSON convention as the capacity errors: an MCP client is
+            // an AI agent and can act on the instruction directly. The instruction
+            // names every route to a valid id (see CATALOG_RECOVERY) rather than a
+            // single tool, so the advice still works when that tool is degraded.
+            throw new Error(JSON.stringify({
+                code: "MODEL_NOT_HOSTED",
+                message: `"${modelId}" is not in the Run BiOS model catalog, so it cannot be trained or served. Run BiOS only runs models it hosts and mirrors itself; ask an admin to mirror this one if you need it.`,
+                recoverable: true,
+                instruction: `${CATALOG_RECOVERY} Then retry ${tool} with that id.`,
+            }));
+        }
+    }
+    /**
+     * Rewrite a model-resolution failure into the answer that is both TRUE and
+     * actionable. The control plane surfaces its mirror's transport error verbatim
+     * ("Could not resolve the model for sizing: Hugging Face request returned
+     * 404"), which names an upstream vendor the caller cannot act on and never
+     * states the real answer: that id is not a Run BiOS catalog model. Callers here
+     * have already passed the registry gate, so a definitive catalog miss is
+     * impossible at this point — the remaining causes are a bad revision or a
+     * catalog entry whose mirrored facts cannot be read right now. Anything that is
+     * not a resolution failure (capacity JSON, auth, validation) is returned
+     * untouched.
+     */
+    function modelResolveFailure(error, modelId, tool) {
+        const text = error instanceof Error ? error.message : String(error);
+        const isResolveFailure = /hugging\s*face/i.test(text)
+            || /could not resolve (the model|an immutable)/i.test(text)
+            || /could not establish .*(immutable|commit)/i.test(text);
+        if (!isResolveFailure)
+            return error instanceof Error ? error : new Error(text);
+        const subject = modelId ? `"${modelId}"` : "the requested model";
+        if (/revision|commit/i.test(text)) {
+            return new Error(JSON.stringify({
+                code: "MODEL_REVISION_UNRESOLVED",
+                message: `Run BiOS could not pin an exact, immutable commit for ${subject}, so it refused to size or deploy it. The revision you supplied is not one it can verify.`,
+                recoverable: true,
+                instruction: `Omit the revision to let the platform pin the catalog's current commit, or copy hf_model_revision/base_model_revision unchanged from preflight_inference's canonical_request. Then retry ${tool}.`,
+                model: modelId,
+            }));
+        }
+        return new Error(JSON.stringify({
+            code: "MODEL_NOT_RESOLVED",
+            message: `Run BiOS could not resolve ${subject} from its own model catalog, so it cannot be sized or deployed. A model that is not in the catalog can never resolve; a catalog model can also fail this way while its mirrored facts are being re-synced.`,
+            recoverable: true,
+            instruction: `${CATALOG_RECOVERY} Then retry ${tool}. If the id IS listed in the catalog, report a catalog sync problem to the user or an admin instead of retrying in a loop.`,
+            model: modelId,
+        }));
+    }
+    /* ══════════════════════════════════════════════════════════════════════════ */
+    /*  TOOL: get_model_config                                                  */
+    /* ══════════════════════════════════════════════════════════════════════════ */
+    server.tool("get_model_config", launchGates.training
+        ? "Get configuration recommendations for a specific model hosted on Run BiOS (see list_models). Returns supported training methods, recommended GPU type and count, default hyperparameters, minimum VRAM required, and estimated cost per hour."
+        : "Get training configuration recommendations for a specific model hosted on Run BiOS (see list_models). Returns supported training methods, recommended GPU type and count, default hyperparameters, minimum VRAM required, and estimated cost per hour. Use this after search_models to plan your training job.", {
+        model: z.string().describe("Full model id from the Run BiOS catalog (e.g., 'meta-llama/Llama-3.1-8B-Instruct')"),
+        model_revision: z
+            .string()
+            .max(256)
+            .optional()
+            .describe("Model branch, tag, or commit. The response returns the exact immutable commit used for sizing."),
+        integration_id: z
+            .string()
+            .optional()
+            .describe("Legacy no-op for catalog models — hosted models are never gated. Integrations are used for Hugging Face dataset imports."),
+    }, async ({ model }) => {
+        const data = await client.api("/api/public/model-config", { params: { id: model } });
+        return json(data);
+    });
+    /* ══════════════════════════════════════════════════════════════════════════ */
+    /*  TOOL: list_supported_architectures                                      */
+    /* ══════════════════════════════════════════════════════════════════════════ */
+    server.tool("list_supported_architectures", "List the architectures Run BiOS supports, so you know what can be trained or served before you try. scope='inference' returns the model architecture classes (e.g. LlamaForCausalLM) that can be DEPLOYED for serving; scope='training' returns the architecture keys the fine-tuning gate accepts. If count is 0 the registry is empty and nothing is explicitly restricted (every architecture Run BiOS supports is allowed). Support here is authoritative: the deployment and training gates read these same rows. The response carries NO build or version identity of any kind — read manifest_provenance, which says how many rows came from a published manifest without naming any build. Never report a platform version from this tool. No authentication required.", {
+        scope: z.enum(["inference", "training"]).optional().describe("Which registry to read. Defaults to 'inference' (servable/deployable architectures)."),
+    }, async ({ scope }) => {
+        const data = await client.api("/api/public/serving-architectures", { params: { scope: scope || "inference" } });
+        // The registry TABLE holds the build identity of the engine image whose
+        // capability manifest published each row (image_tag/bios_version/
+        // manifest_sha256, and the same tag again inside free-text `notes`). None
+        // of it is a customer fact and it must never leave the platform, so the
+        // endpoint now projects those columns away before answering.
+        //
+        // Both passes still run, in this order, and neither is redundant — they
+        // defend against the projection regressing, which is the exact way this
+        // leak reached production the first time:
+        //   1. annotateArchitectureProvenance COUNTS how many rows came from a
+        //      manifest (from `source`, which survives the projection) and states
+        //      what the caller may conclude, so an agent cannot read provenance as
+        //      "the version the platform runs now". It goes FIRST because it needs
+        //      the rows before step 2 rewrites them.
+        //   2. sanitizeArchitectureRegistry then DROPS every build-identity key at
+        //      any depth and content-redacts what is left, so anything the
+        //      projection ever fails to strip still never ships.
+        return json(sanitizeArchitectureRegistry(annotateArchitectureProvenance(data)));
+    });
+    /* ══════════════════════════════════════════════════════════════════════════ */
+    /*  TOOL: get_gpu_pricing                                                   */
+    /* ══════════════════════════════════════════════════════════════════════════ */
+    server.tool("get_gpu_pricing", "Get current GPU pricing and availability. Returns all available GPU types with display name, VRAM in GB, per-second cost, availability status, and supported model sizes. No authentication required.", {}, async () => {
+        const data = await client.api("/api/public/gpu-pricing");
+        return json(data);
+    });
+    /* ══════════════════════════════════════════════════════════════════════════ */
+    /*  TOOL: get_recommended_gpu                                               */
+    /* ══════════════════════════════════════════════════════════════════════════ */
+    server.tool("get_recommended_gpu", "Get authoritative, model-aware GPU options from the training control plane. Returns required counts, live availability, total hourly prices, the cheapest currently bookable recommendation, and compatible alternatives when no GPU is available. It does not invent a duration or total-cost estimate.", {
+        model: z.string().describe("Full model name (e.g., 'meta-llama/Llama-3.1-8B-Instruct')"),
+        adapter: z.enum(TRAINING_ADAPTERS).optional().describe("Adapter type (default: 'lora')."),
+        method: z.enum(["sft", "pt"]).optional().describe("Canonical training method."),
+        model_params_b: z.number().positive().optional().describe("Optional total-parameter hint in billions."),
+        model_active_params_b: z
+            .number()
+            .positive()
+            .optional()
+            .describe("Optional active-parameter hint for MoE models in billions."),
+    }, async (params) => {
+        const data = await client.api("/api/training/gpu-options", {
+            params: buildGPUOptionsParams(params),
+        });
+        return json(data);
+    });
+    /* ══════════════════════════════════════════════════════════════════════════ */
+    /*  TOOL: get_inference_gpu_options                                         */
+    /* ══════════════════════════════════════════════════════════════════════════ */
+    server.tool("get_inference_gpu_options", "Get inference model-fit GPU choices joined to the authoritative deployment inventory and pricing snapshot. PREFER model-addressed sizing: pass model=<model_id> (optionally revision / hf_integration_id) and the SERVER resolves the facts (vision-aware) and returns computed min_gpus, valid_counts, and bookable_counts — the exact minimums the create gate enforces. Returns valid tensor-parallel counts, exact total hourly prices, availability as available/out_of_stock/unknown, and ranked alternatives. Never interpret unknown inventory as available, never offer a count below min_gpus or outside bookable_counts, and never substitute a SKU without user approval.", {
+        model: z.string().optional().describe("Model id for SERVER-resolved sizing (recommended); replaces every client-fact field below."),
+        revision: z.string().optional().describe("Exact model commit for model-addressed sizing."),
+        inference_id: z.string().optional().describe("Size from an existing deployment's pinned facts."),
+        hf_integration_id: z.string().optional().describe("Legacy field kept for compatibility — catalog models are pre-mirrored and never gated, so no integration is needed."),
+        params_b: z.number().positive().optional().describe("DEPRECATED client-fact path: total model parameters in billions; required only when model/inference_id are absent."),
+        active_params_b: z.number().positive().optional().describe("Active MoE parameters in billions, used only for throughput hints."),
+        is_moe: z.boolean().optional(),
+        is_multimodal: z.boolean().optional().describe("Vision tower present (client-fact path only): reserves extra VRAM and can raise minimums. Model-addressed sizing detects this automatically."),
+        quant: quantSchema("Precision to size the weights and KV cache for."),
+        context_length: contextLengthSchema("Context window to size the KV cache for."),
+        kv_heads: z.number().int().positive().optional(),
+        num_layers: z.number().int().positive().optional(),
+        kv_layers: z.number().int().positive().optional(),
+        head_dim: z.number().int().positive().optional(),
+        attention: z.enum(["gqa", "mla"]).optional(),
+        num_attention_heads: z.number().int().positive().optional(),
+        kv_lora_rank: z.number().int().positive().optional(),
+        qk_rope_head_dim: z.number().int().positive().optional(),
+        gpu_tier: z.enum(DEPLOYMENT_GPU_TIERS).optional(),
+    }, async (params) => {
+        // Gate the model against the Run BiOS catalog FIRST. Without it the control
+        // plane answers a sizing miss with its upstream mirror's 404 text, which
+        // names a vendor and hides the real answer ("that id is not in the Run BiOS
+        // catalog"). A registry that cannot answer stays advisory, exactly as on
+        // the create path. This endpoint also accepts the "repo@revision" form, so
+        // probe the repo id alone — the revision is not part of catalog identity.
+        const catalogId = params.model?.split("@")[0]?.trim();
+        if (catalogId)
+            await assertModelHosted(catalogId, "get_inference_gpu_options");
+        try {
+            const data = await client.api("/api/inference/gpu-options", {
+                params: buildDeploymentGPUOptionsParams(params),
+            });
+            return json(data);
+        }
+        catch (error) {
+            throw modelResolveFailure(error, params.model, "get_inference_gpu_options");
+        }
+    });
+    /* ══════════════════════════════════════════════════════════════════════════ */
+    /*  TOOL: preflight_inference                                                */
+    /* ══════════════════════════════════════════════════════════════════════════ */
+    server.tool("preflight_inference", "Validate and canonicalize a deployment without creating a database row, authorizing funds, entering a queue, or allocating a GPU. Returns verified model facts, selected price/stock, compatible alternatives, queue requirements, a request hash, and two-hour wallet-authorization terms. The response is also where you READ the derived serving settings: serving_mode, model_task, supports_images and the resolved context_length are chosen by the platform from the model and checkpoint lineage and cannot be set as inputs. Review this result with the user before create_inference.", deploymentCreateToolSchema, async (params) => {
+        if (params.source_type === "hf_model" && params.hf_model_id) {
+            await assertModelHosted(params.hf_model_id, "preflight_inference");
+        }
+        try {
+            const data = await client.api("/api/inference/preflight", {
+                method: "POST",
+                body: buildDeploymentBody(params),
+            });
+            return json(data);
+        }
+        catch (error) {
+            throw modelResolveFailure(error, params.hf_model_id ?? params.base_model_id, "preflight_inference");
+        }
+    });
+    /* ══════════════════════════════════════════════════════════════════════════ */
+    /*  TOOL: create_inference                                                   */
+    /* ══════════════════════════════════════════════════════════════════════════ */
+    /**
+     * Render a GPU type at a count readably: the type name already says GPU, so
+     * only the plural marker is added ("1 H100_80GB" vs "2 H100_80GB GPUs"). Keeps
+     * the synthesized copy identical to the server's.
+     */
+    const gpusOfType = (gpuType, count) => (count === 1 ? gpuType : `${gpuType} GPUs`);
+    /**
+     * Self-preflight (book-first §2): validate the chosen gpu_type/gpu_count
+     * against the SERVER's model-addressed sizing (computed min_gpus/valid_counts)
+     * BEFORE any create POST, and synthesize the standard structured GPU rejection
+     * when the selection can never be booked. Every rejection this raises is
+     * permanent (GPU_TYPE_TOO_SMALL / GPU_COUNT_BELOW_MINIMUM / GPU_COUNT_INVALID),
+     * never CAPACITY_UNAVAILABLE: the selection is unbookable whatever the stock is.
+     * Advisory only: a failure to ANSWER (endpoint unreachable) never blocks, the
+     * create gate re-validates authoritatively and unknown never fails closed.
+     */
+    async function assertInferenceGpuSelectionBookable(body) {
+        const model = (body.hf_model_id || body.base_model_id);
+        const gpuType = body.gpu_type;
+        const gpuCount = body.gpu_count;
+        if (!model || !gpuType || !Number.isInteger(gpuCount))
+            return;
+        let options;
+        try {
+            options = await client.api("/api/inference/gpu-options", {
+                params: {
+                    model: String(model),
+                    revision: (body.hf_model_revision || body.base_model_revision),
+                    quant: body.quant,
+                    context_length: body.context_length !== undefined ? String(body.context_length) : undefined,
+                    hf_integration_id: body.hf_integration_id,
+                },
+            });
+        }
+        catch {
+            return; // advisory only — the create gate is the enforcement floor
+        }
+        const chosen = options?.options?.find((option) => option?.gpu_type === gpuType);
+        if (!chosen)
+            return;
+        const minGpus = chosen.min_gpus || 0;
+        const validCounts = (chosen.valid_counts || []).filter((count) => Number.isInteger(count));
+        let reason;
+        let message = "";
+        if (chosen.selectable === false) {
+            reason = "model_too_large";
+            message = `This model does not fit on ${gpuType}, at any GPU count.`;
+        }
+        else if (minGpus > 0 && gpuCount < minGpus) {
+            reason = "below_model_minimum";
+            message = `This model needs at least ${minGpus} ${gpusOfType(gpuType, minGpus)} to run, and this request asked for ${gpuCount}.`;
+        }
+        else if (validCounts.length > 0 && !validCounts.includes(gpuCount)) {
+            reason = "invalid_gpu_count";
+            message = `This model cannot be split across ${gpuCount} ${gpusOfType(gpuType, gpuCount)}. Use one of these GPU counts instead: ${validCounts.join(", ")}.`;
+        }
+        if (!reason)
+            return;
+        const selectable = (options.options || []).filter((option) => option && option.selectable !== false);
+        const alternatives = selectable
+            .filter((option) => option.market?.availability_status === "available")
+            .map((option) => ({
+            gpu_type: option.gpu_type,
+            gpu_count: option.min_gpus,
+            min_gpus: option.min_gpus,
+            valid_counts: option.valid_counts,
+            tier: "secure",
+            available_count: option.market?.available_count ?? undefined,
+            price_hour_cents: (option.market?.price_per_gpu_hour_cents || 0) * (option.min_gpus || 1),
+        }));
+        // Same structured shape, codes and instruction text the transport serializes
+        // for real API GPU rejections, so agent clients handle exactly one contract.
+        // Every reason this pre-check can raise is a permanent fact about the request
+        // (the model does not fit, the count is below the model's minimum, the count
+        // cannot be used), so the code is never CAPACITY_UNAVAILABLE and the queue is
+        // never offered: waiting for stock could not book any of them.
+        const permanent = isPermanentGpuCode(gpuRejectionCodeFor(reason));
+        throw new Error(JSON.stringify({
+            code: gpuRejectionCodeFor(reason),
+            status: gpuRejectionStatusFor(reason),
+            reason,
+            message,
+            recoverable: true,
+            retryable_as_submitted: !permanent,
+            instruction: gpuRejectionInstruction({
+                permanent,
+                hasAlternatives: alternatives.length > 0,
+                call: "create_inference",
+            }),
+            available_gpus: alternatives,
+            minimum_requirement: {
+                selected_gpu_min: minGpus,
+                selected_valid_counts: validCounts,
+                per_type: selectable
+                    .filter((option) => (option.min_gpus || 0) >= 1)
+                    .map((option) => ({
+                    gpu_type: option.gpu_type,
+                    min_gpus: option.min_gpus,
+                    valid_counts: option.valid_counts || [],
+                })),
+            },
+            selected: { gpu_type: gpuType, gpu_count: gpuCount, tier: body.gpu_tier || "secure", availability_status: "unknown" },
+            // A permanent rejection must not advertise the queue, and must not report
+            // itself eligible for it either: a caller branching on queue_eligible would
+            // park a request that can never book.
+            queue_offered: !permanent,
+            queue_eligible: body.allow_capacity_queue === true && !permanent,
+            checked_at: options.availability_checked_at,
+        }));
+    }
+    /**
+     * Book-before-reveal (book-first §1): poll a 202 booking handle to its
+     * terminal outcome. Pending keeps polling; a transient 503/market outage
+     * keeps polling (never a capacity verdict); the definitive miss throws the
+     * structured CAPACITY_UNAVAILABLE the transport already serialized; on
+     * timeout the raw booking body is returned with an instruction to keep
+     * polling get_inference_booking.
+     */
+    async function pollInferenceBookingToOutcome(handle, timeoutMs) {
+        const deadline = Date.now() + timeoutMs;
+        for (;;) {
+            if (Date.now() > deadline) {
+                return {
+                    booking: { handle, status: "booking" },
+                    instruction: `The GPU booking is still concluding. Nothing is charged and no deployment exists until a GPU is confirmed. Call get_inference_booking with handle "${handle}" to continue polling.`,
+                };
+            }
+            await new Promise((resolve) => setTimeout(resolve, 2_000));
+            let outcome;
+            try {
+                outcome = await client.api(`/api/inference/bookings/${encodeURIComponent(handle)}`);
+            }
+            catch (error) {
+                const text = error instanceof Error ? error.message : String(error);
+                // ADMISSION_UNAVAILABLE / 503: transient market outage — keep polling,
+                // never fail-closed. Every other error (including the structured
+                // CAPACITY_UNAVAILABLE miss) is terminal.
+                if (text.includes("ADMISSION_UNAVAILABLE") || text.includes("error 503"))
+                    continue;
+                throw error;
+            }
+            if (outcome?.booking?.status === "booking")
+                continue;
+            return outcome;
+        }
+    }
+    server.tool("create_inference", "Create an OpenAI-compatible serving deployment using the exact canonical_request approved through preflight_inference, including hf_model_revision/base_model_revision. Serving mode, OpenAI task and image support are derived by the platform (not inputs) and come back on the response. BOOK-BEFORE-REVEAL: a non-queued create answers 202 with a booking handle while the GPU is secured on real capacity (30-40s typical); this tool polls it and returns the full payload (one-time inference_key) only after the GPU is confirmed — a definitive miss returns the structured CAPACITY_UNAVAILABLE with fresh available_gpus + minimum_requirement and NO deployment exists. Queueing occurs only with explicit allow_capacity_queue=true, max_price_hour_cents prevents a later price increase. Reuse idempotency_key after a timeout to recover the same booking/deployment.", deploymentCreateMutationToolSchema, async ({ idempotency_key, ...params }) => {
+        if (params.source_type === "hf_model" && params.hf_model_id) {
+            await assertModelHosted(params.hf_model_id, "create_inference");
+        }
+        const body = buildDeploymentBody(params);
+        await assertInferenceGpuSelectionBookable(body);
+        try {
+            const data = await client.api("/api/inference", {
+                method: "POST",
+                body,
+                headers: { "Idempotency-Key": idempotency_key },
+            });
+            if (data?.booking?.handle) {
+                return json(await pollInferenceBookingToOutcome(String(data.booking.handle), 120_000));
+            }
+            return json(data);
+        }
+        catch (error) {
+            throw modelResolveFailure(error, params.hf_model_id ?? params.base_model_id, "create_inference");
+        }
+    });
+    /* ══════════════════════════════════════════════════════════════════════════ */
+    /*  TOOL: get_inference_booking                                              */
+    /* ══════════════════════════════════════════════════════════════════════════ */
+    server.tool("get_inference_booking", "Poll a book-before-reveal booking handle from create_inference. Returns {booking:{status:'booking'}} while the GPU is being confirmed, the full create payload (with the ONE-TIME inference_key, exactly once) once the GPU is secured, the structured CAPACITY_UNAVAILABLE error on a definitive miss (no deployment exists, nothing charged), or a retryable ADMISSION_UNAVAILABLE 503 during a transient market outage (never treat it as out-of-stock).", { handle: z.string().describe("Booking handle from create_inference's 202 response.") }, async ({ handle }) => {
+        const data = await client.api(`/api/inference/bookings/${encodeURIComponent(handle)}`);
+        return json(data);
+    });
+    /* ══════════════════════════════════════════════════════════════════════════ */
+    /*  TOOL: list_inferences                                                    */
+    /* ══════════════════════════════════════════════════════════════════════════ */
+    server.tool("list_inferences", "List one bounded, newest-first page of serving deployments in the API key's workspace. Reuse next_cursor with the same status/search filters to continue; start without a cursor after filters change. The returned lifecycle values are durable control-plane state, not a promise that an endpoint is live unless status is running.", {
+        limit: z.number().int().min(1).max(200).optional().describe("Page size (default 50, maximum 200)."),
+        cursor: z.string().max(1024).optional().describe("Opaque next_cursor from the preceding page."),
+        status: z.enum([
+            "all", "running", "provisioning", "stopped", "failed", "queued_capacity", "degraded",
+            "paused_insufficient_funds", "crash_loop", "downloading_weights", "loading_model",
+        ]).optional(),
+        search: z.string().max(120).optional().describe("Case-insensitive deployment-name prefix."),
+    }, async ({ limit, cursor, status, search }) => {
+        const params = new URLSearchParams();
+        if (limit !== undefined)
+            params.set("limit", String(limit));
+        if (cursor)
+            params.set("cursor", cursor);
+        if (status && status !== "all")
+            params.set("status", status);
+        if (search?.trim())
+            params.set("search", search.trim());
+        const query = params.toString();
+        const data = await client.api(`/api/inference${query ? `?${query}` : ""}`);
+        return json(data);
+    });
+    /* ══════════════════════════════════════════════════════════════════════════ */
+    /*  TOOL: get_inference_status                                               */
+    /* ══════════════════════════════════════════════════════════════════════════ */
+    server.tool("get_inference_status", "Read durable deployment status, desired state, loading progress, endpoint, errors, selected GPU/price cap, queue entry/expiry, notification summary, and wallet-authorization state. Also returns status_summary: the lifecycle phase, the GPU (count x SKU), whether the endpoint may be used, and the queue/GPU state, derived from this same response so a field that is null before the pod reports is not mistaken for 'no GPU' or 'no phase'. A queue deadline keeps status=failed for filter compatibility and sets status_reason/error_code=queue_expired. Treat queued_capacity as waiting and report the endpoint live only when status_summary.endpoint_usable is true. The derived serving settings (serving_mode, model_task, supports_images, context_length) are reported here too — they are platform-chosen, never caller-chosen.", { deployment_id: z.string().describe("Deployment ID.") }, async ({ deployment_id }) => {
+        validateId(deployment_id, "deployment_id");
+        const data = await client.api(`/api/inference/${deployment_id}`);
+        // Same raw-text class as the training job detail (top-level last_error and
+        // the nested queue.last_error). The control plane curates these today; this
+        // is the boundary backstop, and it touches no other field.
+        //
+        // Redaction runs OUTSIDE the summariser deliberately: summarizeInferenceStatus
+        // derives status_summary from these same raw fields, so redacting first would
+        // let it summarise text the backstop had already cleaned — and redacting last
+        // covers anything it copied forward.
+        return json(redactFreeTextFields(summarizeInferenceStatus(data), RAW_FAILURE_TEXT_FIELDS));
+    });
+    /* ══════════════════════════════════════════════════════════════════════════ */
+    /*  TOOL: get_inference_metrics                                              */
+    /* ══════════════════════════════════════════════════════════════════════════ */
+    server.tool("get_inference_metrics", "Read serving metrics for a deployment: request counts, prompt/generation token totals, cache hit rate, time to first token, inter-token latency, throughput, GPU utilization and memory, KV cache usage, and a recent time series. Counters are lifetime totals; the time series reflects the selected window. Responses are served from a short cache; zeros are real measurements, not missing data.", {
+        deployment_id: z.string().describe("Deployment ID."),
+        window: z
+            .enum(["1h", "24h", "7d", "30d"])
+            .optional()
+            .describe("Time-series window (default 24h). Sets the series range and bucket size: 1h/1min, 24h/5min, 7d/30min, 30d/1h."),
+    }, async ({ deployment_id, window }) => {
+        validateId(deployment_id, "deployment_id");
+        const params = new URLSearchParams();
+        if (window)
+            params.set("window", window);
+        const query = params.toString();
+        const data = await client.api(`/api/inference/${deployment_id}/metrics${query ? `?${query}` : ""}`);
+        return json(data);
+    });
+    /* ══════════════════════════════════════════════════════════════════════════ */
+    /*  TOOL: get_inference_notifications                                        */
+    /* ══════════════════════════════════════════════════════════════════════════ */
+    server.tool("get_inference_notifications", "Read the durable lifecycle-email history for a deployment. States are pending, sending, delivered, or dead_letter. Dead letters retain the bounded retry count and last error; deployment status remains authoritative even when email delivery fails.", {
+        deployment_id: z.string().describe("Deployment ID."),
+        limit: z.number().int().min(1).max(100).optional().describe("Newest rows to return (default 50, maximum 100)."),
+    }, async ({ deployment_id, limit }) => {
+        validateId(deployment_id, "deployment_id");
+        const params = new URLSearchParams();
+        if (limit !== undefined)
+            params.set("limit", String(limit));
+        const query = params.toString();
+        const data = await client.api(`/api/inference/${deployment_id}/notifications${query ? `?${query}` : ""}`);
+        return json(data);
+    });
+    /* ══════════════════════════════════════════════════════════════════════════ */
+    /*  TOOL: update_inference_policy                                            */
+    /* ══════════════════════════════════════════════════════════════════════════ */
+    server.tool("update_inference_policy", "Update explicit capacity-queue consent or the maximum accepted total hourly GPU price. A cap below the current verified price is rejected. This call does not silently choose another GPU.", {
+        deployment_id: z.string().describe("Deployment ID."),
+        allow_capacity_queue: z.boolean().optional(),
+        max_price_hour_cents: priceCapSchema(false),
+    }, async ({ deployment_id, allow_capacity_queue, max_price_hour_cents }) => {
+        validateId(deployment_id, "deployment_id");
+        const data = await client.api(`/api/inference/${deployment_id}`, {
+            method: "PATCH",
+            body: buildDeploymentPolicyBody({ allow_capacity_queue, max_price_hour_cents }),
+        });
+        return json(data);
+    });
+    /* ══════════════════════════════════════════════════════════════════════════ */
+    /*  TOOL: stop_inference                                                     */
+    /* ══════════════════════════════════════════════════════════════════════════ */
+    server.tool("stop_inference", "Stop a deployment and release GPU capacity plus its wallet authorization. The acknowledgement means the durable stop workflow was accepted; poll get_inference_status until stopped or failed.", { deployment_id: z.string().describe("Deployment ID.") }, async ({ deployment_id }) => {
+        validateId(deployment_id, "deployment_id");
+        const data = await client.api(`/api/inference/${deployment_id}/stop`, { method: "POST" });
+        return json(data);
+    });
+    /* ══════════════════════════════════════════════════════════════════════════ */
+    /*  TOOL: resume_inference                                                   */
+    /* ══════════════════════════════════════════════════════════════════════════ */
+    server.tool("resume_inference", "Atomically resume a stopped deployment. Exactly one concurrent caller can claim the lifecycle generation. The control plane revalidates the saved GPU price cap and wallet authorization before provisioning; capacity may queue only when the saved queue consent allows it.", { deployment_id: z.string().describe("Deployment ID.") }, async ({ deployment_id }) => {
+        validateId(deployment_id, "deployment_id");
+        const data = await client.api(`/api/inference/${deployment_id}/resume`, { method: "POST" });
+        return json(data);
+    });
+    /* ══════════════════════════════════════════════════════════════════════════ */
+    /*  TOOL: restart_inference                                                  */
+    /* ══════════════════════════════════════════════════════════════════════════ */
+    server.tool("restart_inference", "Claim one fenced restart generation. A same-config running deployment restarts in place and never silently releases its GPU for a replacement when the platform cannot confirm that restart. Pending configuration changes and failed/crash-loop recovery explicitly provision a replacement. Poll status because the acknowledgement is not endpoint readiness.", { deployment_id: z.string().describe("Deployment ID.") }, async ({ deployment_id }) => {
+        validateId(deployment_id, "deployment_id");
+        const data = await client.api(`/api/inference/${deployment_id}/restart`, { method: "POST" });
+        return json(data);
+    });
+    /* ══════════════════════════════════════════════════════════════════════════ */
+    /*  TOOL: delete_inference                                                   */
+    /* ══════════════════════════════════════════════════════════════════════════ */
+    server.tool("delete_inference", "Permanently delete a serving deployment. The control plane first verifies infrastructure teardown and records retryable orphan cleanup if needed, then releases/refunds the generation-scoped wallet authorization. This cannot be undone.", { deployment_id: z.string().describe("Deployment ID.") }, async ({ deployment_id }) => {
+        validateId(deployment_id, "deployment_id");
+        const data = await client.api(`/api/inference/${deployment_id}`, { method: "DELETE" });
+        return json(data);
+    });
+    /* ══════════════════════════════════════════════════════════════════════════ */
+    /*  TOOL: list_datasets                                                     */
+    /* ══════════════════════════════════════════════════════════════════════════ */
+    server.tool("list_datasets", "List all datasets in your workspace. Returns dataset ID, name, format (JSONL/Parquet/CSV), row count, file size, column names, and creation date for each dataset.", {}, async () => {
+        const data = await client.api("/api/datasets");
+        return json(data);
+    });
+    /* ══════════════════════════════════════════════════════════════════════════ */
+    /*  TOOL: upload_dataset                                                    */
+    /* ══════════════════════════════════════════════════════════════════════════ */
+    // PRE-LAUNCH GATE (launchGates.datasets — src/config.ts): while datasets are
+    // coming soon this tool is NOT REGISTERED — hidden from tools/list so an agent
+    // never learns the capability exists. The service enforces the same gate
+    // server-side (403 DATASETS_COMING_SOON) as the authority. At launch the flag
+    // opens and the registration returns verbatim.
+    if (!launchGates.datasets) {
+        server.tool("upload_dataset", "Upload a dataset file for fine-tuning. Supports JSONL, Parquet, and CSV formats up to 500MB. The file is automatically validated: format detection, row counting, column identification, and schema validation. Returns the dataset ID needed for create_training_job.", {
+            file_path: z.string().describe("Absolute path to the dataset file on disk"),
+            name: z.string().optional().describe("Display name for the dataset (defaults to filename)"),
+        }, async ({ file_path, name }) => {
+            const absPath = resolve(file_path);
+            const allowedExtensions = [".jsonl"];
+            const ext = absPath.toLowerCase().slice(absPath.lastIndexOf("."));
+            if (!allowedExtensions.includes(ext)) {
+                throw new Error(`Unsupported file type: ${ext}. Allowed: ${allowedExtensions.join(", ")}`);
+            }
+            const normalizedPath = absPath.replace(/\\/g, "/");
+            const sensitivePatterns = ["/etc/", "/.ssh/", "/.env", "/.git/", "/passwd", "/shadow", "/.aws/"];
+            for (const pat of sensitivePatterns) {
+                if (normalizedPath.includes(pat)) {
+                    throw new Error(`Access denied: cannot read files from restricted paths`);
+                }
+            }
+            let fileStat;
+            try {
+                fileStat = await stat(absPath);
+            }
+            catch {
+                throw new Error(`File not found: ${absPath}`);
+            }
+            if (fileStat.size > 500 * 1024 * 1024) {
+                throw new Error(`File too large (${(fileStat.size / 1024 / 1024).toFixed(1)}MB). Maximum is 500MB.`);
+            }
+            const fileBuffer = await readFile(absPath);
+            const fileName = name ?? basename(absPath);
+            const blob = new Blob([fileBuffer]);
+            const formData = new FormData();
+            formData.append("file", blob, basename(absPath));
+            formData.append("name", fileName);
+            formData.append("size", fileStat.size.toString());
+            const data = await client.api("/api/datasets/upload", {
+                method: "POST",
+                formData,
+            });
+            return json(data);
+        });
+    }
+    /* ══════════════════════════════════════════════════════════════════════════ */
+    /*  TOOL: preview_dataset                                                   */
+    /* ══════════════════════════════════════════════════════════════════════════ */
+    server.tool("preview_dataset", "Preview the first rows of a dataset to inspect its structure, column names, and content before training. Useful for verifying the dataset format is correct.", {
+        dataset_id: z.string().describe("Dataset ID (e.g., 'ds_abc123')"),
+        rows: z.number().optional().describe("Number of rows to preview (default: 10, max: 50)"),
+    }, async ({ dataset_id, rows }) => {
+        validateId(dataset_id, "dataset_id");
+        const data = await client.api(`/api/datasets/${dataset_id}/preview`, {
+            params: { page: "1", page_size: (rows ?? 10).toString() },
+        });
+        return json(data);
+    });
+    /* ══════════════════════════════════════════════════════════════════════════ */
+    /*  TOOL: delete_dataset                                                    */
+    /* ══════════════════════════════════════════════════════════════════════════ */
+    server.tool("delete_dataset", "Permanently delete a dataset from your workspace. This cannot be undone. Active training jobs using this dataset are not affected.", {
+        dataset_id: z.string().describe("Dataset ID to delete"),
+    }, async ({ dataset_id }) => {
+        validateId(dataset_id, "dataset_id");
+        await client.api(`/api/datasets/${dataset_id}`, { method: "DELETE" });
+        return result(`Dataset ${dataset_id} deleted successfully.`);
+    });
+    /* ══════════════════════════════════════════════════════════════════════════ */
+    /*  TOOL: list_integrations                                                 */
+    /* ══════════════════════════════════════════════════════════════════════════ */
+    server.tool("list_integrations", "List the integrations connected to your workspace, such as Hugging Face accounts. Returns each integration's ID, label, provider type, and status. Use an integration ID wherever a tool accepts integration_id: importing HuggingFace datasets. This is how you pick WHICH connected account an import should use when several are connected. This read is workspace-scoped: without workspace context it fails with WORKSPACE_CONTEXT_REQUIRED, which is a configuration fix (BIOS_WORKSPACE_ID or a workspace-bound API key), not something to retry.", {}, async () => {
+        const data = await client.api("/api/datasets/integrations");
+        return json(data);
+    });
+    /* ══════════════════════════════════════════════════════════════════════════ */
+    /*  TOOL: import_huggingface_dataset                                        */
+    /* ══════════════════════════════════════════════════════════════════════════ */
+    // PRE-LAUNCH GATE (launchGates.datasets — src/config.ts): not registered while
+    // gated, exactly like upload_dataset above; the service's 403
+    // DATASETS_COMING_SOON stays the authority.
+    if (!launchGates.datasets) {
+        server.tool("import_huggingface_dataset", "Import a dataset from HuggingFace Hub into your workspace. Works with public datasets and private datasets if your HuggingFace account is connected via Integrations. The dataset is downloaded, validated, and stored in your workspace. Returns the dataset ID for use with create_training_job.", {
+            repo_id: z
+                .string()
+                .describe("HuggingFace dataset repo whose rows already carry a messages array (SFT) or a text field (CPT)"),
+            integration_id: z
+                .string()
+                .describe("HuggingFace integration ID from your connected integrations"),
+            split: z.string().optional().describe("Dataset split (default: 'train')"),
+            max_samples: z.number().optional().describe("Max rows to import (imports all if omitted)"),
+            name: z.string().optional().describe("Display name for the imported dataset"),
+        }, async ({ repo_id, integration_id, split, max_samples, name }) => {
+            const data = await client.api(`/api/datasets/integrations/${encodeURIComponent(integration_id)}/import`, {
+                method: "POST",
+                body: {
+                    dataset_id: repo_id,
+                    split: split ?? "train",
+                    max_samples,
+                    name: name ?? repo_id.split("/").pop(),
+                },
+            });
+            return json(data);
+        });
+    }
+    /* ══════════════════════════════════════════════════════════════════════════ */
+    /*  TOOL: get_training_capabilities                                          */
+    /* ══════════════════════════════════════════════════════════════════════════ */
+    server.tool("get_training_capabilities", "Return the authoritative training contract Run BiOS enforces today: enabled and disabled methods, algorithms and adapters; exact hyperparameter names, aliases, types, defaults, enums and ranges; dependencies and incompatibilities. contract_version/schema_version identify the contract you are reading. Call this before constructing an automated training payload instead of relying on a hard-coded client list.", {}, async () => {
+        const data = await client.api("/api/training/capabilities");
+        // The contract used to carry image_compatibility — the training-engine image
+        // VERSION range it was written against. training-service no longer emits it;
+        // this strip stays as a backstop because a customer cannot select a build and
+        // must never learn one, and contract_version/schema_version already version
+        // the contract for clients.
+        return json(stripBuildIdentity(data));
+    });
+    /* ══════════════════════════════════════════════════════════════════════════ */
+    /*  TOOL: preflight_training_job                                            */
+    /* ══════════════════════════════════════════════════════════════════════════ */
+    server.tool("preflight_training_job", "Validate and canonicalize a proposed training job without creating a job, charging the wallet, entering the queue, or allocating a GPU. Returns dataset compatibility, model facts, authoritative GPU choices/prices, queue eligibility, alternatives, warnings, and a request hash.", {
+        model: z.string().describe("Base model id from the Run BiOS catalog (e.g., 'meta-llama/Llama-3.1-8B-Instruct'). Must be hosted on Run BiOS — pick from list_models/search_models. Training always starts from a catalog base model; training FROM a fine-tuned model (adapter stacking) is not supported."),
+        model_revision: z.string().max(256).optional().describe("Requested model branch, tag, or commit. Copy the exact 40-hex value returned in canonical_request into create."),
+        dataset_id: z.string().optional(),
+        dataset_ids: z.array(z.string()).min(1).optional(),
+        method: z.enum(TRAINING_METHODS),
+        adapter: z.enum(TRAINING_ADAPTERS).optional(),
+        gpu_type: z.string().optional(),
+        gpu_count: z.number().int().min(1).max(8).optional(),
+        gpu_priorities: z
+            .array(z.object({
+            gpu_type: z.string(), gpu_count: z.number().int().min(1).max(8),
+            provider: z.string().min(1).max(30).optional(), region: z.string().min(1).max(64).optional(),
+            tier: z.literal("secure").optional(),
+        }))
+            .min(1)
+            .max(5)
+            .optional()
+            .describe("Ranked GPU placement choices. Copy these unchanged from the preflight response's accepted choices; the platform fills in and manages infrastructure placement automatically. Queueing requires 3-5 distinct entries; entry one must match gpu_type/gpu_count."),
+        queue_if_unavailable: z.boolean().optional().describe("Explicit consent to wait in the capacity queue when none of the ranked GPU choices are free; requires 3 to 5 gpu_priorities."),
+        queue_deadline: z.string().min(1).optional().describe("Optional RFC 3339 deadline from one minute through seven days in the future; requires queue_if_unavailable=true."),
+        max_price_hour_cents: priceCapSchema(true),
+        storage_gb: z.number().int().min(1).max(10000).optional(),
+        num_checkpoints: z.number().int().min(1).max(100).optional(),
+        integration_id: z.string().optional(),
+        network_volume_id: z.string().optional(),
+        cache_dataset: z.boolean().optional(),
+        dataset_mixing: z.enum(["shuffle", "sequential", "interleave"]).optional(),
+        config: z.record(z.string(), z.unknown()).optional(),
+    }, async (params) => {
+        await assertModelHosted(params.model, "preflight_training_job");
+        const body = buildTrainingCreateBody(params);
+        const data = await client.api("/api/training/preflight", { method: "POST", body });
+        return json(data);
+    });
+    /* ══════════════════════════════════════════════════════════════════════════ */
+    /*  TOOL: create_training_job                                               */
+    /* ══════════════════════════════════════════════════════════════════════════ */
+    // PRE-LAUNCH GATE (launchGates.training — src/config.ts): while fine-tuning is
+    // coming soon this tool is NOT REGISTERED — hidden from tools/list so an agent
+    // never learns the capability exists. The service enforces the same gate
+    // server-side (403 TRAINING_COMING_SOON before any billing or booking) as the
+    // authority. At launch the flag opens and the registration returns verbatim.
+    if (!launchGates.training) {
+        server.tool("create_training_job", "Create a fine-tuning job using the same contract as the web UI, following BOOK-BEFORE-REVEAL: the call blocks while the ranked GPU ladder is booked (~40s). A job id and the started email exist only once a real pod is secured, so status is 'booked' (booked==secured; training then provisions/downloads/runs on its own) or 'securing' (still booking at the deadline — poll get_training_status until booked/running). With explicit queue consent it may return 'queued'. A definitive booking-time miss returns the structured CAPACITY_UNAVAILABLE (409) with fresh available_gpus and NO job exists (nothing charged); never auto-substitute a GPU. Call preflight_training_job first, preserve the accepted ranked GPU choices, queue deadline, and maximum total hourly price, then reuse one idempotency key after timeouts.", {
+            model: z.string().describe("Base model id from the Run BiOS catalog (e.g., 'meta-llama/Llama-3.1-8B-Instruct'). Must be hosted on Run BiOS — pick from list_models/search_models. Training always starts from a catalog base model; training FROM a fine-tuned model (adapter stacking) is not supported."),
+            model_revision: z.string().max(256).optional().describe("Exact model_revision from preflight canonical_request; a branch or tag is accepted but resolved again before any paid mutation."),
+            idempotency_key: z
+                .string()
+                .min(8)
+                .max(128)
+                .regex(/^[A-Za-z0-9._:-]+$/)
+                .optional()
+                .describe("Stable retry key. Reuse it after a timeout; omit to generate one for this tool call."),
+            dataset_id: z.string().optional().describe("Compatibility field for one dataset ID."),
+            dataset_ids: z.array(z.string()).min(1).optional().describe("One or more dataset IDs to compose for training."),
+            method: z.enum(TRAINING_METHODS).describe("Training method: sft, or pt/cpt for continued pre-training."),
+            adapter: z.enum(TRAINING_ADAPTERS).optional().describe("Any adapter supported by the Run BiOS contract."),
+            gpu_type: z.string().optional().describe("GPU type (e.g., 'A100_80GB'). Use get_recommended_gpu to find the best option. Auto-selected if omitted."),
+            gpu_count: z.number().int().min(1).max(8).optional().describe("Number of GPUs for the primary choice."),
+            gpu_priorities: z
+                .array(z.object({
+                gpu_type: z.string(), gpu_count: z.number().int().min(1).max(8),
+                provider: z.string().min(1).max(30).optional(), region: z.string().min(1).max(64).optional(),
+                tier: z.literal("secure").optional(),
+            }))
+                .min(1)
+                .max(5)
+                .optional()
+                .describe("Ranked GPU placement choices. Copy these unchanged from the preflight response's accepted choices; the platform fills in and manages infrastructure placement automatically. Queueing requires 3-5 distinct entries; entry one must match gpu_type/gpu_count."),
+            queue_if_unavailable: z.boolean().optional().describe("Explicit consent to wait in the capacity queue when none of the ranked GPU choices are free; requires 3 to 5 gpu_priorities."),
+            queue_deadline: z.string().min(1).optional().describe("Optional RFC 3339 deadline from one minute through seven days in the future; requires queue_if_unavailable=true."),
+            max_price_hour_cents: priceCapSchema(true),
+            storage_gb: z.number().int().min(1).max(10000).optional(),
+            num_checkpoints: z.number().int().min(1).max(100).optional(),
+            epochs: z.number().positive().max(1000).optional().describe("Number of training epochs."),
+            learning_rate: z.number().positive().max(1).optional().describe("Learning rate."),
+            batch_size: z.number().int().min(1).max(65536).optional().describe("Per-device train batch size."),
+            gradient_accumulation_steps: z.number().int().min(1).max(65536).optional(),
+            max_seq_length: trainingSeqLengthSchema(),
+            lora_rank: z.number().int().min(1).max(4096).optional(),
+            lora_alpha: z.number().positive().max(1_000_000).optional(),
+            warmup_ratio: z.number().min(0).max(1).optional(),
+            weight_decay: z.number().min(0).max(10).optional(),
+            scheduler: z
+                .enum(["linear", "cosine", "cosine_with_restarts", "polynomial", "constant", "constant_with_warmup"])
+                .optional()
+                .describe("Learning-rate scheduler."),
+            job_name: z.string().max(255).optional(),
+            eval_split_ratio: z.number().min(0).max(0.99).optional(),
+            early_stopping_patience: z.number().int().min(0).max(20).optional()
+                .describe("Stop after N evaluations without a better validation loss (0 = off; default 3 when eval_split_ratio is set). The best checkpoint is always saved."),
+            overlong_policy: z.enum(["truncate", "drop"]).optional()
+                .describe("Samples longer than max_seq_length: 'truncate' keeps the last tokens so the answer is trained (default); 'drop' skips them."),
+            integration_id: z.string().optional(),
+            network_volume_id: z.string().optional(),
+            cache_dataset: z.boolean().optional(),
+            dataset_mixing: z.enum(["shuffle", "sequential", "interleave"]).optional(),
+            config: z.record(z.string(), z.unknown()).optional().describe("Additional Run BiOS training configuration fields."),
+        }, async (params) => {
+            await assertModelHosted(params.model, "create_training_job");
+            const body = buildTrainingCreateBody(params);
+            const data = await client.api("/api/training/jobs", {
+                method: "POST",
+                body,
+                headers: { "Idempotency-Key": params.idempotency_key ?? randomUUID() },
+            });
+            return json(data);
+        });
+    }
+    /* ══════════════════════════════════════════════════════════════════════════ */
+    /*  TOOL: list_training_jobs                                                */
+    /* ══════════════════════════════════════════════════════════════════════════ */
+    server.tool("list_training_jobs", "List all training jobs with their status, progress percentage, base model, training method, GPU type, cost so far, and timestamps. Filter by status to find running, completed, or stopped jobs.", {
+        status: z
+            .enum(["running", "completed", "stopped", "queued", "securing", "booked", "interrupted", "failed"])
+            .optional()
+            .describe("Filter by job status"),
+    }, async ({ status }) => {
+        const data = await client.api("/api/training/jobs", { params: { status } });
+        return json(data);
+    });
+    /* ══════════════════════════════════════════════════════════════════════════ */
+    /*  TOOL: get_training_status                                               */
+    /* ══════════════════════════════════════════════════════════════════════════ */
+    server.tool("get_training_status", "Get detailed status for a specific training job: progress percentage, current step/total steps, current loss, learning rate, elapsed time, estimated time remaining, GPU utilization, and job configuration. Status 'securing' means a create is still booking a pod (poll until 'booked'); 'booked' means the GPU is secured and the job is starting. 'interrupted' is a self-heal rest state after a started job loses its pod — billing is already stopped and it is distinct from 'failed'; call resume_training_job to continue from the last checkpoint.", {
+        job_id: z.string().describe("Training job ID (e.g., 'job_abc123')"),
+    }, async ({ job_id }) => {
+        validateId(job_id, "job_id");
+        const data = await client.api(`/api/training/jobs/${job_id}`);
+        // A stopped job's stop_last_error is the raw transport error from the last
+        // call to the machine, so it carries the request URL and with it the
+        // supplier's hostname. Redact the raw-text fields only; model ids, config
+        // and every other value pass through untouched.
+        return json(redactFreeTextFields(data, RAW_FAILURE_TEXT_FIELDS));
+    });
+    /* ══════════════════════════════════════════════════════════════════════════ */
+    /*  TOOL: get_training_metrics                                              */
+    /* ══════════════════════════════════════════════════════════════════════════ */
+    server.tool("get_training_metrics", "Get training metrics history for a job: training loss over time, eval loss, learning rate schedule, and evaluation results. Use this to check if training is progressing well (loss should decrease) or if the model is overfitting (eval loss increasing while train loss decreases).", {
+        job_id: z.string().describe("Training job ID"),
+    }, async ({ job_id }) => {
+        validateId(job_id, "job_id");
+        const data = await client.api(`/api/training/jobs/${job_id}/metrics`);
+        return json(data);
+    });
+    /* ══════════════════════════════════════════════════════════════════════════ */
+    /*  TOOL: get_training_logs                                                 */
+    /* ══════════════════════════════════════════════════════════════════════════ */
+    server.tool("get_training_logs", "Get structured recent training log entries (level, message, timestamp). Results are newest first and bounded by tail.", {
+        job_id: z.string().describe("Training job ID"),
+        tail: z
+            .number()
+            .int()
+            .min(1)
+            .max(1000)
+            .optional()
+            .describe("Number of most recent log entries to return (default: 200, max: 1000)"),
+    }, async ({ job_id, tail }) => {
+        validateId(job_id, "job_id");
+        const data = await client.api(`/api/training/jobs/${job_id}/logs`, {
+            params: { tail: tail?.toString() },
+        });
+        // Log lines are written by the training engine, so a boot/pull line can
+        // quote the image reference it started from. Redact by content: the
+        // customer keeps every line, minus any build identity inside it.
+        return json(redactBuildIdentityDeep(trimTrainingLogs(data, tail)));
+    });
+    /* ══════════════════════════════════════════════════════════════════════════ */
+    /*  TOOL: stop_training_job                                                 */
+    /* ══════════════════════════════════════════════════════════════════════════ */
+    server.tool("stop_training_job", "Request a durable stop for an active training job. The acknowledgement means the stop workflow was accepted; checkpoint preservation and resumability are reported by later job/checkpoint state, not promised by this call.", {
+        job_id: z.string().describe("Training job ID to stop"),
+        keep_data: z.boolean().optional().describe("Attempt to preserve checkpoint/output data (default: true)."),
+    }, async ({ job_id, keep_data }) => {
+        validateId(job_id, "job_id");
+        const data = await client.api(`/api/training/jobs/${job_id}/stop`, {
+            method: "POST",
+            body: { keep_data: keep_data ?? true },
+        });
+        return json(data);
+    });
+    /* ══════════════════════════════════════════════════════════════════════════ */
+    /*  TOOL: resume_training_job                                               */
+    /* ══════════════════════════════════════════════════════════════════════════ */
+    server.tool("resume_training_job", "Resume a stopped or 'interrupted' training job from its latest checkpoint when the server has verified it as resumable. 'interrupted' is the self-heal rest state a started job enters after losing its pod (billing already stopped, distinct from 'failed'). Resume re-books on secured capacity before reporting resumed (book-before-reveal still applies). The response identifies the job; exact optimizer/epoch continuation depends on the checkpoint manifest and is not assumed by this tool.", {
+        job_id: z.string().describe("Training job ID to resume"),
+        idempotency_key: z
+            .string()
+            .min(8)
+            .max(128)
+            .regex(/^[A-Za-z0-9._:-]+$/)
+            .optional()
+            .describe("Stable retry key. Reuse it after a timeout; omit to generate one for this tool call."),
+    }, async ({ job_id, idempotency_key }) => {
+        validateId(job_id, "job_id");
+        const data = await client.api(`/api/training/jobs/${job_id}/resume`, {
+            method: "POST",
+            headers: { "Idempotency-Key": idempotency_key ?? randomUUID() },
+        });
+        return json(data);
+    });
+    /* ══════════════════════════════════════════════════════════════════════════ */
+    /*  TOOL: get_training_checkpoints                                          */
+    /* ══════════════════════════════════════════════════════════════════════════ */
+    server.tool("get_training_checkpoints", "List recorded checkpoints for a training job. Returns checkpoint identity, step/epoch, size and final/best flags. Use get_checkpoint_download_manifest for file URLs; this list does not fabricate loss, eval metrics, or download URLs.", {
+        job_id: z.string().describe("Training job ID"),
+    }, async ({ job_id }) => {
+        validateId(job_id, "job_id");
+        const data = await client.api(`/api/training/jobs/${job_id}/checkpoints`);
+        return json(data);
+    });
+    /* ══════════════════════════════════════════════════════════════════════════ */
+    /*  TOOL: get_checkpoint_download_manifest                                  */
+    /* ══════════════════════════════════════════════════════════════════════════ */
+    server.tool("get_checkpoint_download_manifest", "Per-file download manifest for a checkpoint, available only in workspaces where model weight downloads are enabled; otherwise the checkpoint is reported as not found. URLs are short-lived.", {
+        job_id: z.string().describe("Training job ID"),
+        checkpoint_id: z.string().describe("Checkpoint ID from get_training_checkpoints"),
+    }, async ({ job_id, checkpoint_id }) => {
+        validateId(job_id, "job_id");
+        validateId(checkpoint_id, "checkpoint_id");
+        const data = await client.api(`/api/training/jobs/${job_id}/checkpoints/${checkpoint_id}/download`);
+        return json(data);
+    });
+    /* ══════════════════════════════════════════════════════════════════════════ */
+    /*  TOOL: delete_training_checkpoint                                        */
+    /* ══════════════════════════════════════════════════════════════════════════ */
+    server.tool("delete_training_checkpoint", "Delete a checkpoint after the API verifies ownership. This is destructive and can remove the ability to deploy or resume from that checkpoint.", {
+        job_id: z.string().describe("Training job ID"),
+        checkpoint_id: z.string().describe("Checkpoint ID"),
+    }, async ({ job_id, checkpoint_id }) => {
+        validateId(job_id, "job_id");
+        validateId(checkpoint_id, "checkpoint_id");
+        const data = await client.api(`/api/training/jobs/${job_id}/checkpoints/${checkpoint_id}`, {
+            method: "DELETE",
+        });
+        return json(data);
+    });
+    /* ══════════════════════════════════════════════════════════════════════════ */
+    /*  TOOL: get_training_evals                                                */
+    /* ══════════════════════════════════════════════════════════════════════════ */
+    server.tool("get_training_evals", "Get evaluation results for a training job. Returns benchmark scores, eval metrics, and model quality assessments computed during or after training.", {
+        job_id: z.string().describe("Training job ID"),
+    }, async ({ job_id }) => {
+        validateId(job_id, "job_id");
+        const data = await client.api(`/api/training/jobs/${job_id}/evals`);
+        return json(data);
+    });
+    /* ══════════════════════════════════════════════════════════════════════════ */
+    /*  TOOL: chat_with_inference                                               */
+    /* ══════════════════════════════════════════════════════════════════════════ */
+    // The schema is capability-aware per deployment (honest advertisement only —
+    // the runtime is gated server-side). When the inference key's deployment is
+    // known to be text-only (no tool parser), the tools/tool_choice/
+    // parallel_tool_calls params are omitted so a caller never offers tools a
+    // text-only model can't call. When it is known to accept no image input, the
+    // messages description says so. Unknown capabilities (undefined) advertise the
+    // full schema (fail-open) — the /v1 endpoint still enforces.
+    const inferenceSupportsTools = deploymentCaps?.supportsTools !== false;
+    const inferenceMessagesDesc = deploymentCaps?.supportsImages === false
+        ? "OpenAI chat messages (text-only — this deployment does not accept image input), including assistant tool_calls and matching role=tool responses."
+        : "OpenAI chat messages, including assistant tool_calls and matching role=tool responses.";
+    const chatWithInferenceDescription = "Call a model through the unified OpenAI-compatible /v1 endpoint. Pass a serverless catalog model id (author/name) to call it by name using a workspace platform key (RUNBIOS_API_KEY with serverless scope), or set RUNBIOS_INFERENCE_KEY to target a dedicated deployment (with or without a model override). Supports complete tool definitions, assistant tool calls, and tool response messages. Set stream=true to consume SSE and receive one aggregated completion with reasoning surfaced as produced. Calls are never retried automatically.";
+    // Shared, always-present params. The tools params are added only for a
+    // deployment that can call tools — kept as two concrete literals (not a Record)
+    // so each registration's `input` stays precisely typed for buildInferenceBody.
+    const chatBaseSchema = {
+        messages: z
+            .array(z.record(z.string(), z.unknown()))
+            .min(1)
+            .describe(inferenceMessagesDesc),
+        model: z
+            .string()
+            .optional()
+            .describe("Model to call on the unified /v1 endpoint. For a serverless catalog model pass its id "
+            + "(author/name) and the gateway routes it; for a dedicated deployment pass its name/id, or "
+            + "omit when a dedicated inference key uniquely selects the deployment."),
+        // Completion length had the same defect the context bounds had: `int()` alone
+        // advertised MAX_SAFE_INTEGER, so the schema told an agent that asking for
+        // nine quadrillion tokens is a legal request. The real ceiling is the SERVED
+        // window minus the prompt, which no static schema can express, so the bound
+        // is the same sanity ceiling serving uses and the description names the
+        // authority.
+        max_tokens: z
+            .number()
+            .int({ error: "max_tokens must be a whole number of tokens." })
+            .min(1, { error: "max_tokens must be at least 1 — omit it to let the endpoint choose." })
+            .max(CONTEXT_TOOL_MAX, {
+            error: (issue) => `max_tokens ${String(issue.input)} is above the ${CONTEXT_TOOL_MAX}-token sanity bound of this tool. `
+                + MAX_TOKENS_POLICY_TEXT,
+        })
+            .optional()
+            .describe(MAX_TOKENS_POLICY_TEXT),
+        temperature: z.number().min(0).max(2).optional(),
+        top_p: z.number().min(0).max(1).optional(),
+        response_format: z.record(z.string(), z.unknown()).optional(),
+        reasoning_effort: z
+            .enum(["none", "minimal", "low", "medium", "high", "xhigh", "max"])
+            .optional()
+            .describe("Standardized reasoning effort. Use 'none' to disable reasoning where the model allows it."),
+        stream: z
+            .boolean()
+            .optional()
+            .describe("Request server-sent streaming. The tool consumes the SSE and returns one aggregated "
+            + "completion (content + reasoning_content surfaced as produced, tool calls reassembled). "
+            + "Defaults to false."),
+        idempotency_key: z
+            .string()
+            .min(1)
+            .max(255)
+            .optional()
+            .describe("Stable caller-generated key to reuse only when explicitly retrying the same POST."),
+        request_id: z.string().min(1).max(255).optional(),
+    };
+    if (inferenceSupportsTools) {
+        server.tool("chat_with_inference", chatWithInferenceDescription, {
+            ...chatBaseSchema,
+            tools: z
+                .array(z.record(z.string(), z.unknown()))
+                .optional()
+                .describe("OpenAI function-tool definitions with JSON Schema object parameters."),
+            tool_choice: z
+                .union([
+                z.enum(["none", "auto", "required"]),
+                z.object({
+                    type: z.literal("function"),
+                    function: z.object({ name: z.string().min(1).max(64) }),
+                }),
+            ])
+                .optional(),
+            parallel_tool_calls: z.boolean().optional(),
+        }, async (input, extra) => {
+            const body = buildInferenceBody(input);
+            const data = await client.inferenceApi(body, input.idempotency_key, input.request_id, extra.signal);
+            return json(data);
+        });
+    }
+    else {
+        // Text-only deployment: no tools/tool_choice params advertised.
+        server.tool("chat_with_inference", chatWithInferenceDescription, chatBaseSchema, async (input, extra) => {
+            const body = buildInferenceBody(input);
+            const data = await client.inferenceApi(body, input.idempotency_key, input.request_id, extra.signal);
+            return json(data);
+        });
+    }
+    return mcp;
+}
+//# sourceMappingURL=server.js.map