The open-source agent harness - the runtime layer that turns an LLM into a working agent.
Log tracebacks for client error responses (#985)
Raman Tehlan8cc845358d9a
diff --git a/.changeset/error-log-cause-stack.md b/.changeset/error-log-cause-stack.mdnew file mode 100644index 000000000..4ecbfa8c0--- /dev/null+++ b/.changeset/error-log-cause-stack.md@@ -0,0 +1,5 @@+---+'@truefoundry/trueforge-core': patch+---++`extractErrorLogFields` appends each `cause` stack after the outer stack, joined with `Caused by:`. A wrapper captures the boundary rather than the throw site, so the origin frames stay on the same traceback.diff --git a/.changeset/log-client-error-tracebacks.md b/.changeset/log-client-error-tracebacks.mdnew file mode 100644index 000000000..6ed841414--- /dev/null+++ b/.changeset/log-client-error-tracebacks.md@@ -0,0 +1,5 @@+---+'@truefoundry/trueforge': patch+---++Log a traceback for every error that leaves the server as a non-2xx response. Thrown `HTTPException`s below 500 were returned with nothing in the log but the access-log line, so a 400/422/424 could not be traced to the code that raised it. Route handlers that caught an error and converted it into a client error now rethrow it as an `HTTPException` carrying the original as `cause`, and OpenAPI request validation throws instead of answering directly, so the app error handler is the one place that builds the error envelope and logs it. Each line carries method, path, status, the error chain, and the stack. When the handler rethrows with `cause`, the traceback includes the route throw and each cause stack. Routine `401`/`403`/`404` rejections stay at debug level.diff --git a/packages/trueforge-core/src/core/util/errorLogFields.ts b/packages/trueforge-core/src/core/util/errorLogFields.tsindex d211abfb1..95bc02083 100644--- a/packages/trueforge-core/src/core/util/errorLogFields.ts+++ b/packages/trueforge-core/src/core/util/errorLogFields.ts@@ -69,12 +69,33 @@ export function describeUnknownError(error: unknown): string {return String(error);}+/**+ * `error.stack` stops at the wrapper. Each `cause` stack is the throw beneath it,+ * so the log keeps the whole chain.+ */+function stackWithCauses(error: Error): string | undefined {+ const stacks: string[] = [];+ const seen = new Set<unknown>();+ let current: unknown = error;+ while (typeof current === 'object' && current !== null && !seen.has(current)) {+ seen.add(current);+ if (current instanceof Error && current.stack !== undefined) {+ stacks.push(current.stack);+ }+ if (!('cause' in current)) {+ break;+ }+ current = Reflect.get(current, 'cause');+ }+ return stacks.length > 0 ? stacks.join('\nCaused by: ') : undefined;+}+export function extractErrorLogFields(error: unknown): ErrorLogFields {if (error instanceof Error) {const chain = describeErrorChain(error, new Set());return {error: chain.length > 0 ? chain : formatObjectErrorForLog(error),- stack: error.stack,+ stack: stackWithCauses(error),};}if (typeof error !== 'object' || error === null) {diff --git a/packages/trueforge-core/tests/core/util/errorLogFields.test.ts b/packages/trueforge-core/tests/core/util/errorLogFields.test.tsnew file mode 100644index 000000000..2a9e89a73--- /dev/null+++ b/packages/trueforge-core/tests/core/util/errorLogFields.test.ts@@ -0,0 +1,62 @@+import { describeUnknownError, extractErrorLogFields } from '../../../src/core/util/errorLogFields';++describe('extractErrorLogFields', () => {+ it('returns the message and stack for a plain error', () => {+ const error = new Error('boom');++ expect(extractErrorLogFields(error)).toEqual({ error: 'boom', stack: error.stack });+ });++ it('chains the wrapper stack and each cause stack', () => {+ const origin = new Error('ECONNREFUSED');+ const wrapper = new Error('fetch failed', { cause: origin });++ expect(extractErrorLogFields(wrapper)).toEqual({+ error: 'fetch failed: ECONNREFUSED',+ stack: `${wrapper.stack ?? ''}\nCaused by: ${origin.stack ?? ''}`,+ });+ });++ it('chains every cause stack from the outside in', () => {+ const root = new Error('root');+ const middle = new Error('middle', { cause: root });+ const outer = new Error('outer', { cause: middle });++ expect(extractErrorLogFields(outer).stack).toBe(+ `${outer.stack ?? ''}\nCaused by: ${middle.stack ?? ''}\nCaused by: ${root.stack ?? ''}`,+ );+ });++ it('keeps a cause stack that sits behind a non-error object', () => {+ const origin = new Error('ECONNREFUSED');+ const wrapper = new Error('fetch failed', { cause: { cause: origin } });++ expect(extractErrorLogFields(wrapper).stack).toBe(`${wrapper.stack ?? ''}\nCaused by: ${origin.stack ?? ''}`);+ });++ it('keeps the outer stack when the cause is not an error', () => {+ const error = new Error('boom', { cause: 'a string' });++ expect(extractErrorLogFields(error)).toEqual({ error: 'boom: a string', stack: error.stack });+ });++ it('survives a cause cycle', () => {+ const a = new Error('a');+ const b = new Error('b', { cause: a });+ Object.defineProperty(a, 'cause', { value: b, configurable: true });++ expect(() => extractErrorLogFields(b)).not.toThrow();+ });++ it('describes non-error values without a stack', () => {+ expect(extractErrorLogFields('plain string')).toEqual({ error: 'plain string' });+ });+});++describe('describeUnknownError', () => {+ it('joins the cause chain', () => {+ const error = new Error('fetch failed', { cause: new Error('ECONNREFUSED') });++ expect(describeUnknownError(error)).toBe('fetch failed: ECONNREFUSED');+ });+});diff --git a/packages/trueforge/src/apis/agents.ts b/packages/trueforge/src/apis/agents.tsindex 5cf30a25a..b083460c1 100644--- a/packages/trueforge/src/apis/agents.ts+++ b/packages/trueforge/src/apis/agents.ts@@ -4,6 +4,7 @@import { OpenAPIHono, type RouteHandler } from '@hono/zod-openapi';import { InvalidPageTokenError, type AgentSpec } from '@truefoundry/trueforge-core/agent-session';import type { Context } from 'hono';+import { HTTPException } from 'hono/http-exception';import type { Authorizer } from '../auth/authorizer';import { createdBySubjectFromRequestContext, type ResolveRequestContext } from '../auth/identity';import configuration from '../config';@@ -110,7 +111,7 @@ export function createAgentsRouter<TTransaction>(deps: AgentsRouterDeps<TTransacreturn c.json({ data: data.map(toWireAgent), pagination }, 200);} catch (error) {if (error instanceof InvalidPageTokenError) {- return c.json({ error: { message: error.message } }, 400);+ throw new HTTPException(400, { message: error.message, cause: error });}throw error;}diff --git a/packages/trueforge/src/apis/mcpServers.ts b/packages/trueforge/src/apis/mcpServers.tsindex 75b407c54..347ba6860 100644--- a/packages/trueforge/src/apis/mcpServers.ts+++ b/packages/trueforge/src/apis/mcpServers.ts@@ -208,7 +208,7 @@ export function createSettingsMcpServersRouter<TTransaction>(deps: SettingsMcpSeawait assertSafeOutboundUrl(incomingManifest.url);} catch (error) {const message = error instanceof Error ? error.message : 'Outbound URL blocked';- return c.json({ error: { message } }, 400);+ throw new HTTPException(400, { message: message, cause: error });}// DCR finishes before the txn (remote I/O stays out of withTransaction on create).@@ -239,7 +239,7 @@ export function createSettingsMcpServersRouter<TTransaction>(deps: SettingsMcpSe});} catch (error) {if (error instanceof MissingStoredSecretError) {- return c.json({ error: { message: 'Header secret is required' } }, 400);+ throw new HTTPException(400, { message: 'Header secret is required', cause: error });}throw error;}@@ -288,7 +288,7 @@ export function createSettingsMcpServersRouter<TTransaction>(deps: SettingsMcpSeawait assertSafeOutboundUrl(incomingManifest.url);} catch (error) {const message = error instanceof Error ? error.message : 'Outbound URL blocked';- return c.json({ error: { message } }, 400);+ throw new HTTPException(400, { message: message, cause: error });}try {@@ -358,7 +358,7 @@ export function createSettingsMcpServersRouter<TTransaction>(deps: SettingsMcpSe);} catch (error) {if (error instanceof MissingStoredSecretError) {- return c.json({ error: { message: 'Header secret is required' } }, 400);+ throw new HTTPException(400, { message: 'Header secret is required', cause: error });}if (error instanceof McpConnectionError) {deps.logger.error(diff --git a/packages/trueforge/src/apis/modelProviders.ts b/packages/trueforge/src/apis/modelProviders.tsindex 5bc006501..1f6a966a5 100644--- a/packages/trueforge/src/apis/modelProviders.ts+++ b/packages/trueforge/src/apis/modelProviders.ts@@ -1,6 +1,7 @@import { OpenAPIHono, type RouteHandler } from '@hono/zod-openapi';import { assertSafeOutboundUrl } from '@truefoundry/trueforge-core/core';import type { Context } from 'hono';+import { HTTPException } from 'hono/http-exception';import type { ResolveRequestContext } from '../auth/identity';import type { IAgentStore } from '../db/agentStore';import {@@ -104,7 +105,7 @@ export function createModelProvidersRouter<TTransaction>(deps: ModelProvidersRouawait assertSafeOutboundUrl(provider.base_url);} catch (error) {const message = error instanceof Error ? error.message : 'Outbound URL blocked';- return c.json({ error: { message } }, 400);+ throw new HTTPException(400, { message: message, cause: error });}try {// Create has no prior row; redacted keep resolves to MissingStoredSecretError → 400.@@ -117,7 +118,7 @@ export function createModelProvidersRouter<TTransaction>(deps: ModelProvidersRoureturn c.json({ data: toWireProvider(record) }, 201);} catch (error) {if (error instanceof MissingStoredSecretError) {- return c.json({ error: { message: 'API key is required' } }, 400);+ throw new HTTPException(400, { message: 'API key is required', cause: error });}if (error instanceof ModelProviderNameConflictError) {return c.json({ error: { message: error.message } }, 409);@@ -136,7 +137,7 @@ export function createModelProvidersRouter<TTransaction>(deps: ModelProvidersRouawait assertSafeOutboundUrl(provider.base_url);} catch (error) {const message = error instanceof Error ? error.message : 'Outbound URL blocked';- return c.json({ error: { message } }, 400);+ throw new HTTPException(400, { message: message, cause: error });}try {// Lock → resolve secret from that snapshot → upsert, all in one txn so concurrent keep@@ -172,7 +173,7 @@ export function createModelProvidersRouter<TTransaction>(deps: ModelProvidersRoureturn c.json({ data: toWireProvider(outcome.record) }, 200);} catch (error) {if (error instanceof MissingStoredSecretError) {- return c.json({ error: { message: 'API key is required' } }, 400);+ throw new HTTPException(400, { message: 'API key is required', cause: error });}throw error;}diff --git a/packages/trueforge/src/apis/sandboxEnvironments.ts b/packages/trueforge/src/apis/sandboxEnvironments.tsindex 9401c164f..549ee31c1 100644--- a/packages/trueforge/src/apis/sandboxEnvironments.ts+++ b/packages/trueforge/src/apis/sandboxEnvironments.ts@@ -7,6 +7,7 @@ import { DaytonaError } from '@daytona/sdk';import { OpenAPIHono, type RouteHandler } from '@hono/zod-openapi';import { InvalidPageTokenError } from '@truefoundry/trueforge-core/agent-session';import type { Context } from 'hono';+import { HTTPException } from 'hono/http-exception';import type { Logger } from 'winston';import { createdBySubjectFromRequestContext, type ResolveRequestContext } from '../auth/identity';import type { IAgentStore } from '../db/agentStore';@@ -108,7 +109,7 @@ export function createSandboxEnvironmentsRouter<TTransaction>(return c.json({ data: listed.data.map(toSandboxEnvironment), pagination: listed.pagination }, 200);} catch (error) {if (error instanceof InvalidPageTokenError) {- return c.json({ error: { message: error.message } }, 400);+ throw new HTTPException(400, { message: error.message, cause: error });}throw error;}@@ -130,8 +131,7 @@ export function createSandboxEnvironmentsRouter<TTransaction>(};type WriteSandboxEnvironmentOutcome =- | { kind: 'saved'; environment: SandboxEnvironment }- | { kind: 'error'; status: 400 | 409 | 422 | 502; message: string };+ { kind: 'saved'; environment: SandboxEnvironment } | { kind: 'error'; status: 409 | 422; message: string };async function writeSandboxEnvironment({c,@@ -221,11 +221,11 @@ export function createSandboxEnvironmentsRouter<TTransaction>(return { kind: 'error', status: 409, message: 'Sandbox environment was updated concurrently; retry' };}if (error instanceof MissingStoredSecretError) {- return { kind: 'error', status: 400, message: 'Secret value is required' };+ throw new HTTPException(400, { message: 'Secret value is required', cause: error });}const secretError = sandboxEnvironmentSecretHttpError(error);if (secretError !== undefined) {- return { kind: 'error', status: secretError.status, message: secretError.message };+ throw new HTTPException(secretError.status, { message: secretError.message, cause: error });}throw error;}@@ -297,7 +297,7 @@ export function createSandboxEnvironmentsRouter<TTransaction>(} catch (error) {const secretError = sandboxEnvironmentSecretHttpError(error);if (secretError !== undefined) {- return c.json({ error: { message: secretError.message } }, secretError.status);+ throw new HTTPException(secretError.status, { message: secretError.message, cause: error });}throw error;}diff --git a/packages/trueforge/src/apis/sandboxProviders.ts b/packages/trueforge/src/apis/sandboxProviders.tsindex 70f911630..6227767a7 100644--- a/packages/trueforge/src/apis/sandboxProviders.ts+++ b/packages/trueforge/src/apis/sandboxProviders.ts@@ -1,5 +1,6 @@import { OpenAPIHono, type RouteHandler } from '@hono/zod-openapi';import type { Context } from 'hono';+import { HTTPException } from 'hono/http-exception';import type { Logger } from 'winston';import { createdBySubjectFromRequestContext, type ResolveRequestContext } from '../auth/identity';import type { ISandboxEnvironmentStore } from '../db/sandboxEnvironmentStore';@@ -112,21 +113,20 @@ export function createSandboxProvidersRouter<TTransaction>(deps: SandboxProvider);} catch (error) {if (error instanceof MissingStoredSecretError) {- return c.json({ error: { message: 'API key is required' } }, 400);+ throw new HTTPException(400, { message: 'API key is required', cause: error });}if (isDaytonaAuthError(error)) {- return c.json({ error: { message: 'Sandbox provider rejected the API key — check the credentials' } }, 422);+ throw new HTTPException(422, {+ message: 'Sandbox provider rejected the API key — check the credentials',+ cause: error,+ });}if (isDaytonaPermissionError(error)) {- return c.json(- {- error: {- message:- 'Sandbox provider denied access: the API key is missing required permissions. Grant write:sandboxes, write:snapshots, and delete:snapshots on the key, then try again.',- },- },- 422,- );+ throw new HTTPException(422, {+ message:+ 'Sandbox provider denied access: the API key is missing required permissions. Grant write:sandboxes, write:snapshots, and delete:snapshots on the key, then try again.',+ cause: error,+ });}throw error;}diff --git a/packages/trueforge/src/apis/schedules.ts b/packages/trueforge/src/apis/schedules.tsindex 725a30210..d7368bd4d 100644--- a/packages/trueforge/src/apis/schedules.ts+++ b/packages/trueforge/src/apis/schedules.ts@@ -8,6 +8,7 @@ import {type TurnStreamingEvent,} from '@truefoundry/trueforge-core/agent-session';import type { Context } from 'hono';+import { HTTPException } from 'hono/http-exception';import type { Logger } from 'winston';import type { Authorizer } from '../auth/authorizer';import {@@ -249,7 +250,7 @@ export function createSchedulesRouter<TTransaction>(deps: SchedulesRouterDeps<TTreturn c.json({ data: data.map(toWireSchedule), pagination }, 200);} catch (error) {if (error instanceof InvalidPageTokenError) {- return c.json({ error: { message: error.message } }, 400);+ throw new HTTPException(400, { message: error.message, cause: error });}throw error;}@@ -287,7 +288,7 @@ export function createSchedulesRouter<TTransaction>(deps: SchedulesRouterDeps<TTreturn c.json({ data: data.map(toWireScheduleRun), pagination }, 200);} catch (error) {if (error instanceof InvalidPageTokenError) {- return c.json({ error: { message: error.message } }, 400);+ throw new HTTPException(400, { message: error.message, cause: error });}throw error;}@@ -360,7 +361,7 @@ export function createSchedulesRouter<TTransaction>(deps: SchedulesRouterDeps<TT}const turnError = getTurnExecutionError(error);if (turnError) {- return c.json({ error: { message: turnError.message } }, turnError.status);+ throw new HTTPException(turnError.status, { message: turnError.message, cause: error });}throw error;}diff --git a/packages/trueforge/src/apis/sessions.ts b/packages/trueforge/src/apis/sessions.tsindex e98fee6ec..8245d84ca 100644--- a/packages/trueforge/src/apis/sessions.ts+++ b/packages/trueforge/src/apis/sessions.ts@@ -19,6 +19,7 @@ import {type RequestReplyRouter,} from '@truefoundry/trueforge-core/request-reply';import type { Context } from 'hono';+import { HTTPException } from 'hono/http-exception';import type { Logger } from 'winston';import { z } from 'zod';import type { Authorizer } from '../auth/authorizer';@@ -483,7 +484,7 @@ export function createSessionsRouter(deps: SessionsRouterDeps) {return c.json({ error: { message: `Session not found: ${sessionId}` } }, 404);}if (error instanceof SessionStoreInvariantError) {- return c.json({ error: { message: error.message } }, 422);+ throw new HTTPException(422, { message: error.message, cause: error });}throw error;}@@ -527,7 +528,7 @@ export function createSessionsRouter(deps: SessionsRouterDeps) {return c.json({ data: data.map(toWireSession), pagination }, 200);} catch (error) {if (error instanceof SessionStoreConflictError) {- return c.json({ error: { message: error.message } }, 400);+ throw new HTTPException(400, { message: error.message, cause: error });}throw error;}@@ -591,7 +592,7 @@ export function createSessionsRouter(deps: SessionsRouterDeps) {return c.json({ data, pagination }, 200);} catch (error) {if (error instanceof SessionStoreConflictError) {- return c.json({ error: { message: error.message } }, 400);+ throw new HTTPException(400, { message: error.message, cause: error });}if (error instanceof SessionStoreNotFoundError) {return c.json({ error: { message: error.message } }, 404);diff --git a/packages/trueforge/src/apis/turns.ts b/packages/trueforge/src/apis/turns.tsindex 7c71d28b8..a7a89fde2 100644--- a/packages/trueforge/src/apis/turns.ts+++ b/packages/trueforge/src/apis/turns.ts@@ -636,7 +636,7 @@ export function createTurnsRouter(deps: TurnsRouterDeps) {return c.json({ data: data.map(toWireTurn), pagination }, 200);} catch (error) {if (error instanceof SessionStoreConflictError) {- return c.json({ error: { message: error.message } }, 400);+ throw new HTTPException(400, { message: error.message, cause: error });}throw error;}@@ -728,7 +728,7 @@ export function createTurnsRouter(deps: TurnsRouterDeps) {} catch (error) {// Every guard and the provider itself raise SandboxError, whose statusCode is the contract.if (error instanceof SandboxError) {- return c.json({ error: { message: error.message } }, error.statusCode);+ throw new HTTPException(error.statusCode, { message: error.message, cause: error });}deps.logger.error('Sandbox file download failed', {...extractErrorLogFields(error),@@ -776,7 +776,7 @@ export function createTurnsRouter(deps: TurnsRouterDeps) {return c.json({ data, pagination }, 200);} catch (error) {if (error instanceof SessionStoreConflictError) {- return c.json({ error: { message: error.message } }, 400);+ throw new HTTPException(400, { message: error.message, cause: error });}throw error;}@@ -888,7 +888,7 @@ export function createTurnsRouter(deps: TurnsRouterDeps) {} catch (error) {const turnError = getTurnExecutionError(error);if (turnError) {- return c.json({ error: { message: turnError.message } }, turnError.status);+ throw new HTTPException(turnError.status, { message: turnError.message, cause: error });}throw error;}diff --git a/packages/trueforge/src/apis/webSearchProviders.ts b/packages/trueforge/src/apis/webSearchProviders.tsindex 5184d4dff..824a3e467 100644--- a/packages/trueforge/src/apis/webSearchProviders.ts+++ b/packages/trueforge/src/apis/webSearchProviders.ts@@ -1,5 +1,6 @@import { OpenAPIHono, type RouteHandler } from '@hono/zod-openapi';import type { Context } from 'hono';+import { HTTPException } from 'hono/http-exception';import type { ResolveRequestContext } from '../auth/identity';import type { IWebSearchProviderStore, WebSearchProviderRecord } from '../db/webSearchProviderStore';import { getWebSearchProviderRoute, putWebSearchProviderRoute } from '../routes/webSearchProviderRoutes';@@ -73,7 +74,7 @@ export function createWebSearchProvidersRouter(deps: WebSearchProvidersRouterDepreturn c.json({ data: toWireProvider(record) }, 200);} catch (error) {if (error instanceof MissingStoredSecretError) {- return c.json({ error: { message: 'API key is required' } }, 400);+ throw new HTTPException(400, { message: 'API key is required', cause: error });}throw error;}diff --git a/packages/trueforge/src/app.ts b/packages/trueforge/src/app.tsindex 1c0b0533e..39f984e11 100644--- a/packages/trueforge/src/app.ts+++ b/packages/trueforge/src/app.ts@@ -102,24 +102,43 @@ export function createRequestBodyLimitMiddleware(maxSize: number): MiddlewareHan});}+/** Expected rejections whose stack says nothing a reader needs; kept out of warn-level logs. */+const QUIET_CLIENT_ERROR_STATUSES = new Set([401, 403, 404]);+export function createAppErrorHandler(params: { logger: Logger }): ErrorHandler {return (error, c) => {+ // One line with the traceback, so a failed request can be traced to the throw site.+ const logError = (status: number, message: string): void => {+ const fields = {+ method: c.req.method,+ path: c.req.path,+ status,+ ...extractErrorLogFields(error),+ };+ if (status >= 500) {+ params.logger.error(message, fields);+ return;+ }+ if (QUIET_CLIENT_ERROR_STATUSES.has(status)) {+ params.logger.debug(message, fields);+ return;+ }+ params.logger.warn(message, fields);+ };+if (error instanceof z.ZodError) {+ logError(400, 'Client API error');return zodErrorResponse(c, error);}if (error instanceof InvalidCronError) {+ logError(400, 'Client API error');return c.json({ error: { message: error.message } }, 400);}if (error instanceof HTTPException) {- if (error.status >= 500) {- params.logger.error('Server API error', {- status: error.status,- ...extractErrorLogFields(error),- });- }+ logError(error.status, error.status >= 500 ? 'Server API error' : 'Client API error');return c.json({ error: { message: error.message } }, error.status);}- params.logger.error('Unhandled error', extractErrorLogFields(error));+ logError(500, 'Unhandled error');return c.json({ error: { message: 'Internal server error' } }, 500);};}diff --git a/packages/trueforge/src/zodErrorResponse.ts b/packages/trueforge/src/zodErrorResponse.tsindex bbeb14fdc..a150c7da1 100644--- a/packages/trueforge/src/zodErrorResponse.ts+++ b/packages/trueforge/src/zodErrorResponse.ts@@ -7,9 +7,10 @@ export function zodErrorResponse(c: Context, error: z.ZodError) {return c.json({ error: { message: z.prettifyError(error) } }, 400);}-export const zodValidationHook: Hook<unknown, object, string, Response | undefined> = (result, c) => {+/** Throws so the app error handler owns both the response and its log line. */+export const zodValidationHook: Hook<unknown, object, string, Response | undefined> = result => {if (!result.success) {- return zodErrorResponse(c, result.error);+ throw result.error;}return undefined;};diff --git a/packages/trueforge/tests/unit/apis/mcpServers.test.ts b/packages/trueforge/tests/unit/apis/mcpServers.test.tsindex 4e60bf573..b4e4dba5d 100644--- a/packages/trueforge/tests/unit/apis/mcpServers.test.ts+++ b/packages/trueforge/tests/unit/apis/mcpServers.test.ts@@ -18,6 +18,7 @@ import { createSqliteDb } from '../../../src/db/sqlite/client';import { SqliteMcpServerStore } from '../../../src/db/sqlite/mcp-server-store/SqliteMcpServerStore';import { SqliteOAuthTokenStore } from '../../../src/db/sqlite/token-store/SqliteOAuthTokenStore';import { mcpOAuthCallbackUrl } from '../../../src/mcp/auth/mcpOAuthHelpers';+import { mountWithErrorHandler } from '../mountWithErrorHandler';jest.mock('undici', () => {const actual = jest.requireActual<typeof import('undici')>('undici');@@ -136,14 +137,16 @@ describe('mcp-servers routers', () => {withTransaction = callback => db.transaction().execute(callback);logger = winston.createLogger({ silent: true });agentStore = new SqliteAgentStore(db);- settingsRouter = createSettingsMcpServersRouter({- resolveMcpServerStore: () => mcpServerStore,- resolveAgentStore: () => agentStore,- tokenStore,- withTransaction,- logger,- resolveRequestContext: () => STANDALONE_REQUEST_CONTEXT,- });+ settingsRouter = mountWithErrorHandler(+ createSettingsMcpServersRouter({+ resolveMcpServerStore: () => mcpServerStore,+ resolveAgentStore: () => agentStore,+ tokenStore,+ withTransaction,+ logger,+ resolveRequestContext: () => STANDALONE_REQUEST_CONTEXT,+ }),+ );catalogRouter = createCatalogRouter({modelCatalog: ModelCatalog.load(),mcpCatalog: McpCatalog.load(),diff --git a/packages/trueforge/tests/unit/apis/modelProviders.test.ts b/packages/trueforge/tests/unit/apis/modelProviders.test.tsindex dc77724c0..334791203 100644--- a/packages/trueforge/tests/unit/apis/modelProviders.test.ts+++ b/packages/trueforge/tests/unit/apis/modelProviders.test.ts@@ -24,6 +24,7 @@ import { SqliteSkillStore } from '../../../src/db/sqlite/skill-store/SqliteSkillimport { SqliteOAuthTokenStore } from '../../../src/db/sqlite/token-store/SqliteOAuthTokenStore';import { SqliteWebSearchProviderStore } from '../../../src/db/sqlite/web-search-provider-store/SqliteWebSearchProviderStore';import { toRedactedSecretValue } from '../../../src/utils/secretRedaction';+import { mountWithErrorHandler } from '../mountWithErrorHandler';const model = {model_id: 'claude-sonnet-4-6',@@ -114,7 +115,7 @@ function withRedactedApiKey<T extends { auth: { api_key: string } }>(provider: T}async function createRouters(): Promise<{- settingsRouter: ReturnType<typeof createSettingsRouter>;+ settingsRouter: ReturnType<typeof mountWithErrorHandler>;catalogRouter: ReturnType<typeof createCatalogRouter>;modelsRouter: ReturnType<typeof createModelsRouter>;modelProviderStore: IModelProviderStore;@@ -126,24 +127,26 @@ async function createRouters(): Promise<{const tokenStore = new SqliteOAuthTokenStore(db);const agentStore = new SqliteAgentStore(db);return {- settingsRouter: createSettingsRouter({- resolveModelProviderStore: () => modelProviderStore,- resolveMcpServerStore: () =>- new McpServerWithAuthStore({- store: new SqliteMcpServerStore(db),- tokenStore,- clientName: configuration.MCP_DCR_OAUTH_CLIENT_NAME,- }),- tokenStore,- resolveSkillStore: () => new SqliteSkillStore(db),- resolveSandboxProviderStore: () => new SqliteSandboxProviderStore(db),- sandboxEnvironmentStore: new SqliteSandboxEnvironmentStore(db),- resolveWebSearchProviderStore: () => new SqliteWebSearchProviderStore(db),- resolveAgentStore: () => agentStore,- withTransaction: callback => db.transaction().execute(callback),- logger: winston.createLogger({ silent: true }),- resolveRequestContext: () => STANDALONE_REQUEST_CONTEXT,- }),+ settingsRouter: mountWithErrorHandler(+ createSettingsRouter({+ resolveModelProviderStore: () => modelProviderStore,+ resolveMcpServerStore: () =>+ new McpServerWithAuthStore({+ store: new SqliteMcpServerStore(db),+ tokenStore,+ clientName: configuration.MCP_DCR_OAUTH_CLIENT_NAME,+ }),+ tokenStore,+ resolveSkillStore: () => new SqliteSkillStore(db),+ resolveSandboxProviderStore: () => new SqliteSandboxProviderStore(db),+ sandboxEnvironmentStore: new SqliteSandboxEnvironmentStore(db),+ resolveWebSearchProviderStore: () => new SqliteWebSearchProviderStore(db),+ resolveAgentStore: () => agentStore,+ withTransaction: callback => db.transaction().execute(callback),+ logger: winston.createLogger({ silent: true }),+ resolveRequestContext: () => STANDALONE_REQUEST_CONTEXT,+ }),+ ),catalogRouter: createCatalogRouter({modelCatalog: ModelCatalog.load(),mcpCatalog: McpCatalog.load(),@@ -162,7 +165,7 @@ async function createRouters(): Promise<{}describe('settings model-providers and models routers', () => {- let settingsRouter: ReturnType<typeof createSettingsRouter>;+ let settingsRouter: ReturnType<typeof mountWithErrorHandler>;let catalogRouter: ReturnType<typeof createCatalogRouter>;let modelsRouter: ReturnType<typeof createModelsRouter>;diff --git a/packages/trueforge/tests/unit/apis/turnHarnessErrorStatus.test.ts b/packages/trueforge/tests/unit/apis/turnHarnessErrorStatus.test.tsindex 83bdb51f4..d657b3f93 100644--- a/packages/trueforge/tests/unit/apis/turnHarnessErrorStatus.test.ts+++ b/packages/trueforge/tests/unit/apis/turnHarnessErrorStatus.test.ts@@ -3,6 +3,7 @@ import type { Sessions } from '@truefoundry/trueforge-core/agent-session';import { AgentHarnessError } from '@truefoundry/trueforge-core/core';import { createLogger } from 'winston';import { createTurnsRouter } from '../../../src/apis/turns';+import { createAppErrorHandler } from '../../../src/app';import { TrueForgeAuthorizer } from '../../../src/auth/authorizer';import { STANDALONE_REQUEST_CONTEXT } from '../../../src/auth/identity';import { McpServerWithAuthStore } from '../../../src/db/McpServerWithAuthStore';@@ -63,7 +64,7 @@ async function postTurnRejectingWith(error: AgentHarnessError): Promise<Response} as unknown as Sessions;const app = new OpenAPIHono();- app.onError((_error, c) => c.json({ error: { message: 'Internal server error' } }, 500));+ app.onError(createAppErrorHandler({ logger: createLogger({ silent: true }) }));app.route('/',createTurnsRouter({diff --git a/packages/trueforge/tests/unit/appErrorHandler.test.ts b/packages/trueforge/tests/unit/appErrorHandler.test.tsindex 62184aa4c..b2d8b1bad 100644--- a/packages/trueforge/tests/unit/appErrorHandler.test.ts+++ b/packages/trueforge/tests/unit/appErrorHandler.test.ts@@ -1,61 +1,170 @@-import { OpenAPIHono } from '@hono/zod-openapi';+import { OpenAPIHono, createRoute, z } from '@hono/zod-openapi';import { HTTPException } from 'hono/http-exception';import winston from 'winston';import { createAppErrorHandler } from '../../src/app';+import { zodValidationHook } from '../../src/zodErrorResponse';++function appThrowing(logger: winston.Logger, thrown: unknown): OpenAPIHono {+ const app = new OpenAPIHono();+ app.onError(createAppErrorHandler({ logger }));+ app.get('/test', () => {+ throw thrown;+ });+ return app;+}++const CLIENT_ERROR_CASES: { status: 400 | 409 | 422 | 424 | 429 }[] = [+ { status: 400 },+ { status: 409 },+ { status: 422 },+ { status: 424 },+ { status: 429 },+];++const QUIET_CLIENT_ERROR_CASES: { status: 401 | 403 | 404 }[] = [{ status: 401 }, { status: 403 }, { status: 404 }];++const SERVER_ERROR_CASES: { status: 500 | 502 | 503 }[] = [{ status: 500 }, { status: 502 }, { status: 503 }];describe('createAppErrorHandler', () => {it('logs the stack for an unhandled error and returns a generic 500', async () => {const logger = winston.createLogger({ silent: true });const errorLog = jest.spyOn(logger, 'error');- const app = new OpenAPIHono();const thrown = new Error('unexpected failure');- app.onError(createAppErrorHandler({ logger }));- app.get('/test', () => {- throw thrown;- });- const response = await app.request('/test');+ const response = await appThrowing(logger, thrown).request('/test');expect(response.status).toBe(500);expect(await response.json()).toEqual({ error: { message: 'Internal server error' } });expect(errorLog).toHaveBeenCalledWith('Unhandled error', {+ method: 'GET',+ path: '/test',+ status: 500,error: thrown.message,stack: thrown.stack,});});- it('logs the stack and status for a server HTTP exception', async () => {+ it.each(SERVER_ERROR_CASES)('logs the stack and status for a $status server HTTP exception', async ({ status }) => {const logger = winston.createLogger({ silent: true });+ const warnLog = jest.spyOn(logger, 'warn');const errorLog = jest.spyOn(logger, 'error');- const app = new OpenAPIHono();- const thrown = new HTTPException(503, { message: 'Service unavailable' });- app.onError(createAppErrorHandler({ logger }));- app.get('/test', () => {- throw thrown;- });+ const thrown = new HTTPException(status, { message: 'Service unavailable' });- const response = await app.request('/test');+ const response = await appThrowing(logger, thrown).request('/test');- expect(response.status).toBe(503);+ expect(response.status).toBe(status);+ expect(warnLog).not.toHaveBeenCalled();expect(errorLog).toHaveBeenCalledWith('Server API error', {- status: 503,+ method: 'GET',+ path: '/test',+ status,error: thrown.message,stack: thrown.stack,});});- it('does not error-log a client HTTP exception', async () => {+ it.each(CLIENT_ERROR_CASES)('warns with the stack for a $status client HTTP exception', async ({ status }) => {const logger = winston.createLogger({ silent: true });+ const warnLog = jest.spyOn(logger, 'warn');const errorLog = jest.spyOn(logger, 'error');- const app = new OpenAPIHono();- app.onError(createAppErrorHandler({ logger }));- app.get('/test', () => {- throw new HTTPException(404, { message: 'Not found' });+ const thrown = new HTTPException(status, { message: 'Unknown model "a/b" — provider not configured' });++ const response = await appThrowing(logger, thrown).request('/test');++ expect(response.status).toBe(status);+ expect(errorLog).not.toHaveBeenCalled();+ expect(warnLog).toHaveBeenCalledWith('Client API error', {+ method: 'GET',+ path: '/test',+ status,+ error: thrown.message,+ stack: thrown.stack,});+ });- const response = await app.request('/test');+ it.each(QUIET_CLIENT_ERROR_CASES)('keeps a $status rejection at debug', async ({ status }) => {+ const logger = winston.createLogger({ silent: true });+ const warnLog = jest.spyOn(logger, 'warn');+ const errorLog = jest.spyOn(logger, 'error');+ const debugLog = jest.spyOn(logger, 'debug');+ const thrown = new HTTPException(status, { message: 'Not found' });++ const response = await appThrowing(logger, thrown).request('/test');- expect(response.status).toBe(404);+ expect(response.status).toBe(status);expect(errorLog).not.toHaveBeenCalled();+ expect(warnLog).not.toHaveBeenCalled();+ expect(debugLog).toHaveBeenCalledWith('Client API error', {+ method: 'GET',+ path: '/test',+ status,+ error: thrown.message,+ stack: thrown.stack,+ });+ });++ it('warns for a thrown ZodError and still returns the prettified 400', async () => {+ const logger = winston.createLogger({ silent: true });+ const warnLog = jest.spyOn(logger, 'warn');+ const parsed = z.object({ name: z.string() }).safeParse({ name: 1 });+ if (parsed.success) {+ throw new Error('expected the fixture to fail validation');+ }++ const response = await appThrowing(logger, parsed.error).request('/test');++ expect(response.status).toBe(400);+ expect(await response.json()).toEqual({ error: { message: z.prettifyError(parsed.error) } });+ expect(warnLog).toHaveBeenCalledWith(+ 'Client API error',+ expect.objectContaining({ method: 'GET', path: '/test', status: 400 }),+ );+ });++ it('chains the route stack and the origin stack when a route rethrows with a cause', async () => {+ const logger = winston.createLogger({ silent: true });+ const warnLog = jest.spyOn(logger, 'warn');+ const origin = new Error('Invalid page token: garbage');+ const thrown = new HTTPException(400, { message: origin.message, cause: origin });++ const response = await appThrowing(logger, thrown).request('/test');++ expect(response.status).toBe(400);+ expect(warnLog).toHaveBeenCalledWith('Client API error', {+ method: 'GET',+ path: '/test',+ status: 400,+ error: origin.message,+ stack: `${thrown.stack ?? ''}\nCaused by: ${origin.stack ?? ''}`,+ });+ });++ it('logs and answers request-validation failures thrown by the validation hook', async () => {+ const logger = winston.createLogger({ silent: true });+ const warnLog = jest.spyOn(logger, 'warn');+ const route = createRoute({+ method: 'post',+ path: '/echo',+ request: { body: { content: { 'application/json': { schema: z.object({ name: z.string() }) } } } },+ responses: { 200: { description: 'ok' } },+ });+ const app = new OpenAPIHono({ defaultHook: zodValidationHook });+ app.onError(createAppErrorHandler({ logger }));+ app.openapi(route, c => c.json({ name: c.req.valid('json').name }, 200));++ const response = await app.request('/echo', {+ method: 'POST',+ headers: { 'content-type': 'application/json' },+ body: JSON.stringify({ name: 1 }),+ });++ expect(response.status).toBe(400);+ expect(await response.json()).toEqual({+ error: { message: expect.stringContaining('expected string') },+ });+ expect(warnLog).toHaveBeenCalledWith(+ 'Client API error',+ expect.objectContaining({ method: 'POST', path: '/echo', status: 400 }),+ );});});diff --git a/packages/trueforge/tests/unit/mountWithErrorHandler.ts b/packages/trueforge/tests/unit/mountWithErrorHandler.tsnew file mode 100644index 000000000..87b2bd2e3--- /dev/null+++ b/packages/trueforge/tests/unit/mountWithErrorHandler.ts@@ -0,0 +1,14 @@+import { OpenAPIHono } from '@hono/zod-openapi';+import { createLogger } from 'winston';+import { createAppErrorHandler } from '../../src/app';++/**+ * Routers throw `HTTPException`; the error envelope and its log line come from the app+ * handler. Mount through this so a router under test answers the way it does in production.+ */+export function mountWithErrorHandler(router: OpenAPIHono): OpenAPIHono {+ const app = new OpenAPIHono();+ app.onError(createAppErrorHandler({ logger: createLogger({ silent: true }) }));+ app.route('/', router);+ return app;+}diff --git a/packages/trueforge/tests/unit/sandbox/sandboxEnvironmentSecrets.test.ts b/packages/trueforge/tests/unit/sandbox/sandboxEnvironmentSecrets.test.tsindex 307b3f399..4848adb15 100644--- a/packages/trueforge/tests/unit/sandbox/sandboxEnvironmentSecrets.test.ts+++ b/packages/trueforge/tests/unit/sandbox/sandboxEnvironmentSecrets.test.ts@@ -10,6 +10,7 @@ import { SqliteSandboxProviderStore } from '../../../src/db/sqlite/sandbox-proviimport { resolveSandboxEnvironment } from '../../../src/runtime/sessionResources';import * as providerUtils from '../../../src/sandbox/providerUtils';import { SECRET_REDACTION } from '../../../src/utils/secretRedaction';+import { mountWithErrorHandler } from '../mountWithErrorHandler';jest.mock('../../../src/sandbox/providerUtils', () => {const actual = jest.requireActual<typeof import('../../../src/sandbox/providerUtils')>(@@ -43,13 +44,15 @@ describe('sandbox environment secrets', () => {tenant_id: STANDALONE_REQUEST_CONTEXT.tenant_id,manifest: daytonaManifest,});- const publicRouter = createSandboxEnvironmentsRouter({- sandboxEnvironmentStore,- resolveAgentStore: () => ({ listAgentNamesUsingSandboxEnvironment: jest.fn().mockResolvedValue([]) }) as never,- resolveSandboxProviderStore: () => sandboxProviderStore,- resolveRequestContext: () => STANDALONE_REQUEST_CONTEXT,- logger,- });+ const publicRouter = mountWithErrorHandler(+ createSandboxEnvironmentsRouter({+ sandboxEnvironmentStore,+ resolveAgentStore: () => ({ listAgentNamesUsingSandboxEnvironment: jest.fn().mockResolvedValue([]) }) as never,+ resolveSandboxProviderStore: () => sandboxProviderStore,+ resolveRequestContext: () => STANDALONE_REQUEST_CONTEXT,+ logger,+ }),+ );const buildRouter = createSandboxEnvironmentBuildRouter({sandboxEnvironmentStore,sandboxProviderStore,