ag-ui-validate 0.1.0 → 0.3.0

package/{src → js/src}/cli-args.ts

@@ -20,6 +20,8 @@ export interface CliConfig {
   sarifFile?: string
   junitFile?: string
   jsonFile?: string
+  /** Pretty output only: one line per rule with a count, not one per finding. */
+  group: boolean
   help: boolean
   version: boolean
 }
@@ -40,6 +42,7 @@ Output (default: human-readable):
   --json-file <path>              additionally write the JSON report to a file
   --sarif-file <path>             additionally write a SARIF log to a file
   --junit-file <path>             additionally write JUnit XML to a file
+  --group                         one line per rule with a count (large streams)
   --no-color                      disable ANSI colors
 
 Rules:
@@ -67,6 +70,7 @@ const FLAGS: Record<string, Flag> = {
   "--help": { takesValue: false, apply: (c) => ((c.help = true), null) },
   "--version": { takesValue: false, apply: (c) => ((c.version = true), null) },
   "--no-color": { takesValue: false, apply: (c) => ((c.color = false), null) },
+  "--group": { takesValue: false, apply: (c) => ((c.group = true), null) },
   "--json": { takesValue: false, apply: (c) => setFormat(c, "json") },
   "--sarif": { takesValue: false, apply: (c) => setFormat(c, "sarif") },
   "--junit": { takesValue: false, apply: (c) => setFormat(c, "junit") },
@@ -150,6 +154,7 @@ export function parseCliArgs(argv: string[]): ParseResult {
     color: null,
     headers: {},
     severityOverrides: {},
+    group: false,
     help: false,
     version: false,
   }
@@ -182,6 +187,12 @@ export function parseCliArgs(argv: string[]): ParseResult {
     if (error !== null) return { ok: false, error }
   }
 
+  if (config.group && config.format !== "pretty") {
+    return {
+      ok: false,
+      error: "--group only applies to the default pretty output, not --json/--sarif/--junit",
+    }
+  }
   if (targets.length > 1) {
     return { ok: false, error: `expected exactly one target, got ${targets.length}` }
   }

package/{src → js/src}/cli.ts

@@ -7,7 +7,7 @@ import { createReadStream, readFileSync, writeFileSync } from "node:fs"
 import process from "node:process"
 import { decideExitCode, parseCliArgs, USAGE } from "./cli-args.js"
 import type { CliConfig } from "./cli-args.js"
-import { formatDiagnosticLine, formatReportSummary, toJsonReport, toJUnit, toSarif } from "./report/index.js"
+import { formatDiagnosticLine, formatGroupedDiagnostics, formatReportSummary, toJsonReport, toJUnit, toSarif } from "./report/index.js"
 import { TransportError, validateBody, validateEndpoint } from "./transport/index.js"
 import type { TransportOptions, TransportResult } from "./transport/index.js"
 import type { Diagnostic, ValidatorOptions } from "./types.js"
@@ -62,8 +62,9 @@ async function main(): Promise<number> {
 
   // Pretty mode streams findings as they are detected; machine formats emit
   // one document at the end, so nothing else may touch stdout before it.
+  // --group defers everything to one collapsed block after the run.
   let printed = 0
-  const onDiagnostic = pretty
+  const onDiagnostic = pretty && !config.group
     ? (d: Diagnostic): void => {
         printed += 1
         process.stdout.write(`${formatDiagnosticLine(d, { color })}\n`)
@@ -116,7 +117,11 @@ async function main(): Promise<number> {
   }
 
   if (pretty) {
-    if (printed > 0) process.stdout.write("\n")
+    if (config.group && report.diagnostics.length > 0) {
+      process.stdout.write(`${formatGroupedDiagnostics(report.diagnostics, { color })}\n\n`)
+    } else if (printed > 0) {
+      process.stdout.write("\n")
+    }
     process.stdout.write(`${formatReportSummary(report, { color })}\n`)
   } else if (config.format === "json") {
     const doc = toJsonReport(report, { tool: { name: TOOL_NAME, version }, target: targetLabel })

package/{src → js/src}/report/index.ts

@@ -1,6 +1,6 @@
 // ag-ui-validate/report: pure reporters over a core Report. No I/O — callers
 // decide where the strings go.
-export { formatDiagnosticLine, formatReportSummary } from "./pretty.js"
+export { formatDiagnosticLine, formatGroupedDiagnostics, formatReportSummary } from "./pretty.js"
 export type { PrettyOptions } from "./pretty.js"
 export { toJsonReport } from "./json.js"
 export type { JsonReportDocument, JsonReportOptions } from "./json.js"

package/{src → js/src}/report/pretty.ts

@@ -1,5 +1,6 @@
 // Human-readable output. Pure string formatting — the CLI decides where it
 // goes and whether a TTY wants color.
+import { RULES } from "../rules/catalog.js"
 import type { Diagnostic, Report, Severity } from "../types.js"
 
 export interface PrettyOptions {
@@ -25,6 +26,48 @@ function count(n: number, noun: string): string {
   return `${n} ${noun}${n === 1 ? "" : "s"}`
 }
 
+const SEVERITY_RANK: Record<Severity, number> = { error: 0, warning: 1, info: 2 }
+const SAMPLE_INDEXES = 3
+
+/**
+ * One line per rule instead of one per occurrence — for large streams where
+ * the same violation repeats. Totals stay honest in the summary; this only
+ * changes what is listed.
+ */
+export function formatGroupedDiagnostics(diagnostics: Diagnostic[], opts: PrettyOptions): string {
+  const groups = new Map<string, Diagnostic[]>()
+  for (const d of diagnostics) {
+    const list = groups.get(d.rule)
+    if (list === undefined) groups.set(d.rule, [d])
+    else list.push(d)
+  }
+
+  const sorted = [...groups.values()].sort((a, b) => {
+    const bySeverity = SEVERITY_RANK[a[0]!.severity] - SEVERITY_RANK[b[0]!.severity]
+    return bySeverity !== 0 ? bySeverity : a[0]!.rule.localeCompare(b[0]!.rule)
+  })
+
+  const lines: string[] = []
+  for (const group of sorted) {
+    const first = group[0]!
+    const title = RULES.get(first.rule)?.title ?? first.message
+    const indexes = group.map((d) => d.eventIndex).filter((i) => i >= 0)
+    let where: string
+    if (indexes.length === 0) {
+      where = "stream-level"
+    } else {
+      const sample = indexes.slice(0, SAMPLE_INDEXES).join(", ")
+      const rest = indexes.length - SAMPLE_INDEXES
+      where = `events ${sample}${rest > 0 ? ` (+${rest} more)` : ""}`
+    }
+    const head = paint(SGR[first.severity], `${SYMBOL[first.severity]} ${first.rule}`, opts.color)
+    const meta = paint("2", `${first.severity.padEnd(7)} ×${group.length}`, opts.color)
+    const cite = paint("2", `  ↳ ${first.specUrl}`, opts.color)
+    lines.push(`${head}  ${meta}  ${title} — ${where}`, cite)
+  }
+  return lines.join("\n")
+}
+
 export function formatReportSummary(report: Report, opts: PrettyOptions): string {
   const { errors, warnings, info } = report.summary
   const lines: string[] = []

package/{src → js/src}/rules/catalog.ts

@@ -6,7 +6,7 @@
 // malformed catalog is a programming error in this package, so the loader
 // throws loudly at import time.
 
-import catalogJson from "./catalog.json"
+import catalogJson from "../../../spec/catalog.json"
 
 export type Severity = "error" | "warning" | "info"
 export type SeverityOrOff = Severity | "off"

package/{src → js/src}/transport/index.ts

@@ -1,7 +1,7 @@
 // ag-ui-validate/transport: SSE + NDJSON clients over the pure core.
 // This is the I/O layer — fetch, streams, and clocks live here, never in the
 // core. Uses only web-platform APIs (fetch, TextDecoder, AbortController) so
-// it stays isomorphic: Node 20+, browsers, Deno, Workers.
+// it stays isomorphic: Node 22+, browsers, Deno, Workers.
 
 import { createValidator } from "../index.js"
 import type { Diagnostic, Report, ValidationLayer, ValidatorOptions } from "../index.js"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ag-ui-validate",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Conformance validator for the AG-UI protocol. Feed it an event stream, get every violation with a rule ID, a severity, and a link to the governing spec section.",
   "keywords": [
     "ag-ui",
@@ -23,10 +23,10 @@
   "type": "module",
   "sideEffects": [
     "./dist/vitest.js",
-    "./src/vitest/index.ts"
+    "./js/src/vitest/index.ts"
   ],
   "engines": {
-    "node": ">=20"
+    "node": ">=22"
   },
   "bin": {
     "ag-ui-validate": "./dist/cli.js"
@@ -88,20 +88,21 @@
   },
   "files": [
     "dist",
-    "src"
+    "js/src",
+    "spec"
   ],
   "scripts": {
-    "build": "tsdown",
-    "typecheck": "tsc --noEmit -p tsconfig.src.json && tsc --noEmit",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "fixtures:build": "npm run build && node scripts/build-fixtures.mjs",
-    "protocol:derive": "node scripts/generate-event-table.mjs",
+    "build": "tsdown --config js/tsdown.config.mjs",
+    "typecheck": "tsc --noEmit -p js/tsconfig.src.json && tsc --noEmit -p js/tsconfig.json",
+    "test": "vitest run --config js/vitest.config.ts",
+    "test:watch": "vitest --config js/vitest.config.ts",
+    "fixtures:build": "npm run build && node js/scripts/build-fixtures.mjs",
+    "protocol:derive": "node js/scripts/generate-event-table.mjs",
     "docs:generate": "node scripts/generate-rule-docs.mjs",
     "docs:check": "node scripts/generate-rule-docs.mjs --check",
-    "demo": "node scripts/demo.mjs",
-    "fuzz": "node scripts/fuzz.mjs",
-    "e2e": "node scripts/e2e-live-server.mjs",
+    "demo": "node js/scripts/demo.mjs",
+    "fuzz": "node js/scripts/fuzz.mjs",
+    "e2e": "node js/scripts/e2e-live-server.mjs",
     "links:check": "node scripts/check-spec-links.mjs",
     "changeset": "changeset",
     "version": "changeset version",

package/{src/rules → spec}/catalog.json

@@ -341,7 +341,7 @@
       "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)",
+      "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",

package/spec/event-categories.json

@@ -0,0 +1,56 @@
+{
+  "$comment": "Wire-type -> category/deprecation data for the canonical event table. Hand-maintained (not derivable from the SDK schemas themselves); shared by every language's event-table derivation tool so this classification is written once. Categories are display/grouping metadata only, not conformance rules — those live in catalog.json.",
+  "categories": [
+    "lifecycle",
+    "text",
+    "toolcall",
+    "state",
+    "activity",
+    "reasoning",
+    "thinking",
+    "special"
+  ],
+  "eventCategory": {
+    "RUN_STARTED": "lifecycle",
+    "RUN_FINISHED": "lifecycle",
+    "RUN_ERROR": "lifecycle",
+    "STEP_STARTED": "lifecycle",
+    "STEP_FINISHED": "lifecycle",
+    "TEXT_MESSAGE_START": "text",
+    "TEXT_MESSAGE_CONTENT": "text",
+    "TEXT_MESSAGE_END": "text",
+    "TEXT_MESSAGE_CHUNK": "text",
+    "TOOL_CALL_START": "toolcall",
+    "TOOL_CALL_ARGS": "toolcall",
+    "TOOL_CALL_END": "toolcall",
+    "TOOL_CALL_CHUNK": "toolcall",
+    "TOOL_CALL_RESULT": "toolcall",
+    "STATE_SNAPSHOT": "state",
+    "STATE_DELTA": "state",
+    "MESSAGES_SNAPSHOT": "state",
+    "ACTIVITY_SNAPSHOT": "activity",
+    "ACTIVITY_DELTA": "activity",
+    "REASONING_START": "reasoning",
+    "REASONING_MESSAGE_START": "reasoning",
+    "REASONING_MESSAGE_CONTENT": "reasoning",
+    "REASONING_MESSAGE_END": "reasoning",
+    "REASONING_MESSAGE_CHUNK": "reasoning",
+    "REASONING_END": "reasoning",
+    "REASONING_ENCRYPTED_VALUE": "reasoning",
+    "THINKING_START": "thinking",
+    "THINKING_END": "thinking",
+    "THINKING_TEXT_MESSAGE_START": "thinking",
+    "THINKING_TEXT_MESSAGE_CONTENT": "thinking",
+    "THINKING_TEXT_MESSAGE_END": "thinking",
+    "RAW": "special",
+    "CUSTOM": "special"
+  },
+  "$deprecatedComment": "@deprecated markers in @ag-ui/core's type definitions, 'Will be removed in 1.0.0'. Maps a deprecated wire type to its replacement.",
+  "deprecated": {
+    "THINKING_START": "REASONING_START",
+    "THINKING_END": "REASONING_END",
+    "THINKING_TEXT_MESSAGE_START": "REASONING_MESSAGE_START",
+    "THINKING_TEXT_MESSAGE_CONTENT": "REASONING_MESSAGE_CONTENT",
+    "THINKING_TEXT_MESSAGE_END": "REASONING_MESSAGE_END"
+  }
+}

package/spec/fixtures/README.md

@@ -0,0 +1,91 @@
+# AG-UI conformance fixture corpus
+
+A language-neutral corpus for testing AG-UI protocol validators. Any
+implementation — TypeScript, Python, Go — that consumes the shared rule
+catalog ([`catalog.json`](../catalog.json)) can be tested
+against these files. The corpus, not per-rule test code, is the suite: adding
+a rule to the catalog means adding a fixture directory here.
+
+## Layout
+
+```
+fixtures/
+├── valid/                       one stream per canonical AG-UI feature
+│   ├── agentic-chat.jsonl
+│   ├── agentic-chat.expected.json     (optional; assumed [] when absent)
+│   └── …
+└── invalid/                     one directory per rule
+    ├── AGUI203-unterminated-tool-call/
+    │   ├── stream.jsonl         the event stream
+    │   ├── expected.json        the exact expected Diagnostic[]
+    │   └── options.json         (optional) validator options for this run
+    └── AGUI506-keepalive-gap/   transport rules use a scenario instead
+        ├── scenario.json        an HTTP response body as timed byte chunks
+        └── expected.json
+```
+
+## Running the corpus against an implementation
+
+For every event-stream fixture (`stream.jsonl`):
+
+1. Read the `.jsonl` file and split it into lines; drop empty lines.
+2. Feed each remaining line to the validator **as a raw string** — do not
+   pre-parse. Malformed lines are intentional (they exercise AGUI502); a
+   conforming validator treats them as diagnostics, never exceptions.
+3. If `options.json` exists, construct the validator with those options
+   (e.g. `{"features": ["shared-state"]}` for AGUI305).
+4. After the last line, finalize (end-of-stream checks).
+5. Deep-compare the accumulated diagnostics with `expected.json`. Order
+   matters: diagnostics are emitted in stream order, and end-of-stream
+   diagnostics use `eventIndex: -1`.
+
+For every transport fixture (`scenario.json`) — these exercise the rules that
+need a live connection (AGUI501, AGUI505–AGUI508):
+
+1. The scenario describes an HTTP response: `contentType` and `chunks`, each
+   chunk being `{ "gapMs": n, "text": "…" }` — the raw bytes as they arrived,
+   with `gapMs` of simulated silence before the chunk.
+2. Feed the chunk bytes through your transport layer (SSE or NDJSON per the
+   content type, sniffing when unknown) with a simulated clock that advances
+   by each `gapMs`; the keepalive window is the default 30 000 ms.
+3. `"abnormalEof": true` means the connection errored after the last chunk
+   (as opposed to closing cleanly) — the AGUI508 condition.
+4. Finalize and deep-compare diagnostics with `expected.json` as above.
+
+Every `invalid/` fixture must fire its directory's namesake rule; every
+`valid/` fixture must produce exactly its `*.expected.json` (usually nothing —
+they are the false-positive guards). `valid/predictive-state-updates` expects
+one `info` finding: the Dojo's real `PredictState` custom event name is
+un-namespaced (AGUI903, see `docs/spec-questions.md` SQ-14).
+
+## Diagnostic shape
+
+```json
+{
+  "rule": "AGUI203",
+  "severity": "error",
+  "message": "TOOL_CALL_START id 'call_7' never terminated",
+  "eventIndex": 3,
+  "eventType": "RUN_FINISHED",
+  "pointer": "/toolCallId",
+  "relatedEventIndex": 1,
+  "specUrl": "https://docs.ag-ui.com/concepts/events#tool-call-events"
+}
+```
+
+`eventType`, `pointer`, and `relatedEventIndex` are optional and omitted when
+absent. Messages come from the catalog's `messageTemplate`s, so independent
+implementations produce identical output.
+
+## Maintenance
+
+Fixtures are generated by [`scripts/build-fixtures.mjs`](../../js/scripts/build-fixtures.mjs),
+which declares each stream's *intended* rule hits independently of the
+validator and refuses to write anything on mismatch — regeneration can never
+silently bake an implementation bug into `expected.json`.
+
+## Not yet covered
+
+- **`valid/real-world/`** — captures from real frameworks (LangGraph, CrewAI,
+  Pydantic AI, Agno, Langflow `stream_protocol=agui`). Contributions welcome;
+  sanitise credentials before submitting.

package/spec/fixtures/invalid/AGUI001-first-event-not-run-started/expected.json

@@ -0,0 +1,10 @@
+[
+  {
+    "rule": "AGUI001",
+    "severity": "error",
+    "message": "First event of the run is TEXT_MESSAGE_START; expected RUN_STARTED",
+    "eventIndex": 0,
+    "specUrl": "https://docs.ag-ui.com/concepts/events#runstarted",
+    "eventType": "TEXT_MESSAGE_START"
+  }
+]

package/spec/fixtures/invalid/AGUI001-first-event-not-run-started/stream.jsonl

@@ -0,0 +1,4 @@
+{"type":"TEXT_MESSAGE_START","messageId":"msg_001","role":"assistant","timestamp":1755300007900}
+{"type":"TEXT_MESSAGE_CONTENT","messageId":"msg_001","delta":"Hello without a run.","timestamp":1755300008000}
+{"type":"TEXT_MESSAGE_END","messageId":"msg_001","timestamp":1755300008100}
+{"type":"RUN_FINISHED","threadId":"thread_001","runId":"run_001","timestamp":1755300008200}

package/spec/fixtures/invalid/AGUI002-duplicate-run-started/expected.json

@@ -0,0 +1,11 @@
+[
+  {
+    "rule": "AGUI002",
+    "severity": "error",
+    "message": "Duplicate RUN_STARTED (runId 'run_002') before the active run terminated",
+    "eventIndex": 1,
+    "specUrl": "https://docs.ag-ui.com/concepts/events#lifecycle-events",
+    "eventType": "RUN_STARTED",
+    "relatedEventIndex": 0
+  }
+]

package/spec/fixtures/invalid/AGUI002-duplicate-run-started/stream.jsonl

@@ -0,0 +1,3 @@
+{"type":"RUN_STARTED","threadId":"thread_001","runId":"run_001","timestamp":1755300008300}
+{"type":"RUN_STARTED","threadId":"thread_001","runId":"run_002","timestamp":1755300008400}
+{"type":"RUN_FINISHED","threadId":"thread_001","runId":"run_001","outcome":{"type":"success"},"timestamp":1755300008500}

package/spec/fixtures/invalid/AGUI003-run-never-terminated/expected.json

@@ -0,0 +1,10 @@
+[
+  {
+    "rule": "AGUI003",
+    "severity": "error",
+    "message": "Run 'run_001' ended without RUN_FINISHED or RUN_ERROR",
+    "eventIndex": -1,
+    "specUrl": "https://docs.ag-ui.com/concepts/events#runfinished",
+    "relatedEventIndex": 0
+  }
+]

package/spec/fixtures/invalid/AGUI003-run-never-terminated/stream.jsonl

@@ -0,0 +1,4 @@
+{"type":"RUN_STARTED","threadId":"thread_001","runId":"run_001","timestamp":1755300008600}
+{"type":"TEXT_MESSAGE_START","messageId":"msg_001","role":"assistant","timestamp":1755300008700}
+{"type":"TEXT_MESSAGE_CONTENT","messageId":"msg_001","delta":"This run just stops.","timestamp":1755300008800}
+{"type":"TEXT_MESSAGE_END","messageId":"msg_001","timestamp":1755300008900}

package/spec/fixtures/invalid/AGUI004-event-after-terminal/expected.json

@@ -0,0 +1,11 @@
+[
+  {
+    "rule": "AGUI004",
+    "severity": "error",
+    "message": "TEXT_MESSAGE_START follows the run's terminal RUN_FINISHED",
+    "eventIndex": 2,
+    "specUrl": "https://docs.ag-ui.com/concepts/events#lifecycle-events",
+    "eventType": "TEXT_MESSAGE_START",
+    "relatedEventIndex": 1
+  }
+]

package/spec/fixtures/invalid/AGUI004-event-after-terminal/stream.jsonl

@@ -0,0 +1,3 @@
+{"type":"RUN_STARTED","threadId":"thread_001","runId":"run_001","timestamp":1755300009000}
+{"type":"RUN_FINISHED","threadId":"thread_001","runId":"run_001","outcome":{"type":"success"},"timestamp":1755300009100}
+{"type":"TEXT_MESSAGE_START","messageId":"msg_001","role":"assistant","timestamp":1755300009200}

package/spec/fixtures/invalid/AGUI005-finished-and-error/expected.json

@@ -0,0 +1,11 @@
+[
+  {
+    "rule": "AGUI005",
+    "severity": "error",
+    "message": "RUN_ERROR emitted after the run already terminated with RUN_FINISHED",
+    "eventIndex": 2,
+    "specUrl": "https://docs.ag-ui.com/concepts/events#runfinished",
+    "eventType": "RUN_ERROR",
+    "relatedEventIndex": 1
+  }
+]

package/spec/fixtures/invalid/AGUI005-finished-and-error/stream.jsonl

@@ -0,0 +1,3 @@
+{"type":"RUN_STARTED","threadId":"thread_001","runId":"run_001","timestamp":1755300009300}
+{"type":"RUN_FINISHED","threadId":"thread_001","runId":"run_001","outcome":{"type":"success"},"timestamp":1755300009400}
+{"type":"RUN_ERROR","message":"boom","timestamp":1755300009500}

package/spec/fixtures/invalid/AGUI006-step-finished-unmatched/expected.json

@@ -0,0 +1,11 @@
+[
+  {
+    "rule": "AGUI006",
+    "severity": "error",
+    "message": "STEP_FINISHED 'plan' has no open STEP_STARTED",
+    "eventIndex": 1,
+    "specUrl": "https://docs.ag-ui.com/concepts/events#stepfinished",
+    "eventType": "STEP_FINISHED",
+    "pointer": "/stepName"
+  }
+]

package/spec/fixtures/invalid/AGUI006-step-finished-unmatched/stream.jsonl

@@ -0,0 +1,3 @@
+{"type":"RUN_STARTED","threadId":"thread_001","runId":"run_001","timestamp":1755300009600}
+{"type":"STEP_FINISHED","stepName":"plan","timestamp":1755300009700}
+{"type":"RUN_FINISHED","threadId":"thread_001","runId":"run_001","outcome":{"type":"success"},"timestamp":1755300009800}

package/spec/fixtures/invalid/AGUI007-step-unterminated/expected.json

@@ -0,0 +1,10 @@
+[
+  {
+    "rule": "AGUI007",
+    "severity": "error",
+    "message": "STEP_STARTED 'plan' never finished",
+    "eventIndex": 2,
+    "specUrl": "https://docs.ag-ui.com/concepts/events#stepstarted",
+    "relatedEventIndex": 1
+  }
+]

package/spec/fixtures/invalid/AGUI007-step-unterminated/stream.jsonl

@@ -0,0 +1,3 @@
+{"type":"RUN_STARTED","threadId":"thread_001","runId":"run_001","timestamp":1755300009900}
+{"type":"STEP_STARTED","stepName":"plan","timestamp":1755300010000}
+{"type":"RUN_FINISHED","threadId":"thread_001","runId":"run_001","outcome":{"type":"success"},"timestamp":1755300010100}

package/spec/fixtures/invalid/AGUI008-unstable-run-ids/expected.json

@@ -0,0 +1,12 @@
+[
+  {
+    "rule": "AGUI008",
+    "severity": "warning",
+    "message": "RUN_FINISHED runId 'run_999' does not match RUN_STARTED runId 'run_001'",
+    "eventIndex": 1,
+    "specUrl": "https://docs.ag-ui.com/concepts/events#runstarted",
+    "eventType": "RUN_FINISHED",
+    "pointer": "/runId",
+    "relatedEventIndex": 0
+  }
+]

package/spec/fixtures/invalid/AGUI008-unstable-run-ids/stream.jsonl

@@ -0,0 +1,2 @@
+{"type":"RUN_STARTED","threadId":"thread_001","runId":"run_001","timestamp":1755300010200}
+{"type":"RUN_FINISHED","threadId":"thread_001","runId":"run_999","outcome":{"type":"success"},"timestamp":1755300010300}

package/spec/fixtures/invalid/AGUI101-content-without-start/expected.json

@@ -0,0 +1,11 @@
+[
+  {
+    "rule": "AGUI101",
+    "severity": "error",
+    "message": "TEXT_MESSAGE_CONTENT for messageId 'msg_ghost' with no open TEXT_MESSAGE_START",
+    "eventIndex": 1,
+    "specUrl": "https://docs.ag-ui.com/concepts/events#text-message-events",
+    "eventType": "TEXT_MESSAGE_CONTENT",
+    "pointer": "/messageId"
+  }
+]

package/spec/fixtures/invalid/AGUI101-content-without-start/stream.jsonl

@@ -0,0 +1,3 @@
+{"type":"RUN_STARTED","threadId":"thread_001","runId":"run_001","timestamp":1755300010400}
+{"type":"TEXT_MESSAGE_CONTENT","messageId":"msg_ghost","delta":"orphan","timestamp":1755300010500}
+{"type":"RUN_FINISHED","threadId":"thread_001","runId":"run_001","outcome":{"type":"success"},"timestamp":1755300010600}

package/spec/fixtures/invalid/AGUI102-end-without-start/expected.json

@@ -0,0 +1,11 @@
+[
+  {
+    "rule": "AGUI102",
+    "severity": "error",
+    "message": "TEXT_MESSAGE_END for messageId 'msg_ghost' with no open TEXT_MESSAGE_START",
+    "eventIndex": 1,
+    "specUrl": "https://docs.ag-ui.com/concepts/events#textmessageend",
+    "eventType": "TEXT_MESSAGE_END",
+    "pointer": "/messageId"
+  }
+]

package/spec/fixtures/invalid/AGUI102-end-without-start/stream.jsonl

@@ -0,0 +1,3 @@
+{"type":"RUN_STARTED","threadId":"thread_001","runId":"run_001","timestamp":1755300010700}
+{"type":"TEXT_MESSAGE_END","messageId":"msg_ghost","timestamp":1755300010800}
+{"type":"RUN_FINISHED","threadId":"thread_001","runId":"run_001","outcome":{"type":"success"},"timestamp":1755300010900}

package/spec/fixtures/invalid/AGUI103-message-unterminated/expected.json

@@ -0,0 +1,10 @@
+[
+  {
+    "rule": "AGUI103",
+    "severity": "error",
+    "message": "TEXT_MESSAGE_START messageId 'msg_001' never ended",
+    "eventIndex": 3,
+    "specUrl": "https://docs.ag-ui.com/concepts/events#text-message-events",
+    "relatedEventIndex": 1
+  }
+]

package/spec/fixtures/invalid/AGUI103-message-unterminated/stream.jsonl

@@ -0,0 +1,4 @@
+{"type":"RUN_STARTED","threadId":"thread_001","runId":"run_001","timestamp":1755300011000}
+{"type":"TEXT_MESSAGE_START","messageId":"msg_001","role":"assistant","timestamp":1755300011100}
+{"type":"TEXT_MESSAGE_CONTENT","messageId":"msg_001","delta":"never ends","timestamp":1755300011200}
+{"type":"RUN_FINISHED","threadId":"thread_001","runId":"run_001","outcome":{"type":"success"},"timestamp":1755300011300}

package/spec/fixtures/invalid/AGUI104-duplicate-message-id/expected.json

@@ -0,0 +1,12 @@
+[
+  {
+    "rule": "AGUI104",
+    "severity": "error",
+    "message": "messageId 'msg_001' was already used by a completed message",
+    "eventIndex": 4,
+    "specUrl": "https://docs.ag-ui.com/concepts/events#textmessagestart",
+    "eventType": "TEXT_MESSAGE_START",
+    "pointer": "/messageId",
+    "relatedEventIndex": 3
+  }
+]

package/spec/fixtures/invalid/AGUI104-duplicate-message-id/stream.jsonl

@@ -0,0 +1,6 @@
+{"type":"RUN_STARTED","threadId":"thread_001","runId":"run_001","timestamp":1755300011400}
+{"type":"TEXT_MESSAGE_START","messageId":"msg_001","role":"assistant","timestamp":1755300011500}
+{"type":"TEXT_MESSAGE_CONTENT","messageId":"msg_001","delta":"first use","timestamp":1755300011600}
+{"type":"TEXT_MESSAGE_END","messageId":"msg_001","timestamp":1755300011700}
+{"type":"TEXT_MESSAGE_START","messageId":"msg_001","role":"assistant","timestamp":1755300011800}
+{"type":"RUN_FINISHED","threadId":"thread_001","runId":"run_001","outcome":{"type":"success"},"timestamp":1755300011900}

package/spec/fixtures/invalid/AGUI105-empty-content-delta/expected.json

@@ -0,0 +1,12 @@
+[
+  {
+    "rule": "AGUI105",
+    "severity": "warning",
+    "message": "TEXT_MESSAGE_CONTENT for messageId 'msg_001' has an empty delta",
+    "eventIndex": 2,
+    "specUrl": "https://docs.ag-ui.com/concepts/events#textmessagecontent",
+    "eventType": "TEXT_MESSAGE_CONTENT",
+    "pointer": "/delta",
+    "relatedEventIndex": 1
+  }
+]

package/spec/fixtures/invalid/AGUI105-empty-content-delta/stream.jsonl

@@ -0,0 +1,5 @@
+{"type":"RUN_STARTED","threadId":"thread_001","runId":"run_001","timestamp":1755300012000}
+{"type":"TEXT_MESSAGE_START","messageId":"msg_001","role":"assistant","timestamp":1755300012100}
+{"type":"TEXT_MESSAGE_CONTENT","messageId":"msg_001","delta":"","timestamp":1755300012200}
+{"type":"TEXT_MESSAGE_END","messageId":"msg_001","timestamp":1755300012300}
+{"type":"RUN_FINISHED","threadId":"thread_001","runId":"run_001","outcome":{"type":"success"},"timestamp":1755300012400}

package/spec/fixtures/invalid/AGUI106-interleaved-same-message-id/expected.json

@@ -0,0 +1,12 @@
+[
+  {
+    "rule": "AGUI106",
+    "severity": "error",
+    "message": "TEXT_MESSAGE_START for messageId 'msg_001', which is already open",
+    "eventIndex": 2,
+    "specUrl": "https://docs.ag-ui.com/concepts/events#implementation-considerations",
+    "eventType": "TEXT_MESSAGE_START",
+    "pointer": "/messageId",
+    "relatedEventIndex": 1
+  }
+]