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.tsindex 50efca2ca..9edf1195b 100644--- a/packages/harness/src/core/index.ts+++ b/packages/harness/src/core/index.ts@@ -133,7 +133,7 @@ export type {// Errors / utilsexport { 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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', () => {