fix(langgraph): harden subagent attribution — ladder tests, empty-description guard, nested-delegation streams (#945)

* test(langgraph): direct unit coverage for the subagent attribution ladder

* fix(langgraph): empty description must not exact-match at the attribution ladder's first rung

* fix(langgraph): register nested delegations as their own stream instead of corrupting the outer card

* refactor(langgraph): drop dead extractToolCallIdFromNamespace helper

* fix(langgraph): truncate nested-delegation keys at the innermost tools: segment

* test(langgraph): correct stale attribution comment in bridge spec

* docs(website): document nested-delegation stream behavior in the subgraphs guide

Author: blove

apps/website/content/docs/langgraph/guides/subgraphs.mdx

@@ -169,6 +169,8 @@ Because `ResearchState` has no `messages` key, the child cannot read the transcr
 
 The `subagents()` signal contains a Map of active child streams. Tool-dispatched children — Deep Agents' default `task` tool or your own delegation tools — are keyed by tool-call id and named by their `subagent_type`. Plain subgraph nodes are keyed by their namespace segment and named by node; they register on their first streamed event and settle with the run.
 
+Nested delegation — a subagent that itself dispatches a delegation tool — surfaces as its own entry too, keyed by its namespace path (truncated at the innermost delegation segment) and treated like a plain subgraph stream. Each level of delegation gets its own stream; the map stays flat, so there's no parent/child linking between the entries.
+
 ```typescript
 // In a shared file (e.g. agent.ts):
 // import { createAgentRef } from '@threadplane/chat';

libs/langgraph/src/lib/internals/stream-manager.bridge.spec.ts

@@ -2847,8 +2847,10 @@ describe('createStreamManagerBridge', () => {
       messageMetadata: { checkpoint_ns: 'tools:aa5c61a1-e3ee-ea36|model' },
     } satisfies StreamEvent]);
 
-    // Attribution only arrives later, via a values event carrying the child's
-    // first human message, which the description ladder matches on.
+    // The messages event above already attributed the namespace positionally
+    // (ensureToolStreamAttribution, #847), so this values event finds the
+    // mapping in place — the description ladder is short-circuited here. See
+    // subagent-tracker.spec.ts for direct ladder coverage.
     transport.emit([{
       type: 'values|tools:aa5c61a1-e3ee-ea36' as StreamEvent['type'],
       namespace: ['tools:aa5c61a1-e3ee-ea36'],

libs/langgraph/src/lib/internals/subagent-tracker.spec.ts

@@ -0,0 +1,162 @@
+// SPDX-License-Identifier: MIT
+//
+// Direct unit coverage for the subagent attribution ladder. The tracker is a
+// plain class, so these tests drive it without the stream-manager bridge.
+// Reaching rungs 1/2 THROUGH the bridge additionally requires the child's
+// `values` event (carrying a human first message) to arrive before any child
+// `messages` event — an ordering no bridge test encodes, which is why ladder
+// coverage lives here instead.
+import { describe, it, expect } from 'vitest';
+import type { BaseMessage } from '@langchain/core/messages';
+import { SubagentTracker, childStreamRefFromNamespace } from './subagent-tracker';
+
+function taskCall(id: string, args: Record<string, unknown>) {
+  return { id, name: 'task', args: { subagent_type: 'researcher', ...args } };
+}
+
+function aiMsg(id: string, content: string): BaseMessage {
+  return { id, type: 'ai', content } as unknown as BaseMessage;
+}
+
+describe('SubagentTracker attribution ladder', () => {
+  it('rung 1: exact description match wins even with multiple candidates', () => {
+    const t = new SubagentTracker();
+    t.registerFromToolCalls([
+      taskCall('call_a', { description: 'Summarize the meeting notes' }),
+      taskCall('call_b', { description: 'Research quantum signals' }),
+    ]);
+    // Namespace id is an internal UUID — deliberately NOT a tool-call id, so
+    // nothing but the ladder can resolve it. Two candidates outstanding, so
+    // the positional rung would refuse; only the exact rung can attribute.
+    const winner = t.matchSubgraphToSubagent('ns-uuid-1', 'Research quantum signals');
+    expect(winner).toBe('call_b');
+  });
+
+  it('rung 2: substring match (either direction) wins when exact fails', () => {
+    const t = new SubagentTracker();
+    t.registerFromToolCalls([
+      taskCall('call_a', { description: 'Summarize the meeting notes' }),
+      taskCall('call_b', { description: 'Research quantum signals' }),
+    ]);
+    // The child's first human message elaborates on the stored description.
+    const winner = t.matchSubgraphToSubagent(
+      'ns-uuid-2',
+      'Research quantum signals across the 2025 arxiv corpus',
+    );
+    expect(winner).toBe('call_b');
+  });
+
+  it('rung 2: an empty stored description is never a substring match', () => {
+    const t = new SubagentTracker();
+    t.registerFromToolCalls([
+      taskCall('call_a', { description: '' }),
+      taskCall('call_b', { description: 'Book a flight' }),
+    ]);
+    // 'anything' contains '' — without the guard at the substring rung,
+    // call_a would claim every stream. It must not.
+    const winner = t.matchSubgraphToSubagent('ns-uuid-3', 'anything unrelated');
+    expect(winner).toBeUndefined();
+  });
+
+  it('rung 3: positional fallback attributes only when exactly one candidate is outstanding', () => {
+    const t = new SubagentTracker();
+    t.registerFromToolCalls([taskCall('call_solo', { task_description: 'x' })]);
+    expect(t.matchSubgraphToSubagent('ns-uuid-4', '')).toBe('call_solo');
+  });
+
+  it('rung 3: refuses with two outstanding candidates and buffers instead', () => {
+    const t = new SubagentTracker();
+    t.registerFromToolCalls([
+      taskCall('call_a', { task_description: 'x' }),
+      taskCall('call_b', { task_description: 'y' }),
+    ]);
+    expect(t.matchSubgraphToSubagent('ns-uuid-5', '')).toBeUndefined();
+
+    // Unattributed messages are held, not dropped and not mis-assigned.
+    t.addMessageToSubagent('ns-uuid-5', aiMsg('m1', 'early chunk'));
+    // getSubagents() hides 'pending' entries — this loop is empty when
+    // correct, and bites only when a mutant wrongly establishes the match
+    // and promotes a candidate to 'running'.
+    for (const subagent of t.getSubagents().values()) {
+      expect(subagent.messages).toHaveLength(0);
+    }
+  });
+
+  it('deferred retry: a pending match resolves when the tool call registers later', () => {
+    const t = new SubagentTracker();
+    // Child stream arrives BEFORE the parent's tool call — nothing to match yet.
+    expect(t.matchSubgraphToSubagent('ns-uuid-6', 'Find flights to Lisbon')).toBeUndefined();
+    t.addMessageToSubagent('ns-uuid-6', aiMsg('m1', 'checking fares'));
+
+    // Parent tool call registers; registerFromToolCalls drains pendingMatches.
+    t.registerFromToolCalls([taskCall('call_late', { description: 'Find flights to Lisbon' })]);
+
+    const subagent = t.getSubagents().get('call_late');
+    expect(subagent?.status).toBe('running');
+    expect(subagent?.messages).toEqual([
+      expect.objectContaining({ id: 'm1', content: 'checking fares' }),
+    ]);
+  });
+
+  it('empty-description attribution never exact-matches an empty stored description', () => {
+    const t = new SubagentTracker();
+    t.registerFromToolCalls([
+      taskCall('call_a', { description: '' }),
+      taskCall('call_b', { description: 'Book a flight' }),
+    ]);
+    // ensureToolStreamAttribution runs the ladder with '' — with two
+    // candidates outstanding it must refuse (positional rung), not let
+    // '' === '' claim call_a at the exact rung.
+    t.ensureToolStreamAttribution('ns-uuid-7');
+    t.addMessageToSubagent('ns-uuid-7', aiMsg('m1', 'child token'));
+    // getSubagents() hides 'pending' entries — this loop is empty when
+    // correct, and bites only when a mutant wrongly establishes the match
+    // and promotes a candidate to 'running'.
+    for (const subagent of t.getSubagents().values()) {
+      expect(subagent.messages).toHaveLength(0);
+    }
+  });
+});
+
+describe('childStreamRefFromNamespace', () => {
+  it('single tools: segment resolves to a tool child by tool-call id', () => {
+    expect(childStreamRefFromNamespace(['tools:call-1'])).toEqual({
+      key: 'call-1', name: '', kind: 'tool',
+    });
+  });
+
+  it('a tool child followed by its own internal nodes stays a tool child', () => {
+    // `model`/`agent` segments after the tools: segment are the child's own
+    // graph internals, not a second delegation.
+    expect(childStreamRefFromNamespace(['tools:call-1', 'agent:step-2'])).toEqual({
+      key: 'call-1', name: '', kind: 'tool',
+    });
+  });
+
+  it('plain subgraph namespace resolves to the first segment, named by node', () => {
+    expect(childStreamRefFromNamespace(['research:uuid-1'])).toEqual({
+      key: 'research:uuid-1', name: 'research', kind: 'subgraph',
+    });
+  });
+
+  it('nested delegation registers as its own subgraph stream, never the outer tool child', () => {
+    expect(childStreamRefFromNamespace(['tools:call-1', 'tools:call-2'])).toEqual({
+      key: 'tools:call-1|tools:call-2', name: 'tools', kind: 'subgraph',
+    });
+  });
+
+  it('nested delegation with intermediate segments still keys the full path', () => {
+    expect(childStreamRefFromNamespace(['tools:call-1', 'agent:x', 'tools:call-2'])).toEqual({
+      key: 'tools:call-1|agent:x|tools:call-2', name: 'tools', kind: 'subgraph',
+    });
+  });
+
+  it('trailing internal segments after the innermost tools: segment do not fragment the key', () => {
+    expect(childStreamRefFromNamespace(['tools:call-1', 'tools:call-2', 'agent:x'])).toEqual({
+      key: 'tools:call-1|tools:call-2', name: 'tools', kind: 'subgraph',
+    });
+    expect(childStreamRefFromNamespace(['tools:call-1', 'tools:call-2', 'model:y'])).toEqual({
+      key: 'tools:call-1|tools:call-2', name: 'tools', kind: 'subgraph',
+    });
+  });
+});

libs/langgraph/src/lib/internals/subagent-tracker.ts

@@ -170,19 +170,26 @@ export class SubagentTracker {
       return toolCallId;
     };
 
-    for (const [toolCallId, subagent] of this.subagents) {
-      if (subagent.kind !== 'tool' || mapped.has(toolCallId)) continue;
-      if (subagent.toolCall.args['description'] === description) {
-        return establish(toolCallId);
+    // The description rungs are only meaningful with a real description.
+    // ensureToolStreamAttribution calls this with '' precisely to skip them:
+    // without this guard, a subagent whose `description` arg is literally ''
+    // exact-matches every empty-description probe, bypassing the positional
+    // rung's one-candidate safety check.
+    if (description) {
+      for (const [toolCallId, subagent] of this.subagents) {
+        if (subagent.kind !== 'tool' || mapped.has(toolCallId)) continue;
+        if (subagent.toolCall.args['description'] === description) {
+          return establish(toolCallId);
+        }
       }
-    }
 
-    for (const [toolCallId, subagent] of this.subagents) {
-      if (subagent.kind !== 'tool' || mapped.has(toolCallId)) continue;
-      const subagentDescription = subagent.toolCall.args['description'];
-      if (typeof subagentDescription !== 'string' || !subagentDescription) continue;
-      if (description.includes(subagentDescription) || subagentDescription.includes(description)) {
-        return establish(toolCallId);
+      for (const [toolCallId, subagent] of this.subagents) {
+        if (subagent.kind !== 'tool' || mapped.has(toolCallId)) continue;
+        const subagentDescription = subagent.toolCall.args['description'];
+        if (typeof subagentDescription !== 'string' || !subagentDescription) continue;
+        if (description.includes(subagentDescription) || subagentDescription.includes(description)) {
+          return establish(toolCallId);
+        }
       }
     }
 
@@ -417,7 +424,13 @@ export function isChildNamespace(namespace: string[] | string | undefined): bool
 
 /** Resolved identity of a child stream, derived from its event namespace. */
 export interface ChildStreamRef {
-  /** Map key: the tool-call id for `tools:` namespaces, else the namespace segment itself. */
+  /**
+   * Map key: the tool-call id for a single `tools:` namespace; for a nested
+   * delegation, the namespace path truncated at (and including) the
+   * innermost `tools:` segment, so trailing internal-node segments don't
+   * fragment one grandchild into several entries; else the namespace segment
+   * itself.
+   */
   key: string;
   /** Display name; for subgraph nodes, the node name. Unused on the tool path. */
   name: string;
@@ -431,27 +444,47 @@ export interface ChildStreamRef {
  * Any other segment (e.g. `research:<uuid>` from a compiled graph added with
  * `add_node`) identifies a plain subgraph child: the full segment is the key
  * (unique per invocation) and the part before the first ':' is the node name.
+ *
+ * A namespace with MORE than one `tools:` segment is a nested delegation — a
+ * subagent that itself dispatched a delegation tool. That stream registers as
+ * its own subgraph-kind entry keyed by the namespace path truncated at the
+ * innermost `tools:` segment (inclusive), so trailing internal-node segments
+ * after it (the grandchild's own `model:`/`agent:` steps) don't fragment one
+ * grandchild into several map entries. Subgraph entries are skipped by every
+ * attribution-ladder rung, so a grandchild can neither merge into the outer
+ * child's card nor mis-attach to a sibling. Linking it to its parent card (a
+ * delegation tree) is deliberately not modeled; the flat map is the contract.
  */
 export function childStreamRefFromNamespace(namespace: string[]): ChildStreamRef | undefined {
-  for (const segment of namespace) {
-    if (segment.startsWith('tools:')) {
-      return { key: segment.slice(6), name: '', kind: 'tool' };
+  const toolSegments = namespace.filter((segment) => segment.startsWith('tools:'));
+  if (toolSegments.length > 1) {
+    let lastToolsIndex = -1;
+    for (let i = namespace.length - 1; i >= 0; i -= 1) {
+      if (namespace[i].startsWith('tools:')) {
+        lastToolsIndex = i;
+        break;
+      }
     }
+    const innermost = namespace[lastToolsIndex];
+    const colon = innermost.indexOf(':');
+    return {
+      // The innermost segment's node name is 'tools' for a delegation-tool
+      // child — an intentionally generic card label; there's no
+      // subagent_type to name it from.
+      key: namespace.slice(0, lastToolsIndex + 1).join('|'),
+      name: colon > 0 ? innermost.slice(0, colon) : innermost,
+      kind: 'subgraph',
+    };
+  }
+  if (toolSegments.length === 1) {
+    return { key: toolSegments[0].slice(6), name: '', kind: 'tool' };
   }
   const first = namespace[0];
   if (!first) return undefined;
   const colon = first.indexOf(':');
   return { key: first, name: colon > 0 ? first.slice(0, colon) : first, kind: 'subgraph' };
 }
 
-export function extractToolCallIdFromNamespace(namespace: string[] | undefined): string | undefined {
-  if (!namespace) return undefined;
-  for (const segment of namespace) {
-    if (segment.startsWith('tools:')) return segment.slice(6);
-  }
-  return undefined;
-}
-
 function parseToolCallArgs(args: Record<string, unknown> | string): Record<string, unknown> {
   if (typeof args !== 'string') return args;
   try {