From 3ccdd252f9376f85e999c4d2bc78873d121fdaf8 Mon Sep 17 00:00:00 2001 From: Danny Avila Date: Sat, 24 Oct 2026 08:51:38 +0200 Subject: [PATCH] =?UTF-8?q?=F0=9F=AA=B5=20fix:=20Explain=20Failed=20Attach?= =?UTF-8?q?ment=20Copies=20and=20Subagent=20Start-Up=20Failures=20(#17398)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * 🪵 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. --- .../agents/__tests__/run-codeTools.test.ts | 6 + .../api/src/agents/failures/subagent.spec.ts | 202 +++++++++++++++++ packages/api/src/agents/failures/subagent.ts | 210 ++++++++++++++++++ packages/api/src/agents/run.ts | 3 + .../api/src/agents/subagentThreads.spec.ts | 51 ++++- packages/api/src/agents/subagentThreads.ts | 13 +- packages/api/src/code/attachments.spec.ts | 78 ++++++- packages/api/src/code/attachments.ts | 49 +++- packages/api/src/code/paths.ts | 5 + 9 files changed, 604 insertions(+), 13 deletions(-) create mode 100644 packages/api/src/agents/failures/subagent.spec.ts create mode 100644 packages/api/src/agents/failures/subagent.ts diff --git a/packages/api/src/agents/__tests__/run-codeTools.test.ts b/packages/api/src/agents/__tests__/run-codeTools.test.ts index 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.ts new file mode 100644 index 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 { + 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.ts new file mode 100644 index 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)[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.ts index 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 '~/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 }, diff --git a/packages/api/src/agents/subagentThreads.spec.ts b/packages/api/src/agents/subagentThreads.spec.ts index 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.ts index 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.ts index 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(), delayMs = 0, denyWrites = false, truncateReads = false, + missingParents = false, + legacyCodeApi = false, }: { objects?: Map; 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(); 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.ts index 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): 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): (task: () => Promise) => Promise { 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.ts index 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: 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.