feat(ag-ui): scriptable provideFakeAgent() and a duplicate-AgentRef warning (#1053)

* feat(ag-ui): warn in development when several AgentRefs share an injector

The ref form of provideAgent() aliases the shared AGENT token, so N refs at
one injector level leave the ref-less injectAgent() pointing at the Nth with
no signal. Each ref-form call now also contributes its debug name to an
internal multi token; the first agent built at that level reads the list and,
in development mode only, emits a single console.warn naming every ref and the
one the bare injectAgent() resolves. Multi providers do not merge across
injectors, so refs at different levels neither collide nor warn.

Behavior is otherwise unchanged: each ref still gets its own agent and its own
config evaluation.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* feat(ag-ui): let provideFakeAgent() take a FakeAgentScript

FakeAgent's script option was constructor-only and unreachable through
provideFakeAgent(), which accepted the shared FakeAgentConfig from
@threadplane/chat/testing (tokens, reasoningTokens, delayMs). provideFakeAgent()
now takes AgUiFakeAgentConfig — that shared config plus the AG-UI-only script —
and passes it to the constructor, so tool calls, state, custom events, and
interrupts are all scriptable through DI. The script shape is exported as
FakeAgentScript. The shared config type in libs/chat is untouched.

Docs updated: the api and guide pages no longer say script is constructor-only
or that provideFakeAgent() cannot emit TOOL_CALL_*, STATE_* or CUSTOM, and each
carries a fence that runs. api-docs regenerated.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>

Author: blove

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

@@ -506,6 +506,38 @@
     ],
     "examples": []
   },
+  {
+    "name": "AgUiFakeAgentConfig",
+    "kind": "interface",
+    "description": "Config accepted by provideFakeAgent: the shared `FakeAgentConfig`\n(`tokens`, `reasoningTokens`, `delayMs`) plus the AG-UI-only `script`, which\nreplaces the canned token reply with raw AG-UI events.",
+    "properties": [
+      {
+        "name": "delayMs",
+        "type": "number",
+        "description": "Milliseconds between successive token emissions.",
+        "optional": true
+      },
+      {
+        "name": "reasoningTokens",
+        "type": "string[]",
+        "description": "Optional reasoning chunks emitted before the text reply.",
+        "optional": true
+      },
+      {
+        "name": "script",
+        "type": "FakeAgentScript",
+        "description": "Deterministic event branches — see FakeAgentScript.",
+        "optional": true
+      },
+      {
+        "name": "tokens",
+        "type": "string[]",
+        "description": "Assistant reply, streamed token-by-token.",
+        "optional": true
+      }
+    ],
+    "examples": []
+  },
   {
     "name": "CustomStreamEvent",
     "kind": "interface",
@@ -546,6 +578,13 @@
     ],
     "examples": []
   },
+  {
+    "name": "FakeAgentScript",
+    "kind": "type",
+    "description": "Deterministic event branches for FakeAgent, reachable through the\nconstructor and through `provideFakeAgent({ script })`.\n\nEach branch supplies a raw AG-UI event sequence — tool calls, state\nsnapshots, custom events, anything the protocol defines. `when: 'initial'`\nmatches a turn whose history carries no tool result; `{ toolMessageFor: id }`\nmatches the follow-up turn whose history carries a tool result for that tool\ncall id. The first matching branch wins, and its `events` are wrapped in\n`RUN_STARTED` / `RUN_FINISHED`. When no branch matches, the canned token\nreply is streamed instead.",
+    "signature": "readonly { events: readonly BaseEvent[]; when: \"initial\" | { toolMessageFor: string } }[]",
+    "examples": []
+  },
   {
     "name": "bridgeCitationsState",
     "kind": "function",
@@ -590,7 +629,7 @@
   {
     "name": "provideAgent",
     "kind": "function",
-    "description": "Provides an Agent instance wired through HttpAgent and toAgent.\nConstructs an HttpAgent from config and wraps it in the runtime-neutral\nAgent contract via toAgent(). Returns a provider array suitable for\nbootstrapApplication or TestBed.configureTestingModule().\n\n**Static vs factory config.** Pass a plain `AgentConfig` object when the\nconfig is known up front. Pass a `() => AgentConfig` factory when the config\ndepends on runtime/DI state — the factory runs inside an Angular injection\ncontext, so it may call `inject()` to read services or route params.\n\n**Typed state via AgentRef.** Pass a typed ref as the first argument to flow\nthe state shape from `provideAgent` to `injectAgent` without repeating the\ngeneric at every call site.\n\n**Several agents at one injector level.** Each `provideAgent(ref, …)` call\nbuilds its own agent, so two (or more) refs may be provided side by side in a\nsingle `providers` array and `injectAgent(refA)` / `injectAgent(refB)` return\ndistinct agents. The ref-less `injectAgent()` resolves a single shared token,\nwhich can only point at one of them: when more than one ref is provided at\nthe same level the **last** call wins. Always inject by ref when an injector\nprovides more than one agent.",
+    "description": "Provides an Agent instance wired through HttpAgent and toAgent.\nConstructs an HttpAgent from config and wraps it in the runtime-neutral\nAgent contract via toAgent(). Returns a provider array suitable for\nbootstrapApplication or TestBed.configureTestingModule().\n\n**Static vs factory config.** Pass a plain `AgentConfig` object when the\nconfig is known up front. Pass a `() => AgentConfig` factory when the config\ndepends on runtime/DI state — the factory runs inside an Angular injection\ncontext, so it may call `inject()` to read services or route params.\n\n**Typed state via AgentRef.** Pass a typed ref as the first argument to flow\nthe state shape from `provideAgent` to `injectAgent` without repeating the\ngeneric at every call site.\n\n**Several agents at one injector level.** Each `provideAgent(ref, …)` call\nbuilds its own agent, so two (or more) refs may be provided side by side in a\nsingle `providers` array and `injectAgent(refA)` / `injectAgent(refB)` return\ndistinct agents. The ref-less `injectAgent()` resolves a single shared token,\nwhich can only point at one of them: when more than one ref is provided at\nthe same level the **last** call wins. Always inject by ref when an injector\nprovides more than one agent. Development builds emit a one-time\n`console.warn` naming the refs involved when an injector level registers more\nthan one, so the silent last-ref-wins aliasing is visible during development.",
     "signature": "provideAgent(ref: AgentRef<T>, configOrFactory: AgentConfig | () => AgentConfig): Provider[]",
     "params": [
       {
@@ -617,12 +656,12 @@
   {
     "name": "provideFakeAgent",
     "kind": "function",
-    "description": "Registers an in-process FakeAgent under AGENT.\n\nUse for offline demos and development. Drop-in replacement for\nprovideAgent({ url }) when no real backend is available.",
-    "signature": "provideFakeAgent(config: FakeAgentConfig): Provider[]",
+    "description": "Registers an in-process FakeAgent under AGENT.\n\nUse for offline demos and development. Drop-in replacement for\nprovideAgent({ url }) when no real backend is available.\n\nPass `script` to stream exact AG-UI events instead of the canned token\nreply — the adapter reduces them into `toolCalls()`, `state()`,\n`customEvents()`, and `interrupt()` exactly as it would real wire events.",
+    "signature": "provideFakeAgent(config: AgUiFakeAgentConfig): Provider[]",
     "params": [
       {
         "name": "config",
-        "type": "FakeAgentConfig",
+        "type": "AgUiFakeAgentConfig",
         "description": "",
         "optional": true
       }
@@ -632,7 +671,8 @@
       "description": ""
     },
     "examples": [
-      "```ts\nTestBed.configureTestingModule({\n  providers: [provideFakeAgent({ tokens: ['Hello from the fake agent'] })],\n});\n```"
+      "```ts\nTestBed.configureTestingModule({\n  providers: [provideFakeAgent({ tokens: ['Hello from the fake agent'] })],\n});\n```",
+      "```ts\nTestBed.configureTestingModule({\n  providers: [provideFakeAgent({\n    delayMs: 0,\n    script: [{\n      when: 'initial',\n      events: [\n        { type: EventType.TOOL_CALL_START, toolCallId: 't1', toolCallName: 'get_weather' },\n        { type: EventType.TOOL_CALL_ARGS, toolCallId: 't1', delta: '{\"city\":\"SF\"}' },\n        { type: EventType.TOOL_CALL_END, toolCallId: 't1' },\n      ] as BaseEvent[],\n    }],\n  })],\n});\n```"
     ]
   },
   {

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

@@ -1,5 +1,5 @@
 ---
-description: FakeAgent and provideFakeAgent() stream a canned AG-UI response in process, with an optional script of raw events for exact test streams.
+description: FakeAgent and provideFakeAgent() stream a canned AG-UI response in process, or an exact script of raw events for tool calls, state, and interrupts.
 ---
 
 # FakeAgent
@@ -22,7 +22,7 @@ bootstrapApplication(AppComponent, {
 });
 ```
 
-Pass a `FakeAgentConfig` to customize the canned response:
+Pass an `AgUiFakeAgentConfig` to customize the canned response:
 
 ```ts
 provideFakeAgent({
@@ -31,13 +31,16 @@ provideFakeAgent({
 })
 ```
 
-### FakeAgentConfig
+### AgUiFakeAgentConfig
 
 | Option | Type | Description |
 |--------|------|-------------|
 | `tokens` | `string[]` | Assistant reply streamed token-by-token. Defaults to a fixed placeholder message. |
 | `reasoningTokens` | `string[]` | Optional reasoning chunks emitted before the text reply. |
 | `delayMs` | `number` | Milliseconds between successive token emissions. Defaults to `60`. |
+| `script` | [`FakeAgentScript`](#script) | Raw AG-UI event branches that replace the canned reply. |
+
+The first three options are the shared `FakeAgentConfig` that every adapter's `provideFakeAgent()` accepts. `script` is the AG-UI-specific addition.
 
 ## FakeAgent class
 
@@ -58,20 +61,60 @@ const agent = toAgent(new FakeAgent({
 
 ### script
 
-The constructor accepts a fourth option that `FakeAgentConfig` does not carry, so it is reachable only by constructing `FakeAgent` yourself:
+`FakeAgentScript` is an exported type. Both the constructor and `provideFakeAgent()` accept it:
 
 ```ts
-script?: readonly {
+type FakeAgentScript = readonly {
   when: 'initial' | { toolMessageFor: string };
   events: readonly BaseEvent[];
 }[];
 ```
 
-Each branch supplies a raw AG-UI event sequence for tests that need an exact stream — tool calls, `STATE_SNAPSHOT`, `CUSTOM` events, anything the protocol defines. `when: 'initial'` matches the first turn; `{ toolMessageFor: id }` matches the turn whose input carries a tool result for that tool call id. The first matching branch wins, and `FakeAgent` wraps its `events` in `RUN_STARTED` and `RUN_FINISHED` for you. When no branch matches, the canned token reply is emitted instead.
+Each branch supplies a raw AG-UI event sequence for tests that need an exact stream — tool calls, `STATE_SNAPSHOT`, `CUSTOM` events, anything the protocol defines. `when: 'initial'` matches a turn whose history carries no tool result; `{ toolMessageFor: id }` matches the follow-up turn whose history carries a tool result for that tool call id, which is what a resolved client tool produces. The first matching branch wins, and `FakeAgent` wraps its `events` in `RUN_STARTED` and `RUN_FINISHED` for you. When no branch matches, the canned token reply is emitted instead.
 
-| Option | Type | Description |
-|--------|------|-------------|
-| `script` | `readonly { when: 'initial' \| { toolMessageFor: string }; events: readonly BaseEvent[] }[]` | Deterministic event branches. Constructor only — not part of `FakeAgentConfig`, so `provideFakeAgent()` cannot set it. |
+Through DI, a script reaches the reducer exactly as wire events would, so `toolCalls()`, `state()`, `customEvents()`, and `interrupt()` all populate:
+
+```ts
+import { TestBed } from '@angular/core/testing';
+import { EventType, type BaseEvent } from '@ag-ui/client';
+import { provideFakeAgent, injectAgent } from '@threadplane/ag-ui';
+
+it('reduces a scripted tool call', async () => {
+  TestBed.configureTestingModule({
+    providers: [
+      provideFakeAgent({
+        delayMs: 0,
+        script: [
+          {
+            when: 'initial',
+            events: [
+              {
+                type: EventType.TOOL_CALL_START,
+                toolCallId: 'tool-1',
+                toolCallName: 'get_weather',
+              } as BaseEvent,
+              {
+                type: EventType.TOOL_CALL_ARGS,
+                toolCallId: 'tool-1',
+                delta: '{"city":"SF"}',
+              } as BaseEvent,
+              { type: EventType.TOOL_CALL_END, toolCallId: 'tool-1' } as BaseEvent,
+            ],
+          },
+        ],
+      }),
+    ],
+  });
+
+  const agent = TestBed.runInInjectionContext(() => injectAgent());
+  await agent.submit({ message: 'weather?' });
+
+  expect(agent.toolCalls()[0]).toMatchObject({
+    name: 'get_weather',
+    args: { city: 'SF' },
+  });
+});
+```
 
 ## TestBed example
 

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

@@ -115,6 +115,18 @@ const support = injectAgent(SUPPORT); // the support agent
 
 <Callout type="warning" title="The ref-less injectAgent() resolves the last ref provided">
 The ref form also aliases the shared token so that the no-argument `injectAgent()` keeps working. That token can only point at one agent, so when several refs are provided at the same injector level the **last** `provideAgent(ref, …)` call wins. In the example above, a bare `injectAgent()` returns the support agent. Always inject by ref when an injector provides more than one agent.
+
+Development builds do not leave this silent. The first time such an injector builds one of its agents, the adapter emits a single `console.warn` naming every ref registered at that level and the one the ref-less `injectAgent()` resolves:
+
+```text
+[@threadplane/ag-ui] provideAgent() was called with more than one AgentRef at the
+same injector level (trip, support). The ref-less injectAgent() reads a single
+shared token, so it resolves the last ref provided (support) and the others are
+reachable only by ref. Inject by ref — injectAgent(ref) — when an injector
+provides more than one agent.
+```
+
+The warning is development-only (`isDevMode()`), fires once per injector, and never changes what DI hands back: each ref keeps its own agent. Refs provided at different injector levels — one in the application config, another in a component's `providers` — do not collide and do not warn.
 </Callout>
 
 With a single ref the alias is exact: one instance, one config evaluation, reachable both as `injectAgent(TRIP)` and as `injectAgent()`.

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

@@ -170,7 +170,7 @@ const trip = injectAgent(TRIP);       // AgUiAgent<TripState>
 const support = injectAgent(SUPPORT); // AgUiAgent<SupportState>
 ```
 
-The ref form also aliases the shared token that the no-argument `injectAgent()` reads. That token can only point at one agent, so when several refs are provided at the same level the **last** `provideAgent(ref, …)` call wins — inject by ref whenever an injector provides more than one agent. See [provideAgent()](/docs/ag-ui/api/provide-agent) for the full rule.
+The ref form also aliases the shared token that the no-argument `injectAgent()` reads. That token can only point at one agent, so when several refs are provided at the same level the **last** `provideAgent(ref, …)` call wins — inject by ref whenever an injector provides more than one agent. Development builds emit a one-time `console.warn` naming the refs involved when an injector level registers more than one, so the aliasing is visible while you build. See [provideAgent()](/docs/ag-ui/api/provide-agent) for the full rule.
 
 Use `provideFakeAgent()` when you need the UI to run without a backend:
 

apps/website/content/docs/ag-ui/guides/fake-agent.mdx

@@ -1,5 +1,5 @@
 ---
-description: Run the chat UI with no backend using provideFakeAgent(), what the canned stream contains, and when to construct FakeAgent with a script instead.
+description: Run the chat UI with no backend using provideFakeAgent(), what the canned stream contains, and how to script exact AG-UI events instead.
 ---
 
 # Fake Agent
@@ -97,11 +97,40 @@ That gives you the same `Agent` contract as `provideFakeAgent()`.
 | `tokens` | `string[]` | A short canned greeting | Emitted as text deltas in order. |
 | `reasoningTokens` | `string[]` | `[]` | Emitted before text deltas. |
 | `delayMs` | `number` | `60` | Delay between events after the initial start delay. |
-| `script` | `readonly { when: 'initial' \| { toolMessageFor: string }; events: readonly BaseEvent[] }[]` | `[]` | Constructor only — not part of `FakeAgentConfig`, so `provideFakeAgent()` cannot set it. Supplies a raw AG-UI event sequence per branch, wrapped in `RUN_STARTED` / `RUN_FINISHED`. |
+| `script` | `FakeAgentScript` | `[]` | Raw AG-UI event branches that replace the canned reply, each wrapped in `RUN_STARTED` / `RUN_FINISHED`. Accepted by the constructor and by `provideFakeAgent()`. |
+
+## Scripting exact events
+
+Set `script` when the canned text reply is not enough — tool calls, shared state, custom events, and interrupts all reach the UI through it, with no backend and no direct construction:
+
+```ts
+import { EventType, type BaseEvent } from '@ag-ui/client';
+import { provideFakeAgent } from '@threadplane/ag-ui';
+
+providers: [
+  provideFakeAgent({
+    delayMs: 0,
+    script: [
+      {
+        when: 'initial',
+        events: [
+          {
+            type: EventType.CUSTOM,
+            name: 'on_interrupt',
+            value: { kind: 'approval', amount: 42 },
+          } as BaseEvent,
+        ],
+      },
+    ],
+  }),
+]
+```
+
+`when: 'initial'` matches a turn whose history carries no tool result. `{ toolMessageFor: 'tool-1' }` matches the follow-up turn whose history carries a tool result for `tool-1`, which is what resolving a client tool produces — so a two-branch script plays a tool call and then the reply that follows it. The first matching branch wins; when none matches, the canned token reply streams instead.
 
 ## What it does not do
 
-`provideFakeAgent()` does not call a model, execute tools, persist history, or simulate interrupts. Constructed directly, `FakeAgent` accepts a `script` of raw AG-UI events for tests that need an exact stream, so tool calls, state, and interrupts are reachable that way.
+`provideFakeAgent()` does not call a model, execute tools, or persist history. It streams what you give it: a canned token reply by default, or the exact events in `script`.
 
 It is deliberately small. Use it to keep UI work moving, not to validate backend behavior.