🪵 fix: Explain Failed Attachment Copies and Subagent Start-Up Failures (#17398)

* 🪵 fix: Explain Failed Attachment Copies and Subagent Start-Up Failures

The attachments .gitignore and import failure warnings logged only a bare
error type: getSafeErrorMetadata reads `status`, which a workspace tool error
does not carry. They now log the request outcome, upstream status and the
worker's error code, never a body or host path. A worker that reports the
folder missing (one that predates LibreChat-AI/code-interpreter#360 on a
root registered by path alone) is reported to the user as needing an update.

A subagent that could not start was logged only as the SDK's `unknown`
resolution cause. The run now passes onSubagentResolutionFailure, which logs
the underlying cause chain (name, code, status, redacted message) and names
an MCP server that needs re-authentication. A detached child thread shows the
SDK's model-facing start-up message instead of a generic failure, and its
failure log carries the task id, resolution cause and a redacted error in
place of the raw stack.

* 🪵 fix: Log Only Trusted Error Text and Recognize the Legacy Missing-Path Reply

- Cause chains keep a message only for errors whose text LibreChat or the SDK
  composes (MCP authentication errors, SubagentResolutionError,
  CodeWorkspaceSelectionError); every other link logs name, code and status.
  Child-thread failures log stack frames without the message line instead of
  redacted error text.
- A retryable MCP refresh or rejection is logged as a sign-in failure a retry
  may clear, not as one that needs re-authentication.
- A worker's missing attachments folder relayed by an older Code API as
  INVALID_PATH "Workspace path does not exist" is also reported as
  unsupported, through the shared isWorkspacePathMissing check.

* 🪵 fix: Log Frames Only From a Verified Stack and Keep OpenID Out of MCP

- Stack frames are read only after the stack's own name: message header, and
  only when that header still matches the error, so a message line shaped
  like a frame is never logged.
- OpenIDReauthRequiredError alone is no longer reported as an MCP sign-in
  failure: model and endpoint headers raise it too.
This commit is contained in:
Danny Avila 2026-10-24 08:51:38 +02:00 • committed by GitHub
parent 38c96a5e3a
commit 3ccdd252f9
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
9 changed files with 604 additions and 13 deletions

View file

@ -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 }));

View file

@ -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();
});
});

View file

@ -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';
}

View file

@ -119,6 +119,7 @@ import { resolveConfigHeaders, resolveModelHeaders, mergeHeaders } from '~/utils
import { 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 },

View file

@ -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 () => {

View file

@ -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(

View file

@ -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);

View file

@ -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): WorkspaceAttachmentUnavailableRe
return '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);
}

View file

@ -54,6 +54,11 @@ function describeUnusablePath(operation: WorkspacePathOperation, displayPath: st
return `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.