mirror of
https://github.com/NousResearch/hermes-agent.git
synced 2026-11-16 19:36:54 +00:00
222 lines
7.3 KiB
TypeScript
222 lines
7.3 KiB
TypeScript
// Attach to the host's running Hermes backend (multiplex-only, Desktop half).
|
|
//
|
|
// `backend-discovery.ts` owns the pure decision; this module performs the IO
|
|
// ladder around it: read the machine-root ledger, validate a candidate at the
|
|
// boundary that actually matters (HTTP readiness → served session token →
|
|
// WebSocket auth), and hold a host-level gate so two apps starting at once
|
|
// produce one backend instead of two.
|
|
//
|
|
// Every dependency is injected so the ladder runs in a test without Electron.
|
|
|
|
import {
|
|
classifyHostSpawnGate,
|
|
type HostBackendRecord,
|
|
parseSpawnLedger,
|
|
recordBaseUrl,
|
|
SPAWN_LEDGER_FILENAME,
|
|
spawnOrAttach
|
|
} from './backend-discovery'
|
|
|
|
/** A gate held longer than this belongs to a spawner that never finished. */
|
|
export const HOST_SPAWN_GATE_STALE_MS = 60_000
|
|
|
|
export interface AttachedBackend {
|
|
baseUrl: string
|
|
pid: number
|
|
port: number
|
|
token: string
|
|
wsUrl: string
|
|
}
|
|
|
|
export interface HostBackendAttachDeps {
|
|
/** Read the ledger file; return null when it is missing/unreadable. */
|
|
readLedger: (path: string) => string | null
|
|
/** Resolve the token the backend actually serves at `GET /`. */
|
|
resolveServedToken: (baseUrl: string) => Promise<string | null>
|
|
/**
|
|
* Session token the backend published for this record when `GET /` withholds
|
|
* it. Absent readers keep the dashboard-HTML-only handshake.
|
|
*/
|
|
publishedTokenFor?: (record: HostBackendRecord) => string | null
|
|
/** Reject unless the backend answers its readiness probe. */
|
|
waitForReady: (baseUrl: string, token: string) => Promise<unknown>
|
|
/** Reject unless `/api/ws` accepts the token — the leg the renderer uses. */
|
|
probeWebSocket: (wsUrl: string) => Promise<{ ok: boolean; reason?: string }>
|
|
log: (message: string) => void
|
|
}
|
|
|
|
export function spawnLedgerPath(hermesHomeRoot: string, join: (...parts: string[]) => string): string {
|
|
return join(hermesHomeRoot, SPAWN_LEDGER_FILENAME)
|
|
}
|
|
|
|
function wsUrlFor(baseUrl: string, token: string): string {
|
|
return `${baseUrl.replace(/^http/, 'ws')}/api/ws?token=${encodeURIComponent(token)}`
|
|
}
|
|
|
|
function nonemptyToken(value: string | null | undefined): string | null {
|
|
const token = String(value ?? '').trim()
|
|
|
|
return token || null
|
|
}
|
|
|
|
/**
|
|
* Validate one candidate all the way to a usable connection, or return null.
|
|
*
|
|
* A failed rung is not an error: it means this record is not the backend we can
|
|
* use, and the caller falls through to the next rung (another record, then
|
|
* spawning). Only a *validated* candidate is ever returned.
|
|
*/
|
|
async function validate(record: HostBackendRecord, deps: HostBackendAttachDeps): Promise<AttachedBackend | null> {
|
|
const baseUrl = recordBaseUrl(record)
|
|
const servedToken = nonemptyToken(await deps.resolveServedToken(baseUrl).catch(() => null))
|
|
let publishedToken: string | null = null
|
|
|
|
if (!servedToken && deps.publishedTokenFor) {
|
|
try {
|
|
publishedToken = nonemptyToken(deps.publishedTokenFor(record))
|
|
} catch {
|
|
publishedToken = null
|
|
}
|
|
}
|
|
|
|
const token = servedToken || publishedToken
|
|
|
|
if (!token) {
|
|
deps.log(`[attach] ${baseUrl} (pid ${record.pid}) did not publish a session token; not attaching`)
|
|
|
|
return null
|
|
}
|
|
|
|
try {
|
|
await deps.waitForReady(baseUrl, token)
|
|
} catch (error) {
|
|
deps.log(`[attach] ${baseUrl} (pid ${record.pid}) is not ready: ${(error as Error).message}`)
|
|
|
|
return null
|
|
}
|
|
|
|
const wsUrl = wsUrlFor(baseUrl, token)
|
|
const probe = await deps.probeWebSocket(wsUrl).catch(error => ({ ok: false, reason: error.message }))
|
|
|
|
if (!probe.ok) {
|
|
deps.log(`[attach] ${baseUrl} (pid ${record.pid}) rejected the session token on /api/ws: ${probe.reason}`)
|
|
|
|
return null
|
|
}
|
|
|
|
return { baseUrl, pid: record.pid, port: record.port, token, wsUrl }
|
|
}
|
|
|
|
/**
|
|
* Discover and attach to the host's running backend.
|
|
*
|
|
* Returns null when the host has none (or the escape hatch is set), which is
|
|
* the caller's signal to spawn exactly one.
|
|
*/
|
|
export async function attachToHostBackend(
|
|
{ isolated, ledgerPath }: { isolated: boolean; ledgerPath: string },
|
|
deps: HostBackendAttachDeps
|
|
): Promise<AttachedBackend | null> {
|
|
const records = parseSpawnLedger(deps.readLedger(ledgerPath))
|
|
const decision = spawnOrAttach({ isolated, records })
|
|
|
|
if (decision.action === 'spawn') {
|
|
if (decision.reason === 'isolated') {
|
|
deps.log('[attach] HERMES_DESKTOP_ISOLATED_BACKEND is set; spawning a dedicated backend')
|
|
}
|
|
|
|
return null
|
|
}
|
|
|
|
// Newest first, then the rest: a stale record must not cost us a live one.
|
|
const ordered = [decision.record, ...records.filter(candidate => candidate !== decision.record)]
|
|
|
|
for (const record of ordered) {
|
|
const attached = await validate(record, deps)
|
|
|
|
if (attached) {
|
|
deps.log(
|
|
`[attach] attached to the running Hermes backend on ${attached.baseUrl} ` +
|
|
`(pid ${attached.pid}, registered by profile "${record.profile || 'default'}"); spawning nothing`
|
|
)
|
|
|
|
return attached
|
|
}
|
|
}
|
|
|
|
return null
|
|
}
|
|
|
|
export interface HostSpawnGateDeps {
|
|
now: () => number
|
|
/** Read the gate record; null when absent, unreadable, or its owner is gone. */
|
|
read: () => { ownerAlive: boolean; startedAt: number } | null
|
|
/** Atomically claim the gate; null means another process won the race. */
|
|
take: () => (() => void) | null
|
|
sleep: (ms: number) => Promise<void>
|
|
}
|
|
|
|
export interface SpawnReservation {
|
|
release: () => void
|
|
}
|
|
|
|
/**
|
|
* Attach to the host backend, or come back holding the host spawn gate.
|
|
*
|
|
* Two apps launching at once both find an empty ledger; without a gate they
|
|
* each spawn a backend and the host ends up with two. The loser waits for the
|
|
* winner's backend to register and attaches to it instead. The wait is bounded
|
|
* and a gate whose owner died is taken over, so a crashed spawner cannot wedge
|
|
* every later launch — worst case we spawn, which is today's behaviour.
|
|
*
|
|
* The caller MUST release the reservation once its spawn is ready or has
|
|
* failed; the ledger entry only appears after the new backend binds.
|
|
*/
|
|
export async function attachOrReserveSpawn(
|
|
options: { isolated: boolean; ledgerPath: string },
|
|
deps: HostBackendAttachDeps,
|
|
gate: HostSpawnGateDeps,
|
|
{ pollMs = 500, waitBudgetMs = HOST_SPAWN_GATE_STALE_MS }: { pollMs?: number; waitBudgetMs?: number } = {}
|
|
): Promise<{ attached: AttachedBackend } | { reservation: SpawnReservation }> {
|
|
const attached = await attachToHostBackend(options, deps)
|
|
|
|
if (attached) {
|
|
return { attached }
|
|
}
|
|
|
|
if (options.isolated) {
|
|
return { reservation: { release: () => {} } }
|
|
}
|
|
|
|
const deadline = gate.now() + waitBudgetMs
|
|
|
|
while (gate.now() < deadline) {
|
|
const gateState = gate.read()
|
|
|
|
if (
|
|
classifyHostSpawnGate(gateState, {
|
|
now: gate.now(),
|
|
staleAfterMs: HOST_SPAWN_GATE_STALE_MS
|
|
}) === 'take'
|
|
) {
|
|
const release = gate.take()
|
|
|
|
if (release) {
|
|
return { reservation: { release } }
|
|
}
|
|
}
|
|
|
|
deps.log('[attach] another app is starting the host backend; waiting for it instead of spawning a second one')
|
|
await gate.sleep(pollMs)
|
|
|
|
const late = await attachToHostBackend(options, deps)
|
|
|
|
if (late) {
|
|
return { attached: late }
|
|
}
|
|
}
|
|
|
|
// Preserve the bounded startup fallback when a stale/unreadable gate cannot
|
|
// be claimed. The no-op reservation owns no file and therefore removes none.
|
|
return { reservation: { release: gate.take() ?? (() => {}) } }
|
|
}
|