Turn the MCP, A2A and inference parsers into libraries, with saved real-traffic test cases #1503

Part of #1437 (assessment: laptop data plane on Praxis) · prep work, useful to Cortex on its own

Status: there is no shipped Cortex–Praxis integration today (the paused cmd/cortex-praxis converter is not one), and the interim path is not decided (LLM traffic to praxis-ai as an inference server, or all traffic through Praxis via #1491). This is a refactor with no behaviour change: it is useful to Cortex on its own, and would make a possible move to Praxis easier whichever path is taken.

Problem

Parsing an LLM, MCP or A2A request is mostly pure work (bytes in, structured result out), but most of it is reachable only as a plugin. One exported entry point exists: inferenceparser.ParseResponse(path, body), which cpex already calls. Everything else is unexported or inline:

• inference (mostly pure):
  • requests: parseAnthropicRequest and parseOpenAIRequest take only the body; parseResponsesRequest also needs headers (zstd decode);
  • responses: parseAnthropicJSON, parseAnthropicSSE, parseResponsesJSON, parseResponsesSSE, parseInferenceJSON, parseInferenceSSE. The SSE parsers write into the request's existing result;
  • per-frame folds: foldAnthropicFrame, foldOpenAIFrame, foldResponsesFrame (responses.go:499). They need stream state that the plugin keeps on pctx, and foldResponseFrame takes pctx itself;
  • plugin-only logic: the dialect is chosen from the path, the response arm from Content-Type and whether a stream ran, and AgentRole is set in OnRequest.
• MCP (not pure today): request parsing is inline in OnRequest (mcpparser/plugin.go:166-266), and needs the method, path, the configured path matcher and the Mcp-Session-Id header. parseMCPResponse returns an unexported type that applyMCPResponseRPC writes into pctx.
• A2A (not pure today): request parsing is inline in OnRequest (a2aparser/plugin.go:35-127). Response parsing is extractSendResponse, extractStreamEvent and sessionIDFromJSON (:259-430). parseA2AParts is only a helper over already-decoded data.

The inference parser also prices the request (cost.go:64-113), so parsing and pricing are one plugin. It imports core/cost/pricing and core/cost/settle from cost.go, cacheblind.go and plugin.go (pricing.Resolver, settle.IsEventStream).

Apart from ParseResponse, nothing outside the plugin can parse a body: not a replay tool, not a test, not another proxy. And there are no saved real-traffic test cases: inference-parser's 18 test files (about 4,900 lines) build inputs as inline JSON, with a few verbatim captured blocks pasted in (e.g. anthropic_test.go:166, :624). The only testdata/ in the repo is core/cost/pricing/testdata.

Proposal

1. Parser libraries (e.g. core/parse/inference, core/parse/mcp, core/parse/a2a): exported ParseRequest(method, path, headers, body, config), ParseResponse(...) and a streaming fold with explicit state, returning the parsed-request types. The three plugins become thin wrappers.
   • MCP and A2A request parsing must be extracted from OnRequest first.
   • The libraries depend on the data package from Split the shared data types out of core/pipeline #1502, so Split the shared data types out of core/pipeline #1502 should land first.
2. Pricing out of the parser library. The library computes no cost. Pricing stays in the plugin wrapper (or moves to a separate cost step), calling Price a request from plain values instead of the plugin request context #1501's plain-value Settle. Moving it changes when the settle-once latch runs, so it needs its own test.
3. Saved test cases as the safety net: real captured request and response pairs (JSON and SSE, per agent) stored under testdata/, each with the expected parsed result, run by one table test per library. They prove the move changed nothing, and they also show exactly what Cortex needs from a parser if another one (e.g. praxis-ai's) were ever used instead. A request to praxis-ai to expose parsed content to other filters is drafted as a Discussion, not yet posted; see Proposal: Assess replacing the laptop Go forward proxy with Praxis — blocked on three upstream capabilities #1437's tracker.

Design questions

1. Library API: whole-body functions only, or also the incremental frame fold the streaming path uses?
2. Should captured fixtures be scrubbed (no real prompts), and where do they come from — a capture tool reading the session archive?
3. Fixture format: one file per case (request, response, expected), or one golden file per parser?

Done when

• The three parser plugins contain no parsing logic, only calls into the libraries; ParseResponse keeps working for cpex.
• Each library has saved real-traffic test cases covering request, JSON response and SSE response.
• The parser libraries import neither core/cost/settle nor core/cost/pricing. The plugin wrapper may.

Evidence read at main @ e455a04 (2026-10-25); not built.