@illuma-ai/agents 1.5.0 → 2.1.1

package/src/messages/cache.test.ts

@@ -412,14 +412,7 @@ describe('addBedrockCacheControl (Bedrock cache checkpoints)', () => {
     expect(first[1]).toEqual({ cachePoint: { type: 'default' } });
   });
 
-  it('skips system messages (cachePoint added inline by AgentContext.buildSystemRunnable)', () => {
-    /* Contract change (upstream PR #128 alignment): system message
-     * cachePoint is now emitted inline in AgentContext.buildSystemRunnable.
-     * addBedrockCacheControl must therefore SKIP system messages so the
-     * 2-cachePoint per-request budget stays available for the conversation
-     * tail. Caching the system prefix is what unlocks cross-user cost
-     * savings — Bedrock's prompt cache is account-scoped, so a stable
-     * system prefix shared across users hits the same cache entry. */
+  it('works with the example from the langchain pr (with multi-turn behavior)', () => {
     const messages: TestMsg[] = [
       {
         role: 'system',
@@ -437,17 +430,15 @@ describe('addBedrockCacheControl (Bedrock cache checkpoints)', () => {
 
     const result = addBedrockCacheControl(messages);
 
-    const system = result[0].content as MessageContentComplex[];
-    const user = result[1].content as MessageContentComplex[];
+    let system = result[0].content as MessageContentComplex[];
+    let user = result[1].content as MessageContentComplex[];
 
-    // System message is left untouched — addBedrockCacheControl does NOT
-    // add a cachePoint here. The cachePoint is added in AgentContext when
-    // the system message is first built.
-    expect(system).toEqual([
-      { type: ContentTypes.TEXT, text: 'You\'re an advanced AI assistant.' },
-    ]);
-
-    // User message still gets a cachePoint (last eligible).
+    // Both messages get cachePoints (last 2 eligible messages)
+    expect(system[0]).toEqual({
+      type: ContentTypes.TEXT,
+      text: 'You\'re an advanced AI assistant.',
+    });
+    expect(system[1]).toEqual({ cachePoint: { type: 'default' } });
     expect(user[0]).toEqual({
       type: ContentTypes.TEXT,
       text: 'What is the capital of France?',
@@ -467,59 +458,30 @@ describe('addBedrockCacheControl (Bedrock cache checkpoints)', () => {
 
     const result2 = addBedrockCacheControl(result);
 
-    const system2 = result2[0].content as MessageContentComplex[];
-    const user2 = result2[1].content as MessageContentComplex[];
-    const assistant2 = result2[2].content as MessageContentComplex[];
+    system = result2[0].content as MessageContentComplex[];
+    user = result2[1].content as MessageContentComplex[];
+    const assistant = result2[2].content as MessageContentComplex[];
 
-    // System message still untouched.
-    expect(system2).toEqual([
-      { type: ContentTypes.TEXT, text: 'You\'re an advanced AI assistant.' },
-    ]);
+    // System message no longer has cachePoint (it's not in the last 2 eligible)
+    expect(system[0]).toEqual({
+      type: ContentTypes.TEXT,
+      text: 'You\'re an advanced AI assistant.',
+    });
+    expect(system.length).toBe(1);
 
-    // Both conversation messages now get cachePoints (last 2 eligible).
-    expect(user2[0]).toEqual({
+    // User message gets cachePoint (second-to-last eligible)
+    expect(user[0]).toEqual({
       type: ContentTypes.TEXT,
       text: 'What is the capital of France?',
     });
-    expect(user2[1]).toEqual({ cachePoint: { type: 'default' } });
+    expect(user[1]).toEqual({ cachePoint: { type: 'default' } });
 
-    expect(assistant2[0]).toEqual({
+    // Assistant message gets cachePoint (last eligible)
+    expect(assistant[0]).toEqual({
       type: ContentTypes.TEXT,
       text: 'Sure! The capital of France is Paris.',
     });
-    expect(assistant2[1]).toEqual({ cachePoint: { type: 'default' } });
-  });
-
-  it('strips stray Anthropic cache_control from system message (cross-provider safety)', () => {
-    /* If a system message arrives with an Anthropic-style cache_control
-     * marker (e.g. cross-provider switch), addBedrockCacheControl should
-     * sanitize it — Bedrock ignores cache_control and stale markers can
-     * confuse provider validation. */
-    const messages: TestMsg[] = [
-      {
-        role: 'system',
-        content: [
-          {
-            type: ContentTypes.TEXT,
-            text: 'You\'re an advanced AI assistant.',
-            cache_control: { type: 'ephemeral' },
-          } as MessageContentComplex,
-        ],
-      },
-      {
-        role: 'user',
-        content: [{ type: ContentTypes.TEXT, text: 'Hi' }],
-      },
-    ];
-
-    const result = addBedrockCacheControl(messages);
-    const system = result[0].content as MessageContentComplex[];
-
-    expect(system).toHaveLength(1);
-    expect('cache_control' in system[0]).toBe(false);
-    expect((system[0] as { text?: string }).text).toBe(
-      'You\'re an advanced AI assistant.'
-    );
+    expect(assistant[1]).toEqual({ cachePoint: { type: 'default' } });
   });
 
   it('is idempotent - calling multiple times does not add duplicate cache points', () => {

package/src/messages/cache.ts

@@ -14,61 +14,6 @@ type MessageWithContent = {
   content?: string | MessageContentComplex[];
 };
 
-type MessageContentWithCacheControl = MessageContentComplex & {
-  cache_control?: unknown;
-};
-
-/**
- * Strips Anthropic-style `cache_control` markers from every block in the
- * given content array. Returns the (possibly cloned) content and a flag
- * indicating whether anything was actually modified — so callers can avoid
- * unnecessary message clones.
- *
- * Used to sanitize a system message's content array before adding Bedrock
- * cache points, so stray Anthropic markers (e.g. left over from a previous
- * Anthropic-provider turn) don't prevent the Bedrock provider from caching
- * the system prefix.
- */
-function stripAnthropicCacheControlFromBlocks(
-  content: MessageContentComplex[]
-): { content: MessageContentComplex[]; modified: boolean } {
-  let modified = false;
-  const strippedContent = content.map((block) => {
-    if (!('cache_control' in block)) {
-      return block;
-    }
-
-    const cloned: MessageContentWithCacheControl = { ...block };
-    delete cloned.cache_control;
-    modified = true;
-    return cloned;
-  });
-
-  return { content: strippedContent, modified };
-}
-
-/**
- * For the Bedrock cache pass, system messages must NOT carry Anthropic
- * cache_control markers (those are an Anthropic-specific encoding and
- * Bedrock uses cachePoint blocks instead). Strip them before the cache
- * point insertion logic walks the message.
- */
-function sanitizeBedrockSystemMessage<T extends MessageWithContent>(
-  message: T
-): T {
-  const content = message.content;
-  if (!Array.isArray(content)) {
-    return message;
-  }
-
-  const stripped = stripAnthropicCacheControlFromBlocks(content);
-  if (!stripped.modified) {
-    return message;
-  }
-
-  return cloneMessage(message, stripped.content);
-}
-
 /** Debug logger for cache operations - set ILLUMA_DEBUG_CACHE=true to enable */
 const debugCache = (message: string, data?: unknown): void => {
   if (process.env.ILLUMA_DEBUG_CACHE === 'true') {
@@ -416,36 +361,8 @@ export function addBedrockCacheControl<
 
   // Clone messages to avoid mutating originals
   const updatedMessages: T[] = messages.map((msg) => {
-    /* PRESERVE cachePoint on system messages — they're added inline by
-     * AgentContext.buildSystemRunnable to mark the cacheable system prefix
-     * for account-level caching. Only strip stray Anthropic cache_control
-     * (which Bedrock ignores). For non-system messages keep the existing
-     * behaviour: full strip + repopulate based on last-2 strategy. */
-    const msgType =
-      'getType' in msg && typeof msg.getType === 'function'
-        ? msg.getType()
-        : undefined;
-    const msgRole = (msg as Record<string, unknown>).role as string | undefined;
-    const isSystem = msgType === 'system' || msgRole === 'system';
-
     const content = msg.content;
     if (Array.isArray(content)) {
-      if (isSystem) {
-        /* System: keep cachePoint, only strip Anthropic cache_control. */
-        if (hasAnthropicCacheControl(content)) {
-          const stripped = content.map((block) => {
-            const rec = block as Record<string, unknown>;
-            if ('cache_control' in rec) {
-              const { cache_control: _, ...rest } = rec;
-              return rest as MessageContentComplex;
-            }
-            return block;
-          });
-          return cloneMessage(msg, stripped) as T;
-        }
-        return cloneMessage(msg, content) as T;
-      }
-
       // Strip existing cachePoint blocks and Anthropic-style cache_control
       const stripped = content
         .filter((block) => !isCachePoint(block))
@@ -539,35 +456,6 @@ export function addBedrockCacheControl<
     const message = updatedMessages[i];
     const msgContent = message.content;
 
-    /* System messages are handled by AgentContext.buildSystemRunnable —
-     * the cachePoint is emitted INLINE in the system message content array
-     * so the cacheable system prefix gets a marker every turn (not just
-     * when the system message happens to be in the last 2 eligible). The
-     * Bedrock converter (src/llm/bedrock/utils/message_inputs.ts:261-294)
-     * passes through cachePoint blocks in system content arrays.
-     *
-     * If we ALSO marked system here, we'd: (a) waste one of the two
-     * cachePoint budget slots that Bedrock honours per-request, starving
-     * the conversation tail, and (b) potentially double-mark a stable
-     * prefix that already has its own cachePoint.
-     *
-     * As a defensive cleanup, strip stray Anthropic-style cache_control
-     * markers from the system message — Bedrock ignores them and they
-     * can confuse provider validation. */
-    const _msgType =
-      'getType' in message && typeof message.getType === 'function'
-        ? message.getType()
-        : undefined;
-    const _msgRole = (message as Record<string, unknown>).role as
-      | string
-      | undefined;
-    if (_msgType === 'system' || _msgRole === 'system') {
-      updatedMessages[i] = sanitizeBedrockSystemMessage(
-        message as MessageWithContent
-      ) as T;
-      continue;
-    }
-
     // Skip empty/whitespace-only content
     if (msgContent == null) continue;
     if (typeof msgContent === 'string' && msgContent.trim() === '') continue;

package/src/messages/format.ts

@@ -274,90 +274,18 @@ export const formatFromLangChain = (
   };
 };
 
-/* DeepSeek reasoning roundtrip: when active, accumulate reasoning text
- * from THINK/THINKING/REASONING blocks and attach to the next AI message
- * as `additional_kwargs.reasoning_content` so it survives multi-turn
- * replays through the OpenAI-compatible DeepSeek API. Upstream PR #136. */
-interface FormatAssistantMessageOptions {
-  preserveReasoningContent?: boolean;
-}
-
-interface FormatAgentMessagesOptions {
-  provider?: Providers;
-}
-
-function extractReasoningContent(
-  part: MessageContentComplex | undefined | null
-): string {
-  if (part == null || typeof part !== 'object') return '';
-  if (part.type === ContentTypes.THINK) {
-    const think = (part as ReasoningContentText).think;
-    return typeof think === 'string' ? think : '';
-  }
-  if (part.type === ContentTypes.THINKING) {
-    const thinking = (part as { thinking?: string }).thinking;
-    return typeof thinking === 'string' ? thinking : '';
-  }
-  if (part.type === ContentTypes.REASONING) {
-    const reasoning = (part as { reasoning?: string }).reasoning;
-    return typeof reasoning === 'string' ? reasoning : '';
-  }
-  if (part.type === ContentTypes.REASONING_CONTENT) {
-    /* Bedrock/Google nested shape: { reasoningContent: { text: ... } } */
-    const nested = (part as { reasoningContent?: { text?: string } })
-      .reasoningContent;
-    if (nested && typeof nested.text === 'string') return nested.text;
-  }
-  return '';
-}
-
 /**
  * Helper function to format an assistant message
  * @param message The message to format
- * @param options Optional formatting options (e.g. DeepSeek reasoning roundtrip)
  * @returns Array of formatted messages
  */
 function formatAssistantMessage(
-  message: Partial<TMessage>,
-  options?: FormatAssistantMessageOptions
+  message: Partial<TMessage>
 ): Array<AIMessage | ToolMessage> {
   const formattedMessages: Array<AIMessage | ToolMessage> = [];
   let currentContent: MessageContentComplex[] = [];
   let lastAIMessage: AIMessage | null = null;
   let hasReasoning = false;
-  let pendingReasoningContent = '';
-  const shouldPreserveReasoningContent =
-    options?.preserveReasoningContent === true;
-
-  const takePendingReasoningContent = (): string | undefined => {
-    if (!shouldPreserveReasoningContent || !pendingReasoningContent) {
-      return undefined;
-    }
-    const reasoningContent = pendingReasoningContent;
-    pendingReasoningContent = '';
-    return reasoningContent;
-  };
-
-  const createAIMessage = (
-    content: string | MessageContentComplex[]
-  ): AIMessage => {
-    const reasoningContent = takePendingReasoningContent();
-    return new AIMessage({
-      content,
-      ...(reasoningContent != null && {
-        additional_kwargs: { reasoning_content: reasoningContent },
-      }),
-    });
-  };
-
-  const attachPendingReasoningContent = (aiMessage: AIMessage): void => {
-    const reasoningContent = takePendingReasoningContent();
-    if (reasoningContent == null) return;
-    aiMessage.additional_kwargs.reasoning_content =
-      typeof aiMessage.additional_kwargs.reasoning_content === 'string'
-        ? `${aiMessage.additional_kwargs.reasoning_content}${reasoningContent}`
-        : reasoningContent;
-  };
 
   if (Array.isArray(message.content)) {
     for (const part of message.content as Array<
@@ -380,15 +308,15 @@ function formatAssistantMessage(
           }, '');
           content =
             `${content}\n${part[ContentTypes.TEXT] ?? part.text ?? ''}`.trim();
-          lastAIMessage = createAIMessage(content);
+          lastAIMessage = new AIMessage({ content });
           formattedMessages.push(lastAIMessage);
           currentContent = [];
           continue;
         }
         // Create a new AIMessage with this text and prepare for tool calls
-        lastAIMessage = createAIMessage(
-          part.text != null ? part.text : ''
-        );
+        lastAIMessage = new AIMessage({
+          content: part.text != null ? part.text : '',
+        });
         formattedMessages.push(lastAIMessage);
       } else if (part.type === ContentTypes.TOOL_CALL) {
         // Skip malformed tool call entries without tool_call property
@@ -413,10 +341,8 @@ function formatAssistantMessage(
 
         if (!lastAIMessage) {
           // "Heal" the payload by creating an AIMessage to precede the tool call
-          lastAIMessage = createAIMessage('');
+          lastAIMessage = new AIMessage({ content: '' });
           formattedMessages.push(lastAIMessage);
-        } else {
-          attachPendingReasoningContent(lastAIMessage);
         }
 
         const tool_call: ToolCallPart = _tool_call;
@@ -459,12 +385,10 @@ function formatAssistantMessage(
       } else if (
         part.type === ContentTypes.THINK ||
         part.type === ContentTypes.THINKING ||
-        part.type === ContentTypes.REASONING ||
         part.type === ContentTypes.REASONING_CONTENT ||
         part.type === 'redacted_thinking'
       ) {
         hasReasoning = true;
-        pendingReasoningContent += extractReasoningContent(part);
         continue;
       } else if (
         part.type === ContentTypes.ERROR ||
@@ -494,10 +418,10 @@ function formatAssistantMessage(
       .trim();
 
     if (content) {
-      formattedMessages.push(createAIMessage(content));
+      formattedMessages.push(new AIMessage({ content }));
     }
   } else if (currentContent.length > 0) {
-    formattedMessages.push(createAIMessage(currentContent));
+    formattedMessages.push(new AIMessage({ content: currentContent }));
   }
 
   return formattedMessages;
@@ -798,8 +722,7 @@ export const formatAgentMessages = (
   payload: TPayload,
   indexTokenCountMap?: Record<number, number | undefined>,
   tools?: Set<string>,
-  skills?: Map<string, string>,
-  options?: FormatAgentMessagesOptions
+  skills?: Map<string, string>
 ): {
   messages: Array<HumanMessage | AIMessage | SystemMessage | ToolMessage>;
   indexTokenCountMap?: Record<number, number>;
@@ -1008,9 +931,7 @@ export const formatAgentMessages = (
     }
 
     // Process the assistant message using the helper function
-    const formattedMessages = formatAssistantMessage(processedMessage, {
-      preserveReasoningContent: options?.provider === Providers.DEEPSEEK,
-    });
+    const formattedMessages = formatAssistantMessage(processedMessage);
     messages.push(...formattedMessages);
 
     // Capture index range BEFORE skill body injection so injected

package/src/scripts/subagent-configurable-inheritance.ts

@@ -0,0 +1,263 @@
+import { config } from 'dotenv';
+config();
+
+import { HumanMessage } from '@langchain/core/messages';
+import type * as t from '@/types';
+import { ChatModelStreamHandler } from '@/stream';
+import { ToolEndHandler, ModelEndHandler } from '@/events';
+import { Providers, GraphEvents } from '@/common';
+import { Run } from '@/run';
+
+/**
+ * Live verification that host-set fields on the parent's outer
+ * `configurable` (e.g. `requestBody`, `user`, `userMCPAuthMap`)
+ * propagate into the subagent's `ON_TOOL_EXECUTE` dispatches.
+ *
+ * Pass criteria: when the SUBAGENT calls the calculator tool, the
+ * `data.configurable` arriving at the parent's ON_TOOL_EXECUTE
+ * handler contains every key the parent put on its outer
+ * configurable (with `thread_id` overridden to a child run id).
+ */
+const apiKey = process.env.OPENAI_API_KEY!;
+if (!apiKey) {
+  console.error('Missing OPENAI_API_KEY');
+  process.exit(1);
+}
+
+const calculatorDef: t.LCTool = {
+  name: 'calculator',
+  description: 'Evaluate a math expression. Use for any arithmetic.',
+  parameters: {
+    type: 'object',
+    properties: {
+      expression: {
+        type: 'string',
+        description: "A JS math expression, e.g. '42 * 58'",
+      },
+    },
+    required: ['expression'],
+  },
+};
+
+type ConfigurableSnapshot = {
+  agentId: string | undefined;
+  configurable: Record<string, unknown> | undefined;
+  metadata: Record<string, unknown> | undefined;
+};
+
+async function main() {
+  console.log('=== Subagent parentConfigurable inheritance — live ===\n');
+
+  // Parent has NO tools — it can only delegate via the math subagent.
+  // The math subagent has the calculator. This forces the spawn-subagent
+  // path so we can observe the subagent's `ON_TOOL_EXECUTE` dispatch.
+  const mathSubagentInputs: t.AgentInputs = {
+    agentId: 'math-worker',
+    provider: Providers.OPENAI,
+    clientOptions: { modelName: 'gpt-4o', apiKey },
+    instructions:
+      'You compute arithmetic. Always use the calculator tool — never estimate. Return the final numeric result as plain text.',
+    maxContextTokens: 8000,
+    toolDefinitions: [calculatorDef],
+  };
+
+  const parentAgent: t.AgentInputs = {
+    agentId: 'supervisor',
+    provider: Providers.OPENAI,
+    clientOptions: { modelName: 'gpt-4o', apiKey },
+    instructions: `You delegate arithmetic to the "math" subagent. You have NO calculator yourself. For any math task, spawn the "math" subagent with the full task as its description, then echo the subagent's text result back to the user.`,
+    maxContextTokens: 8000,
+    // No toolDefinitions on the parent — only the subagent gets the calculator.
+    subagentConfigs: [
+      {
+        type: 'math',
+        name: 'math',
+        description:
+          'A focused arithmetic worker that uses the calculator tool to compute numerical results.',
+        agentInputs: mathSubagentInputs,
+      },
+    ],
+  };
+
+  const parentSnapshots: ConfigurableSnapshot[] = [];
+  const subagentSnapshots: ConfigurableSnapshot[] = [];
+
+  const customHandlers: Record<string, t.EventHandler> = {
+    [GraphEvents.CHAT_MODEL_STREAM]: new ChatModelStreamHandler(),
+    [GraphEvents.TOOL_END]: new ToolEndHandler(),
+    [GraphEvents.CHAT_MODEL_END]: new ModelEndHandler(),
+    [GraphEvents.ON_TOOL_EXECUTE]: {
+      handle: (_event, rawData): void => {
+        const data = rawData as t.ToolExecuteBatchRequest;
+        const snapshot: ConfigurableSnapshot = {
+          agentId: data.agentId,
+          configurable: data.configurable as
+            | Record<string, unknown>
+            | undefined,
+          metadata: data.metadata as Record<string, unknown> | undefined,
+        };
+        const callsLabel = data.toolCalls.map((c) => c.name).join(',');
+        // Parent and subagent have different agent IDs in this script
+        // (parent: 'supervisor', subagent: 'math-worker'). With a self-spawn
+        // subagent both would be the same; this script uses a non-self
+        // subagent precisely so we can distinguish reliably.
+        const isSubagent = data.agentId !== 'supervisor';
+        const metadataRunId = (data.metadata as { run_id?: string } | undefined)
+          ?.run_id;
+        if (isSubagent) {
+          subagentSnapshots.push(snapshot);
+        } else {
+          parentSnapshots.push(snapshot);
+        }
+        console.log(
+          `[ON_TOOL_EXECUTE] origin=${isSubagent ? 'SUBAGENT' : 'PARENT'} agentId=${data.agentId} calls=${callsLabel}`
+        );
+        console.log(
+          `  metadata keys: ${Object.keys(data.metadata ?? {}).join(',') || '<none>'}`
+        );
+        console.log(
+          `  metadata.run_id="${metadataRunId ?? '<none>'}" configurable.run_id="${(data.configurable as { run_id?: string } | undefined)?.run_id ?? '<none>'}" configurable.thread_id="${(data.configurable as { thread_id?: string } | undefined)?.thread_id ?? '<none>'}"`
+        );
+        const results: t.ToolExecuteResult[] = data.toolCalls.map((call) => {
+          const args = call.args as { expression?: string };
+          const expression = args.expression ?? '';
+          let content: string;
+          try {
+            // eslint-disable-next-line no-eval
+            const result = eval(expression);
+            content = `${expression} = ${result}`;
+          } catch (err) {
+            content = `Error: ${String(err)}`;
+          }
+          return {
+            toolCallId: call.id!,
+            status: 'success',
+            content,
+          };
+        });
+        data.resolve(results);
+      },
+    },
+  };
+
+  const run = await Run.create<t.IState>({
+    runId: `sub-cfg-inherit-${Date.now()}`,
+    graphConfig: { type: 'standard', agents: [parentAgent] },
+    customHandlers,
+  });
+
+  const question = new HumanMessage(
+    'Compute (42 * 58) + (13 ** 3). Use the self subagent, and have it use the calculator.'
+  );
+
+  // Parent's outer configurable carries host-set fields AND explicit
+  // run-identity fields so we can verify whether LangGraph respects or
+  // overwrites parent's `run_id` / `parent_run_id` when we forward them
+  // into the child's `workflow.invoke`.
+  const outerConfigurable = {
+    thread_id: 'parent-thread-conv-xyz',
+    run_id: 'parent-run-id-001',
+    parent_run_id: 'grandparent-run-id-000',
+    user_id: 'user_abc',
+    user: { id: 'user_abc', email: 'a@b.c', role: 'USER' },
+    requestBody: {
+      messageId: 'msg-response-id-001',
+      conversationId: 'parent-thread-conv-xyz',
+      parentMessageId: 'user-message-id-000',
+    },
+    userMCPAuthMap: { 'mcp-github': { token: 'abc' } },
+  };
+
+  console.log('User:', question.content);
+  console.log(
+    'Parent outer configurable keys:',
+    Object.keys(outerConfigurable)
+  );
+  console.log();
+
+  await run.processStream(
+    { messages: [question] },
+    {
+      configurable: outerConfigurable,
+      version: 'v2' as const,
+    }
+  );
+
+  console.log('\n=== Verification ===');
+  console.log(
+    `Parent ON_TOOL_EXECUTE dispatches captured: ${parentSnapshots.length}`
+  );
+  console.log(
+    `Subagent ON_TOOL_EXECUTE dispatches captured: ${subagentSnapshots.length}`
+  );
+
+  if (subagentSnapshots.length === 0) {
+    console.error(
+      '\n❌ FAIL: subagent never invoked a tool — model may not have spawned the subagent.'
+    );
+    process.exit(2);
+  }
+
+  const expectedHostKeys = ['user_id', 'user', 'requestBody', 'userMCPAuthMap'];
+  let allPassed = true;
+  subagentSnapshots.forEach((snap, idx) => {
+    const cfg = snap.configurable ?? {};
+    const meta = snap.metadata ?? {};
+    console.log(
+      `\nSubagent dispatch #${idx + 1} (agentId=${snap.agentId}, metadata.run_id=${(meta as { run_id?: string }).run_id ?? '-'}):`
+    );
+
+    // Host-set fields must propagate.
+    for (const key of expectedHostKeys) {
+      const present = key in cfg;
+      const value = cfg[key];
+      console.log(
+        `  ${present ? '✅' : '❌'} ${key} = ${JSON.stringify(value)}`
+      );
+      if (!present) allPassed = false;
+    }
+
+    // Run-identity fields: with full inheritance we expect parent's
+    // values to flow through. LangGraph runtime MAY overwrite them at
+    // child-invoke time — the script logs what actually arrived so we
+    // can see empirically what propagates.
+    console.log(
+      `  ⓘ thread_id observed: "${cfg.thread_id as string}" (parent's: "${outerConfigurable.thread_id}")`
+    );
+    console.log(
+      `  ⓘ run_id observed:    "${cfg.run_id as string}" (parent's: "${outerConfigurable.run_id}")`
+    );
+    console.log(
+      `  ⓘ parent_run_id observed: "${cfg.parent_run_id as string}" (parent's: "${outerConfigurable.parent_run_id}")`
+    );
+
+    const threadInherited = cfg.thread_id === outerConfigurable.thread_id;
+    const runInherited = cfg.run_id === outerConfigurable.run_id;
+    const parentRunInherited =
+      cfg.parent_run_id === outerConfigurable.parent_run_id;
+    console.log(
+      `  ${threadInherited ? '✅' : '⚠️ '} thread_id inherited from parent: ${threadInherited}`
+    );
+    console.log(
+      `  ${runInherited ? '✅' : '⚠️ '} run_id inherited from parent: ${runInherited}`
+    );
+    console.log(
+      `  ${parentRunInherited ? '✅' : '⚠️ '} parent_run_id inherited from parent: ${parentRunInherited}`
+    );
+  });
+
+  if (allPassed) {
+    console.log(
+      '\n✅ Host-set fields propagate. (Run-identity inheritance is informational — see ⚠️ markers above for any LangGraph-runtime overwrites.)'
+    );
+    process.exit(0);
+  } else {
+    console.log('\n❌ FAIL: at least one expected host-set key was missing.');
+    process.exit(1);
+  }
+}
+
+main().catch((err) => {
+  console.error('Script error:', err);
+  process.exit(1);
+});