feat(ag-ui): customEvents signal for live a2ui streaming parity (#606)

* docs(spec): standalone examples/ag-ui design (full-parity ag-ui demo)

Peer to examples/chat over the AG-UI transport. Three sequenced parts:
(1) add customEvents signal to @threadplane/ag-ui (closes the one live-
a2ui-streaming gap; valuable beyond the example) + docs; (2) the
examples/ag-ui app/python/smoke with full feature parity; (3) deploy via
a dedicated Railway service + ag-ui-demo.threadplane.ai. Feasibility
resolved by static spike: everything above the neutral Agent contract is
transport-agnostic; only the customEvents signal is missing.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* docs(plan): ag-ui customEvents signal implementation plan (PR 1)

* feat(ag-ui): accumulate non-interrupt CUSTOM events into a customEvents store signal

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* feat(ag-ui): expose customEvents signal on toAgent (AgUiAgent) for live a2ui streaming

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs(ag-ui): document customEvents signal + live a2ui streaming; regen API reference

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: blove

apps/website/content/docs/ag-ui/api/api-docs.json

@@ -402,6 +402,112 @@
     ],
     "examples": []
   },
+  {
+    "name": "AgUiAgent",
+    "kind": "interface",
+    "description": "The neutral Agent contract, widened with the AG-UI adapter's optional\n`customEvents` signal (the chat composition feature-detects it to enable\nlive a2ui streaming). Mirrors langgraph's LangGraphAgent extension.",
+    "properties": [
+      {
+        "name": "customEvents",
+        "type": "Signal<CustomStreamEvent[]>",
+        "description": "",
+        "optional": false
+      },
+      {
+        "name": "error",
+        "type": "Signal<unknown>",
+        "description": "",
+        "optional": false
+      },
+      {
+        "name": "events$",
+        "type": "Observable<AgentEvent>",
+        "description": "",
+        "optional": false
+      },
+      {
+        "name": "interrupt",
+        "type": "Signal<AgentInterrupt | undefined>",
+        "description": "",
+        "optional": true
+      },
+      {
+        "name": "isLoading",
+        "type": "Signal<boolean>",
+        "description": "",
+        "optional": false
+      },
+      {
+        "name": "messages",
+        "type": "Signal<Message[]>",
+        "description": "",
+        "optional": false
+      },
+      {
+        "name": "regenerate",
+        "type": "(assistantMessageIndex: number) => Promise<void>",
+        "description": "Discards the assistant message at the given index AND all messages after\nit, then re-runs the agent against the trimmed conversation tail. The\npreceding user message (at index - 1) is preserved and re-submitted as\nthe agent's input. No new user message is added to the history.\n\nThrows if the message at `index` is not 'assistant' role, or if the\nagent is currently loading another response.",
+        "optional": false
+      },
+      {
+        "name": "state",
+        "type": "Signal<Record<string, unknown>>",
+        "description": "",
+        "optional": false
+      },
+      {
+        "name": "status",
+        "type": "Signal<AgentStatus>",
+        "description": "",
+        "optional": false
+      },
+      {
+        "name": "stop",
+        "type": "() => Promise<void>",
+        "description": "",
+        "optional": false
+      },
+      {
+        "name": "subagents",
+        "type": "Signal<Map<string, Subagent>>",
+        "description": "",
+        "optional": true
+      },
+      {
+        "name": "submit",
+        "type": "(input: AgentSubmitInput, opts: AgentSubmitOptions) => Promise<void>",
+        "description": "",
+        "optional": false
+      },
+      {
+        "name": "toolCalls",
+        "type": "Signal<ToolCall[]>",
+        "description": "",
+        "optional": false
+      }
+    ],
+    "examples": []
+  },
+  {
+    "name": "CustomStreamEvent",
+    "kind": "interface",
+    "description": "A custom event surfaced to consumers via the agent's `customEvents` signal.\nMirrors the LangGraph adapter's CustomStreamEvent shape so the chat\na2ui partial-args bridge consumes both transports identically.",
+    "properties": [
+      {
+        "name": "data",
+        "type": "unknown",
+        "description": "Arbitrary payload from the backend (JSON-string values are parsed).",
+        "optional": false
+      },
+      {
+        "name": "name",
+        "type": "string",
+        "description": "Event name set by the backend (e.g. 'a2ui-partial', 'state_update').",
+        "optional": false
+      }
+    ],
+    "examples": []
+  },
   {
     "name": "ToAgentOptions",
     "kind": "interface",
@@ -495,7 +601,7 @@
     "name": "toAgent",
     "kind": "function",
     "description": "Wraps an AG-UI AbstractAgent into the runtime-neutral Agent contract.\n\nThe adapter subscribes to source.subscribe({ onEvent }) and reduces every\nevent into the produced Agent's signals. submit() optimistically appends the\nuser message to both our signals and the source agent's internal message\nlist, then calls source.runAgent(). stop() calls source.abortRun().\n\nSubscription cleanup: the returned Agent does NOT manage its own lifetime.\nCallers using DI should rely on the provider's destroy hook; direct callers\nof toAgent() should treat the returned object's lifecycle as tied to the\nagent instance they constructed. The subscriber registered via\nsource.subscribe() will fire for the lifetime of source.",
-    "signature": "toAgent(source: AbstractAgent<>, options: ToAgentOptions): Agent",
+    "signature": "toAgent(source: AbstractAgent<>, options: ToAgentOptions): AgUiAgent",
     "params": [
       {
         "name": "source",
@@ -511,7 +617,7 @@
       }
     ],
     "returns": {
-      "type": "Agent",
+      "type": "AgUiAgent",
       "description": ""
     },
     "examples": []

apps/website/content/docs/ag-ui/concepts/architecture.mdx

@@ -94,6 +94,16 @@ When the user submits input, the adapter builds a user message, appends it local
 
 This is optimistic on purpose. The user message appears immediately while the backend starts the run.
 
+## Live a2ui streaming via `customEvents`
+
+The adapter exposes a `customEvents` signal on the agent returned by
+`toAgent` / `injectAgent`, accumulating every non-`on_interrupt` `CUSTOM`
+AG-UI event for the current run (reset on each `RUN_STARTED`). The chat
+composition feature-detects this signal to drive **progressive** a2ui
+surface rendering — token-by-token, as the backend streams `a2ui-partial`
+events — matching the LangGraph adapter. Without it, a2ui still renders from
+the final tool-call surface; with it, surfaces build up live.
+
 ## Provider choices
 
 Use `provideAgent()` when you have a real AG-UI HTTP endpoint.