Skip to content

The open-source agent harness - the runtime layer that turns an LLM into a working agent.

add prefix for mcp and model errors (#1121)

Raman Tehlan6247d677e807
diff --git a/.changeset/model-mcp-error-prefixes.md b/.changeset/model-mcp-error-prefixes.md
new file mode 100644
index 000000000..fc111e1d0
--- /dev/null
+++ b/.changeset/model-mcp-error-prefixes.md
@@ -0,0 +1,5 @@
+---
+'@truefoundry/trueforge-core': patch
+---
+
+Prefix model and MCP failures so logs and the chat error show which system failed.
diff --git a/packages/trueforge-core/src/core/errors.ts b/packages/trueforge-core/src/core/errors.ts
index d59c7789d..73f7a18ff 100644
--- a/packages/trueforge-core/src/core/errors.ts
+++ b/packages/trueforge-core/src/core/errors.ts
@@ -1,3 +1,48 @@
+/** User-visible label for a model-provider failure. */
+export const MODEL_ERROR_PREFIX = '[Model Error]';
+
+/** User-visible label for an MCP connection or transport failure. */
+export const MCP_ERROR_PREFIX = '[MCP Error]';
+
+function hasErrorPrefix({ prefix, message }: { prefix: string; message: string }): boolean {
+ return message.startsWith(prefix);
+}
+
+/**
+ * Remove leading source labels, in the given order, so an outer wrapper can add context and then apply one label.
+ * A label is removed only when the current text starts with it. Text that matches none of them is returned unchanged.
+ */
+export function stripErrorPrefix({ prefix, message }: { prefix: string | readonly string[]; message: string }): string {
+ const prefixes = typeof prefix === 'string' ? [prefix] : prefix;
+ return prefixes.reduce((current, item) => {
+ if (!hasErrorPrefix({ prefix: item, message: current })) {
+ return current;
+ }
+ return current.slice(item.length).trim();
+ }, message);
+}
+
+/**
+ * Add a source label when it is not already the start of the message.
+ * A second wrap keeps the existing label instead of stacking another copy.
+ */
+export function applyErrorPrefix({ prefix, message }: { prefix: string; message: string }): string {
+ if (hasErrorPrefix({ prefix, message })) {
+ return message;
+ }
+ return `${prefix} ${message}`;
+}
+
+/**
+ * Model-provider failure. The message starts with `[Model Error]` once, and `cause` keeps the upstream error.
+ */
+export class ModelProviderError extends Error {
+ constructor(message: string, options?: ErrorOptions) {
+ super(applyErrorPrefix({ prefix: MODEL_ERROR_PREFIX, message }), options);
+ this.name = 'ModelProviderError';
+ }
+}
+
export type AgentHarnessErrorCode =
| 'invalid_file_input'
| 'invalid_send_input'
@@ -56,7 +101,7 @@ export class McpConnectionError extends AgentHarnessError {
readonly statusCode: number,
options?: ErrorOptions,
) {
- super('mcp_connection_failed', message, options);
+ super('mcp_connection_failed', applyErrorPrefix({ prefix: MCP_ERROR_PREFIX, message }), options);
this.name = 'McpConnectionError';
}
}
diff --git a/packages/trueforge-core/src/core/llm/VercelAILLM.ts b/packages/trueforge-core/src/core/llm/VercelAILLM.ts
index 397cebc81..a1dc948d5 100644
--- a/packages/trueforge-core/src/core/llm/VercelAILLM.ts
+++ b/packages/trueforge-core/src/core/llm/VercelAILLM.ts
@@ -34,6 +34,7 @@ import type {
ChatCompletionTool,
} from 'openai/resources/chat';
import type { Logger } from 'winston';
+import { ModelProviderError } from '../errors';
import { describeUnknownError, extractErrorLogFields } from '../util/errorLogFields';
import { modelSsrfFetch } from '../util/outboundFetch';
import type { ILLM, LLMCreateParams, LLMCreateParamsStreaming } from './ILLM';
@@ -1008,10 +1009,10 @@ export function describeStreamError(raw: unknown): string {
}
export function toStreamError(raw: unknown): Error {
- if (raw instanceof Error) {
+ if (raw instanceof ModelProviderError) {
return raw;
}
- return new Error(describeStreamError(raw), { cause: raw });
+ return new ModelProviderError(describeStreamError(raw), { cause: raw });
}
export function mapFinishReason(reason: FinishReason): RawAssistantMessageWithUsage['finish_reason'] {
@@ -1442,12 +1443,13 @@ export class VercelAILLM implements ILLM {
...(output !== undefined ? { output } : {}),
});
} catch (error) {
+ const streamError = toStreamError(error);
if (this.signal?.aborted) {
- this.logger.debug('LLM call aborted', extractErrorLogFields(error));
+ this.logger.debug('LLM call aborted', extractErrorLogFields(streamError));
} else {
- this.logger.error('Error creating streaming chat completion', extractErrorLogFields(error));
+ this.logger.error('Error creating streaming chat completion', extractErrorLogFields(streamError));
}
- throw toStreamError(error);
+ throw streamError;
}
// Detached: warnings resolve at stream start, and a pending or rejected promise must never
@@ -1480,12 +1482,13 @@ export class VercelAILLM implements ILLM {
result.output.source = `${provider.type}/${provider.name}/${model.name}`;
return result;
} catch (error) {
+ const streamError = toStreamError(error);
if (this.signal?.aborted) {
- this.logger.debug('LLM stream aborted', extractErrorLogFields(error));
+ this.logger.debug('LLM stream aborted', extractErrorLogFields(streamError));
} else {
- this.logger.error('Error reading LLM stream', extractErrorLogFields(error));
+ this.logger.error('Error reading LLM stream', extractErrorLogFields(streamError));
}
- throw toStreamError(error);
+ throw streamError;
}
}
diff --git a/packages/trueforge-core/src/core/mcp/RemoteMCP.ts b/packages/trueforge-core/src/core/mcp/RemoteMCP.ts
index e0d33cb22..0cc53ced1 100644
--- a/packages/trueforge-core/src/core/mcp/RemoteMCP.ts
+++ b/packages/trueforge-core/src/core/mcp/RemoteMCP.ts
@@ -1,6 +1,6 @@
import type { CallToolRequest } from '@modelcontextprotocol/sdk/types.js';
import type { Logger } from 'winston';
-import { McpConnectionError } from '../errors';
+import { applyErrorPrefix, MCP_ERROR_PREFIX, McpConnectionError, stripErrorPrefix } from '../errors';
import type { MCPServerInitInfo } from '../events/schema';
import type { InternalToolCallInfo } from '../llm/LLMTypes';
import type { AgentTracing } from '../tracing/AgentTracing';
@@ -321,11 +321,15 @@ export class RemoteMCP implements ToolSource {
},
onError: error => {
const fields = extractErrorLogFields(error);
+ const logFields = {
+ ...fields,
+ error: applyErrorPrefix({ prefix: MCP_ERROR_PREFIX, message: fields.error }),
+ };
const msg = `Error on remote MCP transport ${this.name}`;
if (fields.error.includes('Body Timeout')) {
- this.logger.warn(msg, fields);
+ this.logger.warn(msg, logFields);
} else {
- this.logger.error(msg, fields);
+ this.logger.error(msg, logFields);
}
},
});
@@ -358,7 +362,8 @@ export class RemoteMCP implements ToolSource {
private toConnectError(error: unknown): McpConnectionError {
const statusCode = error instanceof McpConnectionError ? error.statusCode : 502;
- const message = error instanceof Error ? error.message : String(error);
+ const rawMessage = error instanceof Error ? error.message : String(error);
+ const message = stripErrorPrefix({ prefix: MCP_ERROR_PREFIX, message: rawMessage });
return new McpConnectionError(`Failed to connect to remote MCP server '${this.name}': ${message}`, statusCode, {
cause: error,
});
diff --git a/packages/trueforge-core/src/core/util/errorLogFields.ts b/packages/trueforge-core/src/core/util/errorLogFields.ts
index 95bc02083..32c6223f3 100644
--- a/packages/trueforge-core/src/core/util/errorLogFields.ts
+++ b/packages/trueforge-core/src/core/util/errorLogFields.ts
@@ -1,3 +1,5 @@
+import { MCP_ERROR_PREFIX, MODEL_ERROR_PREFIX, stripErrorPrefix } from '../errors';
+
export interface ErrorLogFields {
error: string;
stack?: string | undefined;
@@ -47,12 +49,27 @@ function describeErrorChain(error: unknown, seen: Set<unknown>): string {
if (head.length === 0) {
return tail;
}
- if (tail.length === 0 || head.includes(tail)) {
+ if (tail.length === 0 || causeMessageAlreadyIncluded({ head, tail })) {
return head;
}
return `${head}: ${tail}`;
}
+/**
+ * A wrapped MCP or model error keeps the upstream error as `cause`, but its message drops the
+ * source label before adding context. That label must not be joined back onto the outer text.
+ */
+function causeMessageAlreadyIncluded({ head, tail }: { head: string; tail: string }): boolean {
+ if (head.includes(tail)) {
+ return true;
+ }
+ const unlabeledTail = stripErrorPrefix({
+ prefix: [MCP_ERROR_PREFIX, MODEL_ERROR_PREFIX],
+ message: tail,
+ });
+ return unlabeledTail.length > 0 && head.includes(unlabeledTail);
+}
+
/**
* User/turn-facing message for any thrown value. Prefer Error.message / `.message`;
* never surface developer-only strings (e.g. unserialisable dumps) in Agent Steps.
diff --git a/packages/trueforge-core/tests/core/llm/VercelAILLM.stream.test.ts b/packages/trueforge-core/tests/core/llm/VercelAILLM.stream.test.ts
index 6435bfcdd..593e2f3bb 100644
--- a/packages/trueforge-core/tests/core/llm/VercelAILLM.stream.test.ts
+++ b/packages/trueforge-core/tests/core/llm/VercelAILLM.stream.test.ts
@@ -11,6 +11,7 @@ import type {
ToolSet,
} from 'ai';
import { APICallError } from 'ai';
+import { ModelProviderError } from '../../../src/core/errors';
import type { ExtendedChatCompletionChunk, RawAssistantMessageWithUsage } from '../../../src/core/llm/LLMTypes';
import {
describeStreamError,
@@ -216,16 +217,20 @@ describe('describeStreamError', () => {
});
describe('toStreamError', () => {
- it('returns Error instances unchanged', () => {
- const err = new Error('keep me');
+ it('wraps Error instances with one model prefix and keeps the cause', () => {
+ const err = new Error('provider unavailable');
err.name = 'AbortError';
- expect(toStreamError(err)).toBe(err);
+ const wrapped = toStreamError(err);
+ expect(wrapped).toBeInstanceOf(ModelProviderError);
+ expect(wrapped).not.toBe(err);
+ expect(wrapped.message).toBe('[Model Error] provider unavailable');
+ expect(wrapped.cause).toBe(err);
});
it('wraps plain objects using describeStreamError', () => {
const wrapped = toStreamError({ message: 'The requested model does not exist.' });
- expect(wrapped).toBeInstanceOf(Error);
- expect(wrapped.message).toBe('The requested model does not exist.');
+ expect(wrapped).toBeInstanceOf(ModelProviderError);
+ expect(wrapped.message).toBe('[Model Error] The requested model does not exist.');
expect(wrapped.cause).toEqual({ message: 'The requested model does not exist.' });
});
});
diff --git a/packages/trueforge/tests/unit/apis/mcpServers.test.ts b/packages/trueforge/tests/unit/apis/mcpServers.test.ts
index b4e4dba5d..b3eb267e0 100644
--- a/packages/trueforge/tests/unit/apis/mcpServers.test.ts
+++ b/packages/trueforge/tests/unit/apis/mcpServers.test.ts
@@ -281,7 +281,7 @@ describe('mcp-servers routers', () => {
expect(response.status).toBe(422);
expect(await response.json()).toEqual({
error: {
- message: "Failed to discover OAuth authorization server for MCP server 'linear'",
+ message: "[MCP Error] Failed to discover OAuth authorization server for MCP server 'linear'",
},
});
expect(await mcpServerStore.getServer({ tenant_id: 'default', name: putBodyWithDcr.name })).toBeUndefined();
diff --git a/packages/trueforge/tests/unit/truefoundry/TrueFoundryMcpServerStore.test.ts b/packages/trueforge/tests/unit/truefoundry/TrueFoundryMcpServerStore.test.ts
index edf5e2a38..24dd7f346 100644
--- a/packages/trueforge/tests/unit/truefoundry/TrueFoundryMcpServerStore.test.ts
+++ b/packages/trueforge/tests/unit/truefoundry/TrueFoundryMcpServerStore.test.ts
@@ -178,7 +178,7 @@ describe('TrueFoundryMcpServerStore', () => {
it('throws when tenant control-plane URL is invalid', async () => {
const { store } = createStore({ controlPlaneUrl: '' });
await expect(store.authorize({ tenant_id: TENANT, name: 'github', userRef: 'user-1' })).rejects.toMatchObject({
- message: 'Tenant control-plane URL is required for TrueFoundry MCP OAuth',
+ message: '[MCP Error] Tenant control-plane URL is required for TrueFoundry MCP OAuth',
statusCode: 500,
});
});