Merge branch 'main' into feat/langgraph-app-mode-itinerary

Author: blove

apps/website/content/AGENTS.md.template

@@ -3,7 +3,7 @@
 Production-ready chat, durable threads, interrupts, subagents, planning, memory, and generative UI for Angular agent apps.
 
 ## Install
-npm install @threadplane/chat @threadplane/langgraph
+npm install @threadplane/chat @threadplane/langgraph @langchain/core @langchain/langgraph-sdk marked
 
 ## Key requirement
 `injectAgent()` MUST be called within an Angular injection context (component constructor or field initializer). Calling it in ngOnInit or any async context throws "NG0203: inject() must be called from an injection context".

apps/website/content/CLAUDE.md.template

@@ -3,7 +3,7 @@
 Production-ready chat, durable threads, interrupts, subagents, planning, memory, and generative UI for Angular agent apps.
 
 ## Install
-npm install @threadplane/chat @threadplane/langgraph
+npm install @threadplane/chat @threadplane/langgraph @langchain/core @langchain/langgraph-sdk marked
 
 ## Key requirement
 `injectAgent()` MUST be called within an Angular injection context (component constructor or field initializer). Calling it in ngOnInit or any async context throws "NG0203: inject() must be called from an injection context".

apps/website/content/docs/a2ui/api/api-docs.json

@@ -460,7 +460,7 @@
       {
         "name": "push",
         "signature": "push(chunk: string): A2uiMessage[]",
-        "description": "",
+        "description": "Push a JSONL stream chunk and return every complete A2UI envelope parsed from it.",
         "params": [
           {
             "name": "chunk",
@@ -881,19 +881,21 @@
   {
     "name": "createA2uiMessageParser",
     "kind": "function",
-    "description": "",
+    "description": "Creates a stateful parser for newline-delimited A2UI message streams.\n\nThe parser buffers incomplete lines, skips malformed JSON, and returns only\nrecognized A2UI envelopes: `surfaceUpdate`, `dataModelUpdate`,\n`beginRendering`, and `deleteSurface`.",
     "signature": "createA2uiMessageParser(): A2uiMessageParser",
     "params": [],
     "returns": {
       "type": "A2uiMessageParser",
       "description": ""
     },
-    "examples": []
+    "examples": [
+      "```ts\nconst parser = createA2uiMessageParser();\nconst messages = parser.push('{\"beginRendering\":{\"surfaceId\":\"s1\",\"root\":\"root\"}}\\n');\n```"
+    ]
   },
   {
     "name": "deleteByPointer",
     "kind": "function",
-    "description": "",
+    "description": "Returns a new model with the key at `pointer` removed.\n\nEmpty string and `/` clear the whole model. Missing parent paths leave the\ninput model unchanged.",
     "signature": "deleteByPointer(model: Record<string, unknown>, pointer: string): Record<string, unknown>",
     "params": [
       {
@@ -913,12 +915,14 @@
       "type": "Record<string, unknown>",
       "description": ""
     },
-    "examples": []
+    "examples": [
+      "```ts\nconst next = deleteByPointer({ user: { name: 'Ada' } }, '/user/name');\n```"
+    ]
   },
   {
     "name": "getByPointer",
     "kind": "function",
-    "description": "",
+    "description": "Reads a value from a model using the package's simple slash-separated pointer syntax.\n\nEmpty string and `/` target the root. Segments are not RFC 6901-unescaped;\nnormalize keys before using pointers that would require `~0` or `~1`.",
     "signature": "getByPointer(model: Record<string, unknown>, pointer: string): unknown",
     "params": [
       {
@@ -938,12 +942,14 @@
       "type": "unknown",
       "description": ""
     },
-    "examples": []
+    "examples": [
+      "```ts\ngetByPointer({ user: { name: 'Ada' } }, '/user/name'); // 'Ada'\n```"
+    ]
   },
   {
     "name": "isLiteralBoolean",
     "kind": "function",
-    "description": "",
+    "description": "Returns true when `value` is an A2UI boolean literal wrapper.",
     "signature": "isLiteralBoolean(value: unknown): value is { literalBoolean: boolean }",
     "params": [
       {
@@ -962,7 +968,7 @@
   {
     "name": "isLiteralNumber",
     "kind": "function",
-    "description": "",
+    "description": "Returns true when `value` is an A2UI number literal wrapper.",
     "signature": "isLiteralNumber(value: unknown): value is { literalNumber: number }",
     "params": [
       {
@@ -981,7 +987,7 @@
   {
     "name": "isLiteralString",
     "kind": "function",
-    "description": "",
+    "description": "Returns true when `value` is an A2UI string literal wrapper.",
     "signature": "isLiteralString(value: unknown): value is { literalString: string }",
     "params": [
       {
@@ -1000,7 +1006,7 @@
   {
     "name": "isPathRef",
     "kind": "function",
-    "description": "",
+    "description": "Returns true when `value` is an A2UI dynamic path reference.",
     "signature": "isPathRef(value: unknown): value is { path: string }",
     "params": [
       {
@@ -1019,7 +1025,7 @@
   {
     "name": "resolveDynamic",
     "kind": "function",
-    "description": "",
+    "description": "Resolves an A2UI dynamic value against a client data model.\n\nLiteral wrappers unwrap to their inner values, `{ path }` references read\nfrom the model by JSON-pointer path, arrays resolve recursively, and\nunrecognized plain values pass through unchanged.",
     "signature": "resolveDynamic(value: unknown, model: Record<string, unknown>, scope: A2uiScope): unknown",
     "params": [
       {
@@ -1045,12 +1051,14 @@
       "type": "unknown",
       "description": ""
     },
-    "examples": []
+    "examples": [
+      "```ts\nconst model = { customer: { name: 'Ada' } };\nresolveDynamic({ path: '/customer/name' }, model); // 'Ada'\nresolveDynamic({ literalString: 'Checkout' }, model); // 'Checkout'\n```"
+    ]
   },
   {
     "name": "setByPointer",
     "kind": "function",
-    "description": "",
+    "description": "Returns a new model with `value` written at `pointer`.\n\nThe input model is not mutated. Missing intermediate objects are created.",
     "signature": "setByPointer(model: Record<string, unknown>, pointer: string, value: unknown): Record<string, unknown>",
     "params": [
       {
@@ -1076,6 +1084,8 @@
       "type": "Record<string, unknown>",
       "description": ""
     },
-    "examples": []
+    "examples": [
+      "```ts\nconst next = setByPointer({}, '/user/name', 'Ada');\n```"
+    ]
   }
 ]

apps/website/content/docs/a2ui/getting-started/quickstart.mdx

@@ -28,7 +28,7 @@ Let's start with a real stream. An agent emits A2UI as newline-delimited JSON 
 ```text
 ---a2ui_JSON---
 {"dataModelUpdate":{"surfaceId":"booking","contents":[{"key":"origin","valueString":"LAX"},{"key":"dest","valueString":"JFK"},{"key":"passengers","valueNumber":1}]}}
-{"surfaceUpdate":{"surfaceId":"booking","components":[{"id":"root","component":{"Column":{"children":{"explicitList":["title","origin","submit"]}}}},{"id":"title","component":{"Text":{"text":"Book a flight","usageHint":"h2"}}},{"id":"origin","component":{"MultipleChoice":{"label":"Origin","options":[{"label":"LAX","value":"LAX"},{"label":"JFK","value":"JFK"}],"selections":{"path":"/origin"},"maxAllowedSelections":1}}},{"id":"submit_label","component":{"Text":{"text":"Search flights"}}},{"id":"submit","component":{"Button":{"child":"submit_label","primary":true,"action":{"name":"bookingSubmit","context":[{"key":"origin","value":{"path":"/origin"}},{"key":"dest","value":{"path":"/dest"}}]}}}}]}}
+{"surfaceUpdate":{"surfaceId":"booking","components":[{"id":"root","component":{"Column":{"children":{"explicitList":["title","origin","submit"]}}}},{"id":"title","component":{"Text":{"text":{"literalString":"Book a flight"},"usageHint":"h2"}}},{"id":"origin","component":{"MultipleChoice":{"label":{"literalString":"Origin"},"options":[{"label":{"literalString":"LAX"},"value":"LAX"},{"label":{"literalString":"JFK"},"value":"JFK"}],"selections":{"path":"/origin"},"maxAllowedSelections":1}}},{"id":"submit_label","component":{"Text":{"text":{"literalString":"Search flights"}}}},{"id":"submit","component":{"Button":{"child":"submit_label","primary":true,"action":{"name":"bookingSubmit","context":[{"key":"origin","value":{"path":"/origin"}},{"key":"dest","value":{"path":"/dest"}}]}}}}]}}
 {"beginRendering":{"surfaceId":"booking","root":"root"}}
 ```
 

apps/website/content/docs/a2ui/guides/message-protocol.mdx

@@ -15,7 +15,7 @@ Every envelope carries that `surfaceId`. A `dataModelUpdate` for `"booking"` onl
 As an **id-keyed adjacency list**. A `surfaceUpdate` carries a flat `components` array. Each entry has an `id` and a single `component` definition. Parent-child links are by id reference, not by nesting.
 
 ```json
-{"surfaceUpdate":{"surfaceId":"booking","components":[{"id":"root","component":{"Column":{"children":{"explicitList":["title","origin","submit"]}}}},{"id":"title","component":{"Text":{"text":"Book a flight","usageHint":"h2"}}}]}}
+{"surfaceUpdate":{"surfaceId":"booking","components":[{"id":"root","component":{"Column":{"children":{"explicitList":["title","origin","submit"]}}}},{"id":"title","component":{"Text":{"text":{"literalString":"Book a flight"},"usageHint":"h2"}}}]}}
 ```
 
 The `component` value is a **keyed union**: a single-key object where the key names the component type and the value holds its props — `{ "<Name>": { props } }`. `{ "Text": { ... } }` is a Text, `{ "Column": { ... } }` is a Column. There's no separate `type` field; the key *is* the type.
@@ -69,7 +69,7 @@ The stream is a sequence of single-key envelope objects. The parser recognizes e
 Defines (or replaces) the components for a surface.
 
 ```json
-{"surfaceUpdate":{"surfaceId":"booking","components":[{"id":"submit_label","component":{"Text":{"text":"Search flights"}}},{"id":"submit","component":{"Button":{"child":"submit_label","primary":true,"action":{"name":"bookingSubmit","context":[{"key":"origin","value":{"path":"/origin"}},{"key":"dest","value":{"path":"/dest"}}]}}}}]}}
+{"surfaceUpdate":{"surfaceId":"booking","components":[{"id":"submit_label","component":{"Text":{"text":{"literalString":"Search flights"}}}},{"id":"submit","component":{"Button":{"child":"submit_label","primary":true,"action":{"name":"bookingSubmit","context":[{"key":"origin","value":{"path":"/origin"}},{"key":"dest","value":{"path":"/dest"}}]}}}}]}}
 ```
 
 ### `dataModelUpdate`

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

@@ -405,7 +405,7 @@
   {
     "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) and the optional `clientTools` capability.\nMirrors langgraph's LangGraphAgent extension.",
+    "description": "The neutral Agent contract, widened with the AG-UI adapter's\n`customEvents` signal (the chat composition feature-detects it to enable\nlive a2ui streaming), the browser client-tools capability, and concrete\nACTIVITY-backed `subagents`.\nMirrors langgraph's LangGraphAgent extension where the protocol surfaces\noverlap.",
     "properties": [
       {
         "name": "clientTools",
@@ -620,7 +620,7 @@
       "description": ""
     },
     "examples": [
-      "```ts\nTestBed.configureTestingModule({\n  providers: [provideFakeAgent({ responses: ['Hello from the fake agent'] })],\n});\n```"
+      "```ts\nTestBed.configureTestingModule({\n  providers: [provideFakeAgent({ tokens: ['Hello from the fake agent'] })],\n});\n```"
     ]
   },
   {
@@ -646,6 +646,8 @@
       "type": "AgUiAgent<>",
       "description": ""
     },
-    "examples": []
+    "examples": [
+      "```ts\nimport { HttpAgent } from '@ag-ui/client';\nimport { toAgent } from '@threadplane/ag-ui';\n\nconst agent = toAgent(new HttpAgent({ url: '/api/agent' }));\n```"
+    ]
   }
 ]

apps/website/content/docs/ag-ui/api/inject-agent.mdx

@@ -65,19 +65,22 @@ These fields are stable across runtime adapters and are what chat components con
 
 ## AG-UI-specific surface
 
-The AG-UI adapter extends the neutral `Agent` contract with one additional signal:
+The AG-UI adapter extends the neutral `Agent` contract with AG-UI-specific protocol surfaces:
 
 | Field | Type | Description |
 |-------|------|-------------|
 | `customEvents()` | `CustomStreamEvent[]` | Custom events emitted by the backend during a run. Accumulates per run; resets on each new `submit()`. |
+| `clientTools` | `ClientToolsCapability` | Browser client-tool catalog, pending calls, and result resolution used by `<chat [clientTools]>`. |
+| `subagents()` | `Map<string, Subagent>` | `ACTIVITY_*` entries with `activityType: 'subagent'`, projected to the neutral subagent contract and keyed by `messageId`. |
 
-`injectAgent()` returns the `AgUiAgent` type — the neutral `Agent` contract plus `customEvents` — so the signal is reachable directly, no cast required:
+`injectAgent()` returns the `AgUiAgent` type — the neutral `Agent` contract plus these AG-UI-specific fields — so they are reachable directly, no cast required:
 
 ```ts
 import { injectAgent } from '@threadplane/ag-ui';
 
 const chat = injectAgent();
-chat.customEvents(); // Signal<CustomStreamEvent[]>
+chat.customEvents(); // CustomStreamEvent[]
+chat.subagents(); // Map<string, Subagent>
 ```
 
 The chat a2ui bridge reads `customEvents` to light up live generative-UI streaming when your backend emits `a2ui-partial` events. The consuming side is documented in chat's [A2UI overview](/docs/chat/a2ui/overview). See the [Custom Events guide](/docs/ag-ui/guides/custom-events) for backend wiring details.

apps/website/content/docs/ag-ui/api/to-agent.mdx

@@ -24,11 +24,13 @@ const agent = toAgent(source, { telemetry: myTelemetrySink });
 
 ## AgUiAgent
 
-`toAgent()` returns an `AgUiAgent`, which extends the neutral `Agent` contract with one additional signal:
+`toAgent()` returns an `AgUiAgent`, which extends the neutral `Agent` contract with AG-UI-specific protocol surfaces:
 
 | Field | Type | Description |
 |-------|------|-------------|
 | `customEvents()` | `Signal<CustomStreamEvent[]>` | Custom events accumulated during a run. Resets at the start of each new run. |
+| `clientTools` | `ClientToolsCapability` | Browser client-tool catalog, pending calls, and result resolution. The chat composition uses this when you pass `<chat [clientTools]>`. |
+| `subagents()` | `Signal<Map<string, Subagent>>` | `ACTIVITY_*` events with `activityType: 'subagent'`, projected to the neutral subagent contract and keyed by `messageId`. |
 
 The standard `Agent` signals (`messages`, `status`, `isLoading`, `error`, `toolCalls`, `state`, `interrupt`) and actions (`submit`, `stop`, `regenerate`) are all present.
 

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

@@ -88,7 +88,9 @@ Every AG-UI event is passed through the reducer. The reducer updates Angular sig
 - `toolCalls` for tool call starts, arguments, results, and completion.
 - `state` for AG-UI state snapshots and JSON Patch deltas.
 - `interrupt` cleared on `RUN_STARTED` and set by the `CUSTOM` `on_interrupt` event.
-- `events$` for custom events.
+- `events$` for runtime-neutral custom-event side effects.
+- `customEvents` for accumulated non-`on_interrupt` `CUSTOM` events used by live a2ui and app-specific reactive UI.
+- `subagents` for `ACTIVITY_*` events with `activityType: 'subagent'`.
 
 When the user submits input, the adapter builds a user message, appends it locally, adds it to the AG-UI source with `source.addMessage()`, then calls `source.runAgent()`.
 
@@ -106,6 +108,12 @@ the final tool-call surface; with it, surfaces build up live.
 
 The consuming side — how the chat composition turns these events into rendered surfaces — lives in chat's [A2UI overview](/docs/chat/a2ui/overview).
 
+## Browser client tools
+
+`AgUiAgent.clientTools` is the browser-tool bridge consumed by `<chat [clientTools]>`. The chat composition registers the browser catalog on the agent; the adapter threads that catalog into every `source.runAgent({ tools })` call, exposes unresolved browser-owned tool calls through `clientTools.pending()`, and sends the browser result back as a tool message before continuing the run.
+
+See chat's [Client Tools guide](/docs/chat/guides/client-tools) for declaring `action()`, `view()`, and `ask()` tools. With AG-UI, the backend must bind the supplied AG-UI tool specs and finish the turn without emitting `TOOL_CALL_RESULT` for browser-owned tools so the client can resolve them.
+
 ## Provider choices
 
 Use `provideAgent()` when you have a real AG-UI HTTP endpoint.
@@ -188,9 +196,10 @@ The AG-UI adapter currently covers:
 - Tool calls from `TOOL_CALL_*`.
 - Shared state from `STATE_SNAPSHOT` and `STATE_DELTA`.
 - Message replacement from `MESSAGES_SNAPSHOT`.
-- Custom events from `CUSTOM`.
+- Custom events from non-`on_interrupt` `CUSTOM` events, surfaced through both `events$` and `customEvents`.
 - Interrupts from `CUSTOM` events named `on_interrupt`.
-- Subagent/activity progress from `ACTIVITY_SNAPSHOT` and `ACTIVITY_DELTA`.
+- Browser client tools via `AgUiAgent.clientTools`.
+- Subagent progress from `ACTIVITY_SNAPSHOT` and `ACTIVITY_DELTA` events whose `activityType` is `subagent`.
 - Citations stored under `state.citations`.
 
 These features are intentionally out of scope for the AG-UI adapter today:

apps/website/content/docs/ag-ui/getting-started/installation.mdx

@@ -9,10 +9,11 @@
 ## Install packages
 
 ```bash
-npm install @threadplane/chat @threadplane/ag-ui @ag-ui/client @ag-ui/core
+npm install @threadplane/chat @threadplane/ag-ui @ag-ui/client @ag-ui/core marked
 ```
 
 `@threadplane/chat` provides the chat UI primitives. `@threadplane/ag-ui` provides the adapter that wires an AG-UI backend into the `Agent` contract those primitives consume.
+`marked` is the required markdown parser peer used by `@threadplane/chat` when assistant messages render through `<chat>`.
 
 ## Peer Dependencies