Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

fix: handle proxied request errors in hook server and improve desktop error messaging

0xken15db7744ece937
diff --git a/cli/src/cli.ts b/cli/src/cli.ts
index 37ad71cdb..dcdf41e76 100644
--- a/cli/src/cli.ts
+++ b/cli/src/cli.ts
@@ -242,6 +242,11 @@ const HERMES_DB = join(env.HERMES_HOME, 'state.db')
// Devin likewise keeps all history in one SQLite store (WAL) — polled per session by DevinReader.
const DEVIN_DB = join(env.DEVIN_HOME, 'sessions.db')
+// How long a control-plane call the daemon proxies for a local client (`/api/machines`, `/api/auth/me`)
+// may wait on the backend. Under the desktop app's own 30s receive timeout, so a slow backend is
+// reported by the daemon in words rather than by the app as a timeout.
+const PROXY_BACKEND_TIMEOUT_MS = 20_000
+
// How long `harness start` waits for the background daemon to report "[backend] connected" before
// declaring an error. A healthy backend connects in well under this; a timeout ⇒ unreachable.
const CONNECT_WAIT_MS = 10_000
@@ -2466,18 +2471,50 @@ async function runForeground(session: AuthSession): Promise<void> {
* (e.g. the desktop app) never needs a bearer token of its own, loopback trust does the
* authenticating. Forwards backend's response status/body verbatim, success or error alike, so a
* local client's model layer needs zero special-casing versus talking to backend directly. */
+ //
+ // A backend that cannot be reached, or does not answer in time, is reported in the SAME shape
+ // (`{success:false, error:{code,message}}`, 502/504) rather than thrown: the hook server runs each
+ // request as a void-discarded async, so a throw here was an unhandledRejection and a local request
+ // that NEVER got a response — the desktop app then sat on its 30s receive timeout and printed a
+ // DioException where "the backend is down" belonged. Same for a backend that accepts the request
+ // and hangs (a Redis presence lookup, say): `fetch` waits forever by default, and the app's
+ // timeout fired first. The bound is shorter than that timeout on purpose, so the daemon is the one
+ // that answers, with a sentence.
async function proxyBackend(method: string, path: string, body?: unknown): Promise<{ status: number; body: Record<string, unknown> }> {
- const accessToken = await auth.accessToken()
+ const failure = (status: number, code: string, message: string): { status: number; body: Record<string, unknown> } =>
+ ({ status, body: { success: false, error: { code, message } } })
+ let accessToken: string
+ try {
+ accessToken = await auth.accessToken()
+ } catch (err) {
+ // No session, or one the SSO service will never renew, is the caller's 401 — the answer the
+ // backend itself would give — not a backend fault; a refresh the service could not serve right
+ // now is. Telling them apart is what lets a local client say "sign in again" only when true.
+ const signedOut = err instanceof AuthSessionError && err.code !== 'UNAVAILABLE'
+ return failure(signedOut ? 401 : 502, signedOut ? 'NOT_SIGNED_IN' : 'AUTH_UNAVAILABLE', err instanceof Error ? err.message : String(err))
+ }
const latest = readAuthSession()
- const res = await fetch(`${backendHttpBase()}${path}`, {
- method,
- headers: {
- authorization: `Bearer ${accessToken}`,
- 'x-autonomous-env': latest?.autonomousEnv ?? session.autonomousEnv,
- ...(body !== undefined ? { 'content-type': 'application/json' } : {}),
- },
- ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
- })
+ let res: Response
+ try {
+ res = await fetch(`${backendHttpBase()}${path}`, {
+ method,
+ headers: {
+ authorization: `Bearer ${accessToken}`,
+ 'x-autonomous-env': latest?.autonomousEnv ?? session.autonomousEnv,
+ ...(body !== undefined ? { 'content-type': 'application/json' } : {}),
+ },
+ ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+ signal: AbortSignal.timeout(PROXY_BACKEND_TIMEOUT_MS),
+ })
+ } catch (err) {
+ const e = err as Error & { cause?: { message?: string } }
+ if (e.name === 'TimeoutError' || e.name === 'AbortError') {
+ return failure(504, 'BACKEND_TIMEOUT', `The Harness backend did not answer ${method} ${path} within ${PROXY_BACKEND_TIMEOUT_MS / 1000}s. Try again in a moment.`)
+ }
+ // undici wraps the socket error as `TypeError: fetch failed` with the real one in `cause`.
+ const why = e.cause?.message ?? e.message
+ return failure(502, 'BACKEND_UNREACHABLE', `Could not reach the Harness backend (${why}). Check the connection and try again.`)
+ }
const json = await res.json().catch(() => ({})) as Record<string, unknown>
return { status: res.status, body: json }
}
diff --git a/cli/src/hookServer.spec.ts b/cli/src/hookServer.spec.ts
index 4c15e3fd1..fdfdcea95 100644
--- a/cli/src/hookServer.spec.ts
+++ b/cli/src/hookServer.spec.ts
@@ -137,6 +137,24 @@ describe('process-owned hook server', () => {
expect(await response.json()).toEqual({ error: 'UNBOUND_HOOK' })
expect(handler).not.toHaveBeenCalled()
})
+
+ it('answers a proxied control-plane read whose handler throws, instead of hanging it', async () => {
+ // The handler is a void-discarded async: a throw used to be an unhandledRejection and a request
+ // with no response, which the desktop app reported 30s later as its own receive timeout.
+ const { base } = await start({ onMachinesList: async () => { throw new TypeError('fetch failed') } })
+ const response = await fetch(`${base}/api/machines`)
+ expect(response.status).toBe(502)
+ expect(await response.json()).toEqual({ success: false, error: { code: 'PROXY_FAILED', message: 'fetch failed' } })
+ })
+
+ it('forwards a proxied answer verbatim, status and body alike', async () => {
+ const { base } = await start({
+ onAuthMe: async () => ({ status: 504, body: { success: false, error: { code: 'BACKEND_TIMEOUT', message: 'slow' } } }),
+ })
+ const response = await fetch(`${base}/api/auth/me`)
+ expect(response.status).toBe(504)
+ expect(await response.json()).toEqual({ success: false, error: { code: 'BACKEND_TIMEOUT', message: 'slow' } })
+ })
})
describe('chooseHookAgent', () => {
diff --git a/cli/src/hookServer.ts b/cli/src/hookServer.ts
index e0a695d03..838bbc038 100644
--- a/cli/src/hookServer.ts
+++ b/cli/src/hookServer.ts
@@ -332,6 +332,16 @@ export function startHookServer(
res.writeHead(code, { 'Content-Type': 'application/json' })
res.end(JSON.stringify(body))
}
+ // A handler that throws must still answer: this whole function is a void-discarded async, so
+ // a throw here is an unhandledRejection and a request that hangs until the caller gives up —
+ // which, for the desktop app, is a 30s timeout that names Dio instead of the fault.
+ const proxied = async (call: () => Promise<{ status: number; body: unknown }>): Promise<void> => {
+ try { const out = await call(); json(out.status, out.body) }
+ catch (e) {
+ console.error(`[hook] ${req.method} ${url} failed:`, e instanceof Error ? e.message : e)
+ json(502, { success: false, error: { code: 'PROXY_FAILED', message: e instanceof Error ? e.message : 'INTERNAL' } })
+ }
+ }
// CSRF guard for mutating endpoints: a cross-origin browser page cannot set a custom header on a
// simple request (it forces a CORS preflight we never allow), so only our same-origin dashboard
// (and the CLI, which sends it too) can trigger actions. A local process could still call it —
@@ -586,29 +596,34 @@ export function startHookServer(
// holds a bearer token itself — loopback trust does the authenticating. Reads are ungated (same
// tier as /api/status); the rename/delete mutations are CSRF-guarded like every other local write.
if (req.method === 'GET' && url === '/api/machines') {
- if (!handlers.onMachinesList) { json(503, { error: 'UNAVAILABLE' }); return }
- const out = await handlers.onMachinesList(); json(out.status, out.body); return
+ const list = handlers.onMachinesList
+ if (!list) { json(503, { error: 'UNAVAILABLE' }); return }
+ await proxied(list); return
}
if (req.method === 'GET' && url === '/api/auth/me') {
- if (!handlers.onAuthMe) { json(503, { error: 'UNAVAILABLE' }); return }
- const out = await handlers.onAuthMe(); json(out.status, out.body); return
+ const me = handlers.onAuthMe
+ if (!me) { json(503, { error: 'UNAVAILABLE' }); return }
+ await proxied(me); return
}
if (req.method === 'PATCH' && url.startsWith('/api/machines/')) {
if (!localOk) { json(403, { error: 'FORBIDDEN' }); return }
- if (!handlers.onMachineRename) { json(503, { error: 'UNAVAILABLE' }); return }
+ const rename = handlers.onMachineRename
+ if (!rename) { json(503, { error: 'UNAVAILABLE' }); return }
const machineId = decodeURIComponent(url.slice('/api/machines/'.length))
if (!machineId) { json(400, { error: 'MISSING_MACHINE_ID' }); return }
let body: { name?: string }
try { body = JSON.parse(await readBody(req)) as { name?: string } } catch { json(400, { error: 'bad json' }); return }
- if (!body.name) { json(400, { error: 'MISSING_NAME' }); return }
- const out = await handlers.onMachineRename(machineId, body.name); json(out.status, out.body); return
+ const name = body.name
+ if (!name) { json(400, { error: 'MISSING_NAME' }); return }
+ await proxied(() => rename(machineId, name)); return
}
if (req.method === 'DELETE' && url.startsWith('/api/machines/')) {
if (!localOk) { json(403, { error: 'FORBIDDEN' }); return }
- if (!handlers.onMachineDelete) { json(503, { error: 'UNAVAILABLE' }); return }
+ const remove = handlers.onMachineDelete
+ if (!remove) { json(503, { error: 'UNAVAILABLE' }); return }
const machineId = decodeURIComponent(url.slice('/api/machines/'.length))
if (!machineId) { json(400, { error: 'MISSING_MACHINE_ID' }); return }
- const out = await handlers.onMachineDelete(machineId); json(out.status, out.body); return
+ await proxied(() => remove(machineId)); return
}
// `harness pairings` — list paired browsers.
diff --git a/desktop/lib/api/api_client.dart b/desktop/lib/api/api_client.dart
index 6178fc0c6..3ecd444c0 100644
--- a/desktop/lib/api/api_client.dart
+++ b/desktop/lib/api/api_client.dart
@@ -92,3 +92,36 @@ class ApiException implements Exception {
bool isUnauthorizedError(Object error) =>
error is DioException && error.response?.statusCode == 401 ||
error is ApiException && error.status == 401;
+
+/// The sentence a failed local-CLI call earns on an error strip. A raw
+/// `DioException` is a paragraph about `RequestOptions.receiveTimeout` — true,
+/// and useless to the person reading it: what they need is which leg failed.
+/// The daemon not listening, the daemon not answering (it proxies to the
+/// backend, so that is nearly always the backend being slow), or the backend
+/// answering with a sentence of its own, which the daemon forwards verbatim.
+String describeApiError(Object error) {
+ if (error is ApiException) return error.message;
+ if (error is DioException) {
+ switch (error.type) {
+ case DioExceptionType.connectionError:
+ return 'the local Harness service is not answering on its port. '
+ 'It usually restarts on its own; retry in a moment.';
+ case DioExceptionType.connectionTimeout:
+ case DioExceptionType.sendTimeout:
+ case DioExceptionType.receiveTimeout:
+ final limit = error.requestOptions.receiveTimeout?.inSeconds;
+ return 'the local Harness service did not answer'
+ '${limit == null ? '' : ' within ${limit}s'} — the Harness '
+ 'backend is probably slow right now. Retry in a moment.';
+ case DioExceptionType.badResponse:
+ return 'the local Harness service answered '
+ '${error.response?.statusCode ?? 'with an error'}.';
+ case DioExceptionType.badCertificate:
+ case DioExceptionType.cancel:
+ case DioExceptionType.transformTimeout:
+ case DioExceptionType.unknown:
+ return error.message ?? error.error?.toString() ?? 'request failed';
+ }
+ }
+ return '$error';
+}
diff --git a/desktop/lib/state/app_state.dart b/desktop/lib/state/app_state.dart
index 996a1b6c8..fa49500be 100644
--- a/desktop/lib/state/app_state.dart
+++ b/desktop/lib/state/app_state.dart
@@ -1143,7 +1143,8 @@ class AppNotifier extends ChangeNotifier {
? send(machineId, agentId)
: _pool?[machineId]?.sendTerminalFrame('app_focus', {
'agentId': agentId,
- if (_deviceFocusRevision != null) 'focusRevision': _deviceFocusRevision,
+ if (_deviceFocusRevision != null)
+ 'focusRevision': _deviceFocusRevision,
});
if (pending != null) unawaited(pending.catchError((_) => false));
}
@@ -1788,7 +1789,7 @@ class AppNotifier extends ChangeNotifier {
await refreshMachines();
} catch (error) {
if (!_authWorkCurrent(revision)) return;
- _lastError = 'Could not load machines: $error';
+ _lastError = 'Could not load machines: ${describeApiError(error)}';
_lastErrorRetryable = true;
}
if (_authWorkCurrent(revision)) notifyListeners();
@@ -2714,7 +2715,7 @@ class AppNotifier extends ChangeNotifier {
_lastError = null;
} catch (error) {
if (!_authWorkCurrent(revision)) return;
- _lastError = 'Could not load machines: $error';
+ _lastError = 'Could not load machines: ${describeApiError(error)}';
_lastErrorRetryable = true;
notifyListeners();
return;
diff --git a/desktop/test/api_client_test.dart b/desktop/test/api_client_test.dart
index c9d79b7d0..349a5233e 100644
--- a/desktop/test/api_client_test.dart
+++ b/desktop/test/api_client_test.dart
@@ -2,6 +2,7 @@ import 'dart:async';
import 'dart:convert';
import 'dart:io';
+import 'package:dio/dio.dart';
import 'package:harness/api/api_client.dart';
import 'package:harness/auth/auth_session.dart';
import 'package:harness/core/config.dart';
@@ -55,4 +56,49 @@ void main() {
await server.close(force: true);
}
});
+
+ group('describeApiError', () {
+ final options = RequestOptions(
+ path: '/api/machines',
+ receiveTimeout: const Duration(seconds: 30),
+ );
+ test('names the leg that failed instead of quoting Dio', () {
+ expect(
+ describeApiError(
+ DioException(
+ requestOptions: options,
+ type: DioExceptionType.receiveTimeout,
+ message:
+ 'The request took longer than 0:00:30.000000 to receive data.',
+ ),
+ ),
+ 'the local Harness service did not answer within 30s — the Harness '
+ 'backend is probably slow right now. Retry in a moment.',
+ );
+ expect(
+ describeApiError(
+ DioException(
+ requestOptions: options,
+ type: DioExceptionType.connectionError,
+ ),
+ ),
+ startsWith('the local Harness service is not answering on its port.'),
+ );
+ });
+ test(
+ 'passes the backend sentence the daemon forwarded straight through',
+ () {
+ expect(
+ describeApiError(
+ ApiException(
+ 'The Harness backend did not answer GET /api/machines within 20s. Try again in a moment.',
+ status: 504,
+ ),
+ ),
+ 'The Harness backend did not answer GET /api/machines within 20s. Try again in a moment.',
+ );
+ expect(describeApiError(StateError('odd')), 'Bad state: odd');
+ },
+ );
+ });
}