Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active
TypeScript aianthropicartifactsawsazurechatgptchatgpt-cloneclaudeclonedeepseekgeminigooglegpt-5librechatmcpo1openairesponses-apivisionwebui
🪵 fix: Explain Failed Attachment Copies and Subagent Start-Up Failures (#17398)
Danny Avila3ccdd252f937
diff --git a/packages/api/src/agents/__tests__/run-codeTools.test.ts b/packages/api/src/agents/__tests__/run-codeTools.test.tsindex e6da4f20cd..fe2bc395e1 100644--- a/packages/api/src/agents/__tests__/run-codeTools.test.ts+++ b/packages/api/src/agents/__tests__/run-codeTools.test.ts@@ -5,6 +5,7 @@ import type { TFile } from 'librechat-data-provider';import type { ProvisionCallbackDeps, ProvisionToolContext } from '~/files/provision/callback';import type { HostSubagentTaskConfig } from '~/agents/subagentDelivery';import type { ServerRequest } from '~/types';+import { reportSubagentResolutionFailure } from '~/agents/failures/subagent';import { createProvisionFilesCallback } from '~/files/provision/callback';import { SUBAGENT_COMPLETION_DELIVERY } from '~/agents/subagentDelivery';import { mergeCodeFilesIntoContext } from '~/agents/codeFilesSession';@@ -528,6 +529,11 @@ describe('createRun code-tool eager/session wiring', () => {);});+ it('reports why a subagent could not start instead of leaving the SDK to guess', async () => {+ const runConfig = await captureRunConfig();+ expect(runConfig.onSubagentResolutionFailure).toBe(reportSubagentResolutionFailure);+ });+it('passes the trusted per-agent code-session partition to the SDK', async () => {const codeSessionKey = 'execute_code:stateful:v1:user';const runConfig = await captureRunConfig(makeAgent({ codeSessionKey }));diff --git a/packages/api/src/agents/failures/subagent.spec.ts b/packages/api/src/agents/failures/subagent.spec.tsnew file mode 100644index 0000000000..e464cea742--- /dev/null+++ b/packages/api/src/agents/failures/subagent.spec.ts@@ -0,0 +1,202 @@+import { logger } from '@librechat/data-schemas';+import { SubagentResolutionError } from '@librechat/agents';+import type { SubagentResolutionDiagnostic } from '@librechat/agents';+import {+ describeErrorCauses,+ describeStackFrames,+ findMCPAuthenticationFailure,+ reportSubagentResolutionFailure,+} from './subagent';+import { MCPAuthenticationRefreshError, MCPAuthenticationRejectedError } from '~/mcp/errors';+import { ReauthenticationRequiredError } from '~/mcp/oauth/tokens';+import { OpenIDReauthRequiredError } from '~/utils/oidc';++const SECRET = 'provider-secret-value';++function diagnostic(+ overrides: Partial<SubagentResolutionDiagnostic> = {},+): SubagentResolutionDiagnostic {+ return {+ phase: 'config',+ subagentType: 'pr-reviewer',+ aborted: false,+ type: 'Error',+ cause: 'unknown',+ message: 'Subagent error: Unable to initialize the selected subagent.',+ parentRunId: 'run-1',+ childRunId: 'child-run-1',+ taskId: 'task-1',+ ...overrides,+ };+}++describe('describeErrorCauses', () => {+ it('keeps name, code and status of every cause, but a message only from trusted errors', () => {+ const root = Object.assign(new Error(`Token refresh failed: api_key=${SECRET}`), {+ code: 'invalid_grant',+ status: 400,+ });+ const error = new SubagentResolutionError('config', 'unknown');+ Object.assign(error, { cause: root });++ const causes = describeErrorCauses(error);++ expect(causes).toEqual([+ {+ name: 'SubagentResolutionError',+ message: 'Subagent error: Unable to initialize the selected subagent.',+ },+ { name: 'Error', code: 'invalid_grant', status: 400 },+ ]);+ expect(JSON.stringify(causes)).not.toContain(SECRET);+ });++ it('stops at a cycle and at its depth bound', () => {+ const first = new Error('first');+ const second = new Error('second', { cause: first });+ Object.assign(first, { cause: second });+ expect(describeErrorCauses(first)).toHaveLength(2);++ let deep: unknown = new Error('0');+ for (let index = 1; index < 10; index++) {+ deep = new Error(String(index), { cause: deep });+ }+ expect(describeErrorCauses(deep)).toHaveLength(4);+ });++ it('describes values that are not errors without echoing them', () => {+ expect(describeErrorCauses(`plain failure ${SECRET}`)).toEqual([{ name: 'string' }]);+ expect(describeErrorCauses(undefined)).toEqual([]);+ expect(describeErrorCauses({ name: 'bad name with spaces', code: { nested: SECRET } })).toEqual(+ [{ name: 'UnknownError' }],+ );+ });+});++describe('describeStackFrames', () => {+ it('keeps where the error was thrown and drops its message', () => {+ const frames = describeStackFrames(new Error(`Authorization: Bearer ${SECRET}\nsecond line`));+ expect(frames.length).toBeGreaterThan(0);+ expect(frames.every((frame) => frame.startsWith('at '))).toBe(true);+ expect(JSON.stringify(frames)).not.toContain(SECRET);+ expect(describeStackFrames('not an error')).toEqual([]);+ });++ it('never mistakes a message line shaped like a frame for one', () => {+ const injected = new Error(`provider said:${String.fromCharCode(10)} at api_key=${SECRET}`);+ const frames = describeStackFrames(injected);+ expect(frames.length).toBeGreaterThan(0);+ expect(JSON.stringify(frames)).not.toContain(SECRET);++ const rewritten = new Error('original');+ void rewritten.stack;+ rewritten.message = `rewritten ${SECRET}`;+ expect(describeStackFrames(rewritten)).toEqual([]);+ });+});++describe('findMCPAuthenticationFailure', () => {+ it('names the MCP server that needs re-authentication anywhere in the cause chain', () => {+ expect(+ findMCPAuthenticationFailure(+ new Error('child init failed', {+ cause: new ReauthenticationRequiredError('clickhouse-docs', 'expired'),+ }),+ ),+ ).toEqual({ serverName: 'clickhouse-docs', retryable: false });+ expect(+ findMCPAuthenticationFailure(new MCPAuthenticationRejectedError('github', false)),+ ).toEqual({ serverName: 'github', retryable: false });+ });++ it('marks failures that a retry may clear as retryable', () => {+ expect(findMCPAuthenticationFailure(new MCPAuthenticationRefreshError())).toEqual({+ retryable: true,+ });+ expect(+ findMCPAuthenticationFailure(new MCPAuthenticationRejectedError('github', true)),+ ).toEqual({ serverName: 'github', retryable: true });+ });++ it('does not treat a model provider or other HTTP 401 as an MCP sign-in', () => {+ expect(+ findMCPAuthenticationFailure(Object.assign(new Error('401 invalid_grant'), { status: 401 })),+ ).toBeUndefined();+ expect(findMCPAuthenticationFailure(new Error('Model not found'))).toBeUndefined();+ expect(+ findMCPAuthenticationFailure(new OpenIDReauthRequiredError('OpenID ID token is expired')),+ ).toBeUndefined();+ });+});++describe('reportSubagentResolutionFailure', () => {+ it('logs the underlying cause and the MCP server, and keeps the SDK classification', () => {+ const warn = jest.spyOn(logger, 'warn').mockImplementation(() => logger);+ const error = new Error(`Initialization failed: ${SECRET}`, {+ cause: new ReauthenticationRequiredError('clickhouse-docs', 'expired'),+ });++ const cause = reportSubagentResolutionFailure(diagnostic(), error);++ expect(cause).toBeUndefined();+ expect(warn).toHaveBeenCalledWith(+ '[subagents] Subagent could not start: an MCP server it uses needs re-authentication',+ {+ phase: 'config',+ subagentType: 'pr-reviewer',+ cause: 'unknown',+ errorType: 'Error',+ aborted: false,+ taskId: 'task-1',+ childRunId: 'child-run-1',+ parentRunId: 'run-1',+ mcpAuthentication: { serverName: 'clickhouse-docs', retryable: false },+ causes: [+ { name: 'Error' },+ {+ name: 'ReauthenticationRequiredError',+ message:+ 'Re-authentication required for "clickhouse-docs": access token expired and no refresh token available',+ },+ ],+ frames: expect.arrayContaining([expect.stringMatching(/^at /)]),+ },+ );+ expect(JSON.stringify(warn.mock.calls)).not.toContain(SECRET);+ warn.mockRestore();+ });++ it('says a retry may succeed when the MCP sign-in failure is transient', () => {+ const warn = jest.spyOn(logger, 'warn').mockImplementation(() => logger);++ reportSubagentResolutionFailure(diagnostic(), new MCPAuthenticationRefreshError());++ expect(warn).toHaveBeenCalledWith(+ '[subagents] Subagent could not start: an MCP server it uses could not authenticate; a retry may succeed',+ expect.objectContaining({ mcpAuthentication: { retryable: true } }),+ );+ warn.mockRestore();+ });++ it('logs other failures without an MCP reason', () => {+ const warn = jest.spyOn(logger, 'warn').mockImplementation(() => logger);++ reportSubagentResolutionFailure(+ diagnostic({ phase: 'identity', taskId: undefined }),+ new Error('Agent not found'),+ );++ expect(warn).toHaveBeenCalledWith('[subagents] Subagent could not start', {+ phase: 'identity',+ subagentType: 'pr-reviewer',+ cause: 'unknown',+ errorType: 'Error',+ aborted: false,+ childRunId: 'child-run-1',+ parentRunId: 'run-1',+ causes: [{ name: 'Error' }],+ frames: expect.any(Array),+ });+ warn.mockRestore();+ });+});diff --git a/packages/api/src/agents/failures/subagent.ts b/packages/api/src/agents/failures/subagent.tsnew file mode 100644index 0000000000..70032fb222--- /dev/null+++ b/packages/api/src/agents/failures/subagent.ts@@ -0,0 +1,210 @@+import { logger } from '@librechat/data-schemas';+import { SubagentResolutionError } from '@librechat/agents';+import type { SubagentResolutionFailureHandler } from '@librechat/agents';+import {+ MCPAuthenticationRefreshError,+ MCPAuthenticationRejectedError,+ MCPTransportAuthenticationError,+} from '~/mcp/errors';+import { ReauthenticationRequiredError } from '~/mcp/oauth/tokens';+import { CodeWorkspaceSelectionError } from '~/code/errors';+import { OboTokenResolutionError } from '~/mcp/oauth/obo';+import { OpenIDReauthRequiredError } from '~/utils/oidc';+import { getSafeErrorText } from '~/utils/errors';++/** Links of an error's `cause` chain described; deeper causes are rarely informative. */+const MAX_CAUSE_DEPTH = 4;+const MAX_CAUSE_MESSAGE_LENGTH = 300;+const MAX_STACK_FRAMES = 8;+const STACK_FRAME = /^\s+at\s/;+const SAFE_LABEL = /^[A-Za-z0-9_.:-]{1,64}$/;+const SAFE_SERVER_NAME = /^[\w .:@-]{1,128}$/;+const REAUTHENTICATION_SERVER = /^Re-authentication required for "([^"]{1,128})"/;++/**+ * One link of an error chain, safe to log. A message is kept only for errors whose text+ * LibreChat or the agents SDK writes itself; any other message may echo a credential or+ * submitted content, so those links log their name, code and status alone.+ */+export interface SafeErrorCause {+ name: string;+ code?: string | number;+ status?: number;+ message?: string;+}++/** An MCP server whose sign-in failed; `retryable` when retrying may succeed without a new one. */+export interface MCPAuthenticationFailure {+ serverName?: string;+ retryable: boolean;+}++function readProperty(value: object, property: string): unknown {+ try {+ return (value as Record<string, unknown>)[property];+ } catch {+ return undefined;+ }+}++function safeLabel(value: unknown): string | undefined {+ return typeof value === 'string' && SAFE_LABEL.test(value) ? value : undefined;+}++function safeStatus(value: unknown): number | undefined {+ return typeof value === 'number' && Number.isInteger(value) && value >= 100 && value <= 599+ ? value+ : undefined;+}++function isMCPAuthenticationError(error: unknown): error is Error {+ return (+ error instanceof ReauthenticationRequiredError ||+ error instanceof MCPAuthenticationRejectedError ||+ error instanceof MCPAuthenticationRefreshError ||+ error instanceof MCPTransportAuthenticationError ||+ error instanceof OboTokenResolutionError+ );+}++/** Errors whose message LibreChat or the agents SDK composes from fixed text and safe names. */+function hasTrustedMessage(error: object): boolean {+ return (+ isMCPAuthenticationError(error) ||+ error instanceof OpenIDReauthRequiredError ||+ error instanceof SubagentResolutionError ||+ error instanceof CodeWorkspaceSelectionError+ );+}++function describeCause(error: unknown): SafeErrorCause {+ if (error == null || typeof error !== 'object') {+ return { name: typeof error };+ }+ const code = readProperty(error, 'code');+ const status = safeStatus(readProperty(error, 'status') ?? readProperty(error, 'statusCode'));+ const message = readProperty(error, 'message');+ return {+ name: safeLabel(readProperty(error, 'name')) ?? 'UnknownError',+ ...(safeLabel(code) != null || (typeof code === 'number' && Number.isInteger(code))+ ? { code: code as string | number }+ : {}),+ ...(status != null ? { status } : {}),+ ...(typeof message === 'string' && message.length > 0 && hasTrustedMessage(error)+ ? { message: getSafeErrorText(message).slice(0, MAX_CAUSE_MESSAGE_LENGTH) }+ : {}),+ };+}++/** Walks `error` and its `cause` chain, bounded and cycle-safe. */+function errorChain(error: unknown): unknown[] {+ const chain: unknown[] = [];+ let current = error;+ while (current != null && chain.length < MAX_CAUSE_DEPTH && !chain.includes(current)) {+ chain.push(current);+ current = typeof current === 'object' ? readProperty(current, 'cause') : undefined;+ }+ return chain;+}++/** The error and its causes by name, code, status and, for trusted errors, message. */+export function describeErrorCauses(error: unknown): SafeErrorCause[] {+ return errorChain(error).map(describeCause);+}++/**+ * Where an error was thrown: the frames V8 appends after the `name: message` header. A stack+ * whose header no longer matches its name and message is skipped, because a message line that+ * looks like a frame could then pass for one.+ */+export function describeStackFrames(error: unknown): string[] {+ if (!(error instanceof Error) || typeof error.stack !== 'string') {+ return [];+ }+ const header = error.message === '' ? error.name : `${error.name}: ${error.message}`;+ if (!error.stack.startsWith(`${header}\n`)) {+ return [];+ }+ return error.stack+ .slice(header.length + 1)+ .split('\n')+ .filter((line) => STACK_FRAME.test(line))+ .slice(0, MAX_STACK_FRAMES)+ .map((line) => getSafeErrorText(line.trim()));+}++function getServerName(error: object): string | undefined {+ const serverName = readProperty(error, 'serverName');+ if (typeof serverName === 'string' && SAFE_SERVER_NAME.test(serverName)) {+ return serverName;+ }+ const message = readProperty(error, 'message');+ const match = typeof message === 'string' ? REAUTHENTICATION_SERVER.exec(message) : null;+ return match != null && SAFE_SERVER_NAME.test(match[1]) ? match[1] : undefined;+}++/** A refresh outage, or a rejection after the connection already refreshed, may pass on retry. */+function isRetryableAuthenticationError(error: Error): boolean {+ if (error instanceof MCPAuthenticationRefreshError) {+ return true;+ }+ return (+ (error instanceof MCPAuthenticationRejectedError || error instanceof OboTokenResolutionError) &&+ error.retryable+ );+}++/**+ * The MCP server whose sign-in failed anywhere in `error`'s cause chain, or undefined when the+ * failure is not an MCP authentication failure. Generic HTTP 401/403 errors do not count: a+ * model provider rejecting its key is not an MCP server asking the user to sign in again.+ */+export function findMCPAuthenticationFailure(error: unknown): MCPAuthenticationFailure | undefined {+ for (const link of errorChain(error)) {+ if (isMCPAuthenticationError(link)) {+ const serverName = getServerName(link);+ return {+ ...(serverName == null ? {} : { serverName }),+ retryable: isRetryableAuthenticationError(link),+ };+ }+ }+ return undefined;+}++/**+ * Logs why a subagent could not start, which the SDK otherwise reports only as a fixed+ * `cause`. Leaves the SDK's classification unchanged: its causes cannot yet say that an MCP+ * server needs re-authentication, so that reason is logged rather than shown.+ */+export const reportSubagentResolutionFailure: SubagentResolutionFailureHandler = (+ detail,+ error,+) => {+ const mcpAuthentication = findMCPAuthenticationFailure(error);+ logger.warn(+ `[subagents] Subagent could not start${describeMCPAuthenticationFailure(mcpAuthentication)}`,+ {+ phase: detail.phase,+ subagentType: detail.subagentType,+ cause: detail.cause,+ errorType: detail.type,+ aborted: detail.aborted,+ ...(detail.taskId != null ? { taskId: detail.taskId } : {}),+ ...(detail.childRunId != null ? { childRunId: detail.childRunId } : {}),+ ...(detail.parentRunId != null ? { parentRunId: detail.parentRunId } : {}),+ ...(mcpAuthentication != null ? { mcpAuthentication } : {}),+ causes: describeErrorCauses(error),+ frames: describeStackFrames(error),+ },+ );+};++function describeMCPAuthenticationFailure(failure: MCPAuthenticationFailure | undefined): string {+ if (failure == null) {+ return '';+ }+ return failure.retryable+ ? ': an MCP server it uses could not authenticate; a retry may succeed'+ : ': an MCP server it uses needs re-authentication';+}diff --git a/packages/api/src/agents/run.ts b/packages/api/src/agents/run.tsindex 0232a992ff..c0ea3aebfb 100644--- a/packages/api/src/agents/run.ts+++ b/packages/api/src/agents/run.ts@@ -119,6 +119,7 @@ import { resolveConfigHeaders, resolveModelHeaders, mergeHeaders } from '~/utilsimport { interruptToolHandler, supportsRunInterruption } from '~/agents/steering/tools';import { extractDefaultParams, resolveReasoningParams } from '~/endpoints/openai/llm';import { getLLMConfig as getAnthropicLLMConfig } from '~/endpoints/anthropic/llm';+import { reportSubagentResolutionFailure } from '~/agents/failures/subagent';import { createScheduledMCPRunPolicy } from '~/schedules/authorization/run';import { CREATE_FILE_TOOL_NAME, EDIT_FILE_TOOL_NAME } from '~/agents/tools';import { buildAgentInitialToolSessions } from '~/agents/codeFilesSession';@@ -3055,6 +3056,8 @@ export async function createRun({indexTokenCountMap,subagentUsageSink,subagentTasks: activeSubagentTasks,+ // Without it a subagent that cannot start logs nothing beyond the SDK's fixed `cause`.+ onSubagentResolutionFailure: reportSubagentResolutionFailure,...(runFilesActive &&runFiles != null && {subagentContext: { prepare: runFiles.prepare, complete: runFiles.complete },diff --git a/packages/api/src/agents/subagentThreads.spec.ts b/packages/api/src/agents/subagentThreads.spec.tsindex e253b18f99..9c2eebbc0c 100644--- a/packages/api/src/agents/subagentThreads.spec.ts+++ b/packages/api/src/agents/subagentThreads.spec.ts@@ -1,6 +1,7 @@import mongoose from 'mongoose';import { randomUUID } from 'node:crypto';import { MongoMemoryServer } from 'mongodb-memory-server';+import { SubagentResolutionError } from '@librechat/agents';import { Constants, EModelEndpoint } from 'librechat-data-provider';import { AIMessage, HumanMessage, ToolMessage } from '@librechat/agents/langchain/messages';import {@@ -2525,8 +2526,9 @@ describe('SubagentThreadTaskStore', () => {}});- it('does not persist arbitrary executor details into the visible child chat', async () => {- loggerErrorSpy.mockClear();+ it('does not persist or log arbitrary executor details', async () => {+ /** `restoreMocks` removes the suite-wide spy after the first test. */+ const errorSpy = jest.spyOn(logger, 'error').mockImplementation(() => logger);const userId = 'safe-error-user';const parentConversationId = randomUUID();await saveParent(userId, parentConversationId);@@ -2552,7 +2554,50 @@ describe('SubagentThreadTaskStore', () => {expect(JSON.stringify(store.claim(config.scopeId, requireAccepted(started).task.taskId)),).not.toContain('provider-secret');- expect(JSON.stringify(loggerErrorSpy.mock.calls)).not.toContain('provider-secret');+ expect(errorSpy).toHaveBeenCalledWith(+ '[subagentThreads] Child-thread execution failed',+ expect.objectContaining({+ causes: [{ name: 'Error' }],+ frames: expect.arrayContaining([expect.stringMatching(/^at /)]),+ }),+ );+ expect(JSON.stringify(errorSpy.mock.calls)).not.toContain('provider-secret');+ });++ it('shows why a subagent could not start and logs the failure for its task', async () => {+ const errorSpy = jest.spyOn(logger, 'error').mockImplementation(() => logger);+ const userId = 'resolution-error-user';+ const parentConversationId = randomUUID();+ await saveParent(userId, parentConversationId);+ const store = new SubagentThreadTaskStore(methods);+ const config = buildSubagentThreadTaskConfig(store, { userId, parentConversationId });+ const started = store.start(+ taskRequest(config.scopeId, {+ run: async () => {+ throw new SubagentResolutionError('config', 'workspace_unavailable');+ },+ }),+ );+ await waitForSettled(store, config.scopeId, started);++ const message =+ 'Subagent error: Workspace unavailable. Retry later or choose another workspace.';+ const messages = await methods.getMessages({+ user: userId,+ conversationId: requireThreadId(started),+ });+ expect(messages[messages.length - 1]?.text).toBe(`Subagent task failed: ${message}`);+ expect(errorSpy).toHaveBeenCalledWith(+ '[subagentThreads] Child-thread execution failed',+ expect.objectContaining({+ taskId: requireAccepted(started).task.taskId,+ detail: message,+ errorName: 'SubagentResolutionError',+ phase: 'config',+ resolutionCause: 'workspace_unavailable',+ causes: [{ name: 'SubagentResolutionError', message }],+ }),+ );});it('routes live task polling and controls to the replica that owns the execution', async () => {diff --git a/packages/api/src/agents/subagentThreads.ts b/packages/api/src/agents/subagentThreads.tsindex c7ea66fbc8..4bca8fefb2 100644--- a/packages/api/src/agents/subagentThreads.ts+++ b/packages/api/src/agents/subagentThreads.ts@@ -1,6 +1,6 @@import { randomUUID } from 'node:crypto';-import { InMemorySubagentTaskStore } from '@librechat/agents';import { logger, tenantStorage } from '@librechat/data-schemas';+import { InMemorySubagentTaskStore, SubagentResolutionError } from '@librechat/agents';import { EModelEndpoint, Constants, subagentActivityConfigSchema } from 'librechat-data-provider';import {mapChatMessagesToStoredMessages,@@ -55,6 +55,7 @@ import {} from './activity';import { boundSubagentActivityUpdate, SubagentActivityStream } from './subagentActivity';import { createSubagentAttemptKey, createSubagentThreadId } from './subagentThreadIds';+import { describeErrorCauses, describeStackFrames } from './failures/subagent';import { ActivityRecorder, activityTreeFromProjection } from './digest';import { runWithDetachedSubagentUsage } from './subagentTaskContext';import { SUBAGENT_COMPLETION_DELIVERY } from './subagentDelivery';@@ -516,8 +517,9 @@ function childAgentId(request: SubagentTaskStartRequest): string | undefined {return request.subagentType === 'self' ? request.parentAgentId : request.subagentType;}+/** A subagent that could not start says why in the SDK's fixed, model-facing wording. */function publicFailureDetail(error: unknown): string {- return error instanceof SubagentThreadPublicError+ return error instanceof SubagentThreadPublicError || error instanceof SubagentResolutionError? error.message.slice(0, 2_000): 'The child run could not be completed.';}@@ -1701,9 +1703,14 @@ export class SubagentThreadTaskStore extends InMemorySubagentTaskStore {throw error;}logger.error('[subagentThreads] Child-thread execution failed', {+ taskId: runtime.taskId,detail: publicFailureDetail(error),errorName: error instanceof Error ? error.name : typeof error,- ...(error instanceof Error && error.stack != null ? { stack: error.stack } : {}),+ ...(error instanceof SubagentResolutionError+ ? { phase: error.phase, resolutionCause: error.resolutionCause }+ : {}),+ causes: describeErrorCauses(error),+ frames: describeStackFrames(error),});if (mayPersist) {await this.persistFailure(diff --git a/packages/api/src/code/attachments.spec.ts b/packages/api/src/code/attachments.spec.tsindex 08e8ba8687..931037b34f 100644--- a/packages/api/src/code/attachments.spec.ts+++ b/packages/api/src/code/attachments.spec.ts@@ -1,4 +1,5 @@import { createHash } from 'node:crypto';+import { logger } from '@librechat/data-schemas';import { Tools, FileContext } from 'librechat-data-provider';import { Constants as AgentConstants } from '@librechat/agents';import type { TFile, TurnFileConsumers, CodeWorkspaceOperation } from 'librechat-data-provider';@@ -40,18 +41,25 @@ type WorkspaceRequest = {* In-memory stand-in for the Code API and its attached worker, implementing the* `import_file` contract: stored objects are copied by reference, a same-digest file is left* unchanged, a different file at the path is a conflict, `write_file` is create-only, and- * `read_file` returns what is stored.+ * `read_file` returns what is stored. With `missingParents`, it is a worker that predates+ * LibreChat-AI/code-interpreter#360 on a root registered by path alone: a write or import into a+ * folder that does not exist yet is `NOT_FOUND`, because that worker never creates one.*/function createFakeWorker({objects = new Map<string, string>(),delayMs = 0,denyWrites = false,truncateReads = false,+ missingParents = false,+ legacyCodeApi = false,}: {objects?: Map<string, string>;delayMs?: number;denyWrites?: boolean;truncateReads?: boolean;+ missingParents?: boolean;+ /** A Code API that predates `NOT_FOUND` relays it as `INVALID_PATH` with the same message. */+ legacyCodeApi?: boolean;} = {}) {const files = new Map<string, string>();const requests: WorkspaceRequest[] = [];@@ -87,6 +95,13 @@ function createFakeWorker({if (denyWrites) {return reply(403, { code: 'WRITE_DISABLED', error: 'File writes are disabled' });}+ const folder = key.slice(0, key.lastIndexOf('/') + 1);+ if (missingParents && ![...files.keys()].some((path) => path.startsWith(folder))) {+ return reply(422, {+ code: legacyCodeApi ? 'INVALID_PATH' : 'NOT_FOUND',+ error: 'Workspace path does not exist',+ });+ }if (request.operation === 'write_file') {if (files.has(key) && request.overwrite === false) {return reply(409, { code: 'EDIT_CONFLICT', error: 'Workspace file already exists' });@@ -703,6 +718,67 @@ describe('primeWorkspaceAttachments', () => {expect(worker.files.get('root:.librechat/attachments/report.pdf')).toBe('pdf');});+ it.each([+ ['NOT_FOUND', false],+ ['INVALID_PATH', true],+ ])(+ 'tells the user to update a worker that cannot create the attachments folder (%s)',+ async (upstreamCode, legacyCodeApi) => {+ const warn = jest.spyOn(logger, 'warn');+ const worker = createFakeWorker({ missingParents: true, legacyCodeApi });+ const { deps, records } = createDeps(worker);+ const file = remember(chatFile('report.pdf', 'pdf', worker.objects));+ const agent = agentWith(attachedContext(), [file]);++ await primeWorkspaceAttachments({ agents: [agent], deps });++ expect(worker.requests.map((request) => request.operation)).toEqual(['write_file']);+ expect(worker.files.size).toBe(0);+ expect(agent.dynamicToolContextMap?.[Tools.execute_code]).toContain(+ "report.pdf (attached by user): this machine's LibreChat worker cannot receive attachments yet; updating the worker enables it",+ );+ expect(records.every((record) => record.copy == null)).toBe(true);+ expect(warn).toHaveBeenCalledWith(+ '[workspaceAttachments] Could not create .librechat/attachments/.gitignore in workspace primary: unsupported',+ {+ type: 'WorkspaceToolHttpError',+ reason: 'rejected',+ upstreamStatus: 422,+ upstreamCode,+ },+ );+ warn.mockRestore();+ },+ );++ it('logs the worker code of a refused import without its message', async () => {+ const warn = jest.spyOn(logger, 'warn');+ const worker = createFakeWorker();+ const { deps } = createDeps(worker);+ const file = remember(chatFile('report.pdf', 'pdf', worker.objects));+ const agent = agentWith(attachedContext(), [file]);++ await primeWorkspaceAttachments({+ agents: [agent],+ deps: { ...deps, digestFile: async () => ({ sha256: sha('other bytes'), bytes: 3 }) },+ });++ expect(agent.dynamicToolContextMap?.[Tools.execute_code]).toContain(+ 'report.pdf (attached by user): copying it to this machine failed',+ );+ expect(warn).toHaveBeenCalledWith(+ `[workspaceAttachments] Import of file ${file.file.file_id} into workspace primary failed: failed`,+ {+ type: 'WorkspaceToolHttpError',+ reason: 'rejected',+ upstreamStatus: 422,+ upstreamCode: 'INVALID_REQUEST',+ },+ );+ expect(JSON.stringify(warn.mock.calls)).not.toContain('source mismatch');+ warn.mockRestore();+ });+it('reports a worker-side write refusal instead of a path', async () => {const worker = createFakeWorker({ denyWrites: true });const { deps } = createDeps(worker);diff --git a/packages/api/src/code/attachments.ts b/packages/api/src/code/attachments.tsindex 347921ea8d..d2b80b7684 100644--- a/packages/api/src/code/attachments.ts+++ b/packages/api/src/code/attachments.ts@@ -33,6 +33,7 @@ import {import { codeExecutionAuthHeaders, getCodeExecutionRouteKey } from '~/agents/execution';import { isAttachedFileWriteDenied } from '~/agents/hitl/byom';import { getSafeErrorMetadata } from '~/utils/errors';+import { isWorkspacePathMissing } from './paths';/** Workspace-relative folder chat attachments are copied into. */export const WORKSPACE_ATTACHMENTS_DIRECTORY = '.librechat/attachments';@@ -276,6 +277,40 @@ function classifyImportFailure(error: unknown): WorkspaceAttachmentUnavailableRereturn 'failed';}+/**+ * A worker that cannot create the attachments folder reports it missing, as `NOT_FOUND` or,+ * through an older Code API, as `INVALID_PATH` with the same message: workers before+ * LibreChat-AI/code-interpreter#360 never created a parent on a root registered by path alone.+ */+function classifyIgnoreFailure(error: unknown): WorkspaceAttachmentUnavailableReason {+ if (error instanceof WorkspaceToolHttpError && isWorkspacePathMissing(error)) {+ return 'unsupported';+ }+ return classifyImportFailure(error);+}++/** What a failed workspace request may log: its outcome and the worker's error code, never a+ * response body, a host path, or file content. */+interface WorkspaceFailureMetadata {+ type: string;+ status?: number;+ reason?: WorkspaceToolHttpError['reason'];+ upstreamStatus?: number;+ upstreamCode?: string;+}++function getWorkspaceFailureMetadata(error: unknown): WorkspaceFailureMetadata {+ if (!(error instanceof WorkspaceToolHttpError)) {+ return getSafeErrorMetadata(error);+ }+ return {+ type: error.name,+ reason: error.reason,+ ...(error.upstreamStatus != null ? { upstreamStatus: error.upstreamStatus } : {}),+ ...(error.upstreamCode != null ? { upstreamCode: error.upstreamCode } : {}),+ };+}+/** Admits at most `limit` tasks at once; a finishing task hands its slot to the next waiter. */function createLimiter(limit: number): <T>(task: () => Promise<T>) => Promise<T> {let active = 0;@@ -519,6 +554,7 @@ async function importOne({const reason = classifyImportFailure(error);logger.warn(`[workspaceAttachments] Import of file ${file.file_id} into workspace ${target.workspaceId} failed: ${reason}`,+ getWorkspaceFailureMetadata(error),);return { status: 'unavailable', reason };} finally {@@ -672,12 +708,13 @@ async function ensureAttachmentsIgnored({},});} catch (error) {- if (classifyImportFailure(error) !== 'conflict') {+ const reason = classifyIgnoreFailure(error);+ if (reason !== 'conflict') {logger.warn(- '[workspaceAttachments] Could not create the attachments .gitignore',- getSafeErrorMetadata(error),+ `[workspaceAttachments] Could not create ${WORKSPACE_ATTACHMENTS_GITIGNORE} in workspace ${target.workspaceId}: ${reason}`,+ getWorkspaceFailureMetadata(error),);- return classifyImportFailure(error);+ return reason;}if (target.context.codeWorkspace?.operations.includes('read_file') !== true) {return 'not_ignored';@@ -703,8 +740,8 @@ async function ensureAttachmentsIgnored({}} catch (readError) {logger.warn(- '[workspaceAttachments] Could not read the attachments .gitignore',- getSafeErrorMetadata(readError),+ `[workspaceAttachments] Could not read ${WORKSPACE_ATTACHMENTS_GITIGNORE} in workspace ${target.workspaceId}`,+ getWorkspaceFailureMetadata(readError),);return classifyImportFailure(readError);}diff --git a/packages/api/src/code/paths.ts b/packages/api/src/code/paths.tsindex d2a0bd02fc..d520382697 100644--- a/packages/api/src/code/paths.ts+++ b/packages/api/src/code/paths.ts@@ -54,6 +54,11 @@ function describeUnusablePath(operation: WorkspacePathOperation, displayPath: streturn `The worker could not open ${quoted}. The file may not exist yet (a command may still be writing it), or the path is a directory or a symlink, or passes through one. List its directory to check before retrying.`;}+/** Whether the worker reported the path absent, in either the current or the legacy shape. */+export function isWorkspacePathMissing(error: WorkspaceToolHttpError): boolean {+ return getWorkspacePathRejection(error) === 'missing';+}+/*** Appends a short explanation to a worker's path rejection so the model can tell a file that* does not exist yet from a malformed path. Other rejections are returned unchanged.