AI-Native Surface: 65 MCP tools, ambient intelligence headers, and GET /v1/discovery

2026-03-17

routerauto-selectormnidiscoveryerror-recovery

What We Built

Made BrainstormRouter's 13 intelligence systems visible and discoverable to AI agents. Previously, the router computed complexity scores, Thompson sampling selections, and budget forecasts on every request — but only ~30% of that intelligence was exposed to callers. Now every completion response includes ambient intelligence headers explaining WHY the engine made each decision.

Added GET /v1/discovery — a self-describing endpoint that returns everything an agent needs to know about routing strategies, health, budget, model stats, and available intelligence headers. Fixed discovery accuracy across all surfaces: llms.txt (both copies), agents.json, and the developers page.

Completed the error recovery registry with 11 new error types (circuit_breaker_open, sentinel_down, tool_blocked, pii_detected, no_compatible_model, governance_violation, tool_governance_violation, model_not_found, byok_enforcement_blocked, insufficient_context) bringing total coverage to 20 error types.

Why It Matters

When OpenClaw connected to BrainstormRouter and sent model: "auto", it couldn't tell what happened. Did it get Thompson sampling? Complexity routing? A random fallback? The response was a black box. Now every response tells the caller: "I picked this model using Thompson sampling with 0.87 confidence because your request scored 6/10 complexity." Agents can adapt their behavior based on these signals.

The discovery inaccuracies were embarrassing — claiming 365 models when we have 247, claiming 46 MCP tools when we have 65. An AI agent reading our first-contact surface was getting wrong information.

How It Works

Ambient Intelligence Headers (every completion response):

X-BR-Selection-Method: thompson-sampling
X-BR-Complexity-Level: moderate
X-BR-Complexity-Score: 6
X-BR-Selection-Confidence: 0.87
X-BR-Models-Considered: 180
X-BR-Context: {"model":"anthropic/claude-sonnet-4","why":"thompson-sampling","complexity":"moderate","confidence":0.87,"cost":0.0134}

Discovery endpoint: GET /v1/discovery returns routing strategies, Thompson sampling thresholds, complexity scoring rules, provider health, budget limits, and all intelligence header documentation.

Error recovery: Every error type now includes a machine-actionable recovery field with the specific endpoint to call.

The Numbers

9 new intelligence headers on every completion response
20/20 error types with recovery hints (was 9/20)
65 MCP tools documented in agents.json (was claiming 46)
247 model endpoints (was claiming 365)
1 new API endpoint: GET /v1/discovery

Competitive Edge

No other AI gateway tells you WHY it chose a model. Portkey gives you the response. OpenRouter gives you the response. BrainstormRouter gives you the response AND the reasoning — complexity score, selection method, confidence level, models considered, budget remaining. This is the data an intelligent agent needs to make better decisions on the next request.

Lockstep Checklist

[x] API Routes: src/api/routes/discovery.ts created, mounted in server.ts, RBAC permission added.
[x] TS SDK: packages/sdk-ts/src/resources/discovery.ts — client.discovery.get().
[x] Python SDK: packages/sdk-py/src/brainstormrouter/resources/discovery.py — sync + async.
[x] OpenAPI: docs/openapi.yaml — discovery endpoint + 18 response header schemas on completions.
[x] Discovery surfaces: site/llms.txt, src/api/server.ts embedded const, site/.well-known/agents.json, site/developers/index.html all updated.