@librechat/agents 4.0.1 → 4.0.3

package/src/tools/subagent/SubagentReplay.ts

@@ -1,20 +1,20 @@
 import type { ToolCall, ToolMessage } from '@langchain/core/messages/tool';
 import type { RunnableConfig } from '@langchain/core/runnables';
-import type { ToolOutputReferenceState } from '@/tools/toolOutputReferences';
-import type { ToolApprovalReplaySnapshot } from '@/hooks';
 import type {
   FadingTier,
   FadingTiers,
   RunStepResumeState,
   ToolSessionContext,
 } from '@/types';
-import { isFadingTier, isLegacyFadingTier } from '@/messages/fading';
+import type { ToolOutputReferenceState } from '@/tools/toolOutputReferences';
+import type { ToolApprovalReplaySnapshot } from '@/hooks';
 import {
   attachRunStepResumeState,
   getRunStepResumeState,
   isRunStepResumeState,
   stripRunStepResumeState,
 } from '@/tools/runStepResume';
+import { isFadingTier, isLegacyFadingTier } from '@/messages/fading';
 
 export const SUBAGENT_RESUME_MANIFEST_CONFIG_KEY =
   '__librechat_subagent_resume_manifest';
@@ -35,6 +35,7 @@ const SUBAGENT_RESUME_PRIVATE_PAYLOAD_KEYS = [
   SUBAGENT_RESUME_WRAPPER_VERSION_KEY,
 ] as const;
 const MAX_RESUME_MANIFEST_DEPTH = 32;
+const HOST_ARGS_DIGEST_PATTERN = /^[a-f0-9]{64}$/;
 
 export interface SubagentCheckpointReference {
   threadId: string;
@@ -83,6 +84,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;
@@ -354,6 +357,7 @@ function isSubagentResumeExecution(
   const childRunId = execution.childRunId;
   const subagentType = execution.subagentType;
   const configId = execution.configId;
+  const hostArgsDigest = execution.hostArgsDigest;
   const approvalExecutionScope = execution.approvalExecutionScope;
   const checkpoints = execution.checkpoints;
   const graphState = execution.graphState;
@@ -363,6 +367,9 @@ function isSubagentResumeExecution(
     !isString(childRunId) ||
     (subagentType != null && !isString(subagentType)) ||
     (configId != null && !isString(configId)) ||
+    (hostArgsDigest != null &&
+      (typeof hostArgsDigest !== 'string' ||
+        !HOST_ARGS_DIGEST_PATTERN.test(hostArgsDigest))) ||
     !isString(approvalExecutionScope) ||
     !Array.isArray(checkpoints) ||
     checkpoints.length === 0 ||

package/src/tools/subagent/childGraphConfig.ts

@@ -15,6 +15,7 @@ import {
   MAX_GRAPH_SUBAGENT_MEMBERS,
   MAX_GRAPH_SUBAGENT_TURNS,
 } from './runtimeLimits';
+import { getSubagentHostArgSpecs } from './hostArgs';
 
 const RESERVED_GRAPH_MEMBER_IDS = new Set([
   '__start__',
@@ -69,6 +70,7 @@ type GraphSubagentConfigCandidate = {
   configId?: unknown;
   agentInputs?: unknown;
   resolveAgentInputs?: unknown;
+  hostArgs?: unknown;
   self?: unknown;
 };
 
@@ -156,10 +158,11 @@ function assertGraphSubagentConfigShape(
     candidate.agentInputs !== undefined ||
     candidate.resolveAgentInputs !== undefined ||
     candidate.configId !== undefined ||
+    candidate.hostArgs !== undefined ||
     candidate.self !== undefined
   ) {
     throw new Error(
-      `Graph subagent "${configType}" cannot define agentInputs or self, or lazy fields configId/resolveAgentInputs.`
+      `Graph subagent "${configType}" cannot define agentInputs or self, or lazy fields configId/resolveAgentInputs/hostArgs.`
     );
   }
 }
@@ -482,6 +485,14 @@ function normalizeSingleAgentConfig(
       `Subagent "${config.type}" cannot combine self with resolveAgentInputs.`
     );
   }
+  if (
+    getSubagentHostArgSpecs(config).length > 0 &&
+    (config.resolveAgentInputs == null || config.agentInputs != null)
+  ) {
+    throw new Error(
+      `Subagent "${config.type}" declares hostArgs, which only a lazy resolveAgentInputs config without eager agentInputs can receive.`
+    );
+  }
   if (config.agentInputs != null) {
     return config as ResolvedSingleAgentSubagentConfig;
   }

package/src/tools/subagent/diagnostics.ts

@@ -1,3 +1,4 @@
+import type { SubagentHostArgs } from '@/types/graph';
 import {
   SubagentSettlementBindingError,
   SubagentDefinitionBindingError,
@@ -5,11 +6,39 @@ import {
   SubagentExecutionInvalidatedError,
 } from './SubagentExecutionRegistry';
 import { describeCodeApiError } from '@/tools/diagnostics';
+import { isSubagentHostArgName } from './hostArgs';
 
 /** Which step of child start-up failed: execution identity, then host config resolution. */
 export type SubagentResolutionPhase = 'identity' | 'config';
 
+/** Why a host resolver refused a declared host argument value. */
+export type SubagentHostArgumentRejection = 'unavailable' | 'not_allowed';
+
+/**
+ * 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 class SubagentHostArgumentError extends Error {
+  readonly argument: string;
+  readonly rejection: SubagentHostArgumentRejection;
+
+  constructor(argument: string, rejection: SubagentHostArgumentRejection) {
+    super('Subagent host argument was rejected.');
+    this.name = 'SubagentHostArgumentError';
+    this.argument = argument;
+    this.rejection = rejection;
+  }
+}
+
+/** Safe host-argument refusal retained across the detached delivery boundary. */
+export type SubagentHostArgumentFailure = {
+  argument: string;
+  rejection: SubagentHostArgumentRejection;
+};
+
 const SUBAGENT_ERROR_TYPES = [
+  ['SubagentHostArgumentError', SubagentHostArgumentError],
   ['SubagentExecutionInvalidatedError', SubagentExecutionInvalidatedError],
   ['SubagentDefinitionBindingError', SubagentDefinitionBindingError],
   ['SubagentInvocationBindingError', SubagentInvocationBindingError],
@@ -20,18 +49,132 @@ type SubagentErrorLabel =
   | (typeof SUBAGENT_ERROR_TYPES)[number][0]
   | ReturnType<typeof describeCodeApiError>['type'];
 
-/**
- * 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.
- */
+const SUBAGENT_RESOLUTION_MESSAGES = {
+  workspace_unavailable:
+    'Subagent error: Workspace unavailable. Retry later or choose another workspace.',
+  agent_unavailable: 'Subagent error: Agent not found or not accessible.',
+  model_unavailable: 'Subagent error: Model or provider unavailable.',
+  configuration_changed:
+    'Subagent error: Subagent configuration changed. Start a new execution.',
+  host_argument_rejected:
+    'Subagent error: A requested subagent argument is not available. Omit it to let the host choose, or pass a different value.',
+  unknown: 'Subagent error: Unable to initialize the selected subagent.',
+} as const;
+
+/** 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;
-};
+  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;
+
+function normalizeResolutionCause(
+  cause: SubagentResolutionCause | void
+): SubagentResolutionCause {
+  switch (cause) {
+  case 'workspace_unavailable':
+  case 'agent_unavailable':
+  case 'model_unavailable':
+  case 'configuration_changed':
+  case 'host_argument_rejected':
+    return cause;
+  default:
+    return 'unknown';
+  }
+}
+
+export function getSubagentResolutionFailureMessage(
+  cause: SubagentResolutionCause
+): SubagentResolutionDiagnostic['message'] {
+  return SUBAGENT_RESOLUTION_MESSAGES[normalizeResolutionCause(cause)];
+}
+
+/** Returns a resolver's typed host-argument refusal when its name is safe to show. */
+export function getSubagentHostArgumentFailure(
+  error: unknown,
+  suppliedHostArgs: SubagentHostArgs | undefined
+): SubagentHostArgumentFailure | undefined {
+  try {
+    if (
+      !(error instanceof SubagentHostArgumentError) ||
+      suppliedHostArgs == null
+    ) {
+      return undefined;
+    }
+    const { argument, rejection } = error;
+    if (
+      typeof argument !== 'string' ||
+      !isSubagentHostArgName(argument) ||
+      !Object.prototype.hasOwnProperty.call(suppliedHostArgs, argument)
+    ) {
+      return undefined;
+    }
+    return {
+      argument,
+      rejection: rejection === 'unavailable' ? 'unavailable' : 'not_allowed',
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+/** Model-facing message for a refused host argument. */
+export function getSubagentHostArgumentFailureMessage(
+  failure: SubagentHostArgumentFailure
+): string {
+  const { argument } = failure;
+  const omit = `Omit "${argument}" to let the host choose, or pass a different value.`;
+  return failure.rejection === 'unavailable'
+    ? `Subagent error: The requested "${argument}" is unavailable right now. ${omit}`
+    : `Subagent error: The requested "${argument}" is not allowed for this subagent. ${omit}`;
+}
+
+/** Safe typed failure retained when detached execution crosses the host boundary. */
+export class SubagentResolutionError extends Error {
+  readonly phase: SubagentResolutionPhase;
+  readonly resolutionCause: SubagentResolutionCause;
+  readonly hostArgument?: SubagentHostArgumentFailure;
+
+  constructor(
+    phase: SubagentResolutionPhase,
+    cause: SubagentResolutionCause,
+    hostArgument?: SubagentHostArgumentFailure
+  ) {
+    super(
+      hostArgument == null
+        ? getSubagentResolutionFailureMessage(cause)
+        : getSubagentHostArgumentFailureMessage(hostArgument)
+    );
+    this.name = 'SubagentResolutionError';
+    this.phase = phase;
+    this.resolutionCause = normalizeResolutionCause(cause);
+    if (hostArgument != null) {
+      this.hostArgument = hostArgument;
+    }
+  }
+}
 
 function describeSubagentError(error: unknown): SubagentErrorLabel {
   try {
@@ -50,14 +193,42 @@ export function logSubagentResolutionFailure(
   phase: SubagentResolutionPhase,
   subagentType: string,
   signal: AbortSignal,
-  error: unknown
-): void {
+  error: unknown,
+  context?: SubagentResolutionContext,
+  onResolutionFailure?: SubagentResolutionFailureHandler,
+  suppliedHostArgs?: SubagentHostArgs
+): SubagentResolutionDiagnostic {
   const detail: SubagentResolutionDiagnostic = {
+    ...context,
     phase,
     subagentType,
     aborted: signal.aborted,
     type: describeSubagentError(error),
+    cause: 'unknown',
+    message: SUBAGENT_RESOLUTION_MESSAGES.unknown,
   };
+  const hostArgumentRejected =
+    getSubagentHostArgumentFailure(error, suppliedHostArgs) != null;
+  if (hostArgumentRejected) {
+    detail.cause = 'host_argument_rejected';
+    detail.message = SUBAGENT_RESOLUTION_MESSAGES.host_argument_rejected;
+  }
+  if (onResolutionFailure != null) {
+    try {
+      const reported = onResolutionFailure(Object.freeze({ ...detail }), error);
+      const cause = hostArgumentRejected
+        ? detail.cause
+        : normalizeResolutionCause(reported);
+      return {
+        ...detail,
+        cause,
+        message: getSubagentResolutionFailureMessage(cause),
+      };
+    } catch {
+      // A broken diagnostic sink must not replace or expose the original failure.
+    }
+  }
   // eslint-disable-next-line no-console
   console.warn('[SubagentExecutor] Subagent resolution failed', detail);
+  return detail;
 }