runbios-mcp 0.2.1 → 0.2.2-dev.174

package/dist/server.js

@@ -572,29 +572,57 @@ launchGates = resolveLaunchGates()) {
         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")
+            ? "Run BiOS serves models through TWO distinct inference products: serverless inference and dedicated deployments. Call get_platform_guide first and choose the product before calling anything.\n"
+            : "Run BiOS provides serverless inference, dedicated deployments, datasets, and training. Call get_platform_guide first and choose the workflow before calling anything.\n")
             + prelaunchNote
             + "Rules that no tool schema can express:\n"
+            + "1. Identity: every tool acts only in the API key's bound organization and workspace. Call introspect_api_key first; never invent or substitute an org/workspace/account.\n"
+            + "2. Serverless is the default for immediate inference: no GPU booking, no deployment object, per-token billing. Use a published model id and chat_with_inference. Do NOT call create_inference for serverless.\n"
+            + "3. Dedicated inference reserves GPUs and bills per second. Use get_inference_gpu_options -> preflight_inference -> explicit spend consent -> create_inference -> poll get_inference_status until running -> chat_with_inference.\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.",
+                ? "4. Models: only ids in the Run BiOS catalog can be served (list_models / search_models). "
+                : "4. Models: only ids in the Run BiOS catalog can be trained or served (list_models / search_models). ")
+            + "This is not a live Hugging Face lookup; an id outside the catalog is rejected, never mirrored on demand.\n"
+            + "5. Dedicated serving is platform-derived: serving mode (full/adapter/merged), OpenAI task, and image support come from model/checkpoint lineage. Read them from preflight/create/status; do not invent them.\n"
+            + `6. Context window: the default is min(model native max, ${CONTEXT_DEFAULT_CEILING}) tokens, falling back to `
+            + `${CONTEXT_UNKNOWN_FALLBACK} when unknown. Read model.native_max_context from preflight_inference.\n`
+            + "7. GPUs and money: never substitute a GPU, create a paid resource, or exceed a price cap without explicit user approval. A 503 is transient, never proof of no capacity.\n"
+            + "8. Report a dedicated endpoint as live only when get_inference_status says running; then call it with chat_with_inference. Serverless needs no such poll.",
     });
     // 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 registeredTools = new Set();
+    // MODEL_CATALOG_PATH is the ONE model-discovery endpoint the platform serves:
+    // GET /api/public/model-catalog (model-service/cmd/main.go registers it, with
+    // /stats and /{author}/{name} beside it).
+    //
+    // list_models and search_models both used to call `/api/public/model-search`,
+    // which no service has ever registered. Measured on production 2026-09-19 it
+    // answered HTTP 463 with an empty body from the load balancer, so BOTH tools
+    // failed for every caller — and they are the two the descriptions tell an agent
+    // to call FIRST, before create_training_job or create_inference. Any agent
+    // following the documented flow hit a dead end on step one.
+    //
+    // One constant, not two string literals: this endpoint moved once already
+    // (catalog_detail_route_test.go records the last time a prefix and its
+    // registrations drifted apart), and two copies is how one of them gets missed.
+    const MODEL_CATALOG_PATH = "/api/public/model-catalog";
+    // billionsParam coerces a human parameter count ("7B", "70b", " 13B ") into the
+    // bare number the catalog filter parses.
+    //
+    // The tool advertises "e.g. '7B', '13B', '70B'" and the handler runs ParseFloat,
+    // which fails on a trailing B and yields 0 — and 0 means "no filter" there. So
+    // every documented spelling of max_params was accepted and then silently
+    // ignored, which is worse than rejecting it: the caller gets a plausible,
+    // unfiltered answer. A value with no digits is left alone for the server to
+    // judge rather than silently dropped here.
+    function billionsParam(v) {
+        if (v === undefined)
+            return undefined;
+        const m = /^\s*([0-9]*\.?[0-9]+)\s*[bB]?\s*$/.exec(v);
+        return m ? m[1] : v;
+    }
     const datasetMixingSchema = z.object({
         mode: z.enum(["sequential", "shuffle", "interleave", "phased"]),
         seed: z.number().int().min(Number.MIN_SAFE_INTEGER).max(Number.MAX_SAFE_INTEGER).optional(),
@@ -657,6 +685,11 @@ launchGates = resolveLaunchGates()) {
             "training_methods",
             "gpu_selection",
             "inference",
+            "serverless_inference",
+            "dedicated_deployment",
+            "trained_model_deployment",
+            "identity_and_scope",
+            "end_to_end",
             "hyperparameters",
             "monitoring",
             "cost_optimization",
@@ -682,15 +715,26 @@ ${gatedSurfaces.join(" and ")} ${gatedSurfaces.length > 1 ? "are" : "is"} not av
 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
+Run BiOS has TWO inference products. Choosing the right one is step zero; they are not two names for the same operation.
+
+## Serverless inference — immediate, no deployment
+Use this by default for published Run BiOS model ids. There is no GPU selection, booking, deployment object, provisioning wait, stop/delete lifecycle, or hourly price cap. It is routed by the platform and billed per token.
+1. Call introspect_api_key to confirm the bound workspace and serverless scope.
+2. Read the published ids and capabilities from the serverless catalog; do not substitute a dedicated catalog repo id for a serverless slug.
+3. Call chat_with_inference with that model id, messages, and only capabilities the model advertises. Streaming is optional.
+4. The completion is the result. Do NOT call preflight_inference or create_inference for serverless.
+
+## Dedicated deployment — reserved GPU, durable endpoint
+Choose this for dedicated capacity, custom/trained checkpoints, or a durable endpoint under your control. It creates a paid resource and bills GPU time per second.
+1. **Find a source** — search_models/list_models for a catalog base model, or get_training_checkpoints for a verified trained checkpoint.
+2. **Check identity and money** — introspect_api_key and get_wallet_balance. Never invent another org/workspace.
+3. **Check GPU fit and price** — get_inference_gpu_options.
+4. **Preflight** — preflight_inference validates the exact request with no wallet, queue, database, or GPU side effects. Read canonical_request, alternatives, queue_required and billing from the response.
+5. **Ask for approval** — before create_inference, state the chosen GPU, count, hourly cap, storage and queue consent. Never substitute an alternative silently.
+6. **Create** — create_inference; retain the returned id and one-time key securely. A booking handle must be polled with get_inference_booking.
+7. **Wait for reality** — poll get_inference_status through queue/provisioning/loading; never report the endpoint live until status=running.
+8. **Run** — call chat_with_inference using the dedicated inference key or deployment identity.
+9. **Observe/control/clean up** — metrics, notifications, stop/resume/restart, then delete_inference when the user explicitly asks to remove the paid deployment.
 
 ## 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.
@@ -787,17 +831,31 @@ END TO END: capture what a model was asked and answered, have people or judges s
         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).
+Run BiOS provides serverless inference, dedicated GPU deployments, datasets, and model training. These are separate products with different billing and lifecycle semantics.
+
+## Choose the workflow before calling tools
+- **Need an answer now from a published serverless model?** Use serverless inference: model id + chat_with_inference. No GPU booking or deployment object; billed per token.
+- **Need dedicated capacity or a durable endpoint?** Use dedicated deployment: GPU options -> preflight -> explicit approval -> create -> wait for running -> chat -> stop/delete. Billed per second of GPU time.
+- **Need custom weights?** Prepare a dataset -> preflight and run training -> monitor -> select a verified checkpoint -> deploy that checkpoint through the dedicated workflow.
+- **Need continuous improvement from real conversations?** Use the Conscious Loop workflow; capture is opt-in and automated model calls spend through the workspace's own serverless account.
 
-## Core Workflow
-1. **Upload a dataset** — JSONL, Parquet, or CSV. The platform auto-validates format, detects columns, and maps fields.
+## Training Workflow
+1. **Upload/import a dataset** — use upload_dataset for a local JSONL file or import_huggingface_dataset for a Hub source. Poll get_dataset_status until ready, then preview_dataset before training. A created row is not proof that processing succeeded.
 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
+7. **Launch and monitor** — create_training_job only after preflight and explicit spend approval. Poll get_training_status; read metrics, evals and logs instead of inferring progress from elapsed time. Stop/resume only when available actions permit it.
+8. **Select a checkpoint** — get_training_checkpoints; use a verified/succeeded checkpoint. A running job or incomplete checkpoint is not deployable.
+9. **Deploy the trained model** — preflight_inference with source_type=checkpoint, source_job_id and source_checkpoint_id, approve GPU/cost, then create_inference. Serving mode and base-model lineage are derived; do not guess them.
+10. **Wait, infer, observe** — poll get_inference_status until running, call chat_with_inference, inspect metrics/notifications, then stop or delete when explicitly requested.
+11. **Clean up safely** — delete_training_checkpoint or delete_dataset only after confirming it is no longer needed. Deleting source data/checkpoints is irreversible and is never implied by stopping training or deleting a deployment.
+
+## Identity, account and scope
+- Every MCP call uses the API key's bound organization and workspace. Start with introspect_api_key and repeat the resolved identity before any paid or destructive action.
+- Never ask an agent to choose an arbitrary account id; tool responses are scoped server-side. A different workspace requires a different authorized credential.
+- get_wallet_balance describes the same billing owner that training, dedicated deployment, and automated Loop calls spend from.
 
 ## 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
@@ -1052,9 +1110,78 @@ When to use: Before SFT, when your domain has specialized vocabulary/knowledge.
 - Memory depends on the full configuration and input shapes, not parameter count alone. Do not invent a smaller minimum or claim that quantization always halves total memory.
 - Full fine-tuning is not a guarantee of higher accuracy than adapters. Use representative validation to compare outcomes.
 - Preflight admission is not proof of universal freedom from hardware faults or OOM. Report actual tested configurations and measured headroom.`,
+            serverless_inference: `# Serverless Inference
+
+Serverless is the immediate, per-token inference product. It does NOT create or manage a deployment and does not reserve a GPU.
+
+## Correct flow
+1. Call introspect_api_key. Confirm the key's bound workspace and serverless permission.
+2. Select a published serverless model id and read its advertised capabilities. A dedicated catalog repository id and a serverless model slug are not interchangeable.
+3. Call chat_with_inference with the model id and messages. Optional surfaces include stream, tools/tool_choice, response_format and reasoning_effort only when the chosen model advertises them.
+4. Read the returned completion. There is no provisioning status to poll and nothing to stop/delete.
+
+## Do not do this
+- Do not call get_inference_gpu_options, preflight_inference or create_inference for serverless.
+- Do not report an unsupported capability as an outage; an honest 400 means choose a model that advertises it.
+- Do not retry an empty completion blindly: finish_reason=length means max_tokens was exhausted, not that the endpoint lost data.
+
+## Billing
+Serverless is billed per token to the API key's bound workspace. It is distinct from dedicated GPU billing and from the Loop agent, even though the Loop agent spends through that workspace's serverless account.`,
+            dedicated_deployment: `# Dedicated Model Deployment
+
+A dedicated deployment reserves GPU capacity and creates a durable endpoint. Use it for dedicated capacity, custom/trained checkpoints, or lifecycle control. It bills GPU time per second and is NOT required for serverless inference.
+
+## Base-model flow
+1. introspect_api_key and get_wallet_balance.
+2. search_models/list_models, then get_inference_gpu_options.
+3. preflight_inference: read canonical_request, selected_gpu, alternatives, queue_required, native context and billing.
+4. State the exact GPU/count, storage, maximum hourly price and queue consent; wait for explicit user approval.
+5. create_inference using canonical_request. Keep the deployment id and one-time inference key secure. If a booking handle is returned, poll get_inference_booking.
+6. Poll get_inference_status through queued/provisioning/loading. Only status=running proves the endpoint is live.
+7. chat_with_inference with the dedicated key/deployment identity.
+8. get_inference_metrics and get_inference_notifications; stop/resume/restart only when requested.
+9. delete_inference is irreversible and only follows explicit confirmation that the paid deployment should be removed.
+
+Capacity errors include bookable alternatives. Never silently substitute a GPU or raise a price cap. A 503 is transient and is not proof that capacity is unavailable.`,
+            trained_model_deployment: launchGates.training
+                ? `# Deploying a Trained Model\n\nTraining creation is not available in this deployment. Existing verified checkpoints can still be read with get_training_checkpoints and deployed through the dedicated workflow when the key has access. Do not claim a running job or incomplete checkpoint is deployable.`
+                : `# Train, Deploy, and Infer a Custom Model
+
+1. Prepare data with upload_dataset or import_huggingface_dataset. Poll get_dataset_status until ready and preview_dataset to verify the actual rows/format.
+2. Choose a catalog base model; call get_training_capabilities, get_model_config, get_recommended_gpu/recommend_training_config, then preflight_training_job.
+3. State method, adapter, GPU/count, dataset sampling, maximum hourly price and estimated bound; obtain explicit spend approval.
+4. create_training_job. Poll get_training_status and read metrics, evals and logs. Do not translate elapsed time into progress or success.
+5. After success, call get_training_checkpoints and select a verified checkpoint.
+6. Call preflight_inference with source_type=checkpoint, source_job_id and source_checkpoint_id. Serving mode/base lineage are derived from the checkpoint; do not invent them.
+7. Obtain deployment spend approval, create_inference, poll until running, then chat_with_inference.
+8. Observe metrics/notifications and clean up only on explicit request. Deleting the deployment does not delete the checkpoint or dataset; each destructive operation is separate and irreversible.`,
+            identity_and_scope: `# Identity, Account, and Scope
+
+Every MCP tool acts inside the API key's bound organization and workspace.
+1. Call introspect_api_key first. Read user/workspace/org, scopes, allowed tools and feature grants from the result.
+2. Call get_wallet_balance before any training, dedicated deployment or automated Loop action that spends.
+3. Never invent, guess or substitute another org/workspace/account id. A different workspace requires a different authorized credential.
+4. Serverless calls, dedicated deployments, training jobs, datasets and Loop artifacts remain scoped to that resolved workspace. Empty lists may mean this workspace has no resources; they do not prove the platform has none globally.
+5. Repeat the resolved workspace and cost owner before asking for spend or destructive consent, without exposing the credential itself.`,
+            end_to_end: launchGates.training || launchGates.datasets
+                ? `# End-to-End Availability\n\nServerless inference and dedicated deployment are fully live. Start with identity_and_scope, then choose serverless_inference or dedicated_deployment. Dataset/training creation is gated in this deployment; do not invent a workaround. Existing datasets, jobs and checkpoints remain readable and manageable through their lifecycle tools.`
+                : `# End-to-End Platform Flow
+
+1. Identity: introspect_api_key and get_wallet_balance.
+2. Data: upload/import -> get_dataset_status until ready -> preview_dataset.
+3. Plan training: catalog model -> capabilities/config -> GPU recommendation -> preflight_training_job.
+4. Consent and train: explicit spend approval -> create_training_job -> status/metrics/evals/logs -> verified checkpoint.
+5. Deploy checkpoint: preflight_inference(source_type=checkpoint) -> explicit deployment approval -> create_inference -> status=running.
+6. Infer: chat_with_inference -> metrics/notifications.
+7. Improve: optional Conscious Loop capture/review/evaluation/training rule; capture and spending are separate opt-ins.
+8. Clean up: stop/delete deployment, checkpoint or dataset only as separate explicit irreversible actions.
+
+At every step use returned ids and available_actions. Never infer the next action from a status label alone, never report success before the authoritative terminal state, and never substitute a GPU/model/price without approval.`,
             inference: `# Model Inference Guide
 
-Deployments serve either a verified fine-tuning checkpoint or a base model from the catalog through an OpenAI-compatible endpoint.
+Run BiOS has two inference products. Use serverless_inference for immediate per-token calls with no deployment, and dedicated_deployment for reserved GPU capacity or trained checkpoints.
+
+Dedicated 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,
@@ -1341,8 +1468,8 @@ create (1-5 choices), and the queue itself stays opt-in.`,
         // ("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 },
+        const data = await client.api(MODEL_CATALOG_PATH, {
+            params: { q, max_params: billionsParam(max_params) },
         });
         return json(data);
     });
@@ -1357,7 +1484,7 @@ create (1-5 choices), and the queue itself stays opt-in.`,
         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", {
+        const data = await client.api(MODEL_CATALOG_PATH, {
             params: {
                 type: type && type !== "all" ? type : undefined,
                 sort,
@@ -1960,6 +2087,12 @@ create (1-5 choices), and the queue itself stays opt-in.`,
             formData.append("file", blob, basename(absPath));
             formData.append("name", fileName);
             formData.append("size", fileStat.size.toString());
+            // Dataset-service's multipart contract requires workspace_id in the BODY.
+            // JSON routes can rely on the gateway-injected header, which is why every
+            // read worked while upload answered `workspace_id: Field required` for a
+            // perfectly valid API key. Hosted MCP has the OAuth grant's workspace;
+            // local stdio resolves the key's binding once through introspection.
+            formData.append("workspace_id", await client.resolvedWorkspaceId());
             const data = await client.api("/api/datasets/upload", {
                 method: "POST",
                 formData,