@librechat/agents 3.3.4 → 3.3.5

package/src/graphs/__tests__/Graph.contextOverflow.test.ts

@@ -1059,13 +1059,24 @@ describe('context overflow recovery', () => {
     const humanMessages = model.calls[0].filter(
       (message) => message instanceof HumanMessage
     );
-    expect(humanMessages).toHaveLength(2);
-    expect(
-      JSON.stringify(humanMessages[humanMessages.length - 1].content).length
-    ).toBeLessThan(100);
-    expect(
-      JSON.stringify(humanMessages[humanMessages.length - 1].content)
-    ).not.toContain('x'.repeat(1_000));
+    /**
+     * Bedrock is a strict-alternation provider: after compaction shrinks the
+     * synthetic context, `coalesceAdjacentUserTurns` merges it into the
+     * adjacent user query — Converse rejects consecutive user turns, and the
+     * `@langchain/aws` converter only merges toolResult-bearing ones. So one
+     * user turn reaches the provider, carrying both the query and the
+     * compacted note, and it must still be small.
+     */
+    expect(humanMessages).toHaveLength(1);
+    const coalescedContent = JSON.stringify(humanMessages[0].content);
+    expect(coalescedContent).toContain('query the table');
+    /**
+     * No closing bracket: compaction truncates at a character budget, and the
+     * cut can land inside the `[Previous tool interaction]` header itself.
+     */
+    expect(coalescedContent).toContain('[Previous tool interaction');
+    expect(coalescedContent.length).toBeLessThan(150);
+    expect(coalescedContent).not.toContain('x'.repeat(1_000));
   });
 
   it('counts unresolved-reference annotations before invoking the provider', async () => {

package/src/graphs/__tests__/Graph.preemptSignal.test.ts

@@ -0,0 +1,126 @@
+// src/graphs/__tests__/Graph.preemptSignal.test.ts
+import type * as t from '@/types';
+import { Providers } from '@/common';
+import { HookRegistry } from '@/hooks/HookRegistry';
+import { StandardGraph } from '../Graph';
+
+const makeAgent = (agentId: string): t.AgentInputs => ({
+  agentId,
+  provider: Providers.OPENAI,
+  instructions: `You are ${agentId}.`,
+});
+
+type DispatchResult = { messages: unknown[]; preventContinuation: boolean };
+
+const dispatchBoundary = (
+  graph: StandardGraph,
+  agentId = 'agent'
+): Promise<DispatchResult> =>
+  (
+    graph as unknown as {
+      dispatchPreemptBoundary: (
+        agentId: string,
+        config: { configurable: { run_id: string } } | undefined
+      ) => Promise<DispatchResult>;
+    }
+  ).dispatchPreemptBoundary(agentId, {
+    configurable: { run_id: 'run_1' },
+  });
+
+/**
+ * Registers a PreemptBoundary hook that aborts `controller` from inside its
+ * own body, then reports whether the signal `executeHooks` handed it observed
+ * that abort. Racing against a short timer keeps a broken composition from
+ * stalling the suite for the 120-second boundary hook timeout.
+ */
+function registerAbortProbe(
+  registry: HookRegistry,
+  controller: AbortController
+): { outcome: () => string | undefined } {
+  let outcome: string | undefined;
+  registry.register('PreemptBoundary', {
+    hooks: [
+      async (_input, signal): Promise<Record<string, never>> => {
+        const aborted = new Promise<string>((resolve) => {
+          if (signal.aborted) {
+            resolve('aborted');
+            return;
+          }
+          signal.addEventListener('abort', () => resolve('aborted'), {
+            once: true,
+          });
+        });
+        const timer = new Promise<string>((resolve) =>
+          setTimeout(() => resolve('not-observed'), 200)
+        );
+        controller.abort();
+        outcome = await Promise.race([aborted, timer]);
+        return {};
+      },
+    ],
+  });
+  return { outcome: () => outcome };
+}
+
+describe('PreemptBoundary abort-signal composition', () => {
+  it('observes a per-call caller abort even when a construction signal exists', async () => {
+    const constructionController = new AbortController();
+    const callerController = new AbortController();
+    const graph = new StandardGraph({
+      runId: 'run_1',
+      signal: constructionController.signal,
+      agents: [makeAgent('agent')],
+    });
+    const registry = new HookRegistry();
+    const probe = registerAbortProbe(registry, callerController);
+    graph.hookRegistry = registry;
+    graph.callerSignal = callerController.signal;
+
+    await dispatchBoundary(graph);
+
+    expect(probe.outcome()).toBe('aborted');
+    expect(constructionController.signal.aborted).toBe(false);
+  });
+
+  it('observes the caller abort when no construction signal exists (multi-agent shape)', async () => {
+    const callerController = new AbortController();
+    const graph = new StandardGraph({
+      runId: 'run_1',
+      agents: [makeAgent('agent')],
+    });
+    const registry = new HookRegistry();
+    const probe = registerAbortProbe(registry, callerController);
+    graph.hookRegistry = registry;
+    graph.callerSignal = callerController.signal;
+
+    await dispatchBoundary(graph);
+
+    expect(probe.outcome()).toBe('aborted');
+  });
+
+  it('still observes the construction signal when no caller signal was supplied', async () => {
+    const constructionController = new AbortController();
+    const graph = new StandardGraph({
+      runId: 'run_1',
+      signal: constructionController.signal,
+      agents: [makeAgent('agent')],
+    });
+    const registry = new HookRegistry();
+    const probe = registerAbortProbe(registry, constructionController);
+    graph.hookRegistry = registry;
+
+    await dispatchBoundary(graph);
+
+    expect(probe.outcome()).toBe('aborted');
+  });
+
+  it('drops the caller signal reference on clearHeavyState', () => {
+    const graph = new StandardGraph({
+      runId: 'run_1',
+      agents: [makeAgent('agent')],
+    });
+    graph.callerSignal = new AbortController().signal;
+    graph.clearHeavyState();
+    expect(graph.callerSignal).toBeUndefined();
+  });
+});

package/src/hooks/HookRegistry.ts

@@ -247,6 +247,34 @@ export class HookRegistry {
     return readList(bucket, event).length > 0;
   }
 
+  /**
+   * True when at least one matcher for `event` would actually DISPATCH on a
+   * query-less call — a wildcard pattern with a non-empty `hooks` array.
+   *
+   * `hasHookFor` answers "is one registered", which is not the same question:
+   * a matcher carrying a pattern is inert for events that supply no
+   * `matchQuery`, so a caller using registration as a proxy for "something
+   * will run" can act on a hook that never fires. Mirrors the two skips in
+   * `executeHooks` (pattern mismatch, empty `hooks`).
+   *
+   * Non-allocating on purpose — `StandardGraph.canClaimPreemptSeal` reads it
+   * once per streamed chunk, where `getMatchers`' defensive `slice()` would
+   * allocate on every delta.
+   */
+  hasDispatchableHookFor(event: HookEvent, sessionId?: string): boolean {
+    if (hasDispatchableInList(readList(this.global, event))) {
+      return true;
+    }
+    if (sessionId === undefined) {
+      return false;
+    }
+    const bucket = this.sessions.get(sessionId);
+    if (bucket === undefined) {
+      return false;
+    }
+    return hasDispatchableInList(readList(bucket, event));
+  }
+
   private ensureSessionBucket(sessionId: string): MatcherBucket {
     const existing = this.sessions.get(sessionId);
     if (existing !== undefined) {
@@ -278,6 +306,18 @@ function readList(
   return bucket[event] ?? [];
 }
 
+function hasDispatchableInList(list: HookMatcher<HookEvent>[]): boolean {
+  for (const matcher of list) {
+    if (
+      (matcher.pattern === undefined || matcher.pattern === '') &&
+      matcher.hooks.length > 0
+    ) {
+      return true;
+    }
+  }
+  return false;
+}
+
 function hasResultAlteringInBucket(bucket: MatcherBucket): boolean {
   for (const event of RESULT_ALTERING_HOOK_EVENTS) {
     if (readList(bucket, event).length > 0) {

package/src/hooks/__tests__/preemptBoundary.test.ts

@@ -0,0 +1,152 @@
+// src/hooks/__tests__/preemptBoundary.test.ts
+import type { HookMatcher, HookCallback, HookOutput } from '../types';
+import { HOOK_EVENTS } from '../types';
+import { HookRegistry } from '../HookRegistry';
+import { executeHooks } from '../executeHooks';
+import {
+  HOOK_PREEMPT_BOUNDARY_CAPABLE,
+  HOOK_INJECTED_MESSAGES_CAPABLE,
+} from '../index';
+
+const noop: HookCallback<
+  'PreemptBoundary'
+> = async (): Promise<HookOutput> => ({});
+
+function makeMatcher(
+  hook: HookCallback<'PreemptBoundary'> = noop
+): HookMatcher<'PreemptBoundary'> {
+  return { hooks: [hook] };
+}
+
+describe('PreemptBoundary hook event', () => {
+  it('is part of the closed event set', () => {
+    expect(HOOK_EVENTS).toContain('PreemptBoundary');
+  });
+
+  it('advertises its own capability flag, separate from injectedMessages', () => {
+    expect(HOOK_PREEMPT_BOUNDARY_CAPABLE).toBe(true);
+    expect(HOOK_INJECTED_MESSAGES_CAPABLE).toBe(true);
+  });
+
+  /**
+   * Load-bearing: `hasResultAlteringHooks` gates eager tool execution. If
+   * `PreemptBoundary` ever counted as result-altering, registering a steering
+   * drain would silently disable eager dispatch for every steering run.
+   */
+  it('is not result-altering, so eager tool execution stays enabled', () => {
+    const registry = new HookRegistry();
+    registry.register('PreemptBoundary', makeMatcher());
+    expect(registry.hasResultAlteringHooks()).toBe(false);
+  });
+
+  it('still reports result-altering when a tool hook is also registered', () => {
+    const registry = new HookRegistry();
+    registry.register('PreemptBoundary', makeMatcher());
+    registry.register('PreToolUse', { hooks: [async () => ({})] });
+    expect(registry.hasResultAlteringHooks()).toBe(true);
+  });
+
+  /**
+   * `hasHookFor` answers "is one registered"; the seal gate needs "will one
+   * fire". A pattern-scoped matcher is inert for a query-less dispatch, so
+   * treating registration as a proxy would seal into a boundary that injects
+   * nothing and cut the answer short.
+   */
+  describe('hasDispatchableHookFor', () => {
+    it('is true for a wildcard matcher with a callback', () => {
+      const registry = new HookRegistry();
+      registry.register('PreemptBoundary', makeMatcher());
+      expect(registry.hasDispatchableHookFor('PreemptBoundary')).toBe(true);
+    });
+
+    it('is false for a pattern-scoped matcher that can never match', () => {
+      const registry = new HookRegistry();
+      registry.register('PreemptBoundary', { pattern: 'Bash', hooks: [noop] });
+      expect(registry.hasHookFor('PreemptBoundary')).toBe(true);
+      expect(registry.hasDispatchableHookFor('PreemptBoundary')).toBe(false);
+    });
+
+    it('is false for a matcher carrying no callbacks', () => {
+      const registry = new HookRegistry();
+      registry.register('PreemptBoundary', { hooks: [] });
+      expect(registry.hasDispatchableHookFor('PreemptBoundary')).toBe(false);
+    });
+
+    it('is false when nothing is registered at all', () => {
+      const registry = new HookRegistry();
+      expect(registry.hasDispatchableHookFor('PreemptBoundary')).toBe(false);
+    });
+
+    it('finds a session-scoped dispatchable matcher', () => {
+      const registry = new HookRegistry();
+      registry.registerSession('run_1', 'PreemptBoundary', makeMatcher());
+      expect(registry.hasDispatchableHookFor('PreemptBoundary')).toBe(false);
+      expect(registry.hasDispatchableHookFor('PreemptBoundary', 'run_1')).toBe(
+        true
+      );
+    });
+  });
+
+  it('keeps registration isolated from the tool boundary event', () => {
+    const registry = new HookRegistry();
+    const matcher = makeMatcher();
+    registry.register('PreemptBoundary', matcher);
+    expect(registry.getMatchers('PreemptBoundary')).toEqual([matcher]);
+    expect(registry.getMatchers('PostToolBatch')).toEqual([]);
+  });
+
+  it('aggregates injectedMessages from the boundary dispatch', async () => {
+    const registry = new HookRegistry();
+    registry.register(
+      'PreemptBoundary',
+      makeMatcher(async () => ({
+        injectedMessages: [
+          { role: 'user', content: 'Skip phase two.', source: 'steer' },
+        ],
+      }))
+    );
+
+    const result = await executeHooks({
+      registry,
+      input: {
+        hook_event_name: 'PreemptBoundary',
+        runId: 'run_1',
+        executingAgentId: 'agent_1',
+        sealCount: 1,
+      },
+      sessionId: 'run_1',
+    });
+
+    expect(result.injectedMessages).toEqual([
+      { role: 'user', content: 'Skip phase two.', source: 'steer' },
+    ]);
+    expect(result.errors).toEqual([]);
+  });
+
+  it('reports the 1-based seal index to the hook', async () => {
+    const registry = new HookRegistry();
+    const seen: number[] = [];
+    registry.register(
+      'PreemptBoundary',
+      makeMatcher(async (input) => {
+        seen.push(input.sealCount);
+        return {};
+      })
+    );
+
+    for (const sealCount of [1, 2]) {
+      await executeHooks({
+        registry,
+        input: {
+          hook_event_name: 'PreemptBoundary',
+          runId: 'run_1',
+          executingAgentId: 'agent_1',
+          sealCount,
+        },
+        sessionId: 'run_1',
+      });
+    }
+
+    expect(seen).toEqual([1, 2]);
+  });
+});

package/src/hooks/index.ts

@@ -4,8 +4,9 @@
 // `src/index.ts` and consumed by `Run.processStream` (RunStart,
 // UserPromptSubmit, Stop, StopFailure), `ToolNode.dispatchToolEvents`
 // (PreToolUse, PostToolUse, PostToolUseFailure, PermissionDenied),
-// `createSummarizeNode` (PreCompact, PostCompact), and
-// `SubagentExecutor.execute` (SubagentStart, SubagentStop).
+// `createSummarizeNode` (PreCompact, PostCompact),
+// `SubagentExecutor.execute` (SubagentStart, SubagentStop), and
+// `StandardGraph.createCallModel` (PreemptBoundary).
 export { HookRegistry } from './HookRegistry';
 export type { HookHaltSignal } from './HookRegistry';
 export { executeHooks, DEFAULT_HOOK_TIMEOUT_MS } from './executeHooks';
@@ -16,6 +17,17 @@ export { executeHooks, DEFAULT_HOOK_TIMEOUT_MS } from './executeHooks';
  * be consumed by an SDK version that would silently drop it.
  */
 export const HOOK_INJECTED_MESSAGES_CAPABLE = true;
+/**
+ * Feature probe for hosts: this SDK dispatches `PreemptBoundary`, so a
+ * cooperative mid-generation seal can drain into the run.
+ *
+ * Deliberately separate from {@link HOOK_INJECTED_MESSAGES_CAPABLE} — an SDK
+ * version can support `injectedMessages` at the tool boundary and know
+ * nothing about preemption. A host that probed the wrong flag would arm an
+ * interrupt control whose seal request is silently ignored, which reads to
+ * the user as a dead button rather than as an unsupported feature.
+ */
+export const HOOK_PREEMPT_BOUNDARY_CAPABLE = true;
 export {
   matchesQuery,
   hasNestedQuantifier,
@@ -52,6 +64,7 @@ export type {
   PostToolUseFailureHookInput,
   PostToolBatchHookInput,
   PostToolBatchEntry,
+  PreemptBoundaryHookInput,
   PermissionDeniedHookInput,
   SubagentStartHookInput,
   SubagentStopHookInput,
@@ -65,6 +78,7 @@ export type {
   PostToolUseHookOutput,
   PostToolUseFailureHookOutput,
   PostToolBatchHookOutput,
+  PreemptBoundaryHookOutput,
   PermissionDeniedHookOutput,
   SubagentStartHookOutput,
   SubagentStopHookOutput,

package/src/hooks/types.ts

@@ -17,6 +17,7 @@ export const HOOK_EVENTS = [
   'PostToolUse',
   'PostToolUseFailure',
   'PostToolBatch',
+  'PreemptBoundary',
   'PermissionDenied',
   'SubagentStart',
   'SubagentStop',
@@ -145,6 +146,39 @@ export interface PostToolBatchHookInput extends BaseHookInput {
   entries: PostToolBatchEntry[];
 }
 
+/**
+ * Fires when a cooperative preemption seals the model stream mid-generation
+ * — the second injection boundary, and the only one that exists during a
+ * long text answer with no tool calls in it.
+ *
+ * Order: fires after the model stream is sealed and BEFORE the next model
+ * call. The `injectedMessages` a hook returns here are appended verbatim and
+ * the agent node self-loops. Returning nothing is a valid outcome (the host's
+ * queue was cancelled or already drained): the run stops honestly rather than
+ * self-looping into an empty turn.
+ *
+ * The sealed turn is NOT yet observable from graph state when this fires.
+ * Dispatch happens inside the agent node, and only the outer graph's reducer
+ * writes `StandardGraph.messages` — which cannot run until the node returns.
+ * A hook calling `Run.getRunMessages()` here sees the state as of the last
+ * completed superstep, so the sealed text is absent. `PostToolBatch` behaves
+ * the same way: a tool-boundary hook cannot see the assistant turn that
+ * requested the tool. This is a property of the single-node outer graph, not
+ * of preemption, and committing first would mean returning from the node and
+ * re-entering — precisely what the self-loop exists to avoid.
+ *
+ * A hook that needs the sealed text should therefore not go looking for it in
+ * graph state. Decide from the host's own queue, or read it after the run.
+ *
+ * Requires `RunConfig.preemption`. This event is deliberately NOT
+ * result-altering, so registering it never disables eager tool execution.
+ */
+export interface PreemptBoundaryHookInput extends BaseHookInput {
+  hook_event_name: 'PreemptBoundary';
+  /** 1-based index of this seal within the run. */
+  sealCount: number;
+}
+
 export interface PermissionDeniedHookInput extends BaseHookInput {
   hook_event_name: 'PermissionDenied';
   toolName: string;
@@ -217,6 +251,7 @@ export type HookInput =
   | PostToolUseHookInput
   | PostToolUseFailureHookInput
   | PostToolBatchHookInput
+  | PreemptBoundaryHookInput
   | PermissionDeniedHookInput
   | SubagentStartHookInput
   | SubagentStopHookInput
@@ -233,6 +268,7 @@ export type HookInputByEvent = {
   PostToolUse: PostToolUseHookInput;
   PostToolUseFailure: PostToolUseFailureHookInput;
   PostToolBatch: PostToolBatchHookInput;
+  PreemptBoundary: PreemptBoundaryHookInput;
   PermissionDenied: PermissionDeniedHookInput;
   SubagentStart: SubagentStartHookInput;
   SubagentStop: SubagentStopHookInput;
@@ -251,14 +287,18 @@ export interface BaseHookOutput {
   additionalContext?: string;
   /**
    * Messages to inject into graph state, one `HumanMessage` per entry
-   * (converted via `ToolNode.convertInjectedMessages`, which preserves
+   * (converted via `convertInjectedMessages`, which preserves
    * `role`/`source`/`isMeta` in `additional_kwargs`). Unlike
    * `additionalContext` — which is consolidated across hooks into a single
    * system-flavored message — each entry keeps its own identity and role,
    * making this the channel for injecting verbatim user speech (e.g. a
    * mid-run steering message). Accumulated across hooks in registration
-   * order. Currently consumed only at the `PostToolBatch` dispatch site;
-   * other events ignore the field.
+   * order.
+   *
+   * Consumed at exactly two dispatch sites, both of which run the same
+   * converter so the emitted shapes cannot drift: `PostToolBatch` (the tool
+   * boundary) and `PreemptBoundary` (a cooperative mid-generation seal).
+   * Every other event ignores the field.
    */
   injectedMessages?: InjectedMessage[];
   /** True to prevent the next model turn. Any hook can set this. */
@@ -367,6 +407,8 @@ export type PostToolUseFailureHookOutput = BaseHookOutput;
 
 export type PostToolBatchHookOutput = BaseHookOutput;
 
+export type PreemptBoundaryHookOutput = BaseHookOutput;
+
 export type PermissionDeniedHookOutput = BaseHookOutput;
 
 export interface SubagentStartHookOutput extends BaseHookOutput {
@@ -395,6 +437,7 @@ export type HookOutputByEvent = {
   PostToolUse: PostToolUseHookOutput;
   PostToolUseFailure: PostToolUseFailureHookOutput;
   PostToolBatch: PostToolBatchHookOutput;
+  PreemptBoundary: PreemptBoundaryHookOutput;
   PermissionDenied: PermissionDeniedHookOutput;
   SubagentStart: SubagentStartHookOutput;
   SubagentStop: SubagentStopHookOutput;
@@ -412,6 +455,7 @@ export type HookOutput =
   | PostToolUseHookOutput
   | PostToolUseFailureHookOutput
   | PostToolBatchHookOutput
+  | PreemptBoundaryHookOutput
   | PermissionDeniedHookOutput
   | SubagentStartHookOutput
   | SubagentStopHookOutput

package/src/index.ts

@@ -1,7 +1,6 @@
 /* Main Operations */
 export * from './run';
 export * from './stream';
-export * from './splitStream';
 export * from './events';
 export * from './messages';
 
@@ -80,4 +79,5 @@ export { getChatModelClass } from './llm/providers';
 export { FakeChatModel, createFakeStreamingLLM } from './llm/fake';
 export { initializeModel } from './llm/init';
 export { attemptInvoke, tryFallbackProviders } from './llm/invoke';
+export { canSealPreempt } from './llm/preempt';
 export { isThinkingEnabled, getMaxOutputTokensKey } from './llm/request';

package/src/langfuse.ts

@@ -1,7 +1,7 @@
 import { CallbackHandler } from '@langfuse/langchain';
-import { isParentCommand } from '@langchain/langgraph';
 import { context as otelContext } from '@opentelemetry/api';
 import { AIMessage, AIMessageChunk } from '@langchain/core/messages';
+import { isGraphInterrupt, isParentCommand } from '@langchain/langgraph';
 import {
   getLangfuseTracerProvider,
   propagateAttributes,
@@ -27,6 +27,10 @@ import { isPresent, parseBooleanEnv } from '@/utils/misc';
 
 const TRACE_METADATA_MAX_LENGTH = 200;
 const LANGFUSE_FORCE_FLUSH_ON_DISPOSE = 'LANGFUSE_FORCE_FLUSH_ON_DISPOSE';
+const GRAPH_INTERRUPT_CONTROL_FLOW = { controlFlow: 'GraphInterrupt' } as const;
+const GRAPH_INTERRUPT_TOOL_OUTPUT = JSON.stringify(
+  GRAPH_INTERRUPT_CONTROL_FLOW
+);
 
 export type LangfuseTraceMetadata = Record<string, string>;
 export type LangfuseTraceAttributes = Record<string, string | number | boolean>;
@@ -209,6 +213,13 @@ class ScopedLangfuseCallbackHandler extends CallbackHandler {
     ...args: Parameters<CallbackHandler['handleChainError']>
   ): ReturnType<CallbackHandler['handleChainError']> {
     const [error, runId, parentRunId] = args;
+    if (error != null && parentRunId != null && isGraphInterrupt(error)) {
+      return super.handleChainEnd(
+        GRAPH_INTERRUPT_CONTROL_FLOW,
+        runId,
+        parentRunId
+      );
+    }
     if (error != null && parentRunId != null && isParentCommand(error)) {
       return super.handleChainEnd(
         { controlFlow: 'ParentCommand' },
@@ -261,6 +272,20 @@ class ScopedLangfuseCallbackHandler extends CallbackHandler {
     return this.withRuntimeContext(() => super.handleToolStart(...args));
   }
 
+  override handleToolError(
+    ...args: Parameters<CallbackHandler['handleToolError']>
+  ): ReturnType<CallbackHandler['handleToolError']> {
+    const [error, runId, parentRunId] = args;
+    if (error != null && parentRunId != null && isGraphInterrupt(error)) {
+      return super.handleToolEnd(
+        GRAPH_INTERRUPT_TOOL_OUTPUT,
+        runId,
+        parentRunId
+      );
+    }
+    return super.handleToolError(...args);
+  }
+
   override handleRetrieverStart(
     ...args: Parameters<CallbackHandler['handleRetrieverStart']>
   ): ReturnType<CallbackHandler['handleRetrieverStart']> {

package/src/llm/bedrock/utils/message_inputs.test.ts

@@ -450,3 +450,85 @@ describe('convertToConverseMessages — v1 reasoning serialization', () => {
     expect(content.some((b) => b.text === 'answer')).toBe(true);
   });
 });
+
+/**
+ * Converse rejects consecutive same-role messages categorically, and both
+ * `ToolMessage` and `HumanMessage` convert to `role: 'user'` — so a hook
+ * injection landing a text turn directly after tool results (`PostToolBatch`
+ * / `PreemptBoundary` drains) must merge into one user message here, with
+ * block order preserved so the toolUse/toolResult pairing stays intact.
+ */
+describe('convertToConverseMessages — user-role run merging', () => {
+  it('merges a tool result followed by an injected text turn into one user message', () => {
+    const messages: BaseMessage[] = [
+      new HumanMessage('run the search'),
+      new AIMessage({
+        content: '',
+        tool_calls: [
+          { id: 'call_1', name: 'search', args: {}, type: 'tool_call' },
+        ],
+      }),
+      new ToolMessage({
+        content: 'search output',
+        tool_call_id: 'call_1',
+        name: 'search',
+      }),
+      new HumanMessage({
+        content: 'Actually, focus on the second result.',
+        additional_kwargs: { source: 'steer' },
+      }),
+    ];
+
+    const { converseMessages } = convertToConverseMessages(messages);
+
+    expect(converseMessages.map((m) => m.role)).toEqual([
+      'user',
+      'assistant',
+      'user',
+    ]);
+    const merged = converseMessages[2];
+    const blockKinds = (merged.content ?? []).map((block) =>
+      'toolResult' in block ? 'toolResult' : 'text'
+    );
+    expect(blockKinds).toEqual(['toolResult', 'text']);
+    expect(
+      (merged.content ?? []).find((block) => 'text' in block)?.text
+    ).toBe('Actually, focus on the second result.');
+  });
+
+  it('still merges adjacent tool-result-only turns', () => {
+    const messages: BaseMessage[] = [
+      new AIMessage({
+        content: '',
+        tool_calls: [
+          { id: 'call_1', name: 'a', args: {}, type: 'tool_call' },
+          { id: 'call_2', name: 'b', args: {}, type: 'tool_call' },
+        ],
+      }),
+      new ToolMessage({ content: 'one', tool_call_id: 'call_1', name: 'a' }),
+      new ToolMessage({ content: 'two', tool_call_id: 'call_2', name: 'b' }),
+    ];
+
+    const { converseMessages } = convertToConverseMessages(messages);
+
+    expect(converseMessages.map((m) => m.role)).toEqual(['assistant', 'user']);
+    const toolResultIds = (converseMessages[1].content ?? [])
+      .map((block) => ('toolResult' in block ? block.toolResult?.toolUseId : undefined))
+      .filter(Boolean);
+    expect(toolResultIds).toEqual(['call_1', 'call_2']);
+  });
+
+  it('does not merge across an assistant turn', () => {
+    const messages: BaseMessage[] = [
+      new HumanMessage('first'),
+      new AIMessage('answer'),
+      new HumanMessage('second'),
+    ];
+    const { converseMessages } = convertToConverseMessages(messages);
+    expect(converseMessages.map((m) => m.role)).toEqual([
+      'user',
+      'assistant',
+      'user',
+    ]);
+  });
+});