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.mdnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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,});});