fix(cockpit-langgraph): make the subgraphs example demonstrate real nesting (#838)

The `cockpit/langgraph/subgraphs` example advertised subagent delegation it
could never perform. `app.config.ts` set no `subagentToolNames`, and the graph
added a compiled subgraph as a plain node — which emits a `research:<uuid>`
namespace, not `tools:<id>`. The SubagentTracker only registers delegation
tool calls, so `agent.subagents()` was permanently empty and the sidebar always
rendered "No active subagents". The manual e2e asserted exactly that empty
state and nothing else. The parent's edges were unconditional, so nothing
decided anything, and both graphs were bare `MessagesState` with no boundary.

Kept the plain subgraph-as-node pattern rather than converting to the tool-call
path: `cockpit/chat/subagents` already demonstrates tool-call delegation end to
end, and this is the repo's only example of LangGraph's actual composition
primitive. The website docs already state the rule
(docs/langgraph/guides/subgraphs.mdx:114 — "Plain subgraph nodes do not appear
in this map"); the example now agrees with them instead of contradicting them.

Backend:
- `orchestrate` makes a structured routing decision; a conditional edge enters
  the child graph or skips straight to `answer`.
- The child's state (`ResearchState`) has no `messages` key, so it exchanges
  only `research_topic` / `research_brief` with the parent and can neither read
  nor append to the transcript.
- `answer` is the sole transcript-writing node.

Frontend:
- Sidebar reads the parent's own state via a typed `agent.value()` instead of
  the map that can never fill, and says plainly why.
- `transcriptNodeNames: ['answer']`. Verified live: without it the message list
  transiently grows to 3 as the child's tokens merge in and its internal brief
  renders as a chat bubble, before the parent's `values` event collapses it
  back to 2. Self-correcting end state, so no final-state assertion catches it.

Tests: three e2e specs replacing the smoke test — the research branch populates
the sidebar, the child's brief never reaches the transcript (paired with a
positive sidebar assertion so it can't pass vacuously), and the direct branch
skips the child and still answers. The manual live-LLM spec asserts the branch
that ran rather than an empty state.

Verified: e2e 3/3 green; production build green; both branches driven against a
real model in Chrome, with the transcript boundary checked from the live DOM.

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

Author: blove

cockpit/langgraph/subgraphs/angular/e2e/fixtures/subgraphs.json

@@ -1,12 +1,40 @@
 {
   "fixtures": [
     {
-      "match": {
-        "userMessage": "Hello"
-      },
+      "match": { "responseFormat": "json_schema", "userMessage": "LangGraph checkpointing" },
       "response": {
-        "content": "Hello \u2014 nice to meet you. What would you like help with today?\n\nTell me the specific question or topic and any preferences (depth: quick summary vs deep dive, date range, types of sources, format: bullet list, tutorial, pros/cons, citations). Example: \u201cCompare CRISPR vs base editors for somatic therapy, include clinical trials since 2020 and cite sources.\u201d\n\nOnce you reply I\u2019ll prepare and run a focused research query and return the findings."
+        "content": {
+          "needs_research": true,
+          "topic": "LangGraph checkpointing: what a checkpointer persists and when"
+        }
+      }
+    },
+    {
+      "match": { "responseFormat": "json_schema", "userMessage": "what can you do" },
+      "response": {
+        "content": {
+          "needs_research": false,
+          "topic": ""
+        }
+      }
+    },
+    {
+      "match": { "systemMessage": "Research Subgraph", "userMessage": "LangGraph checkpointing" },
+      "response": {
+        "content": "- A checkpointer writes one state snapshot per super-step.\n- Snapshots are keyed by thread_id, so each conversation replays independently.\n- Interrupts resume from the snapshot taken immediately before the pause.\n- InMemorySaver is for development; Postgres and SQLite savers persist across restarts."
+      }
+    },
+    {
+      "match": { "systemMessage": "Orchestrator Agent", "userMessage": "LangGraph checkpointing" },
+      "response": {
+        "content": "Checkpointing saves your graph's state as it runs, so a conversation can pause and pick up exactly where it left off. Each thread gets its own history, and durable savers keep it around across restarts."
+      }
+    },
+    {
+      "match": { "systemMessage": "Orchestrator Agent", "userMessage": "what can you do" },
+      "response": {
+        "content": "Hi! I answer questions, and when one needs a factual deep dive I hand the topic to a research subgraph before replying. Ask me something specific and you'll see it happen."
       }
     }
   ]
-}
+}

cockpit/langgraph/subgraphs/angular/e2e/manual/subgraphs.manual.ts

@@ -1,21 +1,45 @@
+// SPDX-License-Identifier: MIT
+//
+// Manual (live-LLM) counterpart to subgraphs.spec.ts. Run against a real
+// OpenAI key with the example served on its cockpit port — the routing
+// decision is a genuine model call here, so assertions check the branch that
+// actually ran rather than baking in a fixture's answer.
 import { expect, test } from '@playwright/test';
 
-test.describe('LangGraph Subgraphs Example', () => {
+test.describe('LangGraph Subgraphs Example (live)', () => {
   test.beforeEach(async ({ page }) => {
     await page.goto('http://localhost:4305');
     await page.waitForSelector('app-subgraphs', { state: 'attached' });
   });
 
-  test('renders the chat interface with subagent sidebar', async ({ page }) => {
-    await expect(page.locator('chat')).toBeVisible();
-    await expect(page.locator('textarea[name="messageText"]')).toBeVisible();
-    await expect(page.locator('text=No active subagents')).toBeVisible();
+  test('a research question routes into the child graph', async ({ page }) => {
+    await page.fill('textarea[name="messageText"]', 'How does LangGraph checkpointing work?');
+    await page.click('button[type="submit"]');
+
+    const panel = page.getByTestId('subgraph-panel');
+    await expect(panel.getByTestId('route')).toContainText('Nested', { timeout: 60_000 });
+    await expect(panel.getByTestId('research-topic')).not.toBeEmpty({ timeout: 60_000 });
+    await expect(panel.getByTestId('research-brief')).not.toBeEmpty({ timeout: 60_000 });
+
+    const assistant = page
+      .locator('chat-message[data-role="assistant"][data-streaming="false"]')
+      .last();
+    await expect(assistant).toBeAttached({ timeout: 60_000 });
+    await expect(assistant.locator('.chat-md')).not.toBeEmpty();
   });
 
-  test('sends a message and receives a response', async ({ page }) => {
-    await page.fill('textarea[name="messageText"]', 'hello');
+  test('a greeting skips the child graph', async ({ page }) => {
+    await page.fill('textarea[name="messageText"]', 'hi there');
     await page.click('button[type="submit"]');
-    await expect(page.locator('.chat-md').first()).toBeVisible({ timeout: 30000 });
-    await expect(page.locator('.chat-md').first()).not.toBeEmpty({ timeout: 30000 });
+
+    const assistant = page
+      .locator('chat-message[data-role="assistant"][data-streaming="false"]')
+      .last();
+    await expect(assistant).toBeAttached({ timeout: 60_000 });
+    await expect(assistant.locator('.chat-md')).not.toBeEmpty();
+
+    const panel = page.getByTestId('subgraph-panel');
+    await expect(panel.getByTestId('route')).toContainText('Direct');
+    await expect(panel.getByTestId('research-brief')).toHaveCount(0);
   });
 });

cockpit/langgraph/subgraphs/angular/e2e/subgraphs.spec.ts

@@ -1,10 +1,58 @@
 // SPDX-License-Identifier: MIT
 import { test, expect } from '@playwright/test';
-import { submitAndWaitForResponse } from '@threadplane-internal/e2e-harness';
 
-test('subgraphs: hello prompt produces assistant turn', async ({ page }) => {
-  const bubble = await submitAndWaitForResponse(page, 'Hello');
-  // Smoke: backend booted, aimock replayed fixture, assistant bubble
-  // finalized (data-streaming="false") and is present in the DOM.
-  await expect(bubble).toBeVisible();
+// Distinctive line from the research subgraph's brief. It exists only in the
+// child graph's `research_brief` output, never in the parent's answer — which
+// is what makes it usable as a probe for the state boundary.
+const BRIEF_MARKER = 'one state snapshot per super-step';
+
+test.describe('cockpit subgraphs: conditional nesting', () => {
+  test('a research question routes into the child graph and shows its brief', async ({ page }) => {
+    await page.goto('/');
+    await page.getByText('Ask something that needs research').click();
+
+    const finalAssistant = page
+      .locator('chat-message[data-role="assistant"][data-streaming="false"]')
+      .last();
+    await expect(finalAssistant).toBeAttached({ timeout: 30_000 });
+
+    const panel = page.getByTestId('subgraph-panel');
+    await expect(panel.getByTestId('route')).toContainText('Nested');
+    await expect(panel.getByTestId('research-topic')).toContainText('checkpointer persists');
+    await expect(panel.getByTestId('research-brief')).toContainText(BRIEF_MARKER);
+    await expect(finalAssistant).toContainText('Checkpointing saves');
+  });
+
+  test("the child's brief never reaches the transcript", async ({ page }) => {
+    await page.goto('/');
+    await page.getByText('Ask something that needs research').click();
+
+    // Sidebar has it (proves the assertion below is not vacuous — the brief
+    // was produced and delivered, it just went somewhere the transcript isn't).
+    await expect(page.getByTestId('research-brief')).toContainText(BRIEF_MARKER, {
+      timeout: 30_000,
+    });
+    await expect(
+      page.locator('chat-message[data-role="assistant"][data-streaming="false"]').last(),
+    ).toBeAttached({ timeout: 30_000 });
+
+    // Scan every rendered message, not just the last one.
+    await expect(page.locator('chat-message').filter({ hasText: BRIEF_MARKER })).toHaveCount(0);
+    await expect(page.locator('chat-message')).toHaveCount(2); // the ask + the parent's answer
+  });
+
+  test('a greeting skips the child graph and still answers', async ({ page }) => {
+    await page.goto('/');
+    await page.getByText('Ask something that does not').click();
+
+    const finalAssistant = page
+      .locator('chat-message[data-role="assistant"][data-streaming="false"]')
+      .last();
+    await expect(finalAssistant).toBeAttached({ timeout: 30_000 });
+    await expect(finalAssistant).toContainText('I answer questions');
+
+    const panel = page.getByTestId('subgraph-panel');
+    await expect(panel.getByTestId('route')).toContainText('Direct');
+    await expect(panel.getByTestId('research-brief')).toHaveCount(0);
+  });
 });

cockpit/langgraph/subgraphs/angular/prompts/subgraphs.md

@@ -1,5 +1,20 @@
 # LangGraph Subgraphs (Angular)
 
-This capability demonstrates composing LangGraph subgraphs — independent graphs invoked as nodes inside a parent graph — using the `@threadplane/chat` Angular component library. The `<chat-subagent-card>` renders a live status card for each active subgraph invocation, letting the user see which specialised agent is running and what it has produced.
+This capability demonstrates LangGraph subgraph composition — a compiled child
+graph added to a parent graph as a plain node — rendered with the
+`@threadplane/chat` Angular component library.
 
-Key components used: `<chat>`, `<chat-subagent-card>`. Cards appear in the message feed as the parent graph delegates work to subgraphs; each card shows the subgraph name, its streamed output, and a completion badge when the subgraph finishes.
+The parent orchestrator routes conditionally: requests that need a factual
+deep dive enter the `research` child graph first, everything else answers
+directly. The child graph's state has no `messages` key, so it exchanges only
+`research_topic` and `research_brief` with the parent and never touches the
+transcript.
+
+The sidebar reads the parent graph's own state through `agent.value()` to show
+which branch ran and what the child returned. It deliberately does **not** use
+`agent.subagents()`: that signal is populated only by delegation *tool calls*
+(`subagentToolNames` + `subagent_type`), not by plain subgraph nodes. For that
+pattern see the Chat Subagents capability.
+
+Key components used: `<chat>`. `provideAgent({ transcriptNodeNames: ['answer'] })`
+keeps the router's and the subgraph's tokens out of the chat transcript.

cockpit/langgraph/subgraphs/angular/src/app/agent-ref.ts

@@ -0,0 +1,24 @@
+// SPDX-License-Identifier: MIT
+import { createAgentRef } from '@threadplane/chat';
+
+/**
+ * Parent graph state for the subgraphs cockpit.
+ *
+ * `research_topic` and `research_brief` are the two keys the parent shares
+ * with the compiled child graph — writing a topic is what routes execution
+ * into the subgraph, and the brief is what comes back out. The child's own
+ * state has no `messages` key, which is why nothing it produces reaches the
+ * transcript.
+ */
+export interface SubgraphsState {
+  messages: unknown[];
+  research_topic: string;
+  research_brief: string;
+}
+
+/**
+ * Typed DI handle for the subgraphs agent.
+ * Wire with `provideAgent(SUBGRAPHS_AGENT, { ... })` and inject with
+ * `injectAgent(SUBGRAPHS_AGENT)` to get `LangGraphAgent<SubgraphsState>`.
+ */
+export const SUBGRAPHS_AGENT = createAgentRef<SubgraphsState>('subgraphs');

cockpit/langgraph/subgraphs/angular/src/app/app.config.ts

@@ -3,12 +3,25 @@ import { ApplicationConfig } from '@angular/core';
 import { provideAgent } from '@threadplane/langgraph';
 import { provideChat } from '@threadplane/chat';
 import { environment } from '../environments/environment';
+import { SUBGRAPHS_AGENT } from './agent-ref';
 
 export const appConfig: ApplicationConfig = {
   providers: [
-    provideAgent({
+    provideAgent(SUBGRAPHS_AGENT, {
       apiUrl: environment.langGraphApiUrl,
       assistantId: environment.streamingAssistantId,
+      // Only the parent's `answer` node writes the user-facing turn.
+      //
+      // This is load-bearing, and its failure mode is mid-stream rather than
+      // final-state. LangGraph emits the child's tokens under a
+      // `research:<uuid>` namespace, and that namespace is NOT a subagent
+      // namespace (`tools:`), so the bridge merges those tokens into the
+      // transcript as they arrive. Verified against a live model: without
+      // this option the message list transiently grows to 3 — the child's
+      // internal brief renders as its own chat bubble — before the parent's
+      // authoritative `values` event collapses it back to 2. Because the end
+      // state self-corrects, a final-state e2e assertion cannot catch it.
+      transcriptNodeNames: ['answer'],
     }),
     provideChat({}),
   ],