fix(langgraph): lifecycle token, error kind, root registry, required interrupt, awaitable mock transport (#1054)

* feat(langgraph): provide AGENT_LIFECYCLE and warn on ambiguous ref-less injects

`AGENT_LIFECYCLE` was exported but never provided, so `inject(AGENT_LIFECYCLE)`
threw NG0201 unless the app wired the token itself. Both forms of
`provideAgent()` now provide it, resolving to the same object as
`injectAgent().lifecycle`.

The ref form also warns in development mode when several `provideAgent(ref, …)`
calls share an injector level and the ambiguous ref-less token is resolved: the
message names every competing ref and the one that won. Injecting by ref stays
silent, and production builds never log.

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

* fix(langgraph): carry the AgentErrorKind on streamErrorAt instead of the class name

`streamErrorAt().classification` stored `error.name`. The bridge normalizes
every failure through `toAgentError()` first, so the field was the literal
'AgentError' on every real stream error — useless as a discriminator.

The field is renamed to `kind` and now carries the `AgentErrorKind`
(`connection` | `auth` | `server` | `interrupted` | `aborted`), the same value
`agent.error()?.kind` carries. A failure that slipped past normalization still
falls back to a constructor name, so the type is `AgentErrorKind | string`.

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

* fix(langgraph): make AgentLifecycleRegistry root-provided so registration is not construction-ordered

The agent injected the registry optionally at construction, so a registry
provided below the agent's injector — or provided after the agent was built —
collected nothing. The registry is now `providedIn: 'root'`: every agent
registers into the same instance regardless of which injector built it, and an
agent created in a route or component injector is visible from the root.

Registration is also scoped to the agent's lifetime — an agent unregisters when
its injector is destroyed — so `lifecycles()` no longer accumulates dead agents.
`provideCockpitTelemetry()` stops re-providing the class, which would have
shadowed the instance agents register into.

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

* fix(langgraph): declare interrupt as required on LangGraphAgent

`interrupt` is optional on the runtime-neutral `Agent` contract because a
runtime without human-in-the-loop support omits it, which meant
`injectAgent().interrupt()` did not compile under `strictNullChecks` even
though the LangGraph adapter always provides it. `LangGraphAgent` now narrows
it to a required `Signal<AgentInterrupt | undefined>`; the chat contract is
untouched.

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

* feat(langgraph): make MockAgentTransport emit/emitError/close awaitable, add flush()

`stream()` is an async generator, so `emit()` only woke the suspended loop and
nothing had reached the signals when it returned. Every spec paid for that with
a hand-rolled `await new Promise(r => setTimeout(r, 0))`.

`emit()`, `emitError()` and `close()` now return a promise that settles once the
generator has drained everything queued at the time of the call (or the run has
ended), plus one macrotask so signal writes have landed. `flush()` waits the
same way without emitting. An emit after the run finished resolves instead of
hanging.

The langgraph specs that hand-rolled the macrotask flush after an emit are
converted to `await transport.emit(...)`; removing the await makes them fail, so
the await is load-bearing. Throttle waits (16 ms and up) are left alone.

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

* docs(langgraph): describe the lifecycle token, root registry, error kind, required interrupt, and awaitable transport

- lifecycle: `kind` replaces `classification` and holds the `AgentErrorKind`;
  the registry is root-provided and unregisters on destroy; `AGENT_LIFECYCLE`
  comes from `provideAgent()` and follows the last-ref-wins rule.
- provide-agent: documents the `AGENT_LIFECYCLE` token and the dev-mode warning
  on an ambiguous ref-less inject.
- testing and mock-stream-transport: every emit is awaited rather than chased
  with a macrotask flush; `flush()` is documented; `chat.interrupt()` drops the
  `?.` now that `LangGraphAgent` requires it. Both pages' spec fences were
  executed verbatim against the adapter and pass; the transport page's first
  fence was additionally missing the optimistic user message in its assertion.
- agent-contract and introduction: the narrowed `interrupt`, and the corrected
  lifecycle/registry facts.

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

* fix(examples): drop the dead interrupt existence guard in the demo shell

LangGraphAgent.interrupt is now a required member, so `agent.interrupt &&`
is always true and the packaged-consumer build rejects it with TS2774.
The call itself still returns AgentInterrupt | undefined, so the remaining
`agent.interrupt()` test is the real condition.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

---------

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

Author: blove

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

@@ -2,14 +2,14 @@
   {
     "name": "AgentLifecycleRegistry",
     "kind": "class",
-    "description": "Optional registry that collects per-instance agent lifecycles within\nan Angular injection context. External instrumentation packages\n(e.g. cockpit-telemetry) provide this token and read from it.\n\n`@threadplane/langgraph` does NOT provide this itself — the configured agent\ninstance writes to the registry only when an external consumer has provided it.",
+    "description": "Application-wide registry of every live agent's AgentLifecycle.\n\nIt is `providedIn: 'root'`, so it always exists and every agent registers\ninto the same instance regardless of which injector built it — an agent\ncreated in a route or component injector is still visible from the root.\nExternal instrumentation packages read `lifecycles()` to observe every agent\nin the application without owning the provider graph.\n\nRegistration is scoped to the agent's lifetime: an agent unregisters when the\ninjector that created it is destroyed, so `lifecycles()` never accumulates\nlifecycles for agents that are gone.",
     "params": [],
     "examples": [],
     "properties": [
       {
         "name": "lifecycles",
         "type": "Signal<readonly AgentLifecycle[]>",
-        "description": "Reactive list of registered lifecycles.",
+        "description": "Reactive list of the lifecycles of every currently live agent.",
         "optional": false
       }
     ],
@@ -26,6 +26,19 @@
             "optional": false
           }
         ]
+      },
+      {
+        "name": "unregister",
+        "signature": "unregister(lifecycle: AgentLifecycle): void",
+        "description": "Drop a lifecycle when its agent's injector is destroyed.",
+        "params": [
+          {
+            "name": "lifecycle",
+            "type": "AgentLifecycle",
+            "description": "",
+            "optional": false
+          }
+        ]
       }
     ]
   },
@@ -563,7 +576,7 @@
   {
     "name": "MockAgentTransport",
     "kind": "class",
-    "description": "Test transport for deterministic agent testing without a real LangGraph server.\n\nScript event batches upfront, then emit them manually or step through them\nin your test specs. Supports error injection and close control.",
+    "description": "Test transport for deterministic agent testing without a real LangGraph server.\n\nScript event batches upfront, then emit them manually or step through them\nin your test specs. Supports error injection and close control.\n\n`emit()`, `emitError()`, `close()` and `flush()` are awaitable: the returned\npromise settles once the adapter has consumed everything queued so far (and\none macrotask later, so throttled signal writes have landed), which removes\nthe hand-rolled `await new Promise(resolve => setTimeout(resolve, 0))` flush\nfrom specs.",
     "params": [
       {
         "name": "script",
@@ -573,7 +586,7 @@
       }
     ],
     "examples": [
-      "```typescript\nconst transport = new MockAgentTransport([\n  [{ type: 'values', messages: [aiMsg('Hello')] }],\n  [{ type: 'values', messages: [aiMsg('Done')] }],\n]);\n```"
+      "```typescript\nconst transport = new MockAgentTransport([\n  [{ type: 'values', messages: [aiMsg('Hello')] }],\n  [{ type: 'values', messages: [aiMsg('Done')] }],\n]);\nawait transport.emit(transport.nextBatch());\n```"
     ],
     "properties": [
       {
@@ -641,8 +654,8 @@
       },
       {
         "name": "close",
-        "signature": "close(): void",
-        "description": "Close the stream. Remaining queued events are drained before completion.",
+        "signature": "close(): Promise<void>",
+        "description": "Close the stream. Remaining queued events are drained before completion.\nResolves once the run has finished.",
         "params": []
       },
       {
@@ -684,8 +697,8 @@
       },
       {
         "name": "emit",
-        "signature": "emit(events: StreamEvent[]): void",
-        "description": "Manually emit events into the stream.",
+        "signature": "emit(events: StreamEvent[]): Promise<void>",
+        "description": "Manually emit events into the stream.\n\nAwait the returned promise: it resolves once the adapter has pulled this\nbatch out of the stream (or the run has ended), so signals are settled and\nassertions read live state rather than the value from before the emit.",
         "params": [
           {
             "name": "events",
@@ -697,8 +710,8 @@
       },
       {
         "name": "emitError",
-        "signature": "emitError(err: Error): void",
-        "description": "Inject an error into the stream.",
+        "signature": "emitError(err: Error): Promise<void>",
+        "description": "Inject an error into the stream. Resolves once the stream has thrown.",
         "params": [
           {
             "name": "err",
@@ -708,6 +721,12 @@
           }
         ]
       },
+      {
+        "name": "flush",
+        "signature": "flush(): Promise<void>",
+        "description": "Resolve once everything emitted so far has been consumed, without emitting\nanything new. Useful after driving the agent by some other route (a\n`submit()`, a `switchThread()`) that has to reach the transport first.",
+        "params": []
+      },
       {
         "name": "getHistory",
         "signature": "getHistory(threadId: string, signal: AbortSignal): Promise<ThreadState<DefaultValues>[]>",
@@ -975,7 +994,7 @@
       {
         "name": "streamErrorAt",
         "type": "Signal<object | null>",
-        "description": "Epoch ms + classification of the most recent stream error. Resets on switchThread().",
+        "description": "Epoch ms + failure class of the most recent stream error. Resets on switchThread().\n\n`kind` is the AgentErrorKind of the normalized `AgentError`\n(`connection` | `auth` | `server` | `interrupted` | `aborted`) — the same\nvalue `agent.error()?.kind` carries. For a failure the runtime could not\nnormalize it falls back to the error's constructor name.",
         "optional": false
       },
       {
@@ -1512,8 +1531,8 @@
       {
         "name": "interrupt",
         "type": "Signal<AgentInterrupt | undefined>",
-        "description": "",
-        "optional": true
+        "description": "Current human-in-the-loop pause, or `undefined` when the run is not paused.\n\nNarrowed from the neutral `Agent` contract, where `interrupt` is optional\nbecause a runtime without human-in-the-loop support omits it. The LangGraph\nadapter always provides it, so `injectAgent().interrupt()` type-checks\ndirectly under `strictNullChecks` — no `?.()` needed.",
+        "optional": false
       },
       {
         "name": "isLoading",
@@ -1946,7 +1965,7 @@
       {
         "name": "interrupt",
         "type": "WritableSignal<AgentInterrupt | undefined>",
-        "description": "",
+        "description": "Current human-in-the-loop pause, or `undefined` when the run is not paused.\n\nNarrowed from the neutral `Agent` contract, where `interrupt` is optional\nbecause a runtime without human-in-the-loop support omits it. The LangGraph\nadapter always provides it, so `injectAgent().interrupt()` type-checks\ndirectly under `strictNullChecks` — no `?.()` needed.",
         "optional": false
       },
       {
@@ -2499,7 +2518,7 @@
   {
     "name": "provideAgent",
     "kind": "function",
-    "description": "Wire the LangGraph adapter into Angular's dependency injection.\n\nRegisters a singleton `LangGraphAgent` constructed from `config`. Retrieve it\nin any component with `injectAgent()`. Provide this at the application root\n(`app.config.ts`) for an app-wide agent.\n\nTo use a different agent in a component subtree, re-provide\n`provideAgent({...})` in that component's `providers: []` array —\nAngular's hierarchical DI scopes the singleton accordingly.\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, route params, or\ncomponent-scoped signals.\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 from its own config, so two (or more) refs may be\nprovided side by side in a single `providers` array and `injectAgent(refA)`\n/ `injectAgent(refB)` return distinct agents. The ref-less `injectAgent()`\nresolves a single shared token, which can only point at one of them: when\nmore than one ref is provided at the same level the **last** call wins.\nAlways inject by ref when an injector provides more than one agent.",
+    "description": "Wire the LangGraph adapter into Angular's dependency injection.\n\nRegisters a singleton `LangGraphAgent` constructed from `config`. Retrieve it\nin any component with `injectAgent()`. Provide this at the application root\n(`app.config.ts`) for an app-wide agent.\n\nTo use a different agent in a component subtree, re-provide\n`provideAgent({...})` in that component's `providers: []` array —\nAngular's hierarchical DI scopes the singleton accordingly.\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, route params, or\ncomponent-scoped signals.\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 from its own config, so two (or more) refs may be\nprovided side by side in a single `providers` array and `injectAgent(refA)`\n/ `injectAgent(refB)` return distinct agents. The ref-less `injectAgent()`\nresolves a single shared token, which can only point at one of them: when\nmore than one ref is provided at the same level the **last** call wins, and\nresolving it in dev mode logs a `console.warn` naming every competing ref.\nThe `AGENT_LIFECYCLE` token follows the same rule. Always inject by ref when\nan injector provides more than one agent.\n\n**Lifecycle token.** Every form also provides `AGENT_LIFECYCLE`, so\n`inject(AGENT_LIFECYCLE)` returns the same object as `injectAgent().lifecycle`\nwithout reaching for the agent itself.",
     "signature": "provideAgent(ref: AgentRef<T>, configOrFactory: AgentConfig<T, BagTemplate> | () => AgentConfig<T>): Provider[]",
     "params": [
       {

apps/website/content/docs/langgraph/api/mock-stream-transport.mdx

@@ -48,17 +48,20 @@ describe('ChatComponent', () => {
     fixture.detectChanges();
 
     const stream = fixture.componentInstance.chat.submit({ message: 'Hello' });
-    transport.emit([
+    await transport.emit([
       {
         type: 'values',
         messages: [{ type: 'ai', content: 'Hi there' }],
       },
     ]);
-    transport.close();
+    await transport.close();
     await stream;
     fixture.detectChanges();
 
+    // submit() appends the user message optimistically, so the streamed
+    // assistant reply is the last entry, not the only one.
     expect(fixture.componentInstance.chat.messages()).toEqual([
+      expect.objectContaining({ role: 'user', content: 'Hello' }),
       expect.objectContaining({ role: 'assistant', content: 'Hi there' }),
     ]);
     expect(fixture.componentInstance.chat.status()).toBe('idle');
@@ -69,7 +72,7 @@ describe('ChatComponent', () => {
     fixture.detectChanges();
 
     const stream = fixture.componentInstance.chat.submit({ message: 'Hello' });
-    transport.emitError(new Error('not found'));
+    await transport.emitError(new Error('not found'));
     await stream;
     fixture.detectChanges();
 
@@ -85,9 +88,10 @@ describe('ChatComponent', () => {
 |--------|-------------|
 | `constructor(script?: StreamEvent[][])` | Optionally seeds scripted event batches for manual stepping (defaults to `[]`). |
 | `nextBatch()` | Returns the next scripted event batch. |
-| `emit(events)` | Pushes one or more `StreamEvent` objects into the active stream. |
-| `emitError(err)` | Makes the active stream reject with `err`. The runtime catches it, so `submit()` still resolves — assert on `status()` and `error()` instead of on a rejected promise. |
-| `close()` | Closes the active stream after queued events drain. |
+| `emit(events)` | Pushes one or more `StreamEvent` objects into the active stream. Returns a promise that resolves once the adapter has consumed the batch. |
+| `emitError(err)` | Makes the active stream reject with `err`. The runtime catches it, so `submit()` still resolves — assert on `status()` and `error()` instead of on a rejected promise. Returns a promise that resolves once the stream has thrown. |
+| `close()` | Closes the active stream after queued events drain. Returns a promise that resolves once the run has finished. |
+| `flush()` | Resolves once everything emitted so far has been consumed, without emitting anything new. |
 | `isStreaming()` | Returns whether a stream is currently active. |
 
 Messages inside a `values` event are raw LangGraph messages, so their role comes from `type` (`'human'`, `'ai'`, `'tool'`, `'system'`), not from a `role` field. The projector reads `_getType()` or the raw `type` and falls back to `'ai'`; a `role` key is never read.
@@ -99,6 +103,15 @@ The transport also records calls in `streams`, `createdQueuedRuns`, `cancelledRu
   or `close()`. This makes stream state and payload assertions deterministic.
 </Callout>
 
+<Callout type="warning" title="Await every emit">
+  `emit()`, `emitError()`, `close()` and `flush()` are asynchronous. `stream()`
+  is an async generator, so nothing has reached the signals at the moment
+  `emit()` returns. Await the promise before asserting — a spec that reads
+  signals synchronously after an emit reads stale state and passes or fails for
+  the wrong reason. `flush()` covers the same wait when the agent was driven by
+  something other than an emit.
+</Callout>
+
 ## What's Next
 
 <CardGroup cols={3}>

apps/website/content/docs/langgraph/api/provide-agent.mdx

@@ -82,7 +82,7 @@ provideAgent({
 const chat = injectAgent();
 ```
 
-Several agents may also coexist at one injector level. Each `provideAgent(ref, …)` call builds its own agent from its own config, so `injectAgent(refA)` and `injectAgent(refB)` return distinct instances. The ref-less `injectAgent()` resolves a single shared token, which can only point at one of them — the last ref-form call at that level wins. Always inject by ref when an injector provides more than one agent.
+Several agents may also coexist at one injector level. Each `provideAgent(ref, …)` call builds its own agent from its own config, so `injectAgent(refA)` and `injectAgent(refB)` return distinct instances. The ref-less `injectAgent()` resolves a single shared token, which can only point at one of them — the last ref-form call at that level wins, and resolving it in development mode logs a warning naming every competing ref. Always inject by ref when an injector provides more than one agent.
 
 ```ts
 export const LIVE = createAgentRef<ChatState>('live');
@@ -95,6 +95,23 @@ providers: [
 // injectAgent(LIVE) !== injectAgent(REPLAY)
 ```
 
+<Callout type="warning" title="Dev-mode warning on an ambiguous ref-less inject">
+In development mode, resolving the ref-less token while several refs share the injector level logs a `console.warn` naming every competing ref and the one that won. It fires only on the ambiguous path: `injectAgent(LIVE)` and `injectAgent(REPLAY)` are unambiguous and stay silent. Production builds never log it.
+</Callout>
+
+## The `AGENT_LIFECYCLE` token
+
+Every form of `provideAgent()` also provides `AGENT_LIFECYCLE`, so instrumentation can read an agent's [lifecycle signals](/docs/langgraph/guides/lifecycle) without depending on the agent itself:
+
+```ts
+import { inject } from '@angular/core';
+import { AGENT_LIFECYCLE } from '@threadplane/langgraph';
+
+const lifecycle = inject(AGENT_LIFECYCLE); // === injectAgent().lifecycle
+```
+
+The token follows the same last-one-wins rule as the ref-less `injectAgent()`: with several refs at one injector level it resolves the last ref's lifecycle. Read `injectAgent(ref).lifecycle` instead when that is the case.
+
 ## Transcript node filtering
 
 LangGraph streams `messages-tuple` chunks for every LLM node in a run. If your graph has side-effect LLM nodes, such as a title generator or evaluator, set `transcriptNodeNames` so only your conversational node updates `messages()`.

apps/website/content/docs/langgraph/concepts/agent-contract.mdx

@@ -136,7 +136,9 @@ The UI lifecycle is intentionally boring — and boring is the goal.
 5. `stop()` aborts the active run when supported, and `retry()` clears `error()` and re-runs the last submitted input after a failure.
 6. `regenerate(index)` rolls back from an assistant message and reruns from the preceding user message.
 
-LangGraph adds deeper lifecycle and history surfaces. `@threadplane/langgraph` exposes `injectAgent().lifecycle` and exports `AgentLifecycle`, `AgentLifecycleRegistry`, and the low-level `AGENT_LIFECYCLE` token. Those are useful for telemetry, debugging, persistence, and time-travel UI. They are not required by `@threadplane/chat`.
+LangGraph adds deeper lifecycle and history surfaces. `@threadplane/langgraph` exposes `injectAgent().lifecycle`, provides the `AGENT_LIFECYCLE` token from every `provideAgent()` call, and ships a root-provided `AgentLifecycleRegistry` that collects the lifecycle of every live agent. Those are useful for telemetry, debugging, persistence, and time-travel UI. They are not required by `@threadplane/chat`. See [Agent lifecycle signals](/docs/langgraph/guides/lifecycle).
+
+`LangGraphAgent` also narrows one optional member of the neutral contract: `interrupt` is required, because the LangGraph adapter always provides it. Code written against `LangGraphAgent` calls `agent.interrupt()` directly; code written against the neutral `Agent` still needs `interrupt?.()`.
 
 ## Testing And Mocks
 

apps/website/content/docs/langgraph/getting-started/introduction.mdx

@@ -40,7 +40,7 @@ chat.messages();         // Message[]
 chat.status();           // 'idle' | 'running' | 'error'
 chat.isLoading();        // boolean
 chat.error();            // AgentError | undefined
-chat.interrupt?.();      // AgentInterrupt | undefined
+chat.interrupt();        // AgentInterrupt | undefined
 chat.history();          // AgentCheckpoint[]
 chat.langGraphHistory(); // ThreadState[]
 ```