ASP.NET Core public route contract¶
The canonical public surface is
backend-dotnet/public-route-contract.json:
56 HTTP method/path pairs and no WebSocket route. ASP.NET Core is the only
public owner, and every entry is aspnet-direct. The 31 Agent v1 routes under
/agent/v1/* (including the run-independent skills catalog/preferences and the user plugin list, settings and pinned GitHub install)
and the POST /host/shutdown route are active alongside the
settings, session rewind, activity, status, and model routes. They cover
run creation, policy/approval/input/trust, cancellation, typed command dispatch, SSE
replay, and reconciliation; this is not a read-only tracer surface.
POST /agent/v1/runs/selected requires a provider/model intent and commits it
with the root run. The native TUI and GUI use this route so an older Host rejects the
request instead of silently ignoring a new field. The legacy create route
remains available to existing clients.
POST /settings/provider/key validates a candidate OpenAI, Anthropic,
Models.dev or custom endpoint credential with the provider before committing it,
preserving an existing key on rejection or unavailable validation, and records
the outcome in provider_key_status.
It shares the normal loopback/bearer boundary and settings transaction gate. GUI
does not fall back to POST /settings when an older Host lacks this route.
Session history adds /sessions/page for paged summaries,
/sessions/{sessionId}/messages for bounded retained-message pages and
/sessions/search for literal full-text hits. These share bearer/loopback checks
and do not expose database maintenance over HTTP.
Each entry contains:
method,path, andtransport— the stable public wire identity;source— the ASP.NET source file that maps the endpoint;classification—aspnet-direct;winui_callers— known desktop call sites, which may be empty for routes without a WinUI caller.
aspnet-direct means ASP.NET performs the business operation itself, including
GET /status and the GET /models provider catalog read from the host settings
store. There is no worker-backed or Python-backed public route left; the media
surfaces (voice, STT, VTS, observation) were removed in the 2026-09-13 passes.
There are no feature-selected owners, shadow reads, public forwarding routes, or alternate host mode. Unknown public paths are never sent to Python.
Reserved routes¶
21 entries intentionally have empty winui_callers: the message search route
GET /sessions/search driven by the CLI; the TUI conversation branch route
(POST /sessions/{sessionId}/fork); 14 additive /agent/v1/* routes —
the 11 run routes (legacy and selected creation, run read, event stream, payload read, approvals,
inputs, trust, cancel, compact, and commands) and the three policy
routes (GET/POST /agent/v1/policies and DELETE /agent/v1/policies/{ruleId})
— which are driven through the Agent harness flow rather than direct WinUI
callers; and the five workspace coordination routes, which external clients
drive over HTTP. The remaining /agent/v1/* routes (run activities, session
run listing, and the session preset read) do have direct ApiService callers.
The three subagent routes have AgentRunClientAdapter callers through the typed
Client library and drive the chat's read-only Subagents panel, including the
bounded change review for a coding result.
The three skill catalog/preferences/package routes have CustomizeView callers
through SkillsApiClient, before a run exists. Package installation is an
explicit user action, not an advertised model tool.
Empty winui_callers is therefore expected for these reserved routes and is not a dead-route signal.
Verification¶
& (Join-Path $env:RU_ROOT ".venv\Scripts\python.exe") scripts\check_aspnetcore_route_matrix.py
dotnet test backend-dotnet/RuBackend.Tests/RuBackend.Tests.csproj --no-restore `
--filter FullyQualifiedName~PublicRouteContractTests
The checker validates count, uniqueness, schema, final classification, source
existence, and route literals. The .NET test starts the real application and
compares the contract against ASP.NET's EndpointDataSource; WebSocket routes
are represented by their HTTP upgrade endpoints during this comparison.
Any public route change must update its endpoint tests, this JSON contract, and the WinUI caller list in the same change.