The open-source agent harness - the runtime layer that turns an LLM into a working agent.
Improve error cause logging (#840)
Chirag Jain1b1050a5dd21
diff --git a/.changeset/sandbox-fetch-error-cause.md b/.changeset/sandbox-fetch-error-cause.mdnew file mode 100644index 000000000..21c0194b0--- /dev/null+++ b/.changeset/sandbox-fetch-error-cause.md@@ -0,0 +1,5 @@+---+'@truefoundry/trueforge-core': patch+---++[truefoundry] Surface nested `Error.cause` and the sandbox URL when TFY sandbox fetch calls fail, so undici "fetch failed" errors include ECONNREFUSED (and similar) instead of an opaque message. Log when a TFY sandbox file upload starts and finishes.diff --git a/.github/fern/openapi/openapi.json b/.github/fern/openapi/openapi.jsonindex b9d8e2deb..9190f254e 100644--- a/.github/fern/openapi/openapi.json+++ b/.github/fern/openapi/openapi.json@@ -5816,7 +5816,7 @@"info": {"description": "HTTP API for the TrueForge agent server (`/api/v1`). Interactive docs are served at `/api/v1/docs` (OpenAPI JSON at `/api/v1/openapi.json`).\n\n**Authentication:** Standalone auth accepts requests without credentials — middleware stamps a local default user. When OIDC or TrueFoundry auth is configured, protected routes require a valid cookie or `Authorization: Bearer` token. There is no built-in API-key scheme; pass custom headers only if your reverse proxy or IdP layer requires them.\n\nCovers DB-backed sessions, the agent registry, settings catalogs, and model/MCP/skill/sandbox providers.","title": "TrueForge API",- "version": "0.2.0"+ "version": "0.2.1"},"openapi": "3.1.0","paths": {diff --git a/docs/openapi.json b/docs/openapi.jsonindex b9d8e2deb..9190f254e 100644--- a/docs/openapi.json+++ b/docs/openapi.json@@ -5816,7 +5816,7 @@"info": {"description": "HTTP API for the TrueForge agent server (`/api/v1`). Interactive docs are served at `/api/v1/docs` (OpenAPI JSON at `/api/v1/openapi.json`).\n\n**Authentication:** Standalone auth accepts requests without credentials — middleware stamps a local default user. When OIDC or TrueFoundry auth is configured, protected routes require a valid cookie or `Authorization: Bearer` token. There is no built-in API-key scheme; pass custom headers only if your reverse proxy or IdP layer requires them.\n\nCovers DB-backed sessions, the agent registry, settings catalogs, and model/MCP/skill/sandbox providers.","title": "TrueForge API",- "version": "0.2.0"+ "version": "0.2.1"},"openapi": "3.1.0","paths": {diff --git a/packages/trueforge-core/src/core/sandbox/provider/TFYSandboxProvider.ts b/packages/trueforge-core/src/core/sandbox/provider/TFYSandboxProvider.tsindex 101365649..8a1b09eeb 100644--- a/packages/trueforge-core/src/core/sandbox/provider/TFYSandboxProvider.ts+++ b/packages/trueforge-core/src/core/sandbox/provider/TFYSandboxProvider.ts@@ -4,7 +4,7 @@ import dedent from 'dedent';import { randomUUID } from 'node:crypto';import { join } from 'node:path/posix';import type { Logger } from 'winston';-import { extractErrorLogFields } from '../../util/errorLogFields';+import { describeUnknownError, extractErrorLogFields } from '../../util/errorLogFields';import type { CodeModeTransport } from '../codeMode/CodeModeTransport';import { CodeModeNatsTransport } from '../codeMode/nats/CodeModeNatsTransport';import { DEFAULT_SANDBOX_NATS_WS_PORT } from '../constants';@@ -152,6 +152,7 @@ export class TFYSandboxProvider implements SandboxProvider {timeout: timeoutSeconds,};+ const execUrl = `${this.serverUrl}/exec`;const controller = new AbortController();const clientTimeoutMs = (timeoutSeconds + CLIENT_TIMEOUT_BUFFER_SECONDS) * 1000;const timer = setTimeout(() => {@@ -159,7 +160,7 @@ export class TFYSandboxProvider implements SandboxProvider {}, clientTimeoutMs);try {- const response = await fetch(`${this.serverUrl}/exec`, {+ const response = await fetch(execUrl, {method: 'POST',headers: { 'Content-Type': 'application/json' },body: JSON.stringify(body),@@ -168,20 +169,31 @@ export class TFYSandboxProvider implements SandboxProvider {if (!response.ok) {const text = await response.text();- this.logger.error(`Sandbox server returned ${String(response.status)}: ${text}`);- return { success: false, error: `Sandbox server returned ${String(response.status)}: ${text}` };+ this.logger.error(`Sandbox server returned ${String(response.status)}: ${text}`, { url: execUrl });+ return {+ success: false,+ error: `Sandbox server returned ${String(response.status)} from ${execUrl}: ${text}`,+ };}const result = (await response.json()) as ExecResult;return result;} catch (e: unknown) {if (e instanceof Error && e.name === 'AbortError') {- this.logger.error(`Sandbox exec timed out after ${String(timeoutSeconds)}s`, extractErrorLogFields(e));- return { success: false, error: `Sandbox exec timed out after ${String(timeoutSeconds)}s` };+ this.logger.error(`Sandbox exec timed out after ${String(timeoutSeconds)}s`, {+ url: execUrl,+ ...extractErrorLogFields(e),+ });+ return {+ success: false,+ error: `Sandbox exec to ${execUrl} timed out after ${String(timeoutSeconds)}s`,+ };}- this.logger.error('Sandbox exec failed', extractErrorLogFields(e));- const message = e instanceof Error ? e.message : 'Unknown error';- return { success: false, error: message };+ this.logger.error('Sandbox exec failed', { url: execUrl, ...extractErrorLogFields(e) });+ return {+ success: false,+ error: `Sandbox exec to ${execUrl} failed: ${describeUnknownError(e)}`,+ };} finally {clearTimeout(timer);}@@ -234,15 +246,27 @@ export class TFYSandboxProvider implements SandboxProvider {return context.with(suppressTracing(context.active()), async () => {const query = new URLSearchParams({ sandbox_id: params.sandboxId, path: params.remotePath });- const response = await fetch(`${this.serverUrl}/files/upload?${query.toString()}`, {- method: 'POST',- headers: { 'Content-Type': 'application/octet-stream' },- body: params.content,- signal: AbortSignal.timeout(FILE_UPLOAD_TIMEOUT_MS),+ const uploadUrl = `${this.serverUrl}/files/upload?${query.toString()}`;+ const bytes = params.content.byteLength;+ this.logger.info('Uploading file to sandbox', {+ sandboxId: params.sandboxId,+ remotePath: params.remotePath,+ bytes,});+ let response: Response;+ try {+ response = await fetch(uploadUrl, {+ method: 'POST',+ headers: { 'Content-Type': 'application/octet-stream' },+ body: params.content,+ signal: AbortSignal.timeout(FILE_UPLOAD_TIMEOUT_MS),+ });+ } catch (e: unknown) {+ throw new Error(`File upload to ${uploadUrl} failed: ${describeUnknownError(e)}`, { cause: e });+ }if (!response.ok) {throw new Error(- `File upload to sandbox failed: Sandbox server returned ${String(response.status)}: ${await response.text()}`,+ `File upload to sandbox failed: Sandbox server returned ${String(response.status)} from ${uploadUrl}: ${await response.text()}`,);}@@ -250,6 +274,11 @@ export class TFYSandboxProvider implements SandboxProvider {if (!result.success) {throw new Error(`File upload to sandbox failed: ${result.error}`);}+ this.logger.info('Uploaded file to sandbox', {+ sandboxId: params.sandboxId,+ remotePath: params.remotePath,+ bytes,+ });});}diff --git a/packages/trueforge-core/src/core/util/errorLogFields.ts b/packages/trueforge-core/src/core/util/errorLogFields.tsindex ba0712cde..d211abfb1 100644--- a/packages/trueforge-core/src/core/util/errorLogFields.ts+++ b/packages/trueforge-core/src/core/util/errorLogFields.ts@@ -11,13 +11,10 @@ function formatObjectErrorForLog(error: object): string {}}-/**- * 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 {+/** Single-hop message for any thrown value (no cause walk). */+function messageOfUnknown(error: unknown): string {if (error instanceof Error) {- return error.message.length > 0 ? error.message : 'An unexpected error occurred';+ return error.message;}if (typeof error !== 'object' || error === null) {return String(error);@@ -29,23 +26,63 @@ export function describeUnknownError(error: unknown): string {try {return JSON.stringify(error);} catch {+ return '';+ }+}++/**+ * Walk `Error.cause` (and plain `{ cause }` objects) so undici-style+ * `TypeError: fetch failed` surfaces the nested `ECONNREFUSED` / cert reason.+ */+function describeErrorChain(error: unknown, seen: Set<unknown>): string {+ if (error === undefined || error === null || seen.has(error)) {+ return '';+ }+ seen.add(error);++ const head = messageOfUnknown(error).trim();+ const nestedCause = typeof error === 'object' && 'cause' in error ? Reflect.get(error, 'cause') : undefined;+ const tail = describeErrorChain(nestedCause, seen).trim();++ if (head.length === 0) {+ return tail;+ }+ if (tail.length === 0 || head.includes(tail)) {+ return head;+ }+ return `${head}: ${tail}`;+}++/**+ * User/turn-facing message for any thrown value. Prefer Error.message / `.message`;+ * never surface developer-only strings (e.g. unserialisable dumps) in Agent Steps.+ * Includes nested `cause` messages when present (e.g. undici "fetch failed").+ */+export function describeUnknownError(error: unknown): string {+ const chain = describeErrorChain(error, new Set());+ if (chain.length > 0) {+ return chain;+ }+ if (typeof error === 'object' && error !== null) {return 'An unexpected error occurred';}+ return String(error);}export function extractErrorLogFields(error: unknown): ErrorLogFields {if (error instanceof Error) {+ const chain = describeErrorChain(error, new Set());return {- error: error.message.length > 0 ? error.message : formatObjectErrorForLog(error),+ error: chain.length > 0 ? chain : 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 };+ const chain = describeErrorChain(error, new Set());+ if (chain.length > 0) {+ return { error: chain };}return { error: formatObjectErrorForLog(error) };}