Quickstart

June 24, 2026 ยท View on GitHub

This quickstart uses the real gateway-smoke app in the repository. It is the fastest way to see role-model route a request and emit explainable runtime artifacts.

Prerequisites

  • Node.js 24
  • pnpm 10.x

Run the smoke flow

From the repository root:

pnpm install
pnpm run smoke

The smoke app lives at role-model-router/apps/gateway-smoke/ and routes a synthetic request through the reference router.

What the smoke request looks like

The smoke run asks the router to satisfy a request with these requirements:

  • roleHintId: "coder"
  • taskType: "coder.edit"
  • requiredCapabilities: ["code.read", "code.write"]
  • preferredCapabilities: ["reasoning.multi_step"]
  • requiredModalities: ["text"]
  • needsTools: true
  • strategy: "balanced"
  • preferLocal: true
  • budgetLimit: 0.01

That request is matched against the sample endpoint metadata in testdata/endpoint-metadata/sample-endpoints.json.

What gets emitted

The smoke run writes artifacts under runtime-output/gateway-smoke/:

FileWhat it shows
router-decision.jsonthe chosen endpoint, eligibility results, scores, and selection reasons
trace-spans.jsonthe high-level routing phases and their timing
trace-events.jsonlevent-level trace output
usage-events.jsonlrequest accounting metadata
observed-performance.jsonthe measured profile aggregated for the chosen endpoint

What you should see

In the current baseline, the smoke flow chooses cli.local.coder.

Why:

  1. it satisfies the required code.read and code.write capabilities
  2. it supports text output and tools
  3. it matches the local preference
  4. the other sample endpoints are excluded for missing required capability

The resulting router-decision.json records:

  • chosen_endpoint_id: "cli.local.coder"
  • exclusion reason code CAPABILITY_MISSING for the non-coder endpoints
  • selection reasons including BEST_TOTAL_SCORE, DECLARED_PROFILE_USED, MEASURED_PROFILE_USED, and LOCAL_PREFERENCE_APPLIED

Inspect the artifacts

Start with these files:

  1. runtime-output/gateway-smoke/router-decision.json
  2. runtime-output/gateway-smoke/trace-spans.json
  3. runtime-output/gateway-smoke/usage-events.jsonl
  4. runtime-output/gateway-smoke/observed-performance.json

Together they show the main four outputs the protocol cares about:

  • decision: what the router chose and why
  • trace: how routing progressed
  • usage: what the request consumed
  • observed performance: how the chosen endpoint behaved

Read the flow in context