@librechat/agents 4.0.1 → 4.0.3

package/dist/types/protection/providerText.d.ts

@@ -0,0 +1,77 @@
+export declare const PROVIDER_TEXT_PROTECTION_VERSION = 1;
+export type ProviderTextProtectionErrorCode = 'blocked' | 'unavailable' | 'timeout' | 'overflow' | 'cancelled' | 'unsupported' | 'incompatible';
+export type ProviderTextProtectionResult = {
+    readonly version: 1;
+    readonly ok: true;
+    readonly value: {
+        readonly content: string;
+        readonly replacements: number;
+        readonly categories: readonly {
+            readonly category: string;
+            readonly count: number;
+        }[];
+    };
+} | {
+    readonly version: 1;
+    readonly ok: false;
+    readonly error: {
+        readonly code: ProviderTextProtectionErrorCode;
+    };
+};
+/** Trusted host adapter. Classification must reject code, JSON and ambiguous text. */
+export interface ProviderTextProtection {
+    readonly version: 1;
+    readonly timeoutMs: number;
+    readonly maxAttemptBytes: number;
+    /** Shared across all attempts using this policy, including child graphs. */
+    readonly maxBufferedBytes: number;
+    readonly classify: (content: string) => 'prose' | 'unsupported';
+    readonly inspect: (input: {
+        readonly version: 1;
+        readonly content: string;
+        readonly target: {
+            readonly source: 'message';
+            readonly field: 'text';
+            readonly provenance: 'model';
+        };
+        readonly signal: AbortSignal;
+    }) => ProviderTextProtectionResult | Promise<ProviderTextProtectionResult>;
+}
+export declare class ProviderTextProtectionError extends Error {
+    readonly code: ProviderTextProtectionErrorCode;
+    constructor(code: ProviderTextProtectionErrorCode);
+}
+/** Internal control flow, never a host policy decision or public capability. */
+export declare function createProviderTextRestartCancellation(): ProviderTextProtectionError;
+export declare function isProviderTextRestartCancellation(error: unknown): boolean;
+/** Provider smoothing must stay lazy while the release boundary owns raw text. */
+export declare function isProtectedProviderTextSignal(signal?: AbortSignal): boolean;
+export declare function validateProviderTextProtection(policy: ProviderTextProtection): void;
+/** A lease stays charged while a cancellation-ignoring producer/handler still owns raw text. */
+export declare class ProviderTextAttempt {
+    private readonly policy;
+    private readonly parent?;
+    private readonly controller;
+    private readonly budget;
+    private readonly deadline;
+    private bytes;
+    private textLength;
+    private readonly fragments;
+    private readonly pending;
+    private readonly timer;
+    private readonly abort;
+    private finished;
+    constructor(policy: ProviderTextProtection, parent?: AbortSignal | undefined);
+    get signal(): AbortSignal;
+    check(): void;
+    private charge;
+    append(text: string, cumulativeReplay?: boolean): void;
+    /** Compare buffered fragments without allocating an uncharged joined copy. */
+    private hasCandidatePrefix;
+    matchesText(text: string): boolean;
+    retain(bytes: number): void;
+    observeChunk(): void;
+    wait<T>(work: Promise<T>): Promise<T>;
+    release(): Promise<string>;
+    finish(): void;
+}

package/dist/types/protection/providerTextInput.d.ts

@@ -0,0 +1,3 @@
+/** Internal provenance for the SDK's pure instruction transform, not a host capability. */
+export declare function markProviderTextInput<T extends object>(input: T): T;
+export declare function isProviderTextInput(input: object): boolean;

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

@@ -0,0 +1,4 @@
+export type * from './types';
+export { createSystemOneReranker } from './systemone';
+export type { SystemOneRerankerOptions } from './systemone';
+export { createWebSearchReranker } from './search';

package/dist/types/rerank/search.d.ts

@@ -0,0 +1,7 @@
+import type { Logger, SearchReranker } from '@/tools/search/types';
+import type { Reranker } from './types';
+/** Adapts index-based rankings to web-search highlights and its existing metrics/fallback policy. */
+export declare function createWebSearchReranker(reranker: Reranker, options?: {
+    timeoutMs?: number;
+    logger?: Logger;
+}): SearchReranker;

package/dist/types/rerank/systemone.d.ts

@@ -0,0 +1,13 @@
+import type { Reranker } from './types';
+import type { DecisionModel } from '@/decisions';
+export interface SystemOneRerankerOptions {
+    /** Inject a configured Jev/Laya HTTP decision model; chat cannot produce expected scores. */
+    model: DecisionModel;
+    /** Relevance levels from least to most relevant; evaluate this rubric for the checkpoint. */
+    rubric: readonly string[];
+    /** Reject oversized batches instead of silently dropping candidates. Defaults to 128. */
+    maxDocuments?: number;
+    timeoutMs?: number;
+}
+/** One shared query/candidate state and one score question per candidate, in one request. */
+export declare function createSystemOneReranker(options: SystemOneRerankerOptions): Reranker;

package/dist/types/rerank/types.d.ts

@@ -0,0 +1,24 @@
+import type { DecisionUsage } from '@/decisions';
+export interface RerankRequest {
+    query: string;
+    documents: readonly string[];
+    topK?: number;
+    signal?: AbortSignal;
+    timeoutMs?: number;
+}
+export interface RankedDocument {
+    /** Index into the submitted documents, not an identity derived from text. */
+    index: number;
+    /** Provider-specific relevance score, ordered descending; not a portable threshold. */
+    score: number;
+}
+export interface RerankResult {
+    results: RankedDocument[];
+    model: string;
+    usage: DecisionUsage | null;
+}
+/** Rankings retain candidate identity; failures reject rather than fabricate scores. */
+export interface Reranker {
+    readonly id: string;
+    rerank(request: RerankRequest): Promise<RerankResult>;
+}

package/dist/types/run.d.ts

@@ -21,9 +21,11 @@ export declare class Run<_T extends t.BaseGraphState> {
     private subagentUsageSink?;
     private preemption?;
     private maxStopContinuations;
+    private providerTextProtection?;
     private streamLimits?;
     private subagentTasks?;
     private subagentContext?;
+    private onSubagentResolutionFailure?;
     private indexTokenCountMap?;
     calibrationRatio: number;
     fadingTier?: t.FadingTier;

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

@@ -11,6 +11,8 @@ export declare const BashExecutionToolSchema: {
             readonly properties?: Record<string, t.JsonSchemaType>;
             readonly required?: string[];
             readonly description?: string;
+            readonly pattern?: string;
+            readonly maxLength?: number;
             readonly additionalProperties?: boolean | t.JsonSchemaType;
         };
         readonly command: {
@@ -89,6 +91,8 @@ export declare const BashExecutionToolDefinition: {
                 readonly properties?: Record<string, t.JsonSchemaType>;
                 readonly required?: string[];
                 readonly description?: string;
+                readonly pattern?: string;
+                readonly maxLength?: number;
                 readonly additionalProperties?: boolean | t.JsonSchemaType;
             };
             readonly command: {

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

@@ -23,6 +23,8 @@ export declare const CodeExecutionToolSchema: {
             readonly properties?: Record<string, t.JsonSchemaType>;
             readonly required?: string[];
             readonly description?: string;
+            readonly pattern?: string;
+            readonly maxLength?: number;
             readonly additionalProperties?: boolean | t.JsonSchemaType;
         };
         readonly lang: {
@@ -107,6 +109,8 @@ export declare const CodeExecutionToolDefinition: {
                 readonly properties?: Record<string, t.JsonSchemaType>;
                 readonly required?: string[];
                 readonly description?: string;
+                readonly pattern?: string;
+                readonly maxLength?: number;
                 readonly additionalProperties?: boolean | t.JsonSchemaType;
             };
             readonly lang: {

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

@@ -11,6 +11,8 @@ export declare const ReadFileToolSchema: {
             readonly properties?: Record<string, import("..").JsonSchemaType>;
             readonly required?: string[];
             readonly description?: string;
+            readonly pattern?: string;
+            readonly maxLength?: number;
             readonly additionalProperties?: boolean | import("..").JsonSchemaType;
         };
         readonly path: {
@@ -33,6 +35,8 @@ export declare const ReadFileToolDefinition: {
                 readonly properties?: Record<string, import("..").JsonSchemaType>;
                 readonly required?: string[];
                 readonly description?: string;
+                readonly pattern?: string;
+                readonly maxLength?: number;
                 readonly additionalProperties?: boolean | import("..").JsonSchemaType;
             };
             readonly path: {

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

@@ -16,6 +16,8 @@ export declare const SkillToolSchema: {
             readonly properties?: Record<string, import("..").JsonSchemaType>;
             readonly required?: string[];
             readonly description?: string;
+            readonly pattern?: string;
+            readonly maxLength?: number;
             readonly additionalProperties?: boolean | import("..").JsonSchemaType;
         };
         readonly skillName: {
@@ -42,6 +44,8 @@ export declare const SkillToolDefinition: {
                 readonly properties?: Record<string, import("..").JsonSchemaType>;
                 readonly required?: string[];
                 readonly description?: string;
+                readonly pattern?: string;
+                readonly maxLength?: number;
                 readonly additionalProperties?: boolean | import("..").JsonSchemaType;
             };
             readonly skillName: {

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

@@ -13,6 +13,8 @@ export declare const SubagentToolSchema: {
             readonly properties?: Record<string, JsonSchemaType>;
             readonly required?: string[];
             readonly description?: string;
+            readonly pattern?: string;
+            readonly maxLength?: number;
             readonly additionalProperties?: boolean | JsonSchemaType;
         };
         readonly description: {

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

@@ -13,6 +13,8 @@ export declare const ToolSearchToolSchema: {
             readonly properties?: Record<string, t.JsonSchemaType>;
             readonly required?: string[];
             readonly description?: string;
+            readonly pattern?: string;
+            readonly maxLength?: number;
             readonly additionalProperties?: boolean | t.JsonSchemaType;
         };
         readonly query: {
@@ -64,6 +66,8 @@ export declare const ToolSearchToolDefinition: {
                 readonly properties?: Record<string, t.JsonSchemaType>;
                 readonly required?: string[];
                 readonly description?: string;
+                readonly pattern?: string;
+                readonly maxLength?: number;
                 readonly additionalProperties?: boolean | t.JsonSchemaType;
             };
             readonly query: {

package/dist/types/tools/search/schema.d.ts

@@ -43,6 +43,8 @@ export declare const WebSearchToolSchema: {
             readonly properties?: Record<string, import("../..").JsonSchemaType>;
             readonly required?: string[];
             readonly description?: string;
+            readonly pattern?: string;
+            readonly maxLength?: number;
             readonly additionalProperties?: boolean | import("../..").JsonSchemaType;
         };
         readonly query: {
@@ -88,6 +90,8 @@ export declare const WebSearchToolDefinition: {
                 readonly properties?: Record<string, import("../..").JsonSchemaType>;
                 readonly required?: string[];
                 readonly description?: string;
+                readonly pattern?: string;
+                readonly maxLength?: number;
                 readonly additionalProperties?: boolean | import("../..").JsonSchemaType;
             };
             readonly query: {

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

@@ -239,6 +239,8 @@ export interface ScrapeResult {
     references?: References;
     highlights?: Highlight[];
 }
+/** Host implementations need only the public ranking seam, not BaseReranker's private state. */
+export type SearchReranker = Pick<BaseReranker, 'provider' | 'rerank'>;
 export interface ProcessSourcesConfig {
     topResults?: number;
     /** Max chars of scraped content stored per source and passed to the
@@ -258,7 +260,7 @@ export interface ProcessSourcesConfig {
     separatorExpandBy?: number;
     strategies?: string[];
     filterContent?: boolean;
-    reranker?: BaseReranker;
+    reranker?: SearchReranker;
     logger?: Logger;
 }
 export interface FirecrawlConfig {

package/dist/types/tools/subagent/SubagentExecutionRegistry.d.ts

@@ -44,6 +44,8 @@ export type SubagentInvocationBinding = Readonly<{
     description: string;
     subagentType: string;
     configId?: string;
+    /** Value-free identity of the call's validated host arguments. */
+    hostArgsDigest?: string;
 }>;
 export type SubagentSettlementBinding = Readonly<{
     definitionAuthority: 'provisional' | 'effective';
@@ -98,6 +100,7 @@ export declare class SubagentSettlementBindingError extends Error {
 export declare class SubagentExecutionRecord<TResult, TResolvedConfig, TActiveRun, TSettledOutput = never> {
     readonly address: SubagentExecutionAddress;
     private identityValue?;
+    private attemptedIdentityValue?;
     private bindingValue?;
     private bindingAuthority?;
     private invocationValue?;
@@ -118,6 +121,9 @@ export declare class SubagentExecutionRecord<TResult, TResolvedConfig, TActiveRu
     constructor(address: SubagentExecutionAddress, resumeExecution?: SubagentResumeExecution);
     get snapshot(): ExecutionSnapshot<TResult, TResolvedConfig, TActiveRun>;
     get identity(): SubagentExecutionIdentity | undefined;
+    /** Correlation only; never committed identity or resume authority. */
+    get attemptedIdentity(): SubagentExecutionIdentity | undefined;
+    recordIdentityAttempt(identity: SubagentExecutionIdentity): void;
     get binding(): SubagentDefinitionBinding | undefined;
     get resumeExecution(): SubagentResumeExecution | undefined;
     get invocation(): SubagentInvocationBinding | undefined;

package/dist/types/tools/subagent/SubagentExecutor.d.ts

@@ -1,7 +1,8 @@
 import { BaseMessage } from '@langchain/core/messages';
 import type { RunnableConfig } from '@langchain/core/runnables';
 import type { ToolCall } from '@langchain/core/messages/tool';
-import type { MultiAgentGraphState, HumanInTheLoopConfig, StandardGraphInput, ExecutableSubagentConfigEntry, SubagentExecutionContext, SubagentContextAdapter, SubagentContextResult, SubagentTaskConfig, SubagentTaskRuntime, SubagentUsageSink, TokenCounter } from '@/types';
+import type { MultiAgentGraphState, HumanInTheLoopConfig, StandardGraphInput, ExecutableSubagentConfigEntry, SubagentExecutionContext, SubagentContextAdapter, SubagentContextResult, SubagentTaskConfig, SubagentTaskRuntime, SubagentHostArgs, SubagentUsageSink, TokenCounter } from '@/types';
+import type { SubagentResolutionPhase, SubagentResolutionCause, SubagentHostArgumentFailure, SubagentResolutionFailureHandler } from './diagnostics';
 import type { SubagentResumeManifest, SettledSubagentToolOutput } from './SubagentReplay';
 import type { GraphFactory } from '@/graphs/graphFactory';
 import type { StandardGraph } from '@/graphs/Graph';
@@ -70,10 +71,21 @@ export type SubagentExecuteParams = {
     taskRuntime?: SubagentTaskRuntime;
     /** Host-restored child transcript for a fresh continuation run. @internal */
     initialMessages?: BaseMessage[];
+    /**
+     * Values for the selected subagent's declared `hostArgs`. Checked against
+     * the declaration before an execution opens, then bound to it.
+     */
+    hostArgs?: SubagentHostArgs;
 };
 export type SubagentExecuteResult = SubagentContextResult & {
     /** Tagged internal failure; foreground callers retain the legacy content. */
     error?: string;
+    /** Safe startup classification retained for detached host delivery. */
+    resolutionFailure?: {
+        phase: SubagentResolutionPhase;
+        cause: SubagentResolutionCause;
+        hostArgument?: SubagentHostArgumentFailure;
+    };
     /** Completed child work whose host projection must be retried without re-execution. */
     retryableDelivery?: true;
 };
@@ -114,6 +126,7 @@ export type SubagentExecutorOptions = {
      * graph's own resolved limits; without this the child would silently
      * revert to the defaults.
      */
+    providerTextProtection?: StandardGraphInput['providerTextProtection'];
     streamLimits?: StandardGraphInput['streamLimits'];
     humanInTheLoop?: HumanInTheLoopConfig;
     /** Shared durable saver used to recover outer tool lifecycle results before
@@ -161,6 +174,8 @@ export type SubagentExecutorOptions = {
     /** Host-owned process-local task namespace for detached execution. */
     taskConfig?: SubagentTaskConfig;
     subagentContext?: SubagentContextAdapter;
+    /** Host diagnostic sink and safe cause classifier for startup failures. */
+    onResolutionFailure?: SubagentResolutionFailureHandler;
 };
 export declare class SubagentExecutor {
     private readonly configs;
@@ -179,6 +194,7 @@ export declare class SubagentExecutor {
     private readonly executionContext;
     private readonly langfuse?;
     private readonly tokenCounter?;
+    private readonly providerTextProtection?;
     private readonly streamLimits?;
     private readonly humanInTheLoop?;
     private readonly checkpointer?;
@@ -189,6 +205,7 @@ export declare class SubagentExecutor {
     private readonly usageSink?;
     private readonly taskConfig?;
     private readonly subagentContext?;
+    private readonly onResolutionFailure?;
     private readonly executions;
     private replayCheckpointWorkflow?;
     private readonly resolveParentHandlerRegistry?;
@@ -264,9 +281,13 @@ export declare class SubagentExecutor {
     clearHeavyState(): void;
     private getResumeCheckpointMarker;
     getSettledToolOutput(call: ToolCall, config: RunnableConfig): Promise<SettledSubagentToolOutput | undefined>;
+    private restoreSettledToolOutput;
     persistSettledToolOutput(call: ToolCall, config: RunnableConfig, settled: SettledSubagentToolOutput): Promise<void>;
     private persistChildCheckpointMarker;
     execute(params: SubagentExecuteParams): Promise<SubagentExecuteResult>;
+    private getReplaySignal;
+    private createReplayResolutionError;
+    private createResolutionFailure;
     private executeOnce;
     private completeHostContext;
     /**

package/dist/types/tools/subagent/SubagentReplay.d.ts

@@ -1,8 +1,8 @@
 import type { ToolCall, ToolMessage } from '@langchain/core/messages/tool';
 import type { RunnableConfig } from '@langchain/core/runnables';
+import type { FadingTier, FadingTiers, RunStepResumeState, ToolSessionContext } from '@/types';
 import type { ToolOutputReferenceState } from '@/tools/toolOutputReferences';
 import type { ToolApprovalReplaySnapshot } from '@/hooks';
-import type { FadingTier, FadingTiers, RunStepResumeState, ToolSessionContext } from '@/types';
 export declare const SUBAGENT_RESUME_MANIFEST_CONFIG_KEY = "__librechat_subagent_resume_manifest";
 export declare const SUBAGENT_RESUME_ATTEMPT_CONFIG_KEY = "__librechat_subagent_resume_attempt";
 export declare const SUBAGENT_PARENT_BATCH_CONFIG_KEY = "__librechat_subagent_parent_batch";
@@ -56,6 +56,8 @@ export interface SubagentResumeExecution {
     subagentType?: string;
     /** Lazy child revision bound when this execution first resolved. */
     configId?: string;
+    /** SHA-256 identity of the host arguments bound to this execution; never the values. */
+    hostArgsDigest?: string;
     approvalExecutionScope: string;
     checkpoints: SubagentCheckpointReference[];
     graphState: SubagentGraphResumeState;

package/dist/types/tools/subagent/diagnostics.d.ts

@@ -1,20 +1,68 @@
+import type { SubagentHostArgs } from '@/types/graph';
 import { SubagentSettlementBindingError, SubagentDefinitionBindingError, SubagentInvocationBindingError, SubagentExecutionInvalidatedError } from './SubagentExecutionRegistry';
 import { describeCodeApiError } from '@/tools/diagnostics';
 /** Which step of child start-up failed: execution identity, then host config resolution. */
 export type SubagentResolutionPhase = 'identity' | 'config';
-declare const SUBAGENT_ERROR_TYPES: readonly [readonly ["SubagentExecutionInvalidatedError", typeof SubagentExecutionInvalidatedError], readonly ["SubagentDefinitionBindingError", typeof SubagentDefinitionBindingError], readonly ["SubagentInvocationBindingError", typeof SubagentInvocationBindingError], readonly ["SubagentSettlementBindingError", typeof SubagentSettlementBindingError]];
-type SubagentErrorLabel = (typeof SUBAGENT_ERROR_TYPES)[number][0] | ReturnType<typeof describeCodeApiError>['type'];
+/** Why a host resolver refused a declared host argument value. */
+export type SubagentHostArgumentRejection = 'unavailable' | 'not_allowed';
 /**
- * Follows the rule in `@/tools/diagnostics`: every field is a value this
- * module owns or a host-registered subagent type, never text from the error.
- * The failure the model sees is a fixed sentence, so this line is the only
- * operator account of it; the host logs its own error text where it throws.
+ * Thrown by a lazy resolver to refuse one declared host argument value. The
+ * parent model receives a fixed message naming the argument; the value and
+ * any error text stay private.
  */
+export declare class SubagentHostArgumentError extends Error {
+    readonly argument: string;
+    readonly rejection: SubagentHostArgumentRejection;
+    constructor(argument: string, rejection: SubagentHostArgumentRejection);
+}
+/** Safe host-argument refusal retained across the detached delivery boundary. */
+export type SubagentHostArgumentFailure = {
+    argument: string;
+    rejection: SubagentHostArgumentRejection;
+};
+declare const SUBAGENT_ERROR_TYPES: readonly [readonly ["SubagentHostArgumentError", typeof SubagentHostArgumentError], readonly ["SubagentExecutionInvalidatedError", typeof SubagentExecutionInvalidatedError], readonly ["SubagentDefinitionBindingError", typeof SubagentDefinitionBindingError], readonly ["SubagentInvocationBindingError", typeof SubagentInvocationBindingError], readonly ["SubagentSettlementBindingError", typeof SubagentSettlementBindingError]];
+type SubagentErrorLabel = (typeof SUBAGENT_ERROR_TYPES)[number][0] | ReturnType<typeof describeCodeApiError>['type'];
+declare const SUBAGENT_RESOLUTION_MESSAGES: {
+    readonly workspace_unavailable: "Subagent error: Workspace unavailable. Retry later or choose another workspace.";
+    readonly agent_unavailable: "Subagent error: Agent not found or not accessible.";
+    readonly model_unavailable: "Subagent error: Model or provider unavailable.";
+    readonly configuration_changed: "Subagent error: Subagent configuration changed. Start a new execution.";
+    readonly host_argument_rejected: "Subagent error: A requested subagent argument is not available. Omit it to let the host choose, or pass a different value.";
+    readonly unknown: "Subagent error: Unable to initialize the selected subagent.";
+};
+/** Host classifications accepted at the public failure boundary. */
+export type SubagentResolutionCause = keyof typeof SUBAGENT_RESOLUTION_MESSAGES;
+export type SubagentResolutionContext = {
+    parentRunId: string;
+    parentAgentId?: string;
+    parentToolCallId?: string;
+    threadId?: string;
+    childRunId: string;
+    childThreadId: string;
+    taskId?: string;
+};
+/** No received error text, writable error names, or stacks enter this payload. */
 export type SubagentResolutionDiagnostic = {
     phase: SubagentResolutionPhase;
     subagentType: string;
     aborted: boolean;
     type: SubagentErrorLabel;
-};
-export declare function logSubagentResolutionFailure(phase: SubagentResolutionPhase, subagentType: string, signal: AbortSignal, error: unknown): void;
+    cause: SubagentResolutionCause;
+    message: (typeof SUBAGENT_RESOLUTION_MESSAGES)[SubagentResolutionCause];
+} & Partial<SubagentResolutionContext>;
+/** The original error is private. Return a classification, never error text. */
+export type SubagentResolutionFailureHandler = (detail: Readonly<SubagentResolutionDiagnostic>, error: unknown) => SubagentResolutionCause | void;
+export declare function getSubagentResolutionFailureMessage(cause: SubagentResolutionCause): SubagentResolutionDiagnostic['message'];
+/** Returns a resolver's typed host-argument refusal when its name is safe to show. */
+export declare function getSubagentHostArgumentFailure(error: unknown, suppliedHostArgs: SubagentHostArgs | undefined): SubagentHostArgumentFailure | undefined;
+/** Model-facing message for a refused host argument. */
+export declare function getSubagentHostArgumentFailureMessage(failure: SubagentHostArgumentFailure): string;
+/** Safe typed failure retained when detached execution crosses the host boundary. */
+export declare class SubagentResolutionError extends Error {
+    readonly phase: SubagentResolutionPhase;
+    readonly resolutionCause: SubagentResolutionCause;
+    readonly hostArgument?: SubagentHostArgumentFailure;
+    constructor(phase: SubagentResolutionPhase, cause: SubagentResolutionCause, hostArgument?: SubagentHostArgumentFailure);
+}
+export declare function logSubagentResolutionFailure(phase: SubagentResolutionPhase, subagentType: string, signal: AbortSignal, error: unknown, context?: SubagentResolutionContext, onResolutionFailure?: SubagentResolutionFailureHandler, suppliedHostArgs?: SubagentHostArgs): SubagentResolutionDiagnostic;
 export {};

package/dist/types/tools/subagent/hostArgs.d.ts

@@ -0,0 +1,57 @@
+import type { SubagentHostArgs, SubagentHostArgSpec, SubagentHostArgSpecs } from '@/types/graph';
+import type { JsonSchemaType } from '@/types/tools';
+/** Bounds on host-declared subagent call arguments and their values. */
+export declare const SUBAGENT_HOST_ARG_LIMITS: Readonly<{
+    argsPerSubagent: 8;
+    distinctArgs: 16;
+    enumValues: 64;
+    mergedEnumValues: 256;
+    valueLength: 256;
+    descriptionLength: 1024;
+}>;
+/** Any subagent entry that may declare host arguments. */
+export type SubagentHostArgDeclaration = {
+    type: string;
+    hostArgs?: SubagentHostArgSpecs;
+};
+export type SubagentHostArgsResult = {
+    ok: true;
+    hostArgs?: SubagentHostArgs;
+} | {
+    ok: false;
+    message: string;
+};
+type HostArgEntry = readonly [string, SubagentHostArgSpec];
+/** A name a host may declare: lowercase snake case, not a built-in subagent argument. */
+export declare function isSubagentHostArgName(name: string): boolean;
+/**
+ * Returns a subagent's validated host argument declarations in declaration
+ * order. Throws on a malformed or oversized declaration.
+ */
+export declare function getSubagentHostArgSpecs(config: SubagentHostArgDeclaration): readonly HostArgEntry[];
+/** Every host argument name declared by at least one subagent. */
+export declare function collectSubagentHostArgNames(configs: readonly SubagentHostArgDeclaration[]): ReadonlySet<string>;
+/**
+ * Builds one optional tool property per declared host argument plus a
+ * per-type summary of the values each subagent accepts. The first
+ * declaration's description wins; enums are unioned across subagents.
+ */
+export declare function buildSubagentHostArgProperties(configs: readonly SubagentHostArgDeclaration[]): {
+    properties: Record<string, JsonSchemaType>;
+    summaries: ReadonlyMap<string, string>;
+};
+/**
+ * Reads the declared host argument properties from raw tool input. Missing,
+ * null, and blank values count as omitted; other non-string values are
+ * rejected rather than coerced.
+ */
+export declare function pickSubagentHostArgInput(input: object, names: ReadonlySet<string>): SubagentHostArgsResult;
+/**
+ * Checks call values against the selected subagent's declarations and
+ * returns them frozen in canonical key order. Rejects arguments the selected
+ * subagent does not declare, including ones declared by a sibling.
+ */
+export declare function resolveSubagentHostArgs(config: SubagentHostArgDeclaration, hostArgs: SubagentHostArgs | undefined): SubagentHostArgsResult;
+/** Opaque, value-free identity of a call's host arguments for replay records. */
+export declare function getSubagentHostArgsDigest(hostArgs: SubagentHostArgs | undefined): string | undefined;
+export {};

package/dist/types/tools/subagent/index.d.ts

@@ -2,3 +2,6 @@ export { DEFAULT_SUBAGENT_DESCRIPTION, SubagentExecutor, filterSubagentResult, f
 export type { SubagentExecuteParams, SubagentExecuteResult, SubagentExecutorOptions, ChildGraphFactory, } from './SubagentExecutor';
 export { InMemorySubagentTaskStore } from './InMemorySubagentTaskStore';
 export type { InMemorySubagentTaskStoreOptions } from './InMemorySubagentTaskStore';
+export { SubagentResolutionError, SubagentHostArgumentError, getSubagentResolutionFailureMessage, getSubagentHostArgumentFailureMessage, } from './diagnostics';
+export { SUBAGENT_HOST_ARG_LIMITS, buildSubagentHostArgProperties, resolveSubagentHostArgs, } from './hostArgs';
+export type { SubagentHostArgumentFailure, SubagentHostArgumentRejection, SubagentResolutionPhase, SubagentResolutionCause, SubagentResolutionContext, SubagentResolutionDiagnostic, SubagentResolutionFailureHandler, } from './diagnostics';

package/dist/types/types/graph.d.ts

@@ -1,3 +1,4 @@
+import type { ProviderTextProtection } from '@/protection/providerText';
 import type { BaseMessage, AIMessageChunk, SystemMessage, UsageMetadata } from '@langchain/core/messages';
 import type { BindToolsInput } from '@langchain/core/language_models/chat_models';
 import type { START, StateGraph, StateGraphArgs } from '@langchain/langgraph';
@@ -8,6 +9,7 @@ import type { RunStep, ModelResponseEvent, ModelToolsClaimedEvent, RunStepDeltaE
 import type { SummarizationNodeInput, SummarizeCompleteEvent, CompactionSemanticIndex, SummarizationConfig, SummarizeStartEvent, SummarizeDeltaEvent } from '@/types/summarize';
 import type { ToolMap, ToolSessionMap, ToolEndEvent, GenericTool, LCTool, ToolExecutionConfig, ToolExecuteBatchRequest } from '@/types/tools';
 import type { TokenCounter, StreamLimits, StreamPreemption, TokenBudgetBreakdown } from '@/types/run';
+import type { SubagentResolutionFailureHandler } from '@/tools/subagent/diagnostics';
 import type { SubagentTaskConfig } from '@/types/subagentTasks';
 import type { StandardGraph, MultiAgentGraph } from '@/graphs';
 import type { ProviderClientOptionsConfig } from '@/types/llm';
@@ -286,6 +288,7 @@ export type ModelEndData = (StreamEventData & {
 }) | undefined;
 export type GraphTools = GenericTool[] | BindToolsInput[] | GoogleAIToolType[];
 export type StandardGraphInput = {
+    providerTextProtection?: ProviderTextProtection;
     runId?: string;
     signal?: AbortSignal;
     agents: AgentInputs[];
@@ -320,6 +323,8 @@ export type StandardGraphInput = {
     subagentTasks?: SubagentTaskConfig;
     /** Host-owned context and result projection for each isolated child execution. */
     subagentContext?: SubagentContextAdapter;
+    /** Receives private startup errors; returns only an SDK-owned public cause. */
+    onSubagentResolutionFailure?: SubagentResolutionFailureHandler;
     /**
      * True when this graph IS a subagent child run (set by `SubagentExecutor`
      * when it constructs the child graph). Drives the hook-input `agentId`
@@ -433,6 +438,26 @@ export interface SubagentResolveConfigurable {
     user?: Readonly<SubagentResolveUserContext>;
     user_id?: string;
 }
+/**
+ * Optional string argument a host lets the parent model pass on a subagent
+ * call, such as where the child should run. The SDK checks the declared shape
+ * before resolution; the host still authorizes the value in its resolver.
+ */
+export interface SubagentHostArgSpec {
+    /** Model-facing explanation of the argument and when to pass it. */
+    description: string;
+    /**
+     * Values this subagent accepts. Omit to accept a bounded free-form string,
+     * whose format the resolver must check.
+     */
+    enum?: readonly string[];
+    /** Maximum length of a free-form value (at most 256). */
+    maxLength?: number;
+}
+/** Host argument declarations keyed by tool-call property name. */
+export type SubagentHostArgSpecs = Readonly<Record<string, SubagentHostArgSpec>>;
+/** Validated host argument values from one subagent call. */
+export type SubagentHostArgs = Readonly<Record<string, string>>;
 /** Runtime context supplied when a host lazily resolves a selected subagent. */
 export interface SubagentResolveContext {
     /** Stable subagent identity selected by the model. */
@@ -451,6 +476,13 @@ export interface SubagentResolveContext {
     signal: AbortSignal;
     /** Stable, sanitized host context from the parent tool invocation. */
     configurable?: Readonly<SubagentResolveConfigurable>;
+    /**
+     * Values the parent passed for this subagent's declared `hostArgs`, already
+     * checked against the declaration. Omitted when the call passed none. Bound
+     * to the execution: a reconstruction with different values is rejected
+     * before the resolver runs.
+     */
+    hostArgs?: SubagentHostArgs;
 }
 /** Host contract for resolving a selected subagent's full graph inputs. */
 export type SubagentAgentInputsResolver = (context: SubagentResolveContext) => Promise<AgentInputs>;
@@ -477,6 +509,12 @@ export interface SubagentConfig extends SubagentConfigBase {
      * `(context.executionId, context.descriptor.configId)`.
      */
     resolveAgentInputs?: SubagentAgentInputsResolver;
+    /**
+     * Optional per-call arguments the parent model may pass for this subagent,
+     * delivered to `resolveAgentInputs` as `context.hostArgs`. Only lazy
+     * configs accept them. Declaring none leaves the tool schema unchanged.
+     */
+    hostArgs?: SubagentHostArgSpecs;
     /** When true, reuse the parent's AgentInputs (context isolation without separate config). */
     self?: boolean;
 }
@@ -491,6 +529,7 @@ export interface GraphSubagentConfig extends SubagentConfigBase {
     kind: 'graph';
     configId?: never;
     resolveAgentInputs?: never;
+    hostArgs?: never;
     allowNested?: false;
     agents: AgentInputs[];
     /**