The open-source agent harness - the runtime layer that turns an LLM into a working agent.
chore: improve error handling for loading schedules, agents, and environments (#962)
harshil-2096c2ccca5b469e
diff --git a/.changeset/schedules-load-error-ui.md b/.changeset/schedules-load-error-ui.mdnew file mode 100644index 000000000..48b38a5e4--- /dev/null+++ b/.changeset/schedules-load-error-ui.md@@ -0,0 +1,5 @@+---+'@truefoundry/trueforge-ui': patch+---++Show clearer empty-state errors when schedules, agents, or environments fail to load, and map browser network noise to the fallback in getErrorMessage.diff --git a/packages/trueforge-ui/src/atoms/AgentsLibrary.tsx b/packages/trueforge-ui/src/atoms/AgentsLibrary.tsxindex 6f46cefc2..357c6d3d6 100644--- a/packages/trueforge-ui/src/atoms/AgentsLibrary.tsx+++ b/packages/trueforge-ui/src/atoms/AgentsLibrary.tsx@@ -733,7 +733,10 @@ export function AgentsLibrary({ onSelectAgent, headerStart }: AgentsLibraryProps<div className="bg-secondary-bg/40 flex min-h-0 flex-1 flex-col">{/* Not flex-col: overflow-hidden table chrome would clip instead of letting this scroll. */}- <div className="min-h-0 flex-1 overflow-y-auto p-4" aria-label="Agents">+ <div+ className={cn('min-h-0 flex-1 overflow-y-auto p-4', error ? 'flex flex-col' : undefined)}+ aria-label="Agents"+ >{isInitialLoading ? (<div className="flex flex-col gap-2 p-1" role="status" aria-label="Loading agents">{Array.from({ length: 6 }, (_, i) => (@@ -741,7 +744,9 @@ export function AgentsLibrary({ onSelectAgent, headerStart }: AgentsLibraryProps))}</div>) : error ? (- <p className="text-failure-bg px-3 py-8 text-center text-sm">{error}</p>+ <div role="alert" className="flex flex-1 flex-col items-center justify-center">+ <EmptyScreen title="Couldn't load agents" description={error} className="h-auto min-h-0 flex-none py-0" />+ </div>) : agents.length === 0 && !hasPageNav ? (<EmptyScreentitle="No Agents Found"diff --git a/packages/trueforge-ui/src/atoms/environments/EnvironmentsPage.tsx b/packages/trueforge-ui/src/atoms/environments/EnvironmentsPage.tsxindex 7b96da7a7..3ebb8b041 100644--- a/packages/trueforge-ui/src/atoms/environments/EnvironmentsPage.tsx+++ b/packages/trueforge-ui/src/atoms/environments/EnvironmentsPage.tsx@@ -15,6 +15,7 @@ import {import { getErrorMessage } from '../../utils/getErrorMessage.js';import { EmptyScreen, EmptyScreenQueryHighlight } from '../EmptyScreen.js';import { auiButtonClass } from '../lib/buttonClasses.js';+import { cn } from '../lib/cn.js';import { formatRelativeTime } from '../lib/dateFormat.js';import { PageHeader } from '../PageHeader.js';import { Button } from '../primitives/Button.js';@@ -91,7 +92,7 @@ export function EnvironmentsPage(_props: EnvironmentsPageProps) {} catch (caught) {if (gen !== loadGenRef.current) return;if (!silent) {- setError(getErrorMessage(caught, 'Failed to load environments'));+ setError(getErrorMessage(caught, 'Check your connection and try again.'));setEnvironments([]);setNextPageToken(undefined);setPreviousPageToken(undefined);@@ -215,9 +216,15 @@ export function EnvironmentsPage(_props: EnvironmentsPageProps) {}/>- <div className="min-h-0 flex-1 overflow-auto px-4 py-4">+ <div className={cn('min-h-0 flex-1 overflow-auto px-4 py-4', error != null ? 'flex flex-col' : undefined)}>{error != null ? (- <p className="text-failure-bg px-3 py-8 text-center text-sm">{error}</p>+ <div role="alert" className="flex flex-1 flex-col items-center justify-center">+ <EmptyScreen+ title="Couldn't load environments"+ description={error}+ className="h-auto min-h-0 flex-none py-0"+ />+ </div>) : loading ? (<div className="flex flex-col gap-2" role="status" aria-label="Loading environments">{Array.from({ length: 5 }, (_, i) => (diff --git a/packages/trueforge-ui/src/atoms/lib/useSearchAgentsList.ts b/packages/trueforge-ui/src/atoms/lib/useSearchAgentsList.tsindex 23a67b4aa..208da4c9c 100644--- a/packages/trueforge-ui/src/atoms/lib/useSearchAgentsList.ts+++ b/packages/trueforge-ui/src/atoms/lib/useSearchAgentsList.ts@@ -192,7 +192,7 @@ export function useSearchAgentsList({setNextPageToken(undefined);setPreviousPageToken(undefined);setHasMore(false);- setError(getErrorMessage(err, 'Failed to load agents.'));+ setError(getErrorMessage(err, 'Check your connection and try again.'));}).finally(() => {if (gen === genRef.current) setLoading(false);diff --git a/packages/trueforge-ui/src/atoms/schedules/SchedulesPage.tsx b/packages/trueforge-ui/src/atoms/schedules/SchedulesPage.tsxindex 7420dbd8c..18952d345 100644--- a/packages/trueforge-ui/src/atoms/schedules/SchedulesPage.tsx+++ b/packages/trueforge-ui/src/atoms/schedules/SchedulesPage.tsx@@ -10,6 +10,7 @@ import { libraryAgentId } from '../../server/ShellModeContext.js';import type { Schedule, ScheduleRun, ScheduleStatus } from '../../server/types.js';import { useSlot } from '../../theme/SlotsProvider.js';import { hasCreatedBySubject } from '../../utils/createdBySubject.js';+import { getErrorMessage } from '../../utils/getErrorMessage.js';import { readScheduleShareSearch, replaceScheduleShareSearch } from '../../utils/scheduleShareUrl.js';import { AgentSearchPicker } from '../AgentSearchPicker.js';import { CreatedByCell } from '../CreatedByCell.js';@@ -238,8 +239,7 @@ export function SchedulesPage({ agentId }: SchedulesPageProps) {void loadRunsForSchedules({ rows: page.data, gen });} catch (caught) {if (gen !== loadGenRef.current) return;- const message = caught instanceof Error ? caught.message : 'Failed to load schedules';- setError(message);+ setError(getErrorMessage(caught, 'Check your connection and try again.'));setSchedules([]);setRunsByScheduleId({});setNextPageToken(undefined);@@ -433,7 +433,7 @@ export function SchedulesPage({ agentId }: SchedulesPageProps) {}/>- <div className="min-h-0 flex-1 overflow-auto px-4 py-4">+ <div className={cn('min-h-0 flex-1 overflow-auto px-4 py-4', error != null ? 'flex flex-col' : undefined)}>{loading ? (<div className="flex flex-col gap-2" role="status" aria-label="Loading schedules">{Array.from({ length: 5 }, (_, i) => (@@ -441,7 +441,13 @@ export function SchedulesPage({ agentId }: SchedulesPageProps) {))}</div>) : error != null ? (- <p className="text-failure-bg px-3 py-8 text-center text-sm">{error}</p>+ <div role="alert" className="flex flex-1 flex-col items-center justify-center">+ <EmptyScreen+ title="Couldn't load schedules"+ description={error}+ className="h-auto min-h-0 flex-none py-0"+ />+ </div>) : schedules.length === 0 ? (<EmptyScreen title="No Schedules Found" description="Create one to get started." className="min-h-full" />) : filtered.length === 0 ? (diff --git a/packages/trueforge-ui/src/utils/getErrorMessage.ts b/packages/trueforge-ui/src/utils/getErrorMessage.tsindex db7b262bb..e336e4baf 100644--- a/packages/trueforge-ui/src/utils/getErrorMessage.ts+++ b/packages/trueforge-ui/src/utils/getErrorMessage.ts@@ -125,28 +125,47 @@ function stringifyError(error: unknown): string {return String(error);}+/** Browser fetch failures that are useless as UI copy when a fallback exists. */+const BROWSER_NETWORK_NOISE = new Set([+ 'failed to fetch',+ 'load failed',+ 'networkerror when attempting to fetch resource.',+]);++function isBrowserNetworkNoise(message: string): boolean {+ return BROWSER_NETWORK_NOISE.has(message.trim().toLowerCase());+}++function preferFallbackForNetworkNoise(message: string, fallback: string | undefined): string {+ if (fallback != null && isBrowserNetworkNoise(message)) {+ return decodeErrorMessageEscapes(fallback);+ }+ return decodeErrorMessageEscapes(message);+}+/*** User-facing error text. Prefers HTTP body `{ error: { message } }` when* present (e.g. TrueForgeError), then `error.message` / `error.error.message`,* then `fallback`, then a string form of the value.*- * Escape sequences (`\n`, `\t`, `\r`, `\uXXXX`, …) are decoded for display when- * still present as literal text.+ * Browser network noise (`Failed to fetch`, etc.) yields `fallback` when one+ * is provided. Escape sequences (`\n`, `\t`, `\r`, `\uXXXX`, …) are decoded for+ * display when still present as literal text.*/export function getErrorMessage(error: unknown, fallback?: string): string {if (typeof error === 'string') {const trimmed = error.trim();- if (trimmed !== '') return decodeErrorMessageEscapes(error);+ if (trimmed !== '') return preferFallbackForNetworkNoise(error, fallback);return fallback != null ? decodeErrorMessageEscapes(fallback) : decodeErrorMessageEscapes(error);}if (isRecord(error) && 'body' in error) {const fromBody = messageFromErrorShaped(error.body);- if (fromBody != null) return decodeErrorMessageEscapes(fromBody);+ if (fromBody != null) return preferFallbackForNetworkNoise(fromBody, fallback);if (error.body != null) {if (typeof error.body === 'string') {const trimmed = error.body.trim();- if (trimmed !== '') return decodeErrorMessageEscapes(error.body);+ if (trimmed !== '') return preferFallbackForNetworkNoise(error.body, fallback);} else {return stringifyError(error.body);}@@ -154,7 +173,7 @@ export function getErrorMessage(error: unknown, fallback?: string): string {}const fromShape = messageFromErrorShaped(error);- if (fromShape != null) return decodeErrorMessageEscapes(fromShape);+ if (fromShape != null) return preferFallbackForNetworkNoise(fromShape, fallback);if (fallback != null) return decodeErrorMessageEscapes(fallback);return stringifyError(error);diff --git a/packages/trueforge-ui/test/atoms/AgentsLibrary.test.tsx b/packages/trueforge-ui/test/atoms/AgentsLibrary.test.tsxindex 973f6deb9..16cbd8bde 100644--- a/packages/trueforge-ui/test/atoms/AgentsLibrary.test.tsx+++ b/packages/trueforge-ui/test/atoms/AgentsLibrary.test.tsx@@ -140,6 +140,22 @@ describe('CenteredModal', () => {});describe('AgentsLibrary', () => {+ it('shows a friendly load error instead of raw fetch failures', async () => {+ const server = createMockAgentUIServer({+ searchAgents: vi.fn(async () => {+ throw new TypeError('Failed to fetch');+ }),+ });+ renderLibrary(<LibraryHarness />, { server });+ fireEvent.click(screen.getByRole('button', { name: 'Open library' }));++ expect(await screen.findByRole('heading', { name: "Couldn't load agents" })).toBeInTheDocument();+ expect(screen.getByText('Check your connection and try again.')).toBeInTheDocument();+ expect(screen.queryByText('Failed to fetch')).not.toBeInTheDocument();+ expect(screen.queryByText('Failed to load agents.')).not.toBeInTheDocument();+ expect(screen.queryByRole('button', { name: 'Retry' })).not.toBeInTheDocument();+ });+it('opens agent details from the row only when the optional server is available', async () => {window.history.replaceState(null, '', '/library?theme=dark&sessionId=stale&view=sessions&s_sts=1&s_ets=2');const server = createMockAgentUIServer({diff --git a/packages/trueforge-ui/test/atoms/environments/EnvironmentsPage.test.tsx b/packages/trueforge-ui/test/atoms/environments/EnvironmentsPage.test.tsxindex d1edc68e8..53f47a818 100644--- a/packages/trueforge-ui/test/atoms/environments/EnvironmentsPage.test.tsx+++ b/packages/trueforge-ui/test/atoms/environments/EnvironmentsPage.test.tsx@@ -108,6 +108,22 @@ describe('EnvironmentsPage', () => {expect(screen.getByText('1 allowed domain')).toBeInTheDocument();});+ it('shows a friendly load error instead of raw fetch failures', async () => {+ renderPage({+ environmentOverrides: {+ listEnvironments: vi.fn(async () => {+ throw new TypeError('Failed to fetch');+ }),+ },+ });++ expect(await screen.findByRole('heading', { name: "Couldn't load environments" })).toBeInTheDocument();+ expect(screen.getByText('Check your connection and try again.')).toBeInTheDocument();+ expect(screen.queryByText('Failed to fetch')).not.toBeInTheDocument();+ expect(screen.queryByText('Failed to load environments')).not.toBeInTheDocument();+ expect(screen.queryByRole('button', { name: 'Retry' })).not.toBeInTheDocument();+ });+it('opens create drawer from New Environment', async () => {renderPage();await waitFor(() => {diff --git a/packages/trueforge-ui/test/atoms/lib/useSearchAgentsList.test.tsx b/packages/trueforge-ui/test/atoms/lib/useSearchAgentsList.test.tsxindex a1e47a18b..4f5b475c0 100644--- a/packages/trueforge-ui/test/atoms/lib/useSearchAgentsList.test.tsx+++ b/packages/trueforge-ui/test/atoms/lib/useSearchAgentsList.test.tsx@@ -218,4 +218,17 @@ describe('useSearchAgentsList', () => {expect(result.current.canNext).toBe(false);expect(result.current.canPrev).toBe(false);});++ it('maps browser network noise to a friendly error', async () => {+ const searchAgents = vi.fn(async () => {+ throw new TypeError('Failed to fetch');+ });+ const server = createMockAgentUIServer({ searchAgents });+ const { result } = renderHook(() => useSearchAgentsList({ enabled: true, query: '', mode: 'paged', limit: 10 }), {+ wrapper: wrapperFor(server),+ });++ await waitFor(() => expect(result.current.error).toBe('Check your connection and try again.'));+ expect(result.current.agents).toEqual([]);+ });});diff --git a/packages/trueforge-ui/test/atoms/schedules/SchedulesPage.test.tsx b/packages/trueforge-ui/test/atoms/schedules/SchedulesPage.test.tsxindex 2b4ed0078..bc1d6f8a2 100644--- a/packages/trueforge-ui/test/atoms/schedules/SchedulesPage.test.tsx+++ b/packages/trueforge-ui/test/atoms/schedules/SchedulesPage.test.tsx@@ -122,6 +122,17 @@ describe('SchedulesPage', () => {expect(searchAgents).not.toHaveBeenCalled();});+ it('shows a friendly load error instead of raw fetch failures', async () => {+ renderPage(sampleSchedules, {}, async () => {+ throw new TypeError('Failed to fetch');+ });++ expect(await screen.findByRole('heading', { name: "Couldn't load schedules" })).toBeInTheDocument();+ expect(screen.getByText('Check your connection and try again.')).toBeInTheDocument();+ expect(screen.queryByText('Failed to fetch')).not.toBeInTheDocument();+ expect(screen.queryByRole('button', { name: 'Retry' })).not.toBeInTheDocument();+ });+it('disables schedule mutations without MANAGE or DELETE', async () => {const { scheduleServer } = renderPage(sampleSchedules, {}, undefined, undefined, {agentId: 'demo-agent',diff --git a/packages/trueforge-ui/test/utils/getErrorMessage.test.ts b/packages/trueforge-ui/test/utils/getErrorMessage.test.tsindex 8ff68c1a1..7bf314e83 100644--- a/packages/trueforge-ui/test/utils/getErrorMessage.test.ts+++ b/packages/trueforge-ui/test/utils/getErrorMessage.test.ts@@ -75,4 +75,25 @@ describe('getErrorMessage', () => {it('reads plain Error.message', () => {expect(getErrorMessage(new Error('boom'), 'fallback')).toBe('boom');});++ it('uses fallback for browser network noise when provided', () => {+ expect(getErrorMessage(new TypeError('Failed to fetch'), 'Check your connection.')).toBe('Check your connection.');+ expect(getErrorMessage(new TypeError('Load failed'), 'Check your connection.')).toBe('Check your connection.');+ expect(+ getErrorMessage(new TypeError('NetworkError when attempting to fetch resource.'), 'Check your connection.'),+ ).toBe('Check your connection.');+ expect(getErrorMessage('Failed to fetch', 'Check your connection.')).toBe('Check your connection.');+ });++ it('keeps browser network noise when no fallback is provided', () => {+ expect(getErrorMessage(new TypeError('Failed to fetch'))).toBe('Failed to fetch');+ });++ it('prefers HTTP body over browser network noise on the Error message', () => {+ const err = Object.assign(new TypeError('Failed to fetch'), {+ statusCode: 503,+ body: { error: { message: 'Service unavailable' } },+ });+ expect(getErrorMessage(err, 'Check your connection.')).toBe('Service unavailable');+ });});