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>

Author: blove

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:
 

libs/ag-ui/src/lib/provide-agent.duplicate-ref-warning.spec.ts

@@ -0,0 +1,75 @@
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { Component, inject } from '@angular/core';
+import { TestBed } from '@angular/core/testing';
+import { createAgentRef } from '@threadplane/chat';
+import { provideAgent, injectAgent } from './provide-agent';
+
+afterEach(() => {
+  TestBed.resetTestingModule();
+  vi.restoreAllMocks();
+});
+
+describe('provideAgent — several refs at one injector level', () => {
+  it('warns once, naming both refs, and still hands out distinct agents', () => {
+    const REF_A = createAgentRef<Record<string, unknown>>('alpha-agent');
+    const REF_B = createAgentRef<Record<string, unknown>>('beta-agent');
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+    TestBed.configureTestingModule({
+      providers: [
+        provideAgent(REF_A, { url: 'http://a.example/agent' }),
+        provideAgent(REF_B, { url: 'http://b.example/agent' }),
+      ],
+    });
+
+    const agentA = TestBed.runInInjectionContext(() => injectAgent(REF_A));
+    const agentB = TestBed.runInInjectionContext(() => injectAgent(REF_B));
+
+    expect(agentA).not.toBe(agentB);
+    expect(warn).toHaveBeenCalledTimes(1);
+    const message = String(warn.mock.calls[0][0]);
+    expect(message).toContain('alpha-agent');
+    expect(message).toContain('beta-agent');
+    expect(message).toContain('injectAgent()');
+    // The bare token still resolves the LAST ref provided, as the warning says.
+    expect(TestBed.runInInjectionContext(() => injectAgent())).toBe(agentB);
+    expect(warn).toHaveBeenCalledTimes(1);
+  });
+
+  it('does not warn for a single ref at a level', () => {
+    const REF = createAgentRef<Record<string, unknown>>('only-agent');
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+    TestBed.configureTestingModule({
+      providers: [provideAgent(REF, { url: 'http://single.example/agent' })],
+    });
+
+    TestBed.runInInjectionContext(() => injectAgent(REF));
+    TestBed.runInInjectionContext(() => injectAgent());
+
+    expect(warn).not.toHaveBeenCalled();
+  });
+
+  it('does not warn when refs sit at different injector levels', () => {
+    const ROOT_REF = createAgentRef<Record<string, unknown>>('root-agent');
+    const LEAF_REF = createAgentRef<Record<string, unknown>>('leaf-agent');
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+
+    @Component({
+      template: '',
+      providers: [provideAgent(LEAF_REF, { url: 'http://leaf.example/agent' })],
+    })
+    class LeafComponent {
+      readonly leaf = injectAgent(LEAF_REF);
+      readonly root = inject(ROOT_REF.token);
+    }
+
+    TestBed.configureTestingModule({
+      imports: [LeafComponent],
+      providers: [provideAgent(ROOT_REF, { url: 'http://root.example/agent' })],
+    });
+    const fixture = TestBed.createComponent(LeafComponent);
+    fixture.detectChanges();
+
+    expect(fixture.componentInstance.leaf).not.toBe(fixture.componentInstance.root);
+    expect(warn).not.toHaveBeenCalled();
+  });
+});

libs/ag-ui/src/lib/provide-agent.ts

@@ -1,4 +1,4 @@
-import { InjectionToken, inject, type Provider } from '@angular/core';
+import { InjectionToken, inject, isDevMode, type Provider } from '@angular/core';
 import { HttpAgent } from '@ag-ui/client';
 import type { AgentRef, AgentRuntimeTelemetrySink } from '@threadplane/chat';
 import { toAgent, ɵtoAgentWithProtectedErrors, type AgUiAgent } from './to-agent';
@@ -62,6 +62,39 @@ function isAgentRef<T>(x: unknown): x is AgentRef<T> {
   return typeof x === 'object' && x !== null && 'token' in x;
 }
 
+/**
+ * @internal — one entry per ref-form `provideAgent()` call, in registration
+ * order. Multi providers do not merge across injectors, so the resolved array
+ * names exactly the refs registered at the injector that resolves it.
+ */
+const AGENT_REF_DEBUG_NAMES = new InjectionToken<string[]>('AG_UI_AGENT_REF_DEBUG_NAMES');
+
+/** @internal — one warning per injector, not one per agent built there. */
+const warnedRefNameSets = new WeakSet<object>();
+
+/**
+ * @internal — development-only notice that the shared `AGENT` alias is
+ * ambiguous at this injector level. Must run inside an injection context.
+ */
+function warnOnAmbiguousSharedAlias(): void {
+  if (!isDevMode()) return;
+  const names = inject(AGENT_REF_DEBUG_NAMES, { optional: true });
+  if (names === null || names.length < 2 || warnedRefNameSets.has(names)) return;
+  warnedRefNameSets.add(names);
+  console.warn(
+    `[@threadplane/ag-ui] provideAgent() was called with more than one AgentRef at the same ` +
+      `injector level (${names.join(', ')}). The ref-less injectAgent() reads a single shared ` +
+      `token, so it resolves the last ref provided (${names[names.length - 1]}) and the others ` +
+      `are reachable only by ref. Inject by ref — injectAgent(ref) — when an injector provides ` +
+      `more than one agent.`,
+  );
+}
+
+/** @internal — the name shown in the ambiguity warning. */
+function refDebugName<T>(ref: AgentRef<T>): string {
+  return String(ref.token).replace(/^InjectionToken\s+/, '');
+}
+
 /**
  * Provides an Agent instance wired through HttpAgent and toAgent.
  * Constructs an HttpAgent from config and wraps it in the runtime-neutral
@@ -83,7 +116,9 @@ function isAgentRef<T>(x: unknown): x is AgentRef<T> {
  * distinct agents. The ref-less `injectAgent()` resolves a single shared token,
  * which can only point at one of them: when more than one ref is provided at
  * the same level the **last** call wins. Always inject by ref when an injector
- * provides more than one agent.
+ * 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 silent last-ref-wins aliasing is visible during development.
  *
  * @example Typed state via AgentRef
  * ```ts
@@ -117,7 +152,14 @@ export function provideAgent<T = Record<string, unknown>>(
   // instance, one config evaluation); with several refs AGENT can only mean one
   // thing, so the last call wins.
   return [
-    { provide: ref.token, useFactory: () => buildAgUiAgent(configOrFactory) },
+    { provide: AGENT_REF_DEBUG_NAMES, multi: true, useValue: refDebugName(ref) },
+    {
+      provide: ref.token,
+      useFactory: () => {
+        warnOnAmbiguousSharedAlias();
+        return buildAgUiAgent(configOrFactory);
+      },
+    },
     { provide: AGENT, useExisting: ref.token },
   ];
 }