Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* Health / occupancy probes for `gbrain mcp expose`, peeled from
* `mcp-expose.ts`: one bounded `tryFetch` that never throws, the `/health`
* bar (`probeHealth`), the "does ANYTHING listen" bar (`probeOccupied`), the
* wall-clock poller (`pollHealth`) and the name-resolution verdict behind the
* `verify.tailnet` warn.
*
* Why a resolver call and not just the fetch error: Bun's `fetch` rejects an
* unresolvable host with the SAME error as a refused connection
* (`Unable to connect. Is the computer able to access the url?`, code
* `ConnectionRefused`), so a message match alone never fires in production.
* After a rejection the URL's hostname is handed to `deps.lookup` (default
* `dns.promises.lookup`) and ITS error decides; the message regex stays a
* secondary hint for runtimes that do spell the cause out. IP literals and
* `localhost` never involve the resolver and are skipped.
*
* Every side effect is injected through `ProbeDeps` (a narrow slice of
* `mcp-expose.ts`'s resolved deps) so tests run with a fake fetch, a fake
* TCP probe and a fake resolver.
*/
import { lookup } from 'node:dns/promises';
import { createConnection, isIP } from 'node:net';
import { TAILSCALE_ACCEPT_DNS_COMMAND } from '../core/tailscale.ts';
import { liveStatusMarkerFor } from '../core/serve-http-status-marker.ts';
export type ProbeFetch = (url: string, init?: { signal?: AbortSignal; redirect?: 'manual' | 'error' | 'follow' }) => Promise<{ ok: boolean; status: number }>;
/** Bounded TCP connect to `host:port` (true on connect, false on refusal / timeout). */
export type TcpProbe = (host: string, port: number, timeoutMs: number) => Promise<boolean>;
/** Resolves when `hostname` resolves on THIS host; rejects with the resolver's error (`code` `ENOTFOUND`, `EAI_AGAIN`, …) otherwise. */
export type HostLookup = (hostname: string) => Promise<void>;
export interface ProbeDeps {
fetch: ProbeFetch;
tcpProbe: TcpProbe;
lookup: HostLookup;
now: () => Date;
sleep: (ms: number) => Promise<void>;
healthIntervalMs: number;
}
/** A fetch rejection whose MESSAGE already names a resolution failure (a secondary hint; Bun's does not). */
const NAME_RESOLUTION_RE = /ENOTFOUND|getaddrinfo|EAI_AGAIN|failed to resolve|Unable to connect.*resolve/i;
/** Resolver error codes that mean "this host cannot resolve the name" (a resolver outage — `EAI_AGAIN` — counts: the verdict is about THIS host). */
const UNRESOLVED_LOOKUP_CODES: ReadonlySet<string> = new Set(['ENOTFOUND', 'EAI_AGAIN', 'EAI_NONAME', 'EAI_NODATA', 'DNS_ENOTFOUND']);
const UNRESOLVED_LOOKUP_RE = /ENOTFOUND|EAI_AGAIN|EAI_NONAME|EAI_NODATA|DNS_ENOTFOUND/;
/** Default `tcpProbe`: one connect attempt, the socket destroyed on every outcome. Any listener — HTTP or not — accepts the connect. */
export function defaultTcpProbe(host: string, port: number, timeoutMs: number): Promise<boolean> {
return new Promise(resolve => {
let settled = false;
const sock = createConnection({ host, port });
const done = (v: boolean) => { if (settled) return; settled = true; sock.destroy(); resolve(v); };
sock.setTimeout(Math.max(1, timeoutMs), () => done(false));
sock.once('connect', () => done(true));
sock.once('error', () => done(false));
});
}
/** Default `lookup`: RFC 6761 `.invalid` negatives, otherwise the system resolver (`getaddrinfo`). */
export const defaultLookup: HostLookup = async (hostname) => {
if (/(^|\.)invalid\.?$/i.test(hostname)) {
throw Object.assign(new Error('getaddrinfo ENOTFOUND'), { code: 'ENOTFOUND' });
}
await lookup(hostname);
};
export interface FetchOutcome {
/** The response (whatever its status), or null when the fetch rejected (connection refused / timeout / unresolved name). */
res: { ok: boolean } | null;
/** The rejection was a name-resolution failure: this host cannot resolve the name, which says nothing about the server. */
unresolved: boolean;
}
function errorMessage(error: unknown): string {
return error instanceof Error ? error.message : String(error);
}
/** A rejection from `deps.lookup` that means the name does not resolve here (by `code`, else by message token). */
export function isUnresolvedLookupError(error: unknown): boolean {
const code = (error as { code?: unknown } | null)?.code;
if (typeof code === 'string' && UNRESOLVED_LOOKUP_CODES.has(code)) return true;
return UNRESOLVED_LOOKUP_RE.test(errorMessage(error));
}
/**
* Whether a fetch REJECTION for `url` means this host cannot resolve the
* name. The resolver is asked directly (bounded by `timeoutMs`; a lookup that
* does not answer in time proves nothing and falls through), skipped for IP
* literals and `localhost`; the fetch message is the secondary hint.
*/
async function nameUnresolved(d: ProbeDeps, url: string, error: unknown, timeoutMs: number): Promise<boolean> {
let host = '';
try { host = new URL(url).hostname.replace(/^\[|\]$/g, ''); } catch { host = ''; }
if (host && host.toLowerCase() !== 'localhost' && isIP(host) === 0) {
let timer: ReturnType<typeof setTimeout> | undefined;
const deadline = new Promise<void>(resolve => { timer = setTimeout(resolve, Math.max(1, timeoutMs)); });
try {
await Promise.race([d.lookup(host), deadline]);
} catch (lookupError) {
if (isUnresolvedLookupError(lookupError)) return true;
} finally {
if (timer) clearTimeout(timer);
}
}
return NAME_RESOLUTION_RE.test(errorMessage(error));
}
/** One bounded fetch, never throws. */
export async function tryFetch(d: ProbeDeps, url: string, timeoutMs: number): Promise<FetchOutcome> {
// The resolver check after a rejection spends only what the fetch left of
// the same budget, so one attempt never exceeds `timeoutMs` even when a
// timed-out fetch is followed by a stalled resolver.
const started = Date.now();
try {
return { res: await d.fetch(url, { signal: AbortSignal.timeout(timeoutMs), redirect: 'manual' }), unresolved: false };
} catch (error) {
const remaining = Math.max(1, timeoutMs - (Date.now() - started));
return { res: null, unresolved: await nameUnresolved(d, url, error, remaining) };
}
}
/** Health: the fetch resolved AND answered 2xx (`res.ok`). Used by `verify.*` and `--status`. */
export async function probeHealth(d: ProbeDeps, url: string, timeoutMs = 1_500): Promise<boolean> {
return (await tryFetch(d, url, timeoutMs)).res?.ok === true;
}
/**
* Occupancy: does ANYTHING listen on the port? True when a TCP connect to
* `127.0.0.1:<port>` is accepted OR the fetch resolves with any status (2xx,
* 404, 500 …); false only when both are refused / time out. A foreign server
* that 404s `/health`, or one that does not speak HTTP at all, still owns the
* port, so the foreign-listener guard and the `--no-service` "does something
* listen" logic use this, never `probeHealth`.
*/
export async function probeOccupied(d: ProbeDeps, port: number, url: string, timeoutMs = 1_500): Promise<boolean> {
const [tcp, http] = await Promise.all([
d.tcpProbe('127.0.0.1', port, timeoutMs).catch(() => false),
tryFetch(d, url, timeoutMs),
]);
return tcp || http.res !== null;
}
/**
* Poll until `budgetMs` of wall-clock time (from `d.now()`) has elapsed; each
* probe's timeout is sized to `min(1500, remaining)` so the last attempt never
* overruns the budget. Always probes at least once. The attempt cap is a
* backstop for a clock that does not advance (tests inject a frozen `now`).
* `unresolved` carries the LAST probe's name-resolution verdict so the caller
* can tell "this host cannot resolve the name" from "still pending".
*/
export async function pollHealth(d: ProbeDeps, url: string, budgetMs: number): Promise<{ ok: boolean; unresolved: boolean }> {
const deadline = d.now().getTime() + Math.max(0, budgetMs);
const maxAttempts = Math.max(1, Math.ceil(budgetMs / Math.max(1, d.healthIntervalMs)));
let unresolved = false;
for (let attempt = 0; attempt < maxAttempts; attempt++) {
const remaining = deadline - d.now().getTime();
if (attempt > 0 && remaining <= 0) break;
const probe = await tryFetch(d, url, Math.max(1, Math.min(1_500, remaining)));
if (probe.res?.ok === true) return { ok: true, unresolved: false };
unresolved = probe.unresolved;
const left = deadline - d.now().getTime();
if (left <= 0) break;
await d.sleep(Math.min(d.healthIntervalMs, left));
}
return { ok: false, unresolved };
}
/** `verify.tailnet` / `--status` detail when this host cannot resolve the MagicDNS name — a warn, never `pending`. */
export function unresolvedDetail(dnsName: string): string {
return `this host cannot resolve ${dnsName} (MagicDNS may be off here: \`${TAILSCALE_ACCEPT_DNS_COMMAND}\`); devices that do resolve it may already reach the server`;
}
/**
* `verify.local` detail when the server on `port` runs in status-only mode
* (its `/health` answers 503): the reason from its marker on this host, so
* the check reads "status-only" with the cause instead of a timeout.
*/
export function statusOnlyHealthDetail(port: number): string | null {
const m = liveStatusMarkerFor(port);
return m ? `status-only (${m.reason}): the server runs but cannot open its brain; \`gbrain doctor --only harness_wiring\` names the fix` : null;
}