@librechat/agents 3.7.7 → 3.7.9

package/src/run.ts

@@ -3,27 +3,28 @@ import { nanoid } from 'nanoid';
 import { PromptTemplate } from '@langchain/core/prompts';
 import { RunnableLambda } from '@langchain/core/runnables';
 import { BaseCallbackHandler } from '@langchain/core/callbacks/base';
-import {
-  Command,
-  INTERRUPT,
-  MemorySaver,
-  isInterrupted,
-} from '@langchain/langgraph';
 import {
   AIMessage,
   BaseMessage,
   HumanMessage,
   SystemMessage,
 } from '@langchain/core/messages';
+import {
+  Command,
+  INTERRUPT,
+  MemorySaver,
+  Overwrite,
+  isInterrupted,
+} from '@langchain/langgraph';
 import type {
   MessageContentComplex,
   UsageMetadata,
 } from '@langchain/core/messages';
 import type { StringPromptValue } from '@langchain/core/prompt_values';
 import type { RunnableConfig } from '@langchain/core/runnables';
+import type { AggregatedHookResult, HookRegistry } from '@/hooks';
 import type { MultiAgentGraph } from '@/graphs/MultiAgentGraph';
 import type { StandardGraph } from '@/graphs/Graph';
-import type { HookRegistry } from '@/hooks';
 import type * as t from '@/types';
 import {
   Callback,
@@ -33,9 +34,9 @@ import {
   REASONING_LABEL_RUN_NAME,
   ACTIVITY_PHASE_RUN_NAME,
   ACTIVITY_PHASE_LABEL_RUN_NAME,
+  DEFAULT_MAX_STOP_CONTINUATIONS,
   DEFAULT_RECURSION_LIMIT,
 } from '@/common';
-import { isBuiltRuntime } from '@/lazyRequire';
 import {
   requireValidSubagentResumeManifest,
   stripSubagentResumeManifest,
@@ -94,15 +95,18 @@ import { applyGraphRuntimeConfig } from '@/graphs/applyGraphRuntimeConfig';
 import { LANGFUSE_OPERATION_METADATA_KEY } from '@/langfuseOperation';
 import { createTokenCounter, encodingForModel } from '@/utils/tokens';
 import { stampSyntheticProviderMessage } from '@/messages/provenance';
+import { isOpenAILike, isLibreChatOpenAIModel } from '@/utils/llm';
+import { executeHooks, mergeAggregatedHookResults } from '@/hooks';
+import { convertInjectedMessages } from '@/messages/injected';
 import { initializeLangfuseTracing } from './instrumentation';
 import { seedRunInitialSessions } from '@/utils/toolSessions';
 import { getTraceIdSeed } from '@/langfuseRuntimeContext';
+import { resolveClientOptionsModel } from '@/llm/request';
 import { createGraph } from '@/graphs/createGraph';
 import { resolveMaxSeals } from '@/llm/preempt';
+import { isBuiltRuntime } from '@/lazyRequire';
 import { initializeModel } from '@/llm/init';
 import { HandlerRegistry } from '@/events';
-import { isOpenAILike, isLibreChatOpenAIModel } from '@/utils/llm';
-import { executeHooks } from '@/hooks';
 
 /** Source-mode runs have no dist siblings for the lazy-loading seam, so every
  *  lazily loadable module is imported through the active loader before the
@@ -130,6 +134,61 @@ export const defaultOmitOptions = new Set([
 const ACTIVITY_LABEL_TRACE_NAME = 'LibreChat Activity Label';
 const ACTIVITY_PHASE_TRACE_NAME = 'LibreChat Activity Phase';
 const REASONING_LABEL_TRACE_NAME = 'LibreChat Reasoning Label';
+const OUTPUT_TRUNCATED_HALT_REASON = 'output_truncated';
+
+function resolveMaxStopContinuations(value: number | undefined): number {
+  if (value == null || !Number.isFinite(value)) {
+    return DEFAULT_MAX_STOP_CONTINUATIONS;
+  }
+  return Math.max(0, Math.floor(value));
+}
+
+function materializeStopContinuation(
+  result: AggregatedHookResult
+): BaseMessage[] {
+  const messages: BaseMessage[] = [];
+  const contexts = result.additionalContexts.filter(
+    (context) => context.trim() !== ''
+  );
+  if (contexts.length > 0) {
+    messages.push(
+      stampSyntheticProviderMessage(
+        new HumanMessage({
+          content: contexts.join('\n\n'),
+          additional_kwargs: {
+            role: 'system',
+            isMeta: true,
+            source: 'hook',
+          },
+        })
+      )
+    );
+  }
+  messages.push(...convertInjectedMessages(result.injectedMessages));
+  return messages;
+}
+
+function advanceCheckpointCursor(
+  config: t.RunStreamConfig
+): t.RunStreamConfig {
+  const configurable = { ...config.configurable };
+  delete configurable.checkpoint_id;
+  delete configurable.checkpoint_map;
+  return { ...config, configurable };
+}
+
+function assertFinalAdmissionSucceeded(result: AggregatedHookResult): void {
+  if (result.hasHookFailures !== true && result.errors.length === 0) {
+    return;
+  }
+  const detail =
+    result.errors.length > 0
+      ? result.errors.join('; ')
+      : 'one or more internal finalizers failed';
+  throw new Error(
+    `StopFinalize terminal admission failed: ${detail}`
+  );
+}
 
 const CUSTOM_GRAPH_EVENTS = new Set<string>([
   GraphEvents.ON_AGENT_UPDATE,
@@ -227,7 +286,10 @@ function getInterruptHookSessionId(payload: unknown): string | undefined {
 
 type InterruptStateSnapshot = {
   config?: RunnableConfig;
-  values?: { messages?: BaseMessage[] };
+  values?: {
+    messages?: BaseMessage[];
+    runStepState?: t.RunStepResumeState;
+  };
   tasks?: Array<{
     interrupts?: Array<{ id?: string; value?: unknown }>;
     state?: RunnableConfig | InterruptStateSnapshot;
@@ -240,10 +302,79 @@ type WorkflowWithStateHistory = {
     options?: { subgraphs?: boolean }
   ): Promise<InterruptStateSnapshot>;
   getStateHistory?(
-    config: RunnableConfig
+    config: RunnableConfig,
+    options?: { filter?: Record<string, unknown>; limit?: number }
   ): AsyncIterableIterator<InterruptStateSnapshot>;
 };
 
+async function resolveCompletedSegmentConfig(
+  workflow: t.CompiledStateWorkflow,
+  config: t.RunStreamConfig,
+  executionId: string,
+  streamSegment: number
+): Promise<t.RunStreamConfig> {
+  const stateWorkflow = workflow as t.CompiledStateWorkflow &
+    WorkflowWithStateHistory;
+  const stateHistory = stateWorkflow.getStateHistory;
+  if (typeof stateHistory !== 'function') {
+    throw new Error(
+      'Cannot continue a checkpointed run without exact state history.'
+    );
+  }
+  const lookup = advanceCheckpointCursor(config);
+
+  const resolveSnapshot = (
+    snapshot: InterruptStateSnapshot | undefined
+  ): t.RunStreamConfig | undefined => {
+    if (snapshot == null) {
+      return undefined;
+    }
+    const runStepState =
+      snapshot.values?.runStepState ??
+      snapshot.tasks
+        ?.flatMap((task) => task.interrupts ?? [])
+        .map((pendingInterrupt) =>
+          getRunStepResumeState(pendingInterrupt.value)
+        )
+        .find((state): state is t.RunStepResumeState => state != null);
+    if (
+      runStepState?.stopContinuationExecutionId !== executionId ||
+      runStepState.streamSegment !== streamSegment
+    ) {
+      return undefined;
+    }
+    const checkpointId = snapshot.config?.configurable?.checkpoint_id;
+    if (typeof checkpointId !== 'string' || checkpointId.length === 0) {
+      return undefined;
+    }
+    return {
+      ...config,
+      configurable: {
+        ...config.configurable,
+        ...snapshot.config?.configurable,
+      },
+    };
+  };
+
+  if (typeof stateWorkflow.getState === 'function') {
+    const latest = await stateWorkflow.getState(lookup);
+    const latestConfig = resolveSnapshot(latest);
+    if (latestConfig != null) {
+      return latestConfig;
+    }
+  }
+
+  for await (const snapshot of stateHistory.call(workflow, lookup)) {
+    const snapshotConfig = resolveSnapshot(snapshot);
+    if (snapshotConfig != null) {
+      return snapshotConfig;
+    }
+  }
+  throw new Error(
+    'Cannot identify the checkpoint committed by the completed graph segment.'
+  );
+}
+
 function getFirstPersistedInterrupt(
   snapshot: InterruptStateSnapshot
 ): { id: string; value: unknown } | undefined {
@@ -283,6 +414,27 @@ function getPersistedMessages(
 
 type ResumeCommandUpdate = ConstructorParameters<typeof Command>[0]['update'];
 
+function overwriteResumeRunStepState(
+  command: Command,
+  state: t.RunStepResumeState
+): Command {
+  const overwrite = new Overwrite(state);
+  const update = Array.isArray(command.update)
+    ? [
+      ...command.update.filter(([key]) => key !== 'runStepState'),
+      ['runStepState', overwrite] as [string, unknown],
+    ]
+    : { ...(command.update ?? {}), runStepState: overwrite };
+  const resumed = new Command({
+    ...(command.graph == null ? {} : { graph: command.graph }),
+    ...(command.resume === undefined ? {} : { resume: command.resume }),
+    update,
+    ...(command.goto === undefined ? {} : { goto: command.goto }),
+  });
+  resumed.lc_direct_tool_output = command.lc_direct_tool_output;
+  return resumed;
+}
+
 function getResumeUpdateMessages(
   update: ResumeCommandUpdate
 ): BaseMessage[] | undefined {
@@ -315,6 +467,7 @@ export class Run<_T extends t.BaseGraphState> {
   private toolExecution?: t.ToolExecutionConfig;
   private subagentUsageSink?: t.SubagentUsageSink;
   private preemption?: t.StreamPreemption;
+  private maxStopContinuations: number;
   private streamLimits?: t.StreamLimits;
   private subagentTasks?: t.SubagentTaskConfig;
   private indexTokenCountMap?: Record<string, number>;
@@ -386,6 +539,9 @@ export class Run<_T extends t.BaseGraphState> {
     this.subagentUsageSink = config.subagentUsageSink;
     this.subagentTasks = config.subagentTasks;
     this.preemption = config.preemption;
+    this.maxStopContinuations = resolveMaxStopContinuations(
+      config.maxStopContinuations
+    );
     this.streamLimits = config.streamLimits;
 
     if (!config.graphConfig) {
@@ -728,12 +884,16 @@ export class Run<_T extends t.BaseGraphState> {
     config: t.RunConfig
   ): Promise<Run<T>> {
     await ensureSourceModeProviders();
-    /** Create tokenCounter if indexTokenCountMap is provided but tokenCounter is not */
+    /** Create tokenCounter if indexTokenCountMap is provided but tokenCounter is
+     *  not. The model is read through both option keys: `modelName` is
+     *  LangChain's alias for `model`, so consulting one alone would give a
+     *  Claude-backed agent an `o200k_base` counter and undercount every message
+     *  it measures. */
     if (config.indexTokenCountMap && !config.tokenCounter) {
       const gc = config.graphConfig;
       const clientOpts =
         'agents' in gc ? gc.agents[0]?.clientOptions : gc.clientOptions;
-      const model = (clientOpts as { model?: string } | undefined)?.model ?? '';
+      const model = resolveClientOptionsModel(clientOpts) ?? '';
       config.tokenCounter = await createTokenCounter(encodingForModel(model));
     }
     return new Run<T>(config);
@@ -794,6 +954,18 @@ export class Run<_T extends t.BaseGraphState> {
     return this.Graph?.getToolCount() ?? 0;
   }
 
+  /**
+   * True when the run's last turn ended at `END` because the provider hit
+   * its output token ceiling while producing plain text/reasoning — no tool
+   * call, so `assertNotTruncatedToolCall` never sees it and the graph reads
+   * the turn as an ordinary completion. Hosts check this alongside
+   * `getPreemptStats()` / `getHaltReason()` to decide whether to persist the
+   * response as unfinished instead of a silently truncated "complete" one.
+   */
+  getOutputTruncated(): boolean {
+    return this.Graph?.outputTruncatedIncomplete ?? false;
+  }
+
   /**
    * Creates a custom event callback handler that intercepts custom events
    * and processes them through our handler registry instead of EventStreamCallbackHandler
@@ -1042,11 +1214,16 @@ export class Run<_T extends t.BaseGraphState> {
       delete config.configurable?.[SUBAGENT_RESUME_ATTEMPT_CONFIG_KEY];
       delete config.configurable?.[SUBAGENT_RESUME_MANIFEST_CONFIG_KEY];
     }
+    let overwriteLegacyResumeState = false;
     if (isResume) {
       await this.restoreInterruptFromCheckpoint(
         config,
         (inputs as Command).update
       );
+      if (graph.getStopContinuationExecutionId() === '') {
+        graph.startStopContinuationExecution(nanoid());
+        overwriteLegacyResumeState = this.hasCheckpointer;
+      }
     }
 
     /**
@@ -1097,6 +1274,7 @@ export class Run<_T extends t.BaseGraphState> {
             checkpointId === '' ? 0 : ++this.checkpointForkSeq,
           ]);
       graph.resetValues(streamOptions?.keepContent, checkpointScope);
+      graph.startStopContinuationExecution(nanoid());
     }
     this._interrupt = undefined;
     this._haltedReason = undefined;
@@ -1162,6 +1340,7 @@ export class Run<_T extends t.BaseGraphState> {
           : undefined,
       traceAnchor: graph.langfuseTraceAnchor,
       runId: graph.langfuseScopeRunId,
+      deferRootRunId: this.id,
       // The aggregate multi-agent policy from the runtime scope — the
       // handler must restore THIS (not the primary agent's config-derived
       // policy) when rejecting a foreign scope.
@@ -1176,6 +1355,7 @@ export class Run<_T extends t.BaseGraphState> {
       throw new Error('Run ID not provided');
     }
 
+    config.runId = this.id;
     config.run_id = this.id;
     config.configurable = Object.assign(config.configurable ?? {}, {
       run_id: this.id,
@@ -1224,191 +1404,209 @@ export class Run<_T extends t.BaseGraphState> {
     let terminalAt: number | undefined;
 
     const consumeStream = async (): Promise<void> => {
-      /**
-       * `streamEvents` accepts both state inputs and `Command` (resume) at
-       * runtime, but our `CompiledStateWorkflow` type narrows the first
-       * arg to `BaseGraphState`. Cast on the call so the resume path
-       * type-checks without widening the wrapper for every caller.
-       */
-      const stream = graphRunnable.streamEvents(
-        inputs as t.IState,
-        { ...config, runName: graph.runName },
-        {
-          raiseError: true,
-          /**
-           * Prevent EventStreamCallbackHandler from processing custom events.
-           * Custom events are already handled via our createCustomEventCallback()
-           * which routes them through the handlerRegistry.
-           * Without this flag, EventStreamCallbackHandler throws errors when
-           * custom events are dispatched for run IDs not in its internal map
-           * (due to timing issues in parallel execution or after run cleanup).
-           */
-          ignoreCustomEvent: true,
-        }
-      );
+      let streamInputs: t.IState | Command = inputs;
+      if (!isResume && this.hasCheckpointer) {
+        streamInputs = {
+          ...(inputs as t.IState),
+          runStepState: new Overwrite(graph.createRunStepResumeState()),
+        } as unknown as t.IState;
+      } else if (overwriteLegacyResumeState) {
+        streamInputs = overwriteResumeRunStepState(
+          inputs as Command,
+          graph.createRunStepResumeState()
+        );
+      }
+      let streamConfig = config;
 
-      for await (const event of stream) {
-        const { data, metadata, ...info } = event;
+      for (;;) {
+        /**
+         * `streamEvents` accepts both state inputs and `Command` (resume) at
+         * runtime, but our `CompiledStateWorkflow` type narrows the first
+         * arg to `BaseGraphState`. Cast on the call so the resume path
+         * type-checks without widening the wrapper for every caller.
+         */
+        const stream = graphRunnable.streamEvents(
+          streamInputs as t.IState,
+          { ...streamConfig, runName: graph.runName },
+          {
+            raiseError: true,
+            /** Custom events are handled by createCustomEventCallback(). */
+            ignoreCustomEvent: true,
+          }
+        );
 
-        const eventName: t.EventName = info.event;
+        for await (const event of stream) {
+          const { data, metadata, ...info } = event;
+          const eventName: t.EventName = info.event;
 
-        /** Skip custom events as they're handled by our callback */
-        if (CUSTOM_GRAPH_EVENTS.has(eventName)) {
-          continue;
-        }
+          if (CUSTOM_GRAPH_EVENTS.has(eventName)) {
+            continue;
+          }
 
-        /**
-         * Detect interrupts surfaced by LangGraph as a synthetic
-         * `__interrupt__` field on the streamed chunk and stash the
-         * first one for the host to read via `run.getInterrupt()`
-         * once the stream drains. Captured as `unknown` because the
-         * SDK does not validate the runtime payload shape — the
-         * built-in ToolNode raises a `HumanInterruptPayload`
-         * (`tool_approval` / `ask_user_question`), but custom nodes
-         * can pass any payload to `interrupt()`. Callers narrow with
-         * the `isToolApprovalInterrupt` / `isAskUserQuestionInterrupt`
-         * guards or assert via `getInterrupt<T>()`.
-         */
-        if (
-          this._interrupt == null &&
-          data.chunk != null &&
-          isInterrupted<unknown>(data.chunk)
-        ) {
-          const interrupts = data.chunk[INTERRUPT];
-          if (interrupts.length > 0) {
-            const first = interrupts[0];
-            /**
-             * Capture the interrupt unconditionally — `interrupt(null)`
-             * and `interrupt(undefined)` are valid pauses (a custom
-             * node may want to pause without metadata) and the host
-             * still needs to know the run is awaiting resume. Gating
-             * on `payload != null` would silently downgrade a paused
-             * run to "completed" and let the `Stop` hook fire,
-             * breaking host resume handling.
-             */
-            this._interrupt = {
-              interruptId: first.id ?? '',
-              threadId,
-              payload: first.value,
-            };
+          if (
+            this._interrupt == null &&
+            data.chunk != null &&
+            isInterrupted<unknown>(data.chunk)
+          ) {
+            const interrupts = data.chunk[INTERRUPT];
+            if (interrupts.length > 0) {
+              const first = interrupts[0];
+              this._interrupt = {
+                interruptId: first.id ?? '',
+                threadId,
+                payload: first.value,
+              };
+            }
+          }
+
+          const modelEndAt =
+            eventName === GraphEvents.CHAT_MODEL_END ? Date.now() : undefined;
+          const handler = this.handlerRegistry?.getHandler(eventName);
+          if (handler) {
+            await handler.handle(eventName, data, metadata, this.Graph);
+          }
+
+          if (eventName === GraphEvents.CHAT_MODEL_END && this.Graph != null) {
+            await this.Graph.closeOpenMessageStep(metadata, modelEndAt);
+          }
+
+          const haltSignal = this.hookRegistry?.getHaltSignal(this.id);
+          if (haltSignal != null) {
+            this._haltedReason = haltSignal.reason;
+            break;
           }
         }
 
-        /**
-         * Stamped before the handler runs: the close below happens after an
-         * arbitrarily slow host handler resolves, and the step's duration
-         * should end when the model did, not when the host finished with it.
-         */
-        const modelEndAt =
-          eventName === GraphEvents.CHAT_MODEL_END ? Date.now() : undefined;
-        const handler = this.handlerRegistry?.getHandler(eventName);
-        if (handler) {
-          await handler.handle(eventName, data, metadata, this.Graph);
+        terminalAt = Date.now();
+
+        if (this._interrupt != null) {
+          const interruptConfig = this.hasCheckpointer
+            ? advanceCheckpointCursor(streamConfig)
+            : streamConfig;
+          await this.resolveInterruptResumeConfig(interruptConfig);
+          return;
+        }
+        if (this._haltedReason != null) {
+          return;
         }
 
-        /**
-         * A finished model call ends its lane's open message step. Placed
-         * here — not in `ModelEndHandler` — because hosts replace the
-         * CHAT_MODEL_END handler with their own instance, which would
-         * silently drop the close.
-         */
-        if (eventName === GraphEvents.CHAT_MODEL_END && this.Graph != null) {
-          await this.Graph.closeOpenMessageStep(metadata, modelEndAt);
+        let stopReason = graph.preemptHaltReason;
+        if (stopReason == null && graph.preemptIncomplete) {
+          stopReason = 'preempt_incomplete';
+        }
+        if (stopReason == null && graph.outputTruncatedIncomplete) {
+          stopReason = OUTPUT_TRUNCATED_HALT_REASON;
         }
 
-        /**
-         * Mid-flight halt: any hook (PreToolUse, PostToolUse,
-         * PostToolBatch, SubagentStart/Stop, PreCompact, PostCompact)
-         * that returned `preventContinuation: true` raises a halt
-         * signal on the registry via `executeHooks`. We poll between
-         * stream events and break out as soon as one is set so the
-         * graph doesn't take another model turn after the halting
-         * operation completes.
-         *
-         * This `break` is NOT graceful, despite what a `continue: false`
-         * reading suggests. Leaving the `for await` calls the iterator's
-         * `return()`, which cancels the reader
-         * (`@langchain/core/utils/stream`), and langgraph's stream wrapper
-         * turns that cancel into `_abortController.abort()`
-         * (`pregel/stream.js`). The in-flight model call or tool batch is
-         * torn down where it stands — it does not finish first.
-         *
-         * A halt is therefore the wrong tool for "stop generating but keep
-         * what you have". That is what `RunConfig.preemption` is for: it
-         * seals the stream at a provider-safe boundary and keeps the run.
-         */
-        const haltSignal = this.hookRegistry?.getHaltSignal(this.id);
-        if (haltSignal != null) {
-          this._haltedReason = haltSignal.reason;
-          break;
+        const stopMessages = graph.getRunMessages() ?? stateInputs?.messages ?? [];
+        const stopContinuationCount = graph.getStopContinuationCount();
+        const continuationBudgetRemaining = Math.max(
+          0,
+          this.maxStopContinuations - stopContinuationCount
+        );
+        let stopResult: AggregatedHookResult | undefined;
+        if (this.hookRegistry?.hasHookFor('Stop', this.id) === true) {
+          stopResult = await executeHooks({
+            registry: this.hookRegistry,
+            input: {
+              hook_event_name: 'Stop',
+              runId: this.id,
+              threadId,
+              agentId: graph.defaultAgentId,
+              messages: stopMessages,
+              stopReason,
+              stopHookActive: stopContinuationCount > 0,
+              continuationCount: stopContinuationCount,
+              continuationBudgetRemaining,
+            },
+            sessionId: this.id,
+            signal: config.signal,
+          }).catch((): undefined => undefined);
         }
-      }
 
-      terminalAt = Date.now();
+        if (this.hookRegistry?.hasHookFor('StopFinalize', this.id) === true) {
+          const stopInjected =
+            stopResult == null ? [] : materializeStopContinuation(stopResult);
+          const continuationPrevented =
+            stopReason != null || stopResult?.preventContinuation === true;
+          const finalized = await executeHooks({
+            registry: this.hookRegistry,
+            input: {
+              hook_event_name: 'StopFinalize',
+              runId: this.id,
+              threadId,
+              agentId: graph.defaultAgentId,
+              messages: stopMessages,
+              stopReason,
+              stopHookActive: stopContinuationCount > 0,
+              continuationCount: stopContinuationCount,
+              continuationBudgetRemaining,
+              continuationPlanned:
+                !continuationPrevented &&
+                stopResult?.stopDecision === 'block' &&
+                stopInjected.length > 0 &&
+                continuationBudgetRemaining > 0,
+              continuationPrevented,
+            },
+            sessionId: this.id,
+            signal: config.signal,
+          });
+          assertFinalAdmissionSucceeded(finalized);
+          stopResult = mergeAggregatedHookResults(stopResult, finalized);
+        }
 
-      if (this._interrupt != null) {
-        await this.resolveInterruptResumeConfig(config);
-      }
+        if (stopResult?.preventContinuation === true) {
+          this._haltedReason =
+            stopResult.stopReason ?? stopResult.reason ?? 'preventContinuation';
+          return;
+        }
 
-      /**
-       * Skip the Stop hook when the run paused on a HITL interrupt
-       * (still pending human input) or was halted by a hook (the host
-       * already chose to stop, so a Stop hook firing now would be
-       * misleading). The host fires Stop on the resumed-and-completed
-       * run instead.
-       */
-      if (
-        this._interrupt == null &&
-        this._haltedReason == null &&
-        this.hookRegistry?.hasHookFor('Stop', this.id) === true
-      ) {
-        await executeHooks({
-          registry: this.hookRegistry,
-          input: {
-            hook_event_name: 'Stop',
-            runId: this.id,
-            threadId,
-            agentId: graph.defaultAgentId,
-            messages: graph.getRunMessages() ?? stateInputs?.messages ?? [],
+        const requestsContinuation =
+          stopReason == null && stopResult?.stopDecision === 'block';
+        if (requestsContinuation && stopResult != null) {
+          const injected = materializeStopContinuation(stopResult);
+          if (injected.length > 0) {
+            if (stopContinuationCount >= this.maxStopContinuations) {
+              throw new Error(
+                'Stop hook attempted to inject messages after the terminal continuation budget was exhausted.'
+              );
+            }
+            const completedSegmentConfig = this.hasCheckpointer
+              ? await resolveCompletedSegmentConfig(
+                graphRunnable,
+                streamConfig,
+                graph.getStopContinuationExecutionId(),
+                graph.getStreamSegment()
+              )
+              : streamConfig;
+            const nextContinuationCount = stopContinuationCount + 1;
+            graph.setStopContinuationCount(nextContinuationCount);
+            graph.advanceStreamSegment();
             /**
-             * A seal whose boundary ended the turn early must say so. The
-             * hook-supplied reason wins when a `PreemptBoundary` hook halted
-             * with one — a persistence/audit `Stop` hook should record the
-             * actual cause, not the generic label — and `preempt_incomplete`
-             * is reserved for the boundary that simply had nothing to inject.
+             * A checkpointer already owns the completed graph state, so only
+             * the delta is submitted. Without one, each invocation starts from
+             * empty state and must be seeded with the live full transcript.
+             * Graph sidecars and the outer Run stay intact in both cases.
              */
-            stopReason:
-              graph.preemptHaltReason ??
-              (graph.preemptIncomplete ? 'preempt_incomplete' : undefined),
-            stopHookActive: false, // will be true when stop is triggered by a hook (Phase 2)
-          },
-          sessionId: this.id,
-        }).catch(() => {
-          /* Stop hook errors must not masquerade as stream failures */
-        });
-      }
+            streamInputs = {
+              messages: this.hasCheckpointer
+                ? injected
+                : [...graph.messages, ...injected],
+              runStepState: graph.createRunStepResumeState(),
+            };
+            streamConfig = completedSegmentConfig;
+            continue;
+          }
+        }
 
-      /**
-       * A `PreemptBoundary` hook that returned `preventContinuation` has its
-       * registry halt cleared by the graph — that is what stops the halt from
-       * cancelling the stream before the sealed turn commits — so the reason
-       * is carried across on the graph instead. Surfaced here, AFTER the
-       * `Stop` dispatch above, so the host still receives a completion signal
-       * to persist the partial answer with while `getHaltReason()` correctly
-       * reports that a hook stopped the run rather than the model finishing.
-       *
-       * An empty boundary — sealed, but nothing to inject because the host's
-       * queue was drained or cancelled in the meantime — cut the answer short
-       * just as surely, only without a hook-supplied reason. It surfaces
-       * through the same channel under the same name the `Stop` dispatch
-       * already used for its `stopReason`, so terminal consumers
-       * (`AgentSession` emits `run.halted`, not `run.completed`) cannot
-       * finalize a truncated answer as a natural finish.
-       */
-      if (this._haltedReason == null && graph.preemptHaltReason != null) {
-        this._haltedReason = graph.preemptHaltReason;
-      } else if (this._haltedReason == null && graph.preemptIncomplete) {
-        this._haltedReason = 'preempt_incomplete';
+        if (graph.preemptHaltReason != null) {
+          this._haltedReason = graph.preemptHaltReason;
+        } else if (graph.preemptIncomplete) {
+          this._haltedReason = 'preempt_incomplete';
+        } else if (graph.outputTruncatedIncomplete) {
+          this._haltedReason = OUTPUT_TRUNCATED_HALT_REASON;
+        }
+        return;
       }
     };
 
@@ -1432,6 +1630,10 @@ export class Run<_T extends t.BaseGraphState> {
     } catch (err) {
       terminalAt = Date.now();
       streamThrew = true;
+      await langfuseHandler?.handleChainError(
+        err instanceof Error ? err : new Error(String(err)),
+        this.id
+      );
       /**
        * Corroborate cancellation against an actually-aborted signal. A
        * provider SDK or host handler can reject with an `AbortError` while
@@ -1614,13 +1816,16 @@ export class Run<_T extends t.BaseGraphState> {
   }
 
   /**
-   * Returns the reason a hook halted the run via
-   * `preventContinuation: true`, or `undefined` if no hook halted.
+   * Returns why the run ended without a natural completion, or `undefined`
+   * when it completed normally. Reasons include hook- and prompt-driven
+   * halts, `preempt_incomplete` when a cooperative seal ended the turn
+   * without continuation content, and `output_truncated` when the provider
+   * stopped a plain-text/reasoning response at its output-token ceiling.
    *
    * Hosts inspect this after `processStream` returns to distinguish a
-   * natural completion (`undefined`) from a hook-driven halt (a
-   * truthy string). Independent from `getInterrupt()` — a halted run
-   * has no interrupt; an interrupted run has no halt reason.
+   * natural completion from a terminal partial response. Independent from
+   * `getInterrupt()` — a halted run has no interrupt; an interrupted run has
+   * no halt reason.
    */
   getHaltReason(): string | undefined {
     return this._haltedReason;
@@ -1833,7 +2038,8 @@ export class Run<_T extends t.BaseGraphState> {
       return;
     }
     this.Graph?.restoreRunStepResumeState(
-      getRunStepResumeState(persistedInterrupt.value)
+      getRunStepResumeState(persistedInterrupt.value) ??
+        snapshot.values?.runStepState
     );
     const persistedMessages = getPersistedMessages(snapshot);
     if (persistedMessages != null) {