ag-ui-validate 0.2.0 → 0.4.0

package/README.md

@@ -15,10 +15,10 @@ spec section.
 2 errors, 0 warnings, 1 info — 3 of 7 AG-UI features exercised
 ```
 
-> **Status: pre-release.** The core validator, the language-neutral fixture
-> corpus, and the transport layer are implemented and tested. The CLI
-> (`npx ag-ui-validate <url|->`), the Vitest matcher, and SARIF/JUnit
-> reporters are in progress.
+> **Status:** released to both npm (`npm install ag-ui-validate`) and PyPI
+> (`pip install ag-ui-validate`). Both packages version in lockstep — same
+> rule catalog, same fixture corpus, byte-identical CLI; see
+> [Python](#python) below.
 
 ## Why
 
@@ -29,7 +29,7 @@ section*. This project is that tool — the AG-UI analogue of what
 
 Three design commitments make it trustworthy:
 
-- **Every diagnostic cites the spec.** Each of the 40 rules carries a
+- **Every diagnostic cites the spec.** Each of the 46 rules carries a
   `specUrl` (and where possible an exact `specQuote`) pointing at the
   governing section of [docs.ag-ui.com](https://docs.ag-ui.com) or the WHATWG
   SSE spec. Behaviour the spec doesn't clearly govern is reported at `info`
@@ -39,7 +39,7 @@ Three design commitments make it trustworthy:
   unknown event types, hostile objects — all diagnostics, never exceptions
   (fuzz-tested against 50k hostile inputs).
 - **False positives are treated as worse than false negatives.** The rules are
-  grounded in `@ag-ui/core` v0.0.58 and the current docs; where the two
+  grounded in `@ag-ui/core` v0.0.59 and the current docs; where the two
   disagree, the SDK wins and the discrepancy is recorded.
 
 ## Quickstart
@@ -56,10 +56,10 @@ npx ag-ui-validate run.jsonl                    # recorded stream (NDJSON/JSONL
 cat run.jsonl | npx ag-ui-validate -            # stdin
 ```
 
-Exit codes: `0` clean, `1` findings at error level (or warnings over
-`--max-warnings`), `2` tool failure. Timing-based transport rules are
-meaningless for recordings, so they are reported as *skipped with a reason*
-rather than risking false positives.
+Exit codes: `0` clean, `1` findings at or above the `--fail-on` threshold
+(`error` by default, or warnings over `--max-warnings`), `2` tool failure.
+Timing-based transport rules are meaningless for recordings, so they are
+reported as *skipped with a reason* rather than risking false positives.
 
 Useful flags (see `--help` for all):
 
@@ -70,20 +70,23 @@ Useful flags (see `--help` for all):
 | `--rule AGUI105=error`, `--off AGUI902` | per-rule severity overrides |
 | `--features shared-state,...` | declare exercised features (enables e.g. AGUI305) |
 | `--max-warnings 0` | fail CI on any warning |
+| `--fail-on <error\|warning\|none>` | severity that triggers a nonzero exit (default `error`; `none` for report-only runs) |
 | `--header "Authorization: Bearer …"`, `--timeout 30` | endpoint options |
 
 ### Validate in CI (GitHub Action)
 
 ```yaml
-- uses: langport-dev/ag-ui-validate/action@main
+- uses: langport-dev/ag-ui-validate-action@v1
   with:
     target: http://localhost:8000/agui   # or a recorded .jsonl file
     sarif-file: agui.sarif               # optional: upload via codeql-action
 ```
 
-The step fails on error-severity findings, writes a findings table to the job
-summary, and exposes `errors`/`warnings`/`info` outputs — see
-[action/README.md](action/README.md).
+The step fails on error-severity findings, writes a findings table (with a
+counts-by-category breakdown) to the job summary, annotates the PR inline
+with `::error`/`::warning` for each finding, and exposes
+`errors`/`warnings`/`info`/`sarif-path`/`report-path` outputs — see
+[langport-dev/ag-ui-validate-action](https://github.com/langport-dev/ag-ui-validate-action).
 
 ### Test your agent in Vitest
 
@@ -124,7 +127,7 @@ const { diagnostics, summary, features, skipped } = v.report()
 ```
 
 The core is a pure function over an event sequence: zero I/O, zero runtime
-dependencies, isomorphic across Node 20+, browsers, Deno, and Workers.
+dependencies, isomorphic across Node 22+, browsers, Deno, and Workers.
 
 ### Validate a live endpoint
 
@@ -170,12 +173,67 @@ import { formatReportSummary, toSarif, toJUnit } from "ag-ui-validate/report"
 }
 ```
 
+## Python
+
+A native Python port ships in [py/](py/) — the same rule catalog, the same
+fixture corpus, and a CLI with byte-identical flags, error messages, and
+JSON/SARIF/JUnit output to the TypeScript one above. It's checked against
+the TypeScript implementation on every PR by Parity CI (see
+[docs/TESTING.md](docs/TESTING.md) for how, and
+[docs/PYTHON-PORT-PLAN.md](docs/PYTHON-PORT-PLAN.md) for the port's full
+milestone history).
+
+```bash
+pip install ag-ui-validate   # or "ag-ui-validate[transport]" for just the endpoint-validating extras
+```
+
+### CLI
+
+```bash
+ag-ui-validate http://localhost:8000/agui   # live endpoint (POSTs a RunAgentInput)
+ag-ui-validate run.jsonl                    # recorded stream (NDJSON/JSONL or SSE capture)
+cat run.jsonl | ag-ui-validate -            # stdin
+```
+
+Same exit codes and the same flags as the [CLI](#cli) above (see
+`ag-ui-validate --help`) — the Python argument parser is a direct,
+hand-rolled port of the TypeScript one rather than `argparse`/`click`,
+specifically to keep both CLIs' invocation and error messages
+byte-for-byte identical.
+
+### Test your agent in pytest
+
+```python
+from ag_ui_validate.pytest_plugin import assert_valid_agui
+
+def test_my_agent_stream(captured_events):
+    assert_valid_agui(captured_events, features=["shared-state"], max_warnings=0)
+```
+
+`assert_valid_agui` accepts a list of events (dicts or JSON strings) or a
+whole JSONL capture as one string, and raises `AssertionError` with every
+finding's rule ID and spec link on failure. It registers automatically as a
+pytest plugin on install — no `conftest.py` setup needed. An async
+counterpart validates a live endpoint directly from a test:
+
+```python
+from ag_ui_validate.pytest_plugin import assert_valid_agui_endpoint
+
+async def test_my_live_agent():
+    await assert_valid_agui_endpoint("http://localhost:8000/agui", max_warnings=0)
+```
+
+`assert_valid_agui` has zero runtime dependencies; only the
+endpoint-validating helpers (`assert_valid_agui_endpoint`,
+`validate_agui_endpoint`) pull in `httpx`
+(`pip install ag-ui-validate[transport]`).
+
 ## The rule catalog
 
-40 rules, maintained as **data** in
-[src/rules/catalog.json](src/rules/catalog.json) so other implementations
-(Python, Go, …) can share them. Every rule has its own page — spec grounding,
-severity, and a violating example from the corpus — in the
+46 rules, maintained as **data** in
+[spec/catalog.json](spec/catalog.json), shared by both implementations in
+this repo ([TypeScript](.) and [Python](py/)) rather than duplicated.
+Every rule has its own page — spec grounding,
 **[rule index](docs/rules/README.md)** (generated from the catalog,
 drift-checked in CI):
 
@@ -187,17 +245,18 @@ drift-checked in CI):
 | State | AGUI301–305 | RFC 6902 patch validity, deltas that fail to apply to reconstructed state |
 | Reasoning | AGUI401–402 | reasoning content without an open reasoning message |
 | Transport | AGUI501–508 | SSE framing, Content-Type, keepalive gaps, buffering, dropped connections |
+| Subagents | AGUI601–606 | duplicate/unmatched `SUBAGENT_STARTED`/`FINISHED`/`ERROR`, unterminated subagents, unknown `parentSubagentRunId`, continuation events that disagree with their entity's owner |
 | Hygiene | AGUI901–903 | `RAW`-wrapping typed events, missing timestamps, un-namespaced `CUSTOM` names |
 
-The event taxonomy itself (33 wire types, field schemas) is derived from
+The event taxonomy itself (36 wire types, field schemas) is derived from
 [`@ag-ui/core`](https://www.npmjs.com/package/@ag-ui/core)'s own schemas and
 drift-tested against the installed SDK on every run.
 
 ## The fixture corpus
 
-[fixtures/](fixtures/README.md) is a language-neutral conformance corpus:
+[spec/fixtures/](spec/fixtures/README.md) is a language-neutral conformance corpus:
 7 valid streams (one per canonical AG-UI feature — the false-positive guards)
-and 40 invalid fixtures (one per rule) with exact expected diagnostics. Any
+and 46 invalid fixtures (one per rule) with exact expected diagnostics. Any
 validator implementation that consumes the shared catalog can be tested
 against it; the replay protocol is documented in the corpus README.
 
@@ -219,7 +278,7 @@ Component-by-component instructions live in
 rules are tracked in [docs/spec-questions.md](docs/spec-questions.md).
 
 Adding a rule: add the catalog entry (with its `specUrl`), add the fixture
-stream + intended findings to `scripts/build-fixtures.mjs`, and run
+stream + intended findings to `js/scripts/build-fixtures.mjs`, and run
 `npm run fixtures:build` — the meta-tests fail until both exist. Rule
 *proposals* belong upstream as issues on
 [`ag-ui-protocol/ag-ui`](https://github.com/ag-ui-protocol/ag-ui) first; this

package/dist/{catalog-BglXBNbL.js → catalog-3e6INLCp.js}

@@ -1,13 +1,14 @@
-//#region src/rules/catalog.json
+//#region ../spec/catalog.json
 var catalog_default = {
 	$comment: "AG-UI conformance rule catalog. Data, not code: a Python/Go implementation shares these rules. Severities follow the working agreement that behaviour the spec does not clearly govern is at most 'info' — entries with 'specQuestion' were downgraded accordingly; see docs/spec-questions.md.",
-	catalogVersion: "0.1.0",
+	catalogVersion: "0.4.0",
 	spec: "0.x",
 	rules: [
 		{
 			"id": "AGUI001",
 			"severity": "error",
 			"title": "Run does not start with RUN_STARTED",
+			"category": "lifecycle",
 			"messageTemplate": "First event of the run is {type}; expected RUN_STARTED",
 			"specUrl": "https://docs.ag-ui.com/concepts/events#runstarted",
 			"specQuote": "The RunStarted event is the first event emitted when an agent begins processing a request.",
@@ -18,6 +19,7 @@ var catalog_default = {
 			"id": "AGUI002",
 			"severity": "error",
 			"title": "Multiple RUN_STARTED in one run",
+			"category": "lifecycle",
 			"messageTemplate": "Duplicate RUN_STARTED (runId '{runId}') before the active run terminated",
 			"specUrl": "https://docs.ag-ui.com/concepts/events#lifecycle-events",
 			"specQuote": "The RunStarted and either RunFinished or RunError events are mandatory, forming the boundaries of an agent run.",
@@ -28,6 +30,7 @@ var catalog_default = {
 			"id": "AGUI003",
 			"severity": "error",
 			"title": "Run not terminated",
+			"category": "lifecycle",
 			"messageTemplate": "Run '{runId}' ended without RUN_FINISHED or RUN_ERROR",
 			"specUrl": "https://docs.ag-ui.com/concepts/events#runfinished",
 			"specQuote": "Every run terminates with either RunFinished or RunError.",
@@ -38,6 +41,7 @@ var catalog_default = {
 			"id": "AGUI004",
 			"severity": "error",
 			"title": "Event after terminal event",
+			"category": "lifecycle",
 			"messageTemplate": "{type} follows the run's terminal {terminalType}",
 			"specUrl": "https://docs.ag-ui.com/concepts/events#lifecycle-events",
 			"specQuote": "The RunStarted and either RunFinished or RunError events are mandatory, forming the boundaries of an agent run.",
@@ -48,6 +52,7 @@ var catalog_default = {
 			"id": "AGUI005",
 			"severity": "error",
 			"title": "RUN_FINISHED and RUN_ERROR are mutually exclusive",
+			"category": "lifecycle",
 			"messageTemplate": "{type} emitted after the run already terminated with {terminalType}",
 			"specUrl": "https://docs.ag-ui.com/concepts/events#runfinished",
 			"specQuote": "Every run terminates with either RunFinished or RunError.",
@@ -58,6 +63,7 @@ var catalog_default = {
 			"id": "AGUI006",
 			"severity": "error",
 			"title": "STEP_FINISHED without matching STEP_STARTED",
+			"category": "lifecycle",
 			"messageTemplate": "STEP_FINISHED '{stepName}' has no open STEP_STARTED",
 			"specUrl": "https://docs.ag-ui.com/concepts/events#stepfinished",
 			"specQuote": "The stepName must match the corresponding StepStarted event.",
@@ -68,6 +74,7 @@ var catalog_default = {
 			"id": "AGUI007",
 			"severity": "error",
 			"title": "Step unterminated at run end",
+			"category": "lifecycle",
 			"messageTemplate": "STEP_STARTED '{stepName}' never finished",
 			"specUrl": "https://docs.ag-ui.com/concepts/events#stepstarted",
 			"specQuote": "The stepName must match the corresponding StepStarted event.",
@@ -78,6 +85,7 @@ var catalog_default = {
 			"id": "AGUI008",
 			"severity": "warning",
 			"title": "Unstable threadId/runId across the run",
+			"category": "lifecycle",
 			"messageTemplate": "RUN_FINISHED {field} '{actual}' does not match RUN_STARTED {field} '{expected}'",
 			"specUrl": "https://docs.ag-ui.com/concepts/events#runstarted",
 			"specQuote": "It also provides crucial identifiers that can be used to associate subsequent events with this specific run.",
@@ -88,6 +96,7 @@ var catalog_default = {
 			"id": "AGUI101",
 			"severity": "error",
 			"title": "TEXT_MESSAGE_CONTENT without start",
+			"category": "text",
 			"messageTemplate": "TEXT_MESSAGE_CONTENT for messageId '{messageId}' with no open TEXT_MESSAGE_START",
 			"specUrl": "https://docs.ag-ui.com/concepts/events#text-message-events",
 			"specQuote": "A message begins with a TextMessageStart event, followed by one or more TextMessageContent events that deliver chunks of text as they become available, and concludes with a TextMessageEnd event.",
@@ -99,6 +108,7 @@ var catalog_default = {
 			"id": "AGUI102",
 			"severity": "error",
 			"title": "TEXT_MESSAGE_END without start",
+			"category": "text",
 			"messageTemplate": "TEXT_MESSAGE_END for messageId '{messageId}' with no open TEXT_MESSAGE_START",
 			"specUrl": "https://docs.ag-ui.com/concepts/events#textmessageend",
 			"specQuote": "messageId: Matches the ID from TextMessageStart",
@@ -110,6 +120,7 @@ var catalog_default = {
 			"id": "AGUI103",
 			"severity": "error",
 			"title": "Text message unterminated at run end",
+			"category": "text",
 			"messageTemplate": "TEXT_MESSAGE_START messageId '{messageId}' never ended",
 			"specUrl": "https://docs.ag-ui.com/concepts/events#text-message-events",
 			"specQuote": "A message begins with a TextMessageStart event, followed by one or more TextMessageContent events that deliver chunks of text as they become available, and concludes with a TextMessageEnd event.",
@@ -121,6 +132,7 @@ var catalog_default = {
 			"id": "AGUI104",
 			"severity": "error",
 			"title": "Duplicate messageId within a run",
+			"category": "text",
 			"messageTemplate": "messageId '{messageId}' was already used by a completed message",
 			"specUrl": "https://docs.ag-ui.com/concepts/events#textmessagestart",
 			"specQuote": "It establishes a unique messageId that will be referenced by subsequent content chunks and the end event.",
@@ -132,6 +144,7 @@ var catalog_default = {
 			"id": "AGUI105",
 			"severity": "warning",
 			"title": "Empty content delta",
+			"category": "text",
 			"messageTemplate": "TEXT_MESSAGE_CONTENT for messageId '{messageId}' has an empty delta",
 			"specUrl": "https://docs.ag-ui.com/concepts/events#textmessagecontent",
 			"specQuote": "delta: Text content chunk (non-empty)",
@@ -144,6 +157,7 @@ var catalog_default = {
 			"id": "AGUI106",
 			"severity": "error",
 			"title": "Interleaved message streams sharing a messageId",
+			"category": "text",
 			"messageTemplate": "TEXT_MESSAGE_START for messageId '{messageId}', which is already open",
 			"specUrl": "https://docs.ag-ui.com/concepts/events#implementation-considerations",
 			"specQuote": "Events with the same ID (e.g., messageId, toolCallId) belong to the same logical stream",
@@ -155,6 +169,7 @@ var catalog_default = {
 			"id": "AGUI201",
 			"severity": "error",
 			"title": "TOOL_CALL_ARGS without start",
+			"category": "toolcall",
 			"messageTemplate": "TOOL_CALL_ARGS for toolCallId '{toolCallId}' with no open TOOL_CALL_START",
 			"specUrl": "https://docs.ag-ui.com/concepts/events#tool-call-events",
 			"specQuote": "When an agent needs to use a tool, it emits a ToolCallStart event, followed by one or more ToolCallArgs events that stream the arguments being passed to the tool, and concludes with a ToolCallEnd event.",
@@ -166,6 +181,7 @@ var catalog_default = {
 			"id": "AGUI202",
 			"severity": "error",
 			"title": "TOOL_CALL_END without start",
+			"category": "toolcall",
 			"messageTemplate": "TOOL_CALL_END for toolCallId '{toolCallId}' with no open TOOL_CALL_START",
 			"specUrl": "https://docs.ag-ui.com/concepts/events#toolcallend",
 			"specQuote": "toolCallId: Matches the ID from ToolCallStart",
@@ -177,6 +193,7 @@ var catalog_default = {
 			"id": "AGUI203",
 			"severity": "error",
 			"title": "Unterminated tool call",
+			"category": "toolcall",
 			"messageTemplate": "TOOL_CALL_START id '{toolCallId}' never terminated",
 			"specUrl": "https://docs.ag-ui.com/concepts/events#tool-call-events",
 			"specQuote": "When an agent needs to use a tool, it emits a ToolCallStart event, followed by one or more ToolCallArgs events that stream the arguments being passed to the tool, and concludes with a ToolCallEnd event.",
@@ -188,6 +205,7 @@ var catalog_default = {
 			"id": "AGUI204",
 			"severity": "error",
 			"title": "Tool call arguments are not valid JSON",
+			"category": "toolcall",
 			"messageTemplate": "Concatenated TOOL_CALL_ARGS for toolCallId '{toolCallId}' do not parse as JSON: {error}",
 			"specUrl": "https://docs.ag-ui.com/concepts/events#toolcallargs",
 			"specQuote": "Frontends should concatenate these deltas in the order received to construct the complete arguments object.",
@@ -199,6 +217,7 @@ var catalog_default = {
 			"id": "AGUI205",
 			"severity": "error",
 			"title": "Duplicate toolCallId within a run",
+			"category": "toolcall",
 			"messageTemplate": "toolCallId '{toolCallId}' was already used by a completed tool call",
 			"specUrl": "https://docs.ag-ui.com/concepts/events#toolcallstart",
 			"specQuote": "toolCallId: Unique identifier for the tool call",
@@ -210,6 +229,7 @@ var catalog_default = {
 			"id": "AGUI206",
 			"severity": "warning",
 			"title": "TOOL_CALL_RESULT before TOOL_CALL_END",
+			"category": "toolcall",
 			"messageTemplate": "TOOL_CALL_RESULT for toolCallId '{toolCallId}' arrived while the call is still open",
 			"specUrl": "https://docs.ag-ui.com/concepts/events#toolcallresult",
 			"specQuote": "This event is sent after the tool has been executed by the system and contains the actual output generated by the tool.",
@@ -221,6 +241,7 @@ var catalog_default = {
 			"id": "AGUI207",
 			"severity": "error",
 			"title": "TOOL_CALL_RESULT references unknown toolCallId",
+			"category": "toolcall",
 			"messageTemplate": "TOOL_CALL_RESULT references toolCallId '{toolCallId}', which was never started",
 			"specUrl": "https://docs.ag-ui.com/concepts/events#toolcallresult",
 			"specQuote": "toolCallId: Matches the ID from the corresponding ToolCallStart event",
@@ -232,6 +253,7 @@ var catalog_default = {
 			"id": "AGUI208",
 			"severity": "info",
 			"title": "parentMessageId references unknown message",
+			"category": "toolcall",
 			"messageTemplate": "TOOL_CALL_START parentMessageId '{parentMessageId}' matches no message observed in this stream",
 			"specUrl": "https://docs.ag-ui.com/concepts/events#toolcallstart",
 			"specQuote": "The optional parentMessageId allows linking the tool call to a specific message in the conversation, providing context for why the tool is being used.",
@@ -244,6 +266,7 @@ var catalog_default = {
 			"id": "AGUI301",
 			"severity": "info",
 			"title": "STATE_DELTA before any STATE_SNAPSHOT",
+			"category": "state",
 			"messageTemplate": "STATE_DELTA precedes any STATE_SNAPSHOT; the base it applies to is not observable on this stream",
 			"specUrl": "https://docs.ag-ui.com/concepts/events#statesnapshot",
 			"specQuote": "This event is typically sent at the beginning of an interaction or when synchronization is needed.",
@@ -256,6 +279,7 @@ var catalog_default = {
 			"id": "AGUI302",
 			"severity": "error",
 			"title": "STATE_DELTA failed to apply",
+			"category": "state",
 			"messageTemplate": "STATE_DELTA failed to apply: {error}",
 			"specUrl": "https://docs.ag-ui.com/concepts/events#statedelta",
 			"specQuote": "Each delta represents specific changes to apply to the current state model.",
@@ -267,6 +291,7 @@ var catalog_default = {
 			"id": "AGUI303",
 			"severity": "error",
 			"title": "STATE_DELTA is not a valid RFC 6902 patch document",
+			"category": "state",
 			"messageTemplate": "STATE_DELTA is not a valid RFC 6902 patch document: {error}",
 			"specUrl": "https://docs.ag-ui.com/concepts/events#statedelta",
 			"specQuote": "The StateDelta event contains incremental updates to the agent's state in the form of JSON Patch operations (as defined in RFC 6902).",
@@ -278,6 +303,7 @@ var catalog_default = {
 			"id": "AGUI304",
 			"severity": "info",
 			"title": "Mid-run STATE_SNAPSHOT discards accumulated deltas",
+			"category": "state",
 			"messageTemplate": "STATE_SNAPSHOT replaces state previously built from {deltaCount} delta(s)",
 			"specUrl": "https://docs.ag-ui.com/concepts/events#statesnapshot",
 			"specQuote": "This event is typically sent at the beginning of an interaction or when synchronization is needed.",
@@ -289,6 +315,7 @@ var catalog_default = {
 			"id": "AGUI305",
 			"severity": "warning",
 			"title": "Shared state declared but never established",
+			"category": "state",
 			"messageTemplate": "features include 'shared-state' but no STATE_SNAPSHOT was emitted",
 			"specUrl": "https://docs.ag-ui.com/concepts/events#state-management-events",
 			"specQuote": "These events are used to manage and synchronize the agent's state with the frontend.",
@@ -301,6 +328,7 @@ var catalog_default = {
 			"id": "AGUI401",
 			"severity": "error",
 			"title": "REASONING_MESSAGE_CONTENT without start",
+			"category": "reasoning",
 			"messageTemplate": "REASONING_MESSAGE_CONTENT for messageId '{messageId}' with no open REASONING_MESSAGE_START",
 			"specUrl": "https://docs.ag-ui.com/concepts/events#reasoningmessagecontent",
 			"specQuote": "Multiple content events with the same messageId should be concatenated to form the complete visible reasoning.",
@@ -312,6 +340,7 @@ var catalog_default = {
 			"id": "AGUI402",
 			"severity": "warning",
 			"title": "Reasoning unterminated at run end",
+			"category": "reasoning",
 			"messageTemplate": "{startType} messageId '{messageId}' never ended",
 			"specUrl": "https://docs.ag-ui.com/concepts/events#reasoning-events",
 			"specQuote": "Reasoning events support LLM reasoning visibility and continuity, enabling chain-of-thought reasoning while maintaining privacy.",
@@ -323,6 +352,7 @@ var catalog_default = {
 			"id": "AGUI501",
 			"severity": "error",
 			"title": "Malformed SSE framing",
+			"category": "transport",
 			"messageTemplate": "Malformed SSE framing: {detail}",
 			"specUrl": "https://html.spec.whatwg.org/multipage/server-sent-events.html#event-stream-interpretation",
 			"since": "0.x",
@@ -332,6 +362,7 @@ var catalog_default = {
 			"id": "AGUI502",
 			"severity": "error",
 			"title": "Event payload is not valid JSON",
+			"category": "transport",
 			"messageTemplate": "Event payload is not valid JSON: {error}",
 			"specUrl": "https://docs.ag-ui.com/concepts/events#base-event-properties",
 			"specQuote": "All events share a common set of base properties.",
@@ -342,7 +373,8 @@ var catalog_default = {
 			"id": "AGUI503",
 			"severity": "error",
 			"title": "Unknown event type",
-			"messageTemplate": "Unknown event type '{type}' (not in @ag-ui/core v{sdkVersion}, and not RAW or CUSTOM)",
+			"category": "transport",
+			"messageTemplate": "Unknown event type '{type}' (not in the installed AG-UI SDK v{sdkVersion}, and not RAW or CUSTOM)",
 			"specUrl": "https://docs.ag-ui.com/concepts/events#event-types-overview",
 			"specQuote": "Events in the protocol are categorized by their purpose.",
 			"since": "0.x",
@@ -352,6 +384,7 @@ var catalog_default = {
 			"id": "AGUI504",
 			"severity": "error",
 			"title": "Event fails schema validation for its declared type",
+			"category": "transport",
 			"messageTemplate": "{type}: {detail}",
 			"specUrl": "https://docs.ag-ui.com/concepts/events#base-event-properties",
 			"specQuote": "All events share a common set of base properties.",
@@ -362,6 +395,7 @@ var catalog_default = {
 			"id": "AGUI505",
 			"severity": "warning",
 			"title": "Unexpected Content-Type",
+			"category": "transport",
 			"messageTemplate": "Content-Type '{contentType}' is neither text/event-stream nor application/x-ndjson",
 			"specUrl": "https://html.spec.whatwg.org/multipage/server-sent-events.html#sse-processing-model",
 			"since": "0.x",
@@ -371,6 +405,7 @@ var catalog_default = {
 			"id": "AGUI506",
 			"severity": "info",
 			"title": "No keepalive frame within the configured window",
+			"category": "transport",
 			"messageTemplate": "No event or keepalive frame for {seconds}s",
 			"specUrl": "https://docs.ag-ui.com/concepts/architecture#standard-http-client",
 			"since": "0.x",
@@ -381,6 +416,7 @@ var catalog_default = {
 			"id": "AGUI507",
 			"severity": "info",
 			"title": "Response appears buffered rather than incrementally flushed",
+			"category": "transport",
 			"messageTemplate": "Response appears buffered: {detail}",
 			"specUrl": "https://docs.ag-ui.com/concepts/architecture#standard-http-client",
 			"since": "0.x",
@@ -391,16 +427,85 @@ var catalog_default = {
 			"id": "AGUI508",
 			"severity": "error",
 			"title": "Stream ended without a terminal event",
+			"category": "transport",
 			"messageTemplate": "Connection ended mid-run '{runId}' without RUN_FINISHED or RUN_ERROR",
 			"specUrl": "https://docs.ag-ui.com/concepts/events#runfinished",
 			"specQuote": "Every run terminates with either RunFinished or RunError.",
 			"since": "0.x",
 			"checkedIn": "transport"
 		},
+		{
+			"id": "AGUI601",
+			"severity": "error",
+			"title": "Duplicate SUBAGENT_STARTED for a subagentRunId",
+			"category": "subagent",
+			"messageTemplate": "SUBAGENT_STARTED reuses subagentRunId '{subagentRunId}', which is already in use this run",
+			"specUrl": "https://docs.ag-ui.com/concepts/subagents#rules-clients-enforce",
+			"specQuote": "a subagent is not started twice within a run",
+			"since": "0.x",
+			"checkedIn": "core"
+		},
+		{
+			"id": "AGUI602",
+			"severity": "error",
+			"title": "SUBAGENT_FINISHED without matching SUBAGENT_STARTED",
+			"category": "subagent",
+			"messageTemplate": "SUBAGENT_FINISHED for subagentRunId '{subagentRunId}' with no open SUBAGENT_STARTED",
+			"specUrl": "https://docs.ag-ui.com/concepts/subagents#rules-clients-enforce",
+			"specQuote": "SubagentFinished and SubagentError name a subagent that is currently active",
+			"since": "0.x",
+			"checkedIn": "core"
+		},
+		{
+			"id": "AGUI603",
+			"severity": "error",
+			"title": "SUBAGENT_ERROR without matching SUBAGENT_STARTED",
+			"category": "subagent",
+			"messageTemplate": "SUBAGENT_ERROR for subagentRunId '{subagentRunId}' with no open SUBAGENT_STARTED",
+			"specUrl": "https://docs.ag-ui.com/concepts/subagents#rules-clients-enforce",
+			"specQuote": "SubagentFinished and SubagentError name a subagent that is currently active",
+			"since": "0.x",
+			"checkedIn": "core"
+		},
+		{
+			"id": "AGUI604",
+			"severity": "error",
+			"title": "Subagent unterminated at run end",
+			"category": "subagent",
+			"messageTemplate": "SUBAGENT_STARTED subagentRunId '{subagentRunId}' never closed with SUBAGENT_FINISHED or SUBAGENT_ERROR",
+			"specUrl": "https://docs.ag-ui.com/concepts/subagents#rules-clients-enforce",
+			"specQuote": "Every started subagent is closed before RunFinished.",
+			"since": "0.x",
+			"checkedIn": "core"
+		},
+		{
+			"id": "AGUI605",
+			"severity": "warning",
+			"title": "parentSubagentRunId references a subagent never started",
+			"category": "subagent",
+			"messageTemplate": "SUBAGENT_STARTED parentSubagentRunId '{parentSubagentRunId}' matches no subagent observed in this stream",
+			"specUrl": "https://docs.ag-ui.com/concepts/subagents#nesting-and-concurrency",
+			"specQuote": "parentSubagentRunId need only name a subagent that has been started, not one still active",
+			"since": "0.x",
+			"checkedIn": "core"
+		},
+		{
+			"id": "AGUI606",
+			"severity": "warning",
+			"title": "Continuation event's subagentRunId disagrees with its entity's owner",
+			"category": "subagent",
+			"messageTemplate": "{type} declares subagentRunId '{actual}', but {entityType} '{entityId}' was opened under {expected}",
+			"specUrl": "https://docs.ag-ui.com/concepts/subagents#rules-clients-enforce",
+			"specQuote": "Continuation and close events agree with the owner their entity was created under.",
+			"since": "0.x",
+			"specQuestion": "SQ-15",
+			"checkedIn": "core"
+		},
 		{
 			"id": "AGUI901",
 			"severity": "info",
 			"title": "RAW event wraps a typed AG-UI event",
+			"category": "hygiene",
 			"messageTemplate": "RAW event wraps an event of type '{wrappedType}', which has a typed AG-UI equivalent",
 			"specUrl": "https://docs.ag-ui.com/concepts/events#raw",
 			"specQuote": "The Raw event acts as a container for events originating from external systems or sources that don't natively follow the Agent UI Protocol.",
@@ -411,6 +516,7 @@ var catalog_default = {
 			"id": "AGUI902",
 			"severity": "info",
 			"title": "Events carry no timestamps",
+			"category": "hygiene",
 			"messageTemplate": "None of the {eventCount} events carry the optional timestamp property",
 			"specUrl": "https://docs.ag-ui.com/concepts/events#base-event-properties",
 			"specQuote": "timestamp: Optional timestamp indicating when the event was created",
@@ -421,6 +527,7 @@ var catalog_default = {
 			"id": "AGUI903",
 			"severity": "info",
 			"title": "CUSTOM event name is not namespaced",
+			"category": "hygiene",
 			"messageTemplate": "CUSTOM event name '{name}' has no namespace prefix (e.g. 'vendor.event')",
 			"specUrl": "https://docs.ag-ui.com/concepts/events#custom",
 			"specQuote": "Teams should document their custom events to ensure consistent implementation across frontends and agents.",
@@ -438,6 +545,16 @@ const SEVERITIES = [
 	"info"
 ];
 const LAYERS = ["core", "transport"];
+const CATEGORIES = [
+	"lifecycle",
+	"text",
+	"toolcall",
+	"state",
+	"reasoning",
+	"transport",
+	"hygiene",
+	"subagent"
+];
 /** Validates catalog data and returns it typed. Throws on structural problems. */
 function validateCatalog(data) {
 	const problems = [];
@@ -451,6 +568,7 @@ function validateCatalog(data) {
 		seen.add(rule.id);
 		if (!SEVERITIES.includes(rule.severity)) problems.push(`${where}: bad severity '${rule.severity}'`);
 		if (!rule.title) problems.push(`${where}: missing title`);
+		if (!CATEGORIES.includes(rule.category)) problems.push(`${where}: bad category '${rule.category}'`);
 		if (!rule.messageTemplate) problems.push(`${where}: missing messageTemplate`);
 		if (!rule.specUrl?.startsWith("https://")) problems.push(`${where}: specUrl must be an https URL`);
 		if (!rule.since) problems.push(`${where}: missing since`);
@@ -469,4 +587,4 @@ function formatMessage(rule, params) {
 //#endregion
 export { validateCatalog as i, RULES as n, formatMessage as r, CATALOG as t };
 
-//# sourceMappingURL=catalog-BglXBNbL.js.map
+//# sourceMappingURL=catalog-3e6INLCp.js.map

package/dist/catalog-3e6INLCp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog-3e6INLCp.js","names":["catalogJson"],"sources":["../spec/catalog.json","../js/src/rules/catalog.ts"],"sourcesContent":["","// Typed loader for the rule catalog. The catalog itself is data\n// (catalog.json) so other implementations can share it; this module gives it\n// types and validates its invariants once at load time.\n//\n// Note the asymmetry: the validator never throws on stream input, but a\n// malformed catalog is a programming error in this package, so the loader\n// throws loudly at import time.\n\nimport catalogJson from \"../../../spec/catalog.json\"\n\nexport type Severity = \"error\" | \"warning\" | \"info\"\nexport type SeverityOrOff = Severity | \"off\"\n\nconst SEVERITIES: readonly string[] = [\"error\", \"warning\", \"info\"]\nconst LAYERS: readonly string[] = [\"core\", \"transport\"]\nexport const CATEGORIES: readonly string[] = [\"lifecycle\", \"text\", \"toolcall\", \"state\", \"reasoning\", \"transport\", \"hygiene\", \"subagent\"]\n\nexport interface RuleDefinition {\n  /** e.g. \"AGUI203\" */\n  id: string\n  severity: Severity\n  title: string\n  /** Which part of the protocol this rule governs, e.g. \"toolcall\". */\n  category: string\n  /** Human template with {placeholder} slots filled per diagnostic. */\n  messageTemplate: string\n  /** Governing spec section. Mandatory: rules that cannot cite one don't ship. */\n  specUrl: string\n  /** Exact sentence from the spec section, where one exists. */\n  specQuote?: string\n  since: string\n  /** Canonical AG-UI feature this rule relates to, if any. */\n  feature?: string\n  /** True when the rule only fires if opts.features declares `feature`. */\n  requiresFeature?: boolean\n  /** Cross-reference into docs/spec-questions.md for downgraded/ambiguous rules. */\n  specQuestion?: string\n  /** Where the rule is evaluated. Transport rules are skipped (and the skip\n   * reported) when validating recorded input with no transport in play. */\n  checkedIn: \"core\" | \"transport\"\n}\n\nexport interface Catalog {\n  catalogVersion: string\n  spec: string\n  rules: readonly RuleDefinition[]\n}\n\n/** Validates catalog data and returns it typed. Throws on structural problems. */\nexport function validateCatalog(data: unknown): Catalog {\n  const problems: string[] = []\n  const cat = data as Catalog\n  if (typeof cat !== \"object\" || cat === null || !Array.isArray(cat.rules)) {\n    throw new Error(\"rule catalog: expected an object with a rules array\")\n  }\n  const seen = new Set<string>()\n  for (const rule of cat.rules) {\n    const where = rule?.id ?? \"<missing id>\"\n    if (!/^AGUI\\d{3}$/.test(rule.id ?? \"\")) problems.push(`${where}: id must match AGUI###`)\n    if (seen.has(rule.id)) problems.push(`${where}: duplicate id`)\n    seen.add(rule.id)\n    if (!SEVERITIES.includes(rule.severity)) problems.push(`${where}: bad severity '${rule.severity}'`)\n    if (!rule.title) problems.push(`${where}: missing title`)\n    if (!CATEGORIES.includes(rule.category)) problems.push(`${where}: bad category '${rule.category}'`)\n    if (!rule.messageTemplate) problems.push(`${where}: missing messageTemplate`)\n    if (!rule.specUrl?.startsWith(\"https://\")) problems.push(`${where}: specUrl must be an https URL`)\n    if (!rule.since) problems.push(`${where}: missing since`)\n    if (!LAYERS.includes(rule.checkedIn)) problems.push(`${where}: bad checkedIn '${rule.checkedIn}'`)\n    if (rule.requiresFeature && !rule.feature) problems.push(`${where}: requiresFeature without feature`)\n  }\n  if (problems.length > 0) {\n    throw new Error(`rule catalog is invalid:\\n  ${problems.join(\"\\n  \")}`)\n  }\n  return cat\n}\n\nexport const CATALOG: Catalog = validateCatalog(catalogJson)\n\nexport const RULES: ReadonlyMap<string, RuleDefinition> = new Map(\n  CATALOG.rules.map((r) => [r.id, r]),\n)\n\n/** Fills a rule's messageTemplate. Unknown placeholders are left intact. */\nexport function formatMessage(rule: RuleDefinition, params: Record<string, unknown>): string {\n  return rule.messageTemplate.replace(/\\{(\\w+)\\}/g, (whole, key: string) =>\n    key in params ? String(params[key]) : whole,\n  )\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;ACaA,MAAM,aAAgC;CAAC;CAAS;CAAW;AAAM;AACjE,MAAM,SAA4B,CAAC,QAAQ,WAAW;AACtD,MAAa,aAAgC;CAAC;CAAa;CAAQ;CAAY;CAAS;CAAa;CAAa;CAAW;AAAU;;AAkCvI,SAAgB,gBAAgB,MAAwB;CACtD,MAAM,WAAqB,CAAC;CAC5B,MAAM,MAAM;CACZ,IAAI,OAAO,QAAQ,YAAY,QAAQ,QAAQ,CAAC,MAAM,QAAQ,IAAI,KAAK,GACrE,MAAM,IAAI,MAAM,qDAAqD;CAEvE,MAAM,uBAAO,IAAI,IAAY;CAC7B,KAAK,MAAM,QAAQ,IAAI,OAAO;EAC5B,MAAM,QAAQ,MAAM,MAAM;EAC1B,IAAI,CAAC,cAAc,KAAK,KAAK,MAAM,EAAE,GAAG,SAAS,KAAK,GAAG,MAAM,wBAAwB;EACvF,IAAI,KAAK,IAAI,KAAK,EAAE,GAAG,SAAS,KAAK,GAAG,MAAM,eAAe;EAC7D,KAAK,IAAI,KAAK,EAAE;EAChB,IAAI,CAAC,WAAW,SAAS,KAAK,QAAQ,GAAG,SAAS,KAAK,GAAG,MAAM,kBAAkB,KAAK,SAAS,EAAE;EAClG,IAAI,CAAC,KAAK,OAAO,SAAS,KAAK,GAAG,MAAM,gBAAgB;EACxD,IAAI,CAAC,WAAW,SAAS,KAAK,QAAQ,GAAG,SAAS,KAAK,GAAG,MAAM,kBAAkB,KAAK,SAAS,EAAE;EAClG,IAAI,CAAC,KAAK,iBAAiB,SAAS,KAAK,GAAG,MAAM,0BAA0B;EAC5E,IAAI,CAAC,KAAK,SAAS,WAAW,UAAU,GAAG,SAAS,KAAK,GAAG,MAAM,+BAA+B;EACjG,IAAI,CAAC,KAAK,OAAO,SAAS,KAAK,GAAG,MAAM,gBAAgB;EACxD,IAAI,CAAC,OAAO,SAAS,KAAK,SAAS,GAAG,SAAS,KAAK,GAAG,MAAM,mBAAmB,KAAK,UAAU,EAAE;EACjG,IAAI,KAAK,mBAAmB,CAAC,KAAK,SAAS,SAAS,KAAK,GAAG,MAAM,kCAAkC;CACtG;CACA,IAAI,SAAS,SAAS,GACpB,MAAM,IAAI,MAAM,+BAA+B,SAAS,KAAK,MAAM,GAAG;CAExE,OAAO;AACT;AAEA,MAAa,UAAmB,gBAAgBA,eAAW;AAE3D,MAAa,QAA6C,IAAI,IAC5D,QAAQ,MAAM,KAAK,MAAM,CAAC,EAAE,IAAI,CAAC,CAAC,CACpC;;AAGA,SAAgB,cAAc,MAAsB,QAAyC;CAC3F,OAAO,KAAK,gBAAgB,QAAQ,eAAe,OAAO,QACxD,OAAO,SAAS,OAAO,OAAO,IAAI,IAAI,KACxC;AACF"}