Skip to content

The agent that grows with you

4.1 KB
Raw Blame
import { JSON_RPC_METHOD_NOT_FOUND } from '@hermes/shared'

/** True when a JSON-RPC call failed because the backend predates the method.
 *  The gateway answers -32601 (`tui_gateway/server.py::dispatch`) and the
 *  shared client keeps that code on the error; the message match is only for
 *  errors that lost their frame across the IPC bridge or a wrapped rethrow. */
export function isMissingRpcMethod(error: unknown): boolean {
  const code = error && typeof error === 'object' ? (error as { code?: unknown }).code : undefined

  if (typeof code === 'number') {
    return code === JSON_RPC_METHOD_NOT_FOUND
  }

  const message = error instanceof Error ? error.message : String(error)

  return /method not found|-32601|unknown method|no such method/i.test(message)
}

export function isOutOfSyncRpcParams(error: Error | string): boolean {
  return /out of sync \(different versions\)/i.test(error.toString())
}

/** REST twin of isMissingRpcMethod: the route does not exist on this backend.
 *  Matches the backend catch-all ('404: {"detail":"No such API endpoint: …}'),
 *  FastAPI's bare 404 on headless serve — directly, or wrapped as "Error
 *  invoking remote method 'hermes:api': Error: 404: …" through the IPC bridge
 *  — and the Electron JSON-guard ("endpoint is likely missing"). Transient
 *  failures (timeouts, 5xx, connection refused) must NOT match: they are
 *  retryable, not a capability verdict. Only sound for calls where a 404 can
 *  mean nothing else — a route with path params can 404 on a bad id. */
export function isMissingRestEndpoint(error: unknown): boolean {
  const message = error instanceof Error ? error.message : String(error)

  return (
    /no such api endpoint/i.test(message) ||
    /endpoint is likely missing/i.test(message) ||
    /(?:^\s*|error:\s*)404\b/i.test(message)
  )
}

/** Narrow twin of isMissingRestEndpoint for routes with path params: only a
 *  backend catch-all verdict (or the Electron HTML guard) proves the ROUTE is
 *  absent; a handler's own 404 (unknown session/profile) never matches. Two
 *  catch-alls exist: `hermes dashboard` answers unmatched `/api/*` with
 *  "No such API endpoint", and headless `hermes serve` (what Desktop's SSH
 *  remotes launch) answers every unmatched GET with its fixed "web UI disabled"
 *  body. A bare `{"detail":"Not Found"}` is not a route verdict. */
export function isUnroutedRestPath(error: unknown): boolean {
  const message = error instanceof Error ? error.message : String(error)

  return (
    /no such api endpoint|endpoint is likely missing/i.test(message) ||
    /(?:^\s*|error:\s*)404:.*headless backend \(hermes serve\): web ui disabled/i.test(message)
  )
}

/** True when the backend refused a request because it owns the profile and the
 *  call is offline-only maintenance (`web_server_sessions.py::_with_session_maintenance`
 *  → HTTP 409 "Exclusive maintenance refused"). The refusal is the steady state
 *  for as long as that gateway runs, so callers treat it as terminal, not
 *  transient. Only the anchored `409: {...}` status marker — bare, or wrapped as
 *  "Error invoking remote method 'hermes:api': Error: 409: …" by the IPC bridge —
 *  counts; a `409` token inside a message body ("Query returned 409 rows", "4096")
 *  never does. */
export function isOfflineMaintenance(error: unknown): boolean {
  const message = error instanceof Error ? error.message : String(error)

  return /(?:^\s*|error:\s*)409:/i.test(message)
}

/** True when a prompt response raced a backend-side timeout / completion. */
export function isMissingPendingPromptRequest(error: unknown, key: string): boolean {
  const message = error instanceof Error ? error.message : String(error)

  return message.toLowerCase().includes(`no pending ${key.toLowerCase()} request`)
}

/** True when a pre-deferral backend refused a mid-turn model switch (4009).
 *  Current gateways park the pick and answer `scope: "pending"` instead. */
export function isBusySessionModelSwitch(error: unknown): boolean {
  const message = error instanceof Error ? error.message : String(error)

  return /session busy/i.test(message) && /switching models/i.test(message)
}