The open-source agent harness - the runtime layer that turns an LLM into a working agent.
chore: add SDK HTTP timeout tracking and user-friendly error handling (#1048)
harshil-2096531350eb3dd6
diff --git a/.changeset/sdk-http-timeout-analytics.md b/.changeset/sdk-http-timeout-analytics.mdnew file mode 100644index 000000000..2e8b6b52d--- /dev/null+++ b/.changeset/sdk-http-timeout-analytics.md@@ -0,0 +1,5 @@+---+'@truefoundry/trueforge-ui': patch+---++Emit `trueforge.sdk.http_timeout` with the request endpoint for every SDK HTTP timeout, and show a clear "Request timed out" toast instead of "Something went wrong" with a bare "timeout" detail.diff --git a/packages/trueforge-ui/src/analytics/AnalyticsProvider.tsx b/packages/trueforge-ui/src/analytics/AnalyticsProvider.tsxindex 306d086b6..e5a526c95 100644--- a/packages/trueforge-ui/src/analytics/AnalyticsProvider.tsx+++ b/packages/trueforge-ui/src/analytics/AnalyticsProvider.tsx@@ -1,7 +1,8 @@'use client';-import { createContext, useCallback, useContext, useMemo, type ReactNode } from 'react';+import { createContext, useCallback, useContext, useEffect, useMemo, type ReactNode } from 'react';+import { bindSdkHttpTimeoutTracking } from './trackSdkHttpTimeout.js';import type { AnalyticsEventProps, TrackAnalytics } from './types.js';// Host owns vendor identify/group/gating; SDK only forwards (name, props) and no-ops when unset@@ -25,6 +26,13 @@ export function AnalyticsProvider({ track, children }: { track?: TrackAnalytics;const value = useMemo(() => (track == null ? null : stableTrack), [stableTrack, track]);+ // API calls run outside React and can't read this context. Hand them the host's+ // `track` here so any request that times out can send an analytics event; clear it on unmount.+ useEffect(() => {+ bindSdkHttpTimeoutTracking(value);+ return () => bindSdkHttpTimeoutTracking(null);+ }, [value]);+return <AnalyticsContext.Provider value={value}>{children}</AnalyticsContext.Provider>;}diff --git a/packages/trueforge-ui/src/analytics/events.ts b/packages/trueforge-ui/src/analytics/events.tsindex 2391f85d7..80560f4c4 100644--- a/packages/trueforge-ui/src/analytics/events.ts+++ b/packages/trueforge-ui/src/analytics/events.ts@@ -74,4 +74,7 @@ export const AnalyticsEvents = {EDITED: 'trueforge.environment.edited',DELETED: 'trueforge.environment.deleted',},+ Sdk: {+ HTTP_TIMEOUT: 'trueforge.sdk.http_timeout',+ },} as const;diff --git a/packages/trueforge-ui/src/analytics/trackSdkHttpTimeout.ts b/packages/trueforge-ui/src/analytics/trackSdkHttpTimeout.tsnew file mode 100644index 000000000..abc9b2d49--- /dev/null+++ b/packages/trueforge-ui/src/analytics/trackSdkHttpTimeout.ts@@ -0,0 +1,115 @@+import { AnalyticsEvents } from './events.js';+import type { TrackAnalytics } from './types.js';++// Exact error class name the SDK sets when an HTTP call hits its request timeout (default ~60s).+const TRUEFORGE_TIMEOUT_ERROR_NAME = 'TrueForgeTimeoutError';+// SDK message shape: "Timeout exceeded when calling POST /v1/sessions." → capture method + path.+const SDK_TIMEOUT_MESSAGE_PATTERN = /^Timeout exceeded when calling (\S+) (.+?)\.?$/;++function readErrorMessage(error: unknown): string | undefined {+ if (typeof error === 'string') {+ const trimmed = error.trim();+ return trimmed === '' ? undefined : trimmed;+ }+ if (error instanceof Error) {+ const trimmed = error.message.trim();+ return trimmed === '' ? undefined : trimmed;+ }+ if (error != null && typeof error === 'object' && 'message' in error) {+ const message = Reflect.get(error, 'message');+ if (typeof message === 'string') {+ const trimmed = message.trim();+ return trimmed === '' ? undefined : trimmed;+ }+ }+ return undefined;+}++function readErrorName(error: unknown): string | undefined {+ if (error instanceof Error && error.name !== '') return error.name;+ if (error != null && typeof error === 'object' && 'name' in error) {+ const name = Reflect.get(error, 'name');+ if (typeof name === 'string' && name !== '') return name;+ }+ return undefined;+}++/**+ * `controller.abort("timeout")` can reject fetch with the raw string. The SDK then+ * `JSON.stringify`s that into the error message, so the toast text is `"timeout"`+ * (quotes included), not the word alone.+ *+ * e.g. `timeout`, `"timeout"`, `'timeout'` → true;+ */+function isTimeoutToken(message: string): boolean {+ const trimmed = message.trim();+ if (trimmed.toLowerCase() === 'timeout') return true;+ const quoted =+ (trimmed.startsWith('"') && trimmed.endsWith('"')) || (trimmed.startsWith("'") && trimmed.endsWith("'"));+ if (!quoted) return false;+ return trimmed.slice(1, -1).trim().toLowerCase() === 'timeout';+}++/**+ * Guess whether this failure was an SDK HTTP timeout.+ * We check the error's name/text instead of `instanceof`, because the UI may see a+ * copy of the class from a different bundle where instanceof would fail.+ * Also treats a bare "timeout" string as a hit — that is what the toast sometimes shows.+ *+ * e.g. true for `TrueForgeTimeoutError`, `new Error('"timeout"')`,+ * `new Error('Timeout exceeded when calling GET /api/v1/agents.')`; false for `new Error('boom')`.+ */+export function isSdkHttpTimeoutError(error: unknown): boolean {+ const name = readErrorName(error);+ if (name === TRUEFORGE_TIMEOUT_ERROR_NAME) return true;++ const message = readErrorMessage(error);+ if (message == null) return false;+ if (isTimeoutToken(message)) return true;+ return SDK_TIMEOUT_MESSAGE_PATTERN.test(message);+}++let reportTimeout: TrackAnalytics | null = null;++/** AnalyticsProvider publishes the host sink so the shared SDK fetch can report timeouts. */+export function bindSdkHttpTimeoutTracking(track: TrackAnalytics | null): void {+ reportTimeout = track;+}++// e.g. `http://localhost:3000/api/v1/sessions/abc/events?limit=20` → `/api/v1/sessions/abc/events`+function requestPath(input: RequestInfo | URL): string {+ const raw = input instanceof Request ? input.url : input instanceof URL ? input.href : input;+ try {+ return new URL(raw, 'http://localhost').pathname;+ } catch {+ return raw;+ }+}++function isFetchTimeout(error: unknown, signal: AbortSignal | undefined): boolean {+ if (signal?.reason === 'timeout') return true;+ if (typeof error === 'string') return isTimeoutToken(error);+ if (error instanceof Error && isTimeoutToken(error.message)) return true;+ return false;+}++/**+ * Wrap the SDK fetch used by every Harness API (chat, settings, schedules, sessions, …).+ * A timeout is reported once here with the request endpoint, including calls that never toast.+ *+ * e.g. a timed-out `GET .../api/v1/sessions/abc/events?limit=20` sends+ * `trueforge.sdk.http_timeout` with `{ endpoint: 'GET /api/v1/sessions/abc/events' }`.+ */+export function withSdkHttpTimeoutTracking(baseFetch: typeof fetch): typeof fetch {+ return async (input, init) => {+ try {+ return await baseFetch(input, init);+ } catch (error) {+ if (reportTimeout != null && isFetchTimeout(error, init?.signal ?? undefined)) {+ const method = (init?.method ?? (input instanceof Request ? input.method : 'GET')).toUpperCase();+ reportTimeout(AnalyticsEvents.Sdk.HTTP_TIMEOUT, { endpoint: `${method} ${requestPath(input)}` });+ }+ throw error;+ }+ };+}diff --git a/packages/trueforge-ui/src/containers/ToasterContainer.tsx b/packages/trueforge-ui/src/containers/ToasterContainer.tsxindex 393512fa1..32f127ee5 100644--- a/packages/trueforge-ui/src/containers/ToasterContainer.tsx+++ b/packages/trueforge-ui/src/containers/ToasterContainer.tsx@@ -2,12 +2,15 @@import { createContext, useCallback, useContext, useMemo, useState, type ReactNode } from 'react';+import { isSdkHttpTimeoutError } from '../analytics/trackSdkHttpTimeout.js';import { useSlot } from '../theme/SlotsProvider.js';import { getErrorMessage } from '../utils/getErrorMessage.js';const MAX_TOAST_DESCRIPTION_CHARS = 480;const MAX_VISIBLE_TOASTS = 5;const SUCCESS_TOAST_TTL_MS = 3000;+const SDK_TIMEOUT_TOAST_TITLE = 'Request timed out';+const SDK_TIMEOUT_TOAST_DESCRIPTION = 'The request took too long and was cancelled. Try again.';type ToastContent = { title: string; description?: string };@@ -36,6 +39,10 @@ function isHttpLikeError(error: unknown): error is Error & { statusCode?: number}function normalizeError(error: unknown): ToastContent {+ if (isSdkHttpTimeoutError(error)) {+ return { title: SDK_TIMEOUT_TOAST_TITLE, description: SDK_TIMEOUT_TOAST_DESCRIPTION };+ }+if (isHttpLikeError(error)) {const statusCode = error.statusCode;if (statusCode != null || error.body != null) {diff --git a/packages/trueforge-ui/src/plugins/trueforge-agent-server-adapter/client.ts b/packages/trueforge-ui/src/plugins/trueforge-agent-server-adapter/client.tsindex 0430fc710..4481104d8 100644--- a/packages/trueforge-ui/src/plugins/trueforge-agent-server-adapter/client.ts+++ b/packages/trueforge-ui/src/plugins/trueforge-agent-server-adapter/client.ts@@ -4,6 +4,8 @@*/import { TrueForge } from '@truefoundry/trueforge-sdk';+import { withSdkHttpTimeoutTracking } from '../../analytics/trackSdkHttpTimeout.js';+export interface CreateTrueForgeClientOptions {baseUrl?: string;/** SDK Bearer token (`Authorization: Bearer …`). */@@ -28,10 +30,11 @@ export function resolveTrueForgeBaseUrl(baseUrl: string): string {}export function createTrueForgeClient(options: CreateTrueForgeClientOptions = {}): TrueForge {+ const fetchFn = withSdkHttpTimeoutTracking(options.fetch ?? globalThis.fetch.bind(globalThis));return new TrueForge({baseUrl: resolveTrueForgeBaseUrl(options.baseUrl ?? DEFAULT_BASE_URL),+ fetch: fetchFn,...(options.token === undefined ? {} : { token: options.token }),- ...(options.fetch === undefined ? {} : { fetch: options.fetch }),});}diff --git a/packages/trueforge-ui/test/analytics/trackSdkHttpTimeout.test.ts b/packages/trueforge-ui/test/analytics/trackSdkHttpTimeout.test.tsnew file mode 100644index 000000000..29a505ba7--- /dev/null+++ b/packages/trueforge-ui/test/analytics/trackSdkHttpTimeout.test.ts@@ -0,0 +1,72 @@+import { describe, expect, it, vi } from 'vitest';++import { AnalyticsEvents } from '@/analytics/events.js';+import {+ bindSdkHttpTimeoutTracking,+ isSdkHttpTimeoutError,+ withSdkHttpTimeoutTracking,+} from '@/analytics/trackSdkHttpTimeout.js';++describe('isSdkHttpTimeoutError', () => {+ it('matches TrueForgeTimeoutError by name', () => {+ const error = Object.assign(new Error('Timeout exceeded when calling POST /v1/sessions.'), {+ name: 'TrueForgeTimeoutError',+ });+ expect(isSdkHttpTimeoutError(error)).toBe(true);+ });++ it('matches the SDK timeout message shape', () => {+ expect(isSdkHttpTimeoutError(new Error('Timeout exceeded when calling GET /v1/agents.'))).toBe(true);+ });++ it('matches the opaque bare "timeout" message', () => {+ expect(isSdkHttpTimeoutError(new Error('timeout'))).toBe(true);+ expect(isSdkHttpTimeoutError('timeout')).toBe(true);+ });++ it('matches the JSON-quoted abort reason the SDK puts on TrueForgeError', () => {+ const error = Object.assign(new Error('"timeout"'), { name: 'TrueForgeError' });+ expect(isSdkHttpTimeoutError(error)).toBe(true);+ });++ it('rejects unrelated errors', () => {+ expect(isSdkHttpTimeoutError(new Error('boom'))).toBe(false);+ expect(isSdkHttpTimeoutError({ statusCode: 500 })).toBe(false);+ expect(isSdkHttpTimeoutError(null)).toBe(false);+ });+});++describe('withSdkHttpTimeoutTracking', () => {+ it('reports the request endpoint for a timeout and ignores other failures', async () => {+ const track = vi.fn();+ bindSdkHttpTimeoutTracking(track);++ const timeoutSignal = new AbortController();+ timeoutSignal.abort('timeout');+ let failure: unknown = 'timeout';+ const wrapped = withSdkHttpTimeoutTracking(async () => {+ throw failure;+ });++ await expect(+ wrapped('http://localhost:3000/api/v1/sessions/abc/events?limit=20', {+ method: 'GET',+ signal: timeoutSignal.signal,+ }),+ ).rejects.toBe('timeout');++ failure = new Error('boom');+ await expect(+ wrapped('http://localhost:3000/api/v1/agents', {+ method: 'POST',+ }),+ ).rejects.toThrow('boom');++ expect(track).toHaveBeenCalledTimes(1);+ expect(track).toHaveBeenCalledWith(AnalyticsEvents.Sdk.HTTP_TIMEOUT, {+ endpoint: 'GET /api/v1/sessions/abc/events',+ });++ bindSdkHttpTimeoutTracking(null);+ });+});diff --git a/packages/trueforge-ui/test/containers/ToasterContainer.test.tsx b/packages/trueforge-ui/test/containers/ToasterContainer.test.tsxindex 366df434e..217602404 100644--- a/packages/trueforge-ui/test/containers/ToasterContainer.test.tsx+++ b/packages/trueforge-ui/test/containers/ToasterContainer.test.tsx@@ -1,6 +1,8 @@import { act, fireEvent, render, renderHook, screen, waitFor } from '@testing-library/react';+import type { ReactNode } from 'react';import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';+import { AnalyticsProvider } from '@/analytics/AnalyticsProvider.js';import { Toast } from '@/atoms/Toast.js';import { ToasterProvider, useToaster, useToasterOptional } from '@/containers/ToasterContainer.js';import { SlotsProvider } from '@/theme/SlotsProvider.js';@@ -19,6 +21,16 @@ function Trigger({ errors }: { errors: unknown[] }) {);}+function renderToaster(ui: ReactNode) {+ return render(+ <SlotsProvider>+ <AnalyticsProvider>+ <ToasterProvider>{ui}</ToasterProvider>+ </AnalyticsProvider>+ </SlotsProvider>,+ );+}+describe('ToasterProvider', () => {beforeEach(() => {vi.spyOn(console, 'error').mockImplementation(() => {});@@ -36,13 +48,7 @@ describe('ToasterProvider', () => {});it('stacks multiple error toasts', async () => {- render(- <SlotsProvider>- <ToasterProvider>- <Trigger errors={[new Error('first'), new Error('second')]} />- </ToasterProvider>- </SlotsProvider>,- );+ renderToaster(<Trigger errors={[new Error('first'), new Error('second')]} />);fireEvent.click(screen.getByRole('button', { name: 'boom' }));@@ -52,13 +58,7 @@ describe('ToasterProvider', () => {});it('dismisses one toast without removing the other', async () => {- render(- <SlotsProvider>- <ToasterProvider>- <Trigger errors={[new Error('keep-me'), new Error('drop-me')]} />- </ToasterProvider>- </SlotsProvider>,- );+ renderToaster(<Trigger errors={[new Error('keep-me'), new Error('drop-me')]} />);fireEvent.click(screen.getByRole('button', { name: 'boom' }));expect(await screen.findByText('drop-me')).toBeTruthy();@@ -83,13 +83,7 @@ describe('ToasterProvider', () => {body: { detail: 'invalid agent' },});- render(- <SlotsProvider>- <ToasterProvider>- <Trigger errors={[httpError]} />- </ToasterProvider>- </SlotsProvider>,- );+ renderToaster(<Trigger errors={[httpError]} />);fireEvent.click(screen.getByRole('button', { name: 'boom' }));@@ -103,13 +97,7 @@ describe('ToasterProvider', () => {body: { error: { message: 'Name taken' } },});- render(- <SlotsProvider>- <ToasterProvider>- <Trigger errors={[httpError]} />- </ToasterProvider>- </SlotsProvider>,- );+ renderToaster(<Trigger errors={[httpError]} />);fireEvent.click(screen.getByRole('button', { name: 'boom' }));@@ -120,13 +108,7 @@ describe('ToasterProvider', () => {it('keeps only the five most recent errors visible', async () => {const errors = Array.from({ length: 6 }, (_, index) => new Error(`error-${index + 1}`));- render(- <SlotsProvider>- <ToasterProvider>- <Trigger errors={errors} />- </ToasterProvider>- </SlotsProvider>,- );+ renderToaster(<Trigger errors={errors} />);fireEvent.click(screen.getByRole('button', { name: 'boom' }));@@ -134,6 +116,43 @@ describe('ToasterProvider', () => {expect(screen.queryByText('error-1')).not.toBeInTheDocument();expect(screen.getByText('error-6')).toBeInTheDocument();});++ it('shows a clear toast for SDK HTTP timeouts and leaves ordinary errors generic', async () => {+ const timeoutError = Object.assign(new Error('Timeout exceeded when calling POST /v1/sessions.'), {+ name: 'TrueForgeTimeoutError',+ });++ renderToaster(<Trigger errors={[new Error('ordinary'), timeoutError]} />);++ fireEvent.click(screen.getByRole('button', { name: 'boom' }));+ expect(await screen.findByText('Something went wrong')).toBeInTheDocument();+ expect(screen.getByText('ordinary')).toBeInTheDocument();+ expect(screen.getByText('Request timed out')).toBeInTheDocument();+ expect(screen.getByText('The request took too long and was cancelled. Try again.')).toBeInTheDocument();+ });++ it('replaces a JSON-quoted timeout from TrueForgeError', async () => {+ const error = Object.assign(new Error('"timeout"'), { name: 'TrueForgeError' });++ renderToaster(<Trigger errors={[error]} />);++ fireEvent.click(screen.getByRole('button', { name: 'boom' }));++ expect(await screen.findByText('Request timed out')).toBeInTheDocument();+ expect(screen.getByText('The request took too long and was cancelled. Try again.')).toBeInTheDocument();+ expect(screen.queryByText('"timeout"')).not.toBeInTheDocument();+ });++ it('replaces a bare timeout message with clear toast copy', async () => {+ renderToaster(<Trigger errors={[new Error('timeout'), 'timeout']} />);++ fireEvent.click(screen.getByRole('button', { name: 'boom' }));++ expect(await screen.findAllByText('Request timed out')).toHaveLength(2);+ expect(screen.getAllByText('The request took too long and was cancelled. Try again.')).toHaveLength(2);+ expect(screen.queryByText('timeout')).not.toBeInTheDocument();+ expect(screen.queryByText('Something went wrong')).not.toBeInTheDocument();+ });});describe('Toast copy', () => {