@librechat/agents 3.3.4 → 3.3.6

package/dist/types/hooks/types.d.ts

@@ -8,7 +8,7 @@ import type { InjectedMessage } from '@/types/tools';
  * `docs/hooks-design-report.md` §3.2 for the mapping to existing
  * `@librechat/agents` emission points.
  */
-export declare const HOOK_EVENTS: readonly ["RunStart", "UserPromptSubmit", "PreToolUse", "PostToolUse", "PostToolUseFailure", "PostToolBatch", "PermissionDenied", "SubagentStart", "SubagentStop", "Stop", "StopFailure", "PreCompact", "PostCompact"];
+export declare const HOOK_EVENTS: readonly ["RunStart", "UserPromptSubmit", "PreToolUse", "PostToolUse", "PostToolUseFailure", "PostToolBatch", "PreemptBoundary", "PermissionDenied", "SubagentStart", "SubagentStop", "Stop", "StopFailure", "PreCompact", "PostCompact"];
 export type HookEvent = (typeof HOOK_EVENTS)[number];
 /** Tool-gating decision; executeHooks folds with `deny > ask > allow` precedence. */
 export type ToolDecision = 'allow' | 'deny' | 'ask';
@@ -117,6 +117,38 @@ export interface PostToolBatchHookInput extends BaseHookInput {
     /** All tool calls (and their outcomes) from this batch, in batch order. */
     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;
@@ -170,7 +202,7 @@ export interface PostCompactHookInput extends BaseHookInput {
     messagesAfterCount: number;
 }
 /** Discriminated union of every hook input shape. */
-export type HookInput = RunStartHookInput | UserPromptSubmitHookInput | PreToolUseHookInput | PostToolUseHookInput | PostToolUseFailureHookInput | PostToolBatchHookInput | PermissionDeniedHookInput | SubagentStartHookInput | SubagentStopHookInput | StopHookInput | StopFailureHookInput | PreCompactHookInput | PostCompactHookInput;
+export type HookInput = RunStartHookInput | UserPromptSubmitHookInput | PreToolUseHookInput | PostToolUseHookInput | PostToolUseFailureHookInput | PostToolBatchHookInput | PreemptBoundaryHookInput | PermissionDeniedHookInput | SubagentStartHookInput | SubagentStopHookInput | StopHookInput | StopFailureHookInput | PreCompactHookInput | PostCompactHookInput;
 /** Compile-time map from event name to its input shape. */
 export type HookInputByEvent = {
     RunStart: RunStartHookInput;
@@ -179,6 +211,7 @@ export type HookInputByEvent = {
     PostToolUse: PostToolUseHookInput;
     PostToolUseFailure: PostToolUseFailureHookInput;
     PostToolBatch: PostToolBatchHookInput;
+    PreemptBoundary: PreemptBoundaryHookInput;
     PermissionDenied: PermissionDeniedHookInput;
     SubagentStart: SubagentStartHookInput;
     SubagentStop: SubagentStopHookInput;
@@ -196,14 +229,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. */
@@ -305,6 +342,7 @@ export interface PostToolUseHookOutput extends BaseHookOutput {
 }
 export type PostToolUseFailureHookOutput = BaseHookOutput;
 export type PostToolBatchHookOutput = BaseHookOutput;
+export type PreemptBoundaryHookOutput = BaseHookOutput;
 export type PermissionDeniedHookOutput = BaseHookOutput;
 export interface SubagentStartHookOutput extends BaseHookOutput {
     decision?: ToolDecision;
@@ -326,6 +364,7 @@ export type HookOutputByEvent = {
     PostToolUse: PostToolUseHookOutput;
     PostToolUseFailure: PostToolUseFailureHookOutput;
     PostToolBatch: PostToolBatchHookOutput;
+    PreemptBoundary: PreemptBoundaryHookOutput;
     PermissionDenied: PermissionDeniedHookOutput;
     SubagentStart: SubagentStartHookOutput;
     SubagentStop: SubagentStopHookOutput;
@@ -335,7 +374,7 @@ export type HookOutputByEvent = {
     PostCompact: PostCompactHookOutput;
 };
 /** Superset output shape used by the executor's fold loop. */
-export type HookOutput = RunStartHookOutput | UserPromptSubmitHookOutput | PreToolUseHookOutput | PostToolUseHookOutput | PostToolUseFailureHookOutput | PostToolBatchHookOutput | PermissionDeniedHookOutput | SubagentStartHookOutput | SubagentStopHookOutput | StopHookOutput | StopFailureHookOutput | PreCompactHookOutput | PostCompactHookOutput;
+export type HookOutput = RunStartHookOutput | UserPromptSubmitHookOutput | PreToolUseHookOutput | PostToolUseHookOutput | PostToolUseFailureHookOutput | PostToolBatchHookOutput | PreemptBoundaryHookOutput | PermissionDeniedHookOutput | SubagentStartHookOutput | SubagentStopHookOutput | StopHookOutput | StopFailureHookOutput | PreCompactHookOutput | PostCompactHookOutput;
 /**
  * A hook callback is a plain async function registered against a specific
  * event. The `signal` is always supplied by `executeHooks` and combines the

package/dist/types/index.d.ts

@@ -1,6 +1,5 @@
 export * from './run';
 export * from './stream';
-export * from './splitStream';
 export * from './events';
 export * from './messages';
 export * from './graphs';
@@ -18,6 +17,7 @@ export * from './tools/ReadFile';
 export * from './tools/skillCatalog';
 export * from './tools/ToolSearch';
 export * from './tools/ToolNode';
+export * from './tools/intentArg';
 export * from './tools/schema';
 export * from './tools/handlers';
 export * from './tools/local';
@@ -45,4 +45,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/dist/types/llm/invoke.d.ts

@@ -54,6 +54,13 @@ export declare function projectMessagesForProvider({ model, messages, provider,
     maxToolResultChars?: number;
     callOptions?: unknown;
 }): BaseMessage[];
+/**
+ * The serving model's id, read through the same wrapper stack
+ * `collectModelCallbackSources` walks — `bindTools` returns a
+ * `RunnableBinding` and a system runnable pipes a `RunnableSequence`, and
+ * neither exposes the chat model's `model` at the top level.
+ */
+export declare function resolveServingModelId(model: unknown): string | undefined;
 /**
  * Invokes a chat model with the given messages, handling both streaming and
  * non-streaming paths.

package/dist/types/llm/openai/index.d.ts

@@ -42,17 +42,6 @@ export declare function shouldIncludeEncryptedReasoning(model: string, params: {
     reasoning?: unknown;
 }): boolean;
 export declare function emitStreamChunkCallback(chunk: ChatGenerationChunk, runManager?: CallbackManagerForLLMRun): Promise<void>;
-/**
- * Formats a tool in either OpenAI format, or LangChain structured tool format
- * into an OpenAI tool format. If the tool is already in OpenAI format, return without
- * any changes. If it is in LangChain structured tool format, convert it to OpenAI tool format
- * using OpenAI's `zodFunction` util, falling back to `convertToOpenAIFunction` if the parameters
- * returned from the `zodFunction` util are not defined.
- *
- * @param {BindToolsInput} tool The tool to convert to an OpenAI tool.
- * @param {Object} [fields] Additional fields to add to the OpenAI tool.
- * @returns {ToolDefinition} The inputted tool in OpenAI tool format.
- */
 export declare function _convertToOpenAITool(tool: BindToolsInput, fields?: {
     /**
      * If `true`, model output is guaranteed to exactly match the JSON Schema

package/dist/types/llm/preempt.d.ts

@@ -0,0 +1,40 @@
+import type { AIMessageChunk } from '@langchain/core/messages';
+/**
+ * Normalizes a host-supplied seal budget.
+ *
+ * Read in two places that interpret it differently — a numeric comparison in
+ * the seal gate and an addition into the recursion limit — so a value like
+ * `1.5` would permit two seals while reserving fractional headroom, `NaN`
+ * would poison the recursion limit outright, and `Infinity` would remove both
+ * bounds at once. Normalizing once keeps the two readings in agreement.
+ *
+ * `0` is honored as a deliberate "never seal"; anything not finite falls back
+ * to the default rather than silently disabling the feature.
+ */
+export declare function resolveMaxSeals(maxSeals: number | undefined): number;
+/**
+ * Cooperative mid-generation seal gate. Returns true ONLY when sealing here
+ * yields a message sequence valid on EVERY supported provider:
+ *  - non-whitespace TEXT content, so the FIRST injected user turn is preceded
+ *    by a non-empty assistant turn — no empty-content 400s. Note this says
+ *    nothing about adjacency AMONG several injected turns: a boundary that
+ *    drains two steers emits two consecutive user messages, which strict
+ *    providers reject. That is normalized at the provider-facing hop by
+ *    `coalesceAdjacentUserTurns`, not here;
+ *  - no tool call in flight, so no `tool_use` can be orphaned AND no eagerly
+ *    prestarted execution can be stripped out from under the model.
+ *
+ * Anthropic's server-side tools need no check of their own. Every
+ * `server_tool_use` content block also emits a `tool_call_chunk`
+ * (`_makeMessageChunkFromAnthropicEvent`), and `concat` keeps that chunk on
+ * the accumulated message for the remainder of the turn, so the tool-call
+ * gates below already cover it. The practical consequence is worth stating
+ * plainly: once a turn starts a web search it is no longer preemptible, and
+ * a queued message waits for the ordinary tool boundary instead.
+ *
+ * Nothing is stripped and nothing is repaired: when the accumulated shape is
+ * not already safe the stream simply runs on, and whatever the host queued
+ * lands at the next tool boundary instead. Chunks accumulate monotonically
+ * through `concat`, so an unsafe shape can never be observed at a seal point.
+ */
+export declare function canSealPreempt(chunk: AIMessageChunk | undefined): boolean;

package/dist/types/messages/alternation.d.ts

@@ -0,0 +1,23 @@
+import type { BaseMessage } from '@langchain/core/messages';
+import { Providers } from '@/common';
+/**
+ * Providers whose APIs specify strict user/assistant alternation. Mistral
+ * rejects consecutive user turns outright. Bedrock's Converse API documents
+ * the alternation requirement across many model families; enforcement varies
+ * by family — Claude on Converse currently tolerates adjacent user turns
+ * (verified live, 2026-07-28) — so the payload is normalized for all of them
+ * rather than betting on per-family leniency. Anthropic's own Messages API,
+ * OpenAI and Gemini all accept consecutive user turns, so they are
+ * deliberately absent.
+ */
+export declare const strictAlternationProviders: ReadonlySet<Providers>;
+/**
+ * Merges runs of consecutive human turns into one, for providers that reject
+ * them. Purely a wire-shaping pass: it returns a new array of new messages,
+ * so graph state and the host's persisted messages keep the per-message
+ * identity that steer rendering and the trailing-steer anchor rely on.
+ *
+ * Tool-result turns are excluded — the converters merge those themselves, and
+ * combining one with a text turn would orphan the pairing.
+ */
+export declare function coalesceAdjacentUserTurns(messages: BaseMessage[]): BaseMessage[];

package/dist/types/messages/handoffCue.d.ts

@@ -0,0 +1,40 @@
+import type { BaseMessage } from '@langchain/core/messages';
+/**
+ * Bracketed-meta convention, like the handoff path's
+ * `[Processed tool result and transferring to …]` bridge. The wording makes
+ * two things unambiguous to the model: the assistant turn above is FINISHED,
+ * and it belongs to a previous stage — so the successor answers as itself
+ * instead of continuing someone else's sentence.
+ */
+export declare const PREDECESSOR_HANDOFF_CUE: string;
+/**
+ * Appends a user-turn handoff cue when a payload ends with an assistant turn
+ * that THIS RUN produced — which only happens when a different agent in a
+ * multi-agent workflow produced it (an agent's own self-loops always re-enter
+ * on a tool result or an injected user turn).
+ *
+ * Why: providers with prefill semantics (Anthropic, Bedrock-Claude) treat a
+ * trailing assistant message as a prefill and CONTINUE it. A bare direct-edge
+ * successor therefore speaks in its predecessor's voice — or, when the
+ * trailing turn reads complete (a preemption steer's short resume, say),
+ * returns empty content (danny-avila/agents#345, reproduced live 3/3).
+ * Handoff edges with instructions and prompt-instruction edges already break
+ * the prefill with a user turn; this closes the same gap for bare edges.
+ *
+ * Fail-safe OFF by provenance: the trailing payload message must be one the
+ * run itself produced (`isRunProduced`, backed by the graph's run-produced id
+ * set — immune to summarization compaction, which rewrites the live array
+ * and stales index-based boundaries). Host-supplied trailing assistant
+ * turns (deliberate prefill flows) never match — the run has not produced
+ * them — so single-agent prefill behavior is untouched. Wire-only: the cue is
+ * appended to the provider projection, never to graph state or host history.
+ */
+export declare function appendPredecessorHandoffCue(messages: BaseMessage[], isRunProduced: ((message: BaseMessage) => boolean) | undefined): BaseMessage[];
+/**
+ * Strips a trailing handoff cue. The counterpart for the serving-provider
+ * funnel: an Anthropic-like PRIMARY bakes the cue into its measured payload,
+ * and a tolerant fallback (OpenAI, Mistral, Bedrock-Nova) re-sending that
+ * payload must not ship the Claude-only synthetic turn. Identity on the
+ * no-op path.
+ */
+export declare function removePredecessorHandoffCue(messages: BaseMessage[]): BaseMessage[];

package/dist/types/messages/index.d.ts

@@ -7,6 +7,9 @@ export * from './cache';
 export * from './anthropicToolCache';
 export * from './content';
 export * from './tools';
+export * from './injected';
+export * from './alternation';
+export * from './handoffCue';
 export * from './contextPruning';
 export * from './contextPruningSettings';
 export * from './reducer';

package/dist/types/messages/injected.d.ts

@@ -0,0 +1,3 @@
+import type { BaseMessage } from '@langchain/core/messages';
+import type { InjectedMessage } from '@/types/tools';
+export declare function convertInjectedMessages(messages: InjectedMessage[]): BaseMessage[];

package/dist/types/run.d.ts

@@ -17,6 +17,7 @@ export declare class Run<_T extends t.BaseGraphState> {
     private interruptingToolNames?;
     private toolExecution?;
     private subagentUsageSink?;
+    private preemption?;
     private indexTokenCountMap?;
     calibrationRatio: number;
     graphRunnable?: t.CompiledStateWorkflow;
@@ -109,6 +110,12 @@ export declare class Run<_T extends t.BaseGraphState> {
      */
     getCalibrationRatio(): number;
     getResolvedInstructionOverhead(): number | undefined;
+    /**
+     * Cooperative-seal counters for this run. `emptyBoundaries` is the one to
+     * watch: it counts seals whose `PreemptBoundary` produced nothing to
+     * inject, which ends the turn early and leaves the answer unfinished.
+     */
+    getPreemptStats(): t.PreemptStats;
     getToolCount(): number;
     /**
      * Creates a custom event callback handler that intercepts custom events

package/dist/types/stream.d.ts

@@ -8,7 +8,21 @@ export declare function getChunkContent({ chunk, provider, reasoningKey, }: {
     provider?: Providers;
     reasoningKey: 'reasoning_content' | 'reasoning';
 }): string | t.MessageContentComplex[] | undefined;
+/**
+ * Brands a handler as one that dispatches content parts for the SDK — either
+ * `ChatModelStreamHandler` itself or a wrapper forwarding to one.
+ *
+ * Identity alone is not a usable contract here. Hosts compose and wrap
+ * handlers (`composeEventHandlers`, `createRunHandlers`), and every wrapper
+ * fails `instanceof` while still driving the same dispatch. A brand survives
+ * wrapping, so "does this handler own content-part dispatch" can be answered
+ * about a value the SDK did not construct.
+ */
+export declare const SDK_STREAM_DISPATCH: unique symbol;
+/** True when `handler` is, or forwards to, the SDK's stream dispatcher. */
+export declare function dispatchesChatModelStream(handler?: t.EventHandler): boolean;
 export declare class ChatModelStreamHandler implements t.EventHandler {
+    readonly [SDK_STREAM_DISPATCH] = true;
     handle(event: string, data: t.StreamEventData, metadata?: Record<string, unknown>, graph?: StandardGraph): Promise<void>;
     handleReasoning(chunk: Partial<AIMessageChunk>, agentContext: AgentContext): void;
 }

package/dist/types/tools/BashExecutor.d.ts

@@ -4,6 +4,15 @@ import { Constants } from '@/common';
 export declare const BashExecutionToolSchema: {
     readonly type: "object";
     readonly properties: {
+        readonly intent: {
+            readonly type: "string" | "number" | "integer" | "float" | "boolean" | "array" | "object";
+            readonly enum?: string[];
+            readonly items?: t.JsonSchemaType;
+            readonly properties?: Record<string, t.JsonSchemaType>;
+            readonly required?: string[];
+            readonly description?: string;
+            readonly additionalProperties?: boolean | t.JsonSchemaType;
+        };
         readonly command: {
             readonly type: "string";
             readonly description: "The bash command or script to execute.\n- The environment is stateless; variables and state don't persist between executions.\n- Prior /mnt/data files are available and can be modified in place.\n- Persist handoff artifacts in `/mnt/data` with standard extensions (.json/.txt/.csv/.tsv/.log/.parquet/.png/.jpg/.pdf/.xlsx); failed executions do not register new files; `/tmp` and odd extensions are same-call scratch only, not later-call storage.\n- Bash: multi-line files use heredoc/printf; run Python via python3 -c/heredoc, not bare Python.\n- Input code **IS ALREADY** displayed to the user, so **DO NOT** repeat it in your response unless asked.\n- Output code **IS NOT** displayed to the user, so **DO** write all desired output explicitly.\n- IMPORTANT: You MUST explicitly print/output ALL results you want the user to see.\n- Use `echo`, `printf`, or `cat` for all outputs.";
@@ -71,6 +80,15 @@ export declare const BashExecutionToolDefinition: {
     readonly schema: {
         readonly type: "object";
         readonly properties: {
+            readonly intent: {
+                readonly type: "string" | "number" | "integer" | "float" | "boolean" | "array" | "object";
+                readonly enum?: string[];
+                readonly items?: t.JsonSchemaType;
+                readonly properties?: Record<string, t.JsonSchemaType>;
+                readonly required?: string[];
+                readonly description?: string;
+                readonly additionalProperties?: boolean | t.JsonSchemaType;
+            };
             readonly command: {
                 readonly type: "string";
                 readonly description: "The bash command or script to execute.\n- The environment is stateless; variables and state don't persist between executions.\n- Prior /mnt/data files are available and can be modified in place.\n- Persist handoff artifacts in `/mnt/data` with standard extensions (.json/.txt/.csv/.tsv/.log/.parquet/.png/.jpg/.pdf/.xlsx); failed executions do not register new files; `/tmp` and odd extensions are same-call scratch only, not later-call storage.\n- Bash: multi-line files use heredoc/printf; run Python via python3 -c/heredoc, not bare Python.\n- Input code **IS ALREADY** displayed to the user, so **DO NOT** repeat it in your response unless asked.\n- Output code **IS NOT** displayed to the user, so **DO** write all desired output explicitly.\n- IMPORTANT: You MUST explicitly print/output ALL results you want the user to see.\n- Use `echo`, `printf`, or `cat` for all outputs.";

package/dist/types/tools/CodeExecutor.d.ts

@@ -13,6 +13,15 @@ export declare function appendFailedExecutionFileReminder(output: string, code:
 export declare const CodeExecutionToolSchema: {
     readonly type: "object";
     readonly properties: {
+        readonly intent: {
+            readonly type: "string" | "number" | "integer" | "float" | "boolean" | "array" | "object";
+            readonly enum?: string[];
+            readonly items?: t.JsonSchemaType;
+            readonly properties?: Record<string, t.JsonSchemaType>;
+            readonly required?: string[];
+            readonly description?: string;
+            readonly additionalProperties?: boolean | t.JsonSchemaType;
+        };
         readonly lang: {
             readonly type: "string";
             readonly enum: readonly ["py", "js", "ts", "c", "cpp", "java", "php", "rs", "go", "d", "f90", "r", "bash"];
@@ -74,6 +83,15 @@ export declare const CodeExecutionToolDefinition: {
     readonly schema: {
         readonly type: "object";
         readonly properties: {
+            readonly intent: {
+                readonly type: "string" | "number" | "integer" | "float" | "boolean" | "array" | "object";
+                readonly enum?: string[];
+                readonly items?: t.JsonSchemaType;
+                readonly properties?: Record<string, t.JsonSchemaType>;
+                readonly required?: string[];
+                readonly description?: string;
+                readonly additionalProperties?: boolean | t.JsonSchemaType;
+            };
             readonly lang: {
                 readonly type: "string";
                 readonly enum: readonly ["py", "js", "ts", "c", "cpp", "java", "php", "rs", "go", "d", "f90", "r", "bash"];

package/dist/types/tools/ReadFile.d.ts

@@ -4,6 +4,15 @@ export declare const ReadFileToolDescription = "Read the contents of a file. Ret
 export declare const ReadFileToolSchema: {
     readonly type: "object";
     readonly properties: {
+        readonly intent: {
+            readonly type: "string" | "number" | "integer" | "float" | "boolean" | "array" | "object";
+            readonly enum?: string[];
+            readonly items?: import("..").JsonSchemaType;
+            readonly properties?: Record<string, import("..").JsonSchemaType>;
+            readonly required?: string[];
+            readonly description?: string;
+            readonly additionalProperties?: boolean | import("..").JsonSchemaType;
+        };
         readonly path: {
             readonly type: "string";
             readonly description: "Path to the file. For skill files: \"{skillName}/{path}\" (e.g. \"pdf-analyzer/src/utils.py\"). For code execution output: the path as returned by the execution tool.";
@@ -17,6 +26,15 @@ export declare const ReadFileToolDefinition: {
     readonly parameters: {
         readonly type: "object";
         readonly properties: {
+            readonly intent: {
+                readonly type: "string" | "number" | "integer" | "float" | "boolean" | "array" | "object";
+                readonly enum?: string[];
+                readonly items?: import("..").JsonSchemaType;
+                readonly properties?: Record<string, import("..").JsonSchemaType>;
+                readonly required?: string[];
+                readonly description?: string;
+                readonly additionalProperties?: boolean | import("..").JsonSchemaType;
+            };
             readonly path: {
                 readonly type: "string";
                 readonly description: "Path to the file. For skill files: \"{skillName}/{path}\" (e.g. \"pdf-analyzer/src/utils.py\"). For code execution output: the path as returned by the execution tool.";

package/dist/types/tools/SkillTool.d.ts

@@ -9,6 +9,15 @@ export declare const SkillToolDescription = "Invoke a skill from the user's libr
 export declare const SkillToolSchema: {
     readonly type: "object";
     readonly properties: {
+        readonly intent: {
+            readonly type: "string" | "number" | "integer" | "float" | "boolean" | "array" | "object";
+            readonly enum?: string[];
+            readonly items?: import("..").JsonSchemaType;
+            readonly properties?: Record<string, import("..").JsonSchemaType>;
+            readonly required?: string[];
+            readonly description?: string;
+            readonly additionalProperties?: boolean | import("..").JsonSchemaType;
+        };
         readonly skillName: {
             readonly type: "string";
             readonly description: "The kebab-case identifier of the skill to invoke (e.g. \"financial-analyzer\", \"meeting-notes\"). Must match a name from the \"Available Skills\" section.";
@@ -26,6 +35,15 @@ export declare const SkillToolDefinition: {
     readonly parameters: {
         readonly type: "object";
         readonly properties: {
+            readonly intent: {
+                readonly type: "string" | "number" | "integer" | "float" | "boolean" | "array" | "object";
+                readonly enum?: string[];
+                readonly items?: import("..").JsonSchemaType;
+                readonly properties?: Record<string, import("..").JsonSchemaType>;
+                readonly required?: string[];
+                readonly description?: string;
+                readonly additionalProperties?: boolean | import("..").JsonSchemaType;
+            };
             readonly skillName: {
                 readonly type: "string";
                 readonly description: "The kebab-case identifier of the skill to invoke (e.g. \"financial-analyzer\", \"meeting-notes\"). Must match a name from the \"Available Skills\" section.";

package/dist/types/tools/SubagentTool.d.ts

@@ -6,6 +6,15 @@ export declare const SubagentToolDescription = "Delegate a task to a specialized
 export declare const SubagentToolSchema: {
     readonly type: "object";
     readonly properties: {
+        readonly intent: {
+            readonly type: "string" | "number" | "integer" | "float" | "boolean" | "array" | "object";
+            readonly enum?: string[];
+            readonly items?: JsonSchemaType;
+            readonly properties?: Record<string, JsonSchemaType>;
+            readonly required?: string[];
+            readonly description?: string;
+            readonly additionalProperties?: boolean | JsonSchemaType;
+        };
         readonly description: {
             readonly type: "string";
             readonly description: "Complete task description for the subagent. This is the ONLY information it receives — include all necessary context, requirements, and constraints.";

package/dist/types/tools/ToolNode.d.ts

@@ -57,7 +57,32 @@ type RunToolBatchContext<T = unknown> = {
      * which relies on `node:async_hooks` and is browser-incompatible).
      */
     runInput?: T;
+    /** Batch-local error-completion ownership (see {@link ToolErrorOwnership}). */
+    errorOwnership?: ToolErrorOwnership;
 };
+/**
+ * Batch-local record of who owns each failed call's completion event.
+ *
+ * Kept per invocation rather than on the instance: tool-call ids are
+ * provider-scoped (and synthetic ids can repeat), so concurrent `run()`s on
+ * one ToolNode would otherwise share and cross-consume these markers — one
+ * invocation's thrown-error marker suppressing another's only completion,
+ * or leaving a stale marker behind when an interrupt aborts a batch before
+ * the output loop reads it.
+ *
+ * - `handlerOwned`: the errorHandler ran and dispatched (or threw — a throw
+ *   is not proof it didn't dispatch). The output loop must skip these.
+ * - `undispatched`: the handler explicitly reported it could NOT dispatch,
+ *   so the output loop owns the completion instead.
+ *
+ * A call in NEITHER set returned an error `ToolMessage` without ever
+ * entering the catch path, so the output loop owns it too.
+ */
+export type ToolErrorOwnership = {
+    handlerOwned: Set<string>;
+    undispatched: Set<string>;
+};
+export declare function createToolErrorOwnership(): ToolErrorOwnership;
 export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
     private toolMap;
     private loadRuntimeTools?;
@@ -68,12 +93,12 @@ export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
     toolCallStepIds?: Map<string, string>;
     errorHandler?: t.ToolNodeConstructorParams['errorHandler'];
     /**
-     * Tool call ids whose `errorHandler` did NOT dispatch the error completion
-     * event (it returned `false` or threw). The output loop must dispatch the
-     * completion for these itself — skipping them there would strand the
-     * client's tool-call part without a terminal event.
+     * Fallback error-completion ownership for calls that reach `runTool`
+     * outside a batch context (direct `runTool` use in tests / embedders).
+     * Batch-scoped ownership is threaded via `RunToolBatchContext` instead —
+     * see {@link ToolErrorOwnership} for why per-invocation scoping matters.
      */
-    private undispatchedToolErrors;
+    private looseErrorOwnership;
     private toolUsageCount;
     /** Maps toolCallId → turn captured in runTool, used by handleRunToolCompletions */
     private toolCallTurns;
@@ -392,6 +417,13 @@ export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
      * those arrays and consumes them right after this returns.
      */
     private dispatchPostToolBatchAndInjectContext;
+    /**
+     * Whether `name`'s own schema declares a BUSINESS parameter called
+     * `intent` (declared, and not the injected label contract — see
+     * `isIntentLabelProperty`). Such a parameter must keep participating in
+     * `{{tool…}}` placeholder substitution; only the display label is exempt.
+     */
+    private toolDeclaresBusinessIntent;
     private dispatchStepCompleted;
     /**
      * Emits the completed run step for a single host-reported result before
@@ -401,13 +433,6 @@ export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
      * actually dispatched so the caller can fall back to batch-time emission.
      */
     private dispatchEarlyToolCompletion;
-    /**
-     * Converts InjectedMessage instances to LangChain HumanMessage objects.
-     * Both 'user' and 'system' roles become HumanMessage to avoid provider
-     * rejections (Anthropic/Google reject non-leading SystemMessages).
-     * The original role is preserved in additional_kwargs for downstream consumers.
-     */
-    private convertInjectedMessages;
     /**
      * Execute a group of direct (in-process) tool calls with interrupt-safe
      * ordering, returning outputs aligned 1:1 with `directCalls`.

package/dist/types/tools/ToolSearch.d.ts

@@ -6,6 +6,15 @@ export declare const ToolSearchToolDescription = "Searches deferred tools using
 export declare const ToolSearchToolSchema: {
     readonly type: "object";
     readonly properties: {
+        readonly intent: {
+            readonly type: "string" | "number" | "integer" | "float" | "boolean" | "array" | "object";
+            readonly enum?: string[];
+            readonly items?: t.JsonSchemaType;
+            readonly properties?: Record<string, t.JsonSchemaType>;
+            readonly required?: string[];
+            readonly description?: string;
+            readonly additionalProperties?: boolean | t.JsonSchemaType;
+        };
         readonly query: {
             readonly type: "string";
             readonly maxLength: 200;
@@ -48,6 +57,15 @@ export declare const ToolSearchToolDefinition: {
     readonly schema: {
         readonly type: "object";
         readonly properties: {
+            readonly intent: {
+                readonly type: "string" | "number" | "integer" | "float" | "boolean" | "array" | "object";
+                readonly enum?: string[];
+                readonly items?: t.JsonSchemaType;
+                readonly properties?: Record<string, t.JsonSchemaType>;
+                readonly required?: string[];
+                readonly description?: string;
+                readonly additionalProperties?: boolean | t.JsonSchemaType;
+            };
             readonly query: {
                 readonly type: "string";
                 readonly maxLength: 200;