ag-ui-validate 0.3.0 → 0.4.0

package/js/src/rules/checks/subagents.ts

@@ -0,0 +1,78 @@
+// Subagent lifecycle rules: AGUI601–AGUI605.
+//
+// Scope: the SUBAGENT_STARTED/FINISHED/ERROR lifecycle itself, per
+// https://docs.ag-ui.com/concepts/subagents#rules-clients-enforce. Ownership
+// consistency for events attributed to a subagent via their own optional
+// subagentRunId field (text messages, tool calls, steps, ...) is a separate,
+// broader concern not covered here.
+
+import type { CheckApi, RunState, EmitFn } from "./context.js"
+import { str } from "./context.js"
+
+export function handleSubagentEvent(api: CheckApi): void {
+  const { type, event, run, emit, index } = api
+
+  switch (type) {
+    case "SUBAGENT_STARTED": {
+      const id = str(event, "subagentRunId")
+      if (id === undefined) return
+      run.knownSubagentRunIds.add(id)
+
+      const open = run.openSubagents.get(id)
+      if (open !== undefined) {
+        emit("AGUI601", { subagentRunId: id }, { pointer: "/subagentRunId", relatedEventIndex: open.startIndex })
+        return
+      }
+      const closed = run.closedSubagents.get(id)
+      if (closed !== undefined && !closed.resumable) {
+        emit("AGUI601", { subagentRunId: id }, { pointer: "/subagentRunId", relatedEventIndex: closed.index })
+        return
+      }
+
+      // Either brand new, or a legitimate resumption of a suspended subagent.
+      run.openSubagents.set(id, { startIndex: index })
+      if (closed !== undefined) run.closedSubagents.delete(id)
+
+      const parent = str(event, "parentSubagentRunId")
+      if (parent !== undefined && !run.knownSubagentRunIds.has(parent)) {
+        emit("AGUI605", { parentSubagentRunId: parent }, { pointer: "/parentSubagentRunId" })
+      }
+      return
+    }
+
+    case "SUBAGENT_FINISHED": {
+      const id = str(event, "subagentRunId")
+      if (id === undefined) return
+      const open = run.openSubagents.get(id)
+      if (open === undefined) {
+        emit("AGUI602", { subagentRunId: id }, { pointer: "/subagentRunId" })
+        return
+      }
+      run.openSubagents.delete(id)
+      const outcome = event.outcome
+      const resumable = typeof outcome === "object" && outcome !== null && (outcome as { type?: unknown }).type === "suspended"
+      run.closedSubagents.set(id, { index, resumable })
+      return
+    }
+
+    case "SUBAGENT_ERROR": {
+      const id = str(event, "subagentRunId")
+      if (id === undefined) return
+      const open = run.openSubagents.get(id)
+      if (open === undefined) {
+        emit("AGUI603", { subagentRunId: id }, { pointer: "/subagentRunId" })
+        return
+      }
+      run.openSubagents.delete(id)
+      run.closedSubagents.set(id, { index, resumable: false })
+      return
+    }
+  }
+}
+
+/** AGUI604 — open subagents when the run reaches a clean end. */
+export function endOfRunSubagents(run: RunState, emit: EmitFn, atIndex: number): void {
+  for (const [id, open] of run.openSubagents) {
+    emit("AGUI604", { subagentRunId: id }, { eventIndex: atIndex, relatedEventIndex: open.startIndex })
+  }
+}

package/js/src/rules/checks/text.ts

@@ -1,7 +1,7 @@
 // Text message rules: AGUI101–AGUI106, plus TEXT_MESSAGE_CHUNK stream handling.
 
 import type { CheckApi, RunState, EmitFn } from "./context.js"
-import { str } from "./context.js"
+import { checkOwnerConsistency, str } from "./context.js"
 
 export function handleTextEvent(api: CheckApi): void {
   const { type, event, run, emit, index } = api
@@ -25,8 +25,10 @@ export function handleTextEvent(api: CheckApi): void {
         })
         return
       }
-      run.openMessages.set(id, { startIndex: index })
+      const owner = str(event, "subagentRunId")
+      run.openMessages.set(id, { startIndex: index, owner })
       run.knownMessageIds.add(id)
+      run.messageOwner.set(id, owner)
       return
     }
 
@@ -45,16 +47,19 @@ export function handleTextEvent(api: CheckApi): void {
       if (event.delta === "") {
         emit("AGUI105", { messageId: id }, { pointer: "/delta", relatedEventIndex: open.startIndex })
       }
+      checkOwnerConsistency(emit, type, "messageId", id, event, open.owner)
       return
     }
 
     case "TEXT_MESSAGE_END": {
       const id = str(event, "messageId")
       if (id === undefined) return
-      if (!run.openMessages.has(id)) {
+      const open = run.openMessages.get(id)
+      if (open === undefined) {
         emit("AGUI102", { messageId: id }, { pointer: "/messageId" })
         return
       }
+      checkOwnerConsistency(emit, type, "messageId", id, event, open.owner)
       run.openMessages.delete(id)
       run.closedMessages.set(id, index)
       return
@@ -86,6 +91,9 @@ export function handleTextEvent(api: CheckApi): void {
       }
       run.textChunk = { messageId: id, startIndex: index }
       run.knownMessageIds.add(id)
+      // Chunk attribution consistency is a known gap (SQ-15); still record
+      // the owner so a TOOL_CALL_START.parentMessageId can inherit it.
+      run.messageOwner.set(id, str(event, "subagentRunId"))
       return
     }
   }

package/js/src/rules/checks/toolcalls.ts

@@ -1,7 +1,7 @@
 // Tool call rules: AGUI201–AGUI208, plus TOOL_CALL_CHUNK stream handling.
 
 import type { CheckApi, RunState, EmitFn } from "./context.js"
-import { str } from "./context.js"
+import { checkOwnerConsistency, str } from "./context.js"
 
 export function handleToolCallEvent(api: CheckApi): void {
   const { type, event, run, emit, index } = api
@@ -16,8 +16,12 @@ export function handleToolCallEvent(api: CheckApi): void {
         emit("AGUI205", { toolCallId: id }, { pointer: "/toolCallId", relatedEventIndex: related })
         return
       }
-      run.openToolCalls.set(id, { startIndex: index, args: "", sawArgs: false })
       const parent = str(event, "parentMessageId")
+      // An untagged call inherits its parent message's owner (AGUI606's "an
+      // untagged tool call inherits the parent message's owner");
+      // ToolCallResult is deliberately exempt — it states its own owner.
+      const owner = str(event, "subagentRunId") ?? (parent !== undefined ? run.messageOwner.get(parent) : undefined)
+      run.openToolCalls.set(id, { startIndex: index, args: "", sawArgs: false, owner })
       if (parent !== undefined && !run.knownMessageIds.has(parent)) {
         emit("AGUI208", { parentMessageId: parent }, { pointer: "/parentMessageId" })
       }
@@ -37,6 +41,7 @@ export function handleToolCallEvent(api: CheckApi): void {
         open.args += delta
         open.sawArgs = true
       }
+      checkOwnerConsistency(emit, type, "toolCallId", id, event, open.owner)
       return
     }
 
@@ -48,6 +53,7 @@ export function handleToolCallEvent(api: CheckApi): void {
         emit("AGUI202", { toolCallId: id }, { pointer: "/toolCallId" })
         return
       }
+      checkOwnerConsistency(emit, type, "toolCallId", id, event, open.owner)
       run.openToolCalls.delete(id)
       run.closedToolCalls.set(id, index)
       checkArgsJson(id, open, emit, index)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ag-ui-validate",
-  "version": "0.3.0",
+  "version": "0.4.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",
@@ -117,7 +117,7 @@
     }
   },
   "devDependencies": {
-    "@ag-ui/core": "^0.0.58",
+    "@ag-ui/core": "^0.0.59",
     "@changesets/cli": "^3.0.0",
     "@types/node": "^26.2.0",
     "tsdown": "^0.22.14",

package/spec/catalog.json

@@ -1,12 +1,13 @@
 {
   "$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.",
@@ -17,6 +18,7 @@
       "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.",
@@ -27,6 +29,7 @@
       "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.",
@@ -37,6 +40,7 @@
       "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.",
@@ -47,6 +51,7 @@
       "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.",
@@ -57,6 +62,7 @@
       "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.",
@@ -67,6 +73,7 @@
       "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.",
@@ -77,6 +84,7 @@
       "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.",
@@ -87,6 +95,7 @@
       "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.",
@@ -98,6 +107,7 @@
       "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",
@@ -109,6 +119,7 @@
       "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.",
@@ -120,6 +131,7 @@
       "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.",
@@ -131,6 +143,7 @@
       "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)",
@@ -143,6 +156,7 @@
       "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",
@@ -154,6 +168,7 @@
       "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.",
@@ -165,6 +180,7 @@
       "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",
@@ -176,6 +192,7 @@
       "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.",
@@ -187,6 +204,7 @@
       "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.",
@@ -198,6 +216,7 @@
       "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",
@@ -209,6 +228,7 @@
       "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.",
@@ -220,6 +240,7 @@
       "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",
@@ -231,6 +252,7 @@
       "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.",
@@ -243,6 +265,7 @@
       "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.",
@@ -255,6 +278,7 @@
       "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.",
@@ -266,6 +290,7 @@
       "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).",
@@ -277,6 +302,7 @@
       "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.",
@@ -288,6 +314,7 @@
       "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.",
@@ -300,6 +327,7 @@
       "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.",
@@ -311,6 +339,7 @@
       "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.",
@@ -322,6 +351,7 @@
       "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",
@@ -331,6 +361,7 @@
       "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.",
@@ -341,6 +372,7 @@
       "id": "AGUI503",
       "severity": "error",
       "title": "Unknown event type",
+      "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.",
@@ -351,6 +383,7 @@
       "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.",
@@ -361,6 +394,7 @@
       "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",
@@ -370,6 +404,7 @@
       "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",
@@ -380,6 +415,7 @@
       "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",
@@ -390,16 +426,85 @@
       "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.",
@@ -410,6 +515,7 @@
       "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",
@@ -420,6 +526,7 @@
       "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.",

package/spec/event-categories.json

@@ -8,7 +8,8 @@
     "activity",
     "reasoning",
     "thinking",
-    "special"
+    "special",
+    "subagent"
   ],
   "eventCategory": {
     "RUN_STARTED": "lifecycle",
@@ -43,7 +44,10 @@
     "THINKING_TEXT_MESSAGE_CONTENT": "thinking",
     "THINKING_TEXT_MESSAGE_END": "thinking",
     "RAW": "special",
-    "CUSTOM": "special"
+    "CUSTOM": "special",
+    "SUBAGENT_STARTED": "subagent",
+    "SUBAGENT_FINISHED": "subagent",
+    "SUBAGENT_ERROR": "subagent"
   },
   "$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": {

package/spec/fixtures/invalid/AGUI501-missing-data-prefix/scenario.json

@@ -3,15 +3,15 @@
   "chunks": [
     {
       "gapMs": 0,
-      "text": "data: {\"type\":\"RUN_STARTED\",\"threadId\":\"thread_001\",\"runId\":\"run_001\",\"timestamp\":1755300020500}\n\n"
+      "text": "data: {\"type\":\"RUN_STARTED\",\"threadId\":\"thread_001\",\"runId\":\"run_001\",\"timestamp\":1755300022900}\n\n"
     },
     {
       "gapMs": 0,
-      "text": "{\"type\":\"CUSTOM\",\"name\":\"acme.ping\",\"value\":1,\"timestamp\":1755300020600}\n\n"
+      "text": "{\"type\":\"CUSTOM\",\"name\":\"acme.ping\",\"value\":1,\"timestamp\":1755300023000}\n\n"
     },
     {
       "gapMs": 0,
-      "text": "data: {\"type\":\"RUN_FINISHED\",\"threadId\":\"thread_001\",\"runId\":\"run_001\",\"outcome\":{\"type\":\"success\"},\"timestamp\":1755300020700}\n\n"
+      "text": "data: {\"type\":\"RUN_FINISHED\",\"threadId\":\"thread_001\",\"runId\":\"run_001\",\"outcome\":{\"type\":\"success\"},\"timestamp\":1755300023100}\n\n"
     }
   ]
 }

package/spec/fixtures/invalid/AGUI502-payload-not-json/stream.jsonl

@@ -1,3 +1,3 @@
-{"type":"RUN_STARTED","threadId":"thread_001","runId":"run_001","timestamp":1755300019000}
+{"type":"RUN_STARTED","threadId":"thread_001","runId":"run_001","timestamp":1755300021400}
 {"type": broken json
-{"type":"RUN_FINISHED","threadId":"thread_001","runId":"run_001","outcome":{"type":"success"},"timestamp":1755300019100}
+{"type":"RUN_FINISHED","threadId":"thread_001","runId":"run_001","outcome":{"type":"success"},"timestamp":1755300021500}

package/spec/fixtures/invalid/AGUI503-unknown-event-type/expected.json

@@ -2,7 +2,7 @@
   {
     "rule": "AGUI503",
     "severity": "error",
-    "message": "Unknown event type 'AGUI_PING' (not in the installed AG-UI SDK v0.0.58, and not RAW or CUSTOM)",
+    "message": "Unknown event type 'AGUI_PING' (not in the installed AG-UI SDK v0.0.59, and not RAW or CUSTOM)",
     "eventIndex": 1,
     "specUrl": "https://docs.ag-ui.com/concepts/events#event-types-overview",
     "eventType": "AGUI_PING"

package/spec/fixtures/invalid/AGUI503-unknown-event-type/stream.jsonl

@@ -1,3 +1,3 @@
-{"type":"RUN_STARTED","threadId":"thread_001","runId":"run_001","timestamp":1755300019200}
-{"type":"AGUI_PING","timestamp":1755300019300}
-{"type":"RUN_FINISHED","threadId":"thread_001","runId":"run_001","outcome":{"type":"success"},"timestamp":1755300019400}
+{"type":"RUN_STARTED","threadId":"thread_001","runId":"run_001","timestamp":1755300021600}
+{"type":"AGUI_PING","timestamp":1755300021700}
+{"type":"RUN_FINISHED","threadId":"thread_001","runId":"run_001","outcome":{"type":"success"},"timestamp":1755300021800}