Skip to content

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

send error messages instead of unknown error where possible (#254)

Heer Ambavif651e045193d
diff --git a/packages/harness/src/core/index.ts b/packages/harness/src/core/index.ts
index 50efca2ca..9edf1195b 100644
--- a/packages/harness/src/core/index.ts
+++ b/packages/harness/src/core/index.ts
@@ -133,7 +133,7 @@ export type {
// Errors / utils
export { AgentHarnessError, McpConnectionError, McpDcrConfigurationError } from './errors';
-export { extractErrorLogFields } from './util/errorLogFields';
+export { describeUnknownError, extractErrorLogFields } from './util/errorLogFields';
export { PromiseTimeoutError, withTimeout } from './util/promiseUtils';
// Sandbox (concrete implementation; provider details exported for composition)
diff --git a/packages/harness/src/core/llm/VercelAILLM.ts b/packages/harness/src/core/llm/VercelAILLM.ts
index eb8f71a57..50e699830 100644
--- a/packages/harness/src/core/llm/VercelAILLM.ts
+++ b/packages/harness/src/core/llm/VercelAILLM.ts
@@ -34,7 +34,7 @@ import type {
ChatCompletionTool,
} from 'openai/resources/chat';
import type { Logger } from 'winston';
-import { extractErrorLogFields } from '../util/errorLogFields';
+import { describeUnknownError, extractErrorLogFields } from '../util/errorLogFields';
import type { ILLM, LLMCreateParams, LLMCreateParamsStreaming } from './ILLM';
import {
type CompletionUsage,
@@ -985,19 +985,12 @@ export function describeStreamError(raw: unknown): string {
}
return raw.message;
}
+ return describeUnknownError(raw);
+}
- if (typeof raw !== 'object' || raw === null) {
- return String(raw);
- }
- const message: unknown = Reflect.get(raw, 'message');
- if (typeof message === 'string' && message.length > 0) {
- return message;
- }
- try {
- return JSON.stringify(raw);
- } catch {
- return `unserialisable provider error (${Object.keys(raw).join(', ')})`;
- }
+export function toStreamError(raw: unknown): Error {
+ if (raw instanceof Error) return raw;
+ return new Error(describeStreamError(raw), { cause: raw });
}
export function mapFinishReason(reason: FinishReason): RawAssistantMessageWithUsage['finish_reason'] {
@@ -1430,7 +1423,7 @@ export class VercelAILLM implements ILLM {
} else {
this.logger.error('Error creating streaming chat completion', extractErrorLogFields(error));
}
- throw error;
+ throw toStreamError(error);
}
// Detached: warnings resolve at stream start, and a pending or rejected promise must never
@@ -1468,7 +1461,7 @@ export class VercelAILLM implements ILLM {
} else {
this.logger.error('Error reading LLM stream', extractErrorLogFields(error));
}
- throw error;
+ throw toStreamError(error);
}
}
diff --git a/packages/harness/src/core/runtime/AgentThread.ts b/packages/harness/src/core/runtime/AgentThread.ts
index 8445a3819..47bc4beaf 100644
--- a/packages/harness/src/core/runtime/AgentThread.ts
+++ b/packages/harness/src/core/runtime/AgentThread.ts
@@ -54,6 +54,7 @@ import { executeToolCalls } from '../mcp/executeToolCalls';
import type { IToolSet, MCPAuthRequired } from '../mcp/IMCPServer';
import type { Sandbox, SandboxInfo } from '../sandbox/Sandbox';
import type { AgentTracing } from '../tracing/AgentTracing';
+import { describeUnknownError, extractErrorLogFields } from '../util/errorLogFields';
import type { AgentDefinition } from './AgentDefinition';
import type {
AgentThreadConstructorInput,
@@ -1358,7 +1359,10 @@ export class AgentThread {
if (outcome === 'exit') return;
}
} catch (error) {
- yield this.generateErrorEvent(error instanceof Error ? error.message : 'Unknown error occurred');
+ // Providers / transports often reject with plain objects; instanceof Error would
+ // otherwise collapse those into an opaque "Unknown error occurred" in Agent Steps.
+ this.logger.error('Agent thread execution failed', extractErrorLogFields(error));
+ yield this.generateErrorEvent(describeUnknownError(error));
} finally {
this.contextBusy = false;
}
diff --git a/packages/harness/src/core/util/errorLogFields.ts b/packages/harness/src/core/util/errorLogFields.ts
index da955f705..ba0712cde 100644
--- a/packages/harness/src/core/util/errorLogFields.ts
+++ b/packages/harness/src/core/util/errorLogFields.ts
@@ -3,9 +3,49 @@ export interface ErrorLogFields {
stack?: string | undefined;
}
+function formatObjectErrorForLog(error: object): string {
+ try {
+ return JSON.stringify(error);
+ } catch {
+ return `unserialisable error (${Object.keys(error).join(', ')})`;
+ }
+}
+
+/**
+ * User/turn-facing message for any thrown value. Prefer Error.message / `.message`;
+ * never surface developer-only strings (e.g. unserialisable dumps) in Agent Steps.
+ */
+export function describeUnknownError(error: unknown): string {
+ if (error instanceof Error) {
+ return error.message.length > 0 ? error.message : 'An unexpected error occurred';
+ }
+ if (typeof error !== 'object' || error === null) {
+ return String(error);
+ }
+ const message: unknown = Reflect.get(error, 'message');
+ if (typeof message === 'string' && message.length > 0) {
+ return message;
+ }
+ try {
+ return JSON.stringify(error);
+ } catch {
+ return 'An unexpected error occurred';
+ }
+}
+
export function extractErrorLogFields(error: unknown): ErrorLogFields {
if (error instanceof Error) {
- return { error: error.message, stack: error.stack };
+ return {
+ error: error.message.length > 0 ? error.message : formatObjectErrorForLog(error),
+ stack: error.stack,
+ };
+ }
+ if (typeof error !== 'object' || error === null) {
+ return { error: String(error) };
+ }
+ const message: unknown = Reflect.get(error, 'message');
+ if (typeof message === 'string' && message.length > 0) {
+ return { error: message };
}
- return { error: String(error) };
+ return { error: formatObjectErrorForLog(error) };
}
diff --git a/packages/harness/tests/core/helperOwnership.test.ts b/packages/harness/tests/core/helperOwnership.test.ts
index c702832ad..034792000 100644
--- a/packages/harness/tests/core/helperOwnership.test.ts
+++ b/packages/harness/tests/core/helperOwnership.test.ts
@@ -5,7 +5,7 @@ import {
INTERNAL_SYSTEM_PROMPT,
makeUnknownToolInfo,
} from '../../src/core/runtime/contextUtils';
-import { extractErrorLogFields } from '../../src/core/util/errorLogFields';
+import { describeUnknownError, extractErrorLogFields } from '../../src/core/util/errorLogFields';
import { PromiseTimeoutError, withTimeout } from '../../src/core/util/promiseUtils';
describe('canonical helper ownership fidelity', () => {
@@ -13,6 +13,25 @@ describe('canonical helper ownership fidelity', () => {
const err = new Error('x');
expect(extractErrorLogFields(err)).toEqual({ error: 'x', stack: err.stack });
expect(extractErrorLogFields('plain')).toEqual({ error: 'plain' });
+ expect(extractErrorLogFields({ message: 'provider blew up' })).toEqual({ error: 'provider blew up' });
+ expect(extractErrorLogFields({ code: 'rate_limit', status: 429 })).toEqual({
+ error: JSON.stringify({ code: 'rate_limit', status: 429 }),
+ });
+ });
+
+ it('describeUnknownError prefers message fields over opaque placeholders', () => {
+ expect(describeUnknownError(new Error('boom'))).toBe('boom');
+ expect(describeUnknownError({ message: 'The requested model does not exist.' })).toBe(
+ 'The requested model does not exist.',
+ );
+ expect(describeUnknownError(undefined)).toBe('undefined');
+ });
+
+ it('describeUnknownError uses a bland fallback when the value cannot be serialised', () => {
+ const circular: { self?: unknown } = {};
+ circular.self = circular;
+ expect(describeUnknownError(circular)).toBe('An unexpected error occurred');
+ expect(extractErrorLogFields(circular).error).toMatch(/^unserialisable error \(/);
});
it('DaytonaProvider owns http→ws URL conversion (no shared helper module)', () => {
diff --git a/packages/harness/tests/core/llm/VercelAILLM.stream.test.ts b/packages/harness/tests/core/llm/VercelAILLM.stream.test.ts
index 8b7e6dfb4..bb15d4aed 100644
--- a/packages/harness/tests/core/llm/VercelAILLM.stream.test.ts
+++ b/packages/harness/tests/core/llm/VercelAILLM.stream.test.ts
@@ -17,6 +17,7 @@ import {
mapFinishReason,
mapStreamToChunks,
normalizeUsage,
+ toStreamError,
} from '../../../src/core/llm/VercelAILLM';
// ─────────── Helpers ───────────
@@ -214,6 +215,21 @@ describe('describeStreamError', () => {
});
});
+describe('toStreamError', () => {
+ it('returns Error instances unchanged', () => {
+ const err = new Error('keep me');
+ err.name = 'AbortError';
+ expect(toStreamError(err)).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.cause).toEqual({ message: 'The requested model does not exist.' });
+ });
+});
+
// ─────────── mapStreamToChunks ───────────
describe('mapStreamToChunks', () => {