Home Dashboard GitHub

MNI v2: Agent-Native Runtime Interface — Self-Awareness, Self-Healing Errors, Transparent Health

2026-03-15

What We Built

MNI v2 (Machine-Native Interface v2) transforms BrainstormRouter from an API that agents _can_ use into one that agents _want_ to use. Three new endpoints give agents complete self-awareness in a single call, transparent provider health, and machine-actionable error recovery on every failure.

GET /v1/self is the megaendpoint — one call returns identity, capabilities, health (sentinel + circuit breaker), budget, memory stats, configuration, dynamic suggestions ("register a provider", "enable guardrails"), and recent errors. An agent goes from "who am I and what can I do?" to fully informed in one round trip.

GET /v1/catalog/runnable answers the #1 question agents have: "what models will actually work if I call them right now?" It filters the full 365-model catalog by circuit breaker state, sentinel health, BYOK key availability, and budget — returning only models guaranteed to succeed, with exact counts of why others were filtered out.

Every error response now includes a recovery field with structured next steps: the endpoint to call, the HTTP method, a body template, and a docs link. Agents no longer need to parse error messages — they follow the recovery hint programmatically.

Why It Matters

AI agents are the primary consumers of AI gateway APIs, yet every gateway today is designed for human developers reading docs. An agent hitting "All endpoints filtered out" has no idea whether to register a provider key, increase its budget, or wait for a circuit breaker to close. It retries, fails, retries — burning tokens on confusion.

MNI v2 eliminates this entirely. Every error is self-healing. Every call to /v1/self tells the agent exactly what to configure next. The filtered_out counts in /v1/catalog/runnable explain precisely why models are unavailable. This is the difference between an API that works _for_ humans and one that works _as_ a tool for AI agents.

How It Works

Error Recovery Registry (src/api/shared/error-recovery.ts):

// Every error type maps to a structured recovery hint
resolveRecoveryHint({ type: "byok_required", provider: "anthropic" });
// → { action: "register_provider", endpoint: "POST /v1/providers",
//    body_template: { provider: "anthropic", api_key: "<your_api_key>" } }

Error Enrichment Middleware — runs as post-processing on all /v1/ responses. Clones the response, checks for missing recovery field, enriches from registry, and sets X-BR-Recovery- headers.

Self-Awareness Megaendpoint — aggregates from 8 existing systems (RBAC, sentinel, circuit breaker, budget, memory, config, provider keys, usage events) into one cached (30s) response. Dynamic suggestions are computed based on tenant state.

Runnable Catalog — cross-references CircuitBreakerManager.getAllStates(), EndpointSentinel.getProviderStatus(), tenant BYOK keys, and env-provided keys to compute the exact routable set.

CLI (packages/cli/) — br self, br models, br chat "hello", br health, br providers add anthropic — full API client from the terminal.

The Numbers

  • 3 new API endpoints: /v1/self, /v1/catalog/runnable, /v1/health/providers
  • 9 error types with machine-actionable recovery hints
  • 57 MCP tool descriptions rewritten (action-oriented, <200 chars, "when to use" triggers)
  • 6 Link headers on every response (up from 2): service-desc, describedby, getting-started, mcp-server, self-awareness, agent-discovery
  • 9 CLI commands in br binary: auth, self, models, chat, health, providers, budget, usage, killswitch
  • 2 SDK resources added: self + runnable in both TypeScript and Python SDKs
  • 0 lint errors, 0 type errors — clean pnpm check

Competitive Edge

No other AI gateway provides machine-actionable error recovery. Portkey, OpenRouter, and LiteLLM return human-readable error messages that agents must parse with heuristics. BrainstormRouter returns structured recovery objects that agents execute directly — no guessing, no retries, no wasted tokens. Combined with /v1/self (zero-to-informed in one call) and the br CLI (terminal-native control), BrainstormRouter is the first AI gateway designed for AI agents as first-class consumers.

Lockstep Checklist

  • [x] API Routes: src/api/routes/runnable.ts, self.ts, provider-health.ts — 3 new routes mounted in server.ts
  • [x] TS SDK: packages/sdk-ts/src/resources/self.ts, runnable.ts — wired into BrainstormRouter client
  • [x] Python SDK: packages/sdk-py/src/brainstormrouter/resources/self.py, runnable.py — sync + async
  • [x] MCP Schemas: All 57 tool descriptions rewritten in src/mcp/tool-manifest.ts
  • [ ] Master Record: docs/architecture/master-capability-record.md — update pending