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.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
import { PRODUCT_FEEDBACK } from './lib/productUsageContract.js'
import { appProductUsageReport, APP_USAGE_VOCABULARY, APP_USAGE_VOCABULARY_HEADER } from './lib/appProductUsageReport.js'
/**
* Tiny localhost HTTP server for the Claude Code hook callbacks. `hook/notify.mjs` POSTs here on
* SessionStart/SessionEnd (127.0.0.1:<PORT>). This replaces the old Fastify routes — the browser
* UI is gone; only these two endpoints remain local.
*/
import { createHash, randomUUID } from 'node:crypto'
import { join } from 'node:path'
import http from 'node:http'
import type { AddressInfo } from 'node:net'
import { admitHook, hooksFor } from './engines/hooks.js'
import { HERMES_HOMES, HERMES_SOURCE } from './engines/hermes/contract.js'
import { readStorePool } from './engines/kit/storePool.js'
import { isInteractiveSource } from './engines/kit/storeSource.js'
import { IdentityReadUnavailable } from './engines/kit/identityScan.js'
import { createPendingAdmissions, type AdmissionDecision } from './core/engines/pendingAdmission.js'
import { paneReadIdentity } from './core/transcripts/readIdentity.js'
import { processIdentityKey } from './lib/terminalRuntime.js'
import { isRecentlyDeleted } from './lib/deletedSessions.js'
import { registry, type RegisterInput, type RegisteredSession } from './lib/registry.js'
import { sid } from './lib/log.js'
import { VERSION } from './version.js'
import { env } from './config/env.js'
import { hookCredentialMatches, loadOrCreateHookCredential, loadOrCreateHookToken } from './lib/hookAuth.js'
import { peerIsThisAccount, type PeerAccount } from './lib/peerAccount.js'
import { LOCAL_CREDENTIAL_REQUIRED, localCredentialMatches } from './lib/localCredential.js'
import { routeStoreRequest, type StoreHandler } from './lib/storeProxy.js'
import type { HookTerminalHint } from './lib/terminalTypes.js'
import { ENGINES, type AgentEngine } from './engines/types.js'
import { isLoopbackRequest, loopbackHosts } from './lib/loopbackRequest.js'
import { isTrustedLocal, listenLocalSocket, type LocalSocketServer } from './lib/localSocket.js'
import { PTY_HOST_INSTANCE } from './lib/ptyHost/instance.js'
/**
* Which agent does a hook belong to, given the two grades of evidence?
*
* Caller ancestry — the hook's process descends from the engine we registered — is the strong one and
* always wins. It is not always available: Cursor posts its hooks from outside the pane's process tree,
* so requiring ancestry rejected every hook that engine ever sent and no session bound at all.
*
* Only Cursor may use the weaker runtime evidence: the hook named a pane carrying exactly one Cursor
* agent, and the caller already proved it can read the 0600 hook credential. Other engines must match
* ancestry. A delayed hook from an exited Codex process can name a pane now running a NEW Codex
* session; trusting that pane alone binds the old transcript to the replacement agent.
* Two candidates is not a tie to break, so we answer nothing.
*/
export function chooseHookAgent<T>(byAncestry: readonly T[], byRuntimeOnly: readonly T[], engine: AgentEngine): {
agent: T | null
reason: 'ancestry' | 'runtime' | 'ambiguous' | 'none'
} {
if (byAncestry.length === 1) return { agent: byAncestry[0], reason: 'ancestry' }
if (byAncestry.length > 1) return { agent: null, reason: 'ambiguous' }
if (engine !== 'cursor') return { agent: null, reason: 'none' }
if (byRuntimeOnly.length === 1) return { agent: byRuntimeOnly[0], reason: 'runtime' }
return { agent: null, reason: byRuntimeOnly.length ? 'ambiguous' : 'none' }
}
export interface PairOutcome {
status: number
body: Record<string, unknown>
/** A busy backend's Retry-After, passed on where an answer is forwarded whole (the usage report). */
retryAfterMs?: number
}
export interface HookServerHandlers {
onAutonomousDeviceRequest?: (method: string, target: string, body?: unknown) => Promise<{ status: number; body: unknown }>
onRegistered: (
entry: RegisteredSession,
meta: {
isNew: boolean
evicted: string | null
rebound: string | null
/** An agent this bind left with no session and no process — see registry.register. */
orphaned?: { agentId: string; sessionId: string } | null
hookEvent?: string
},
) => void | Promise<void>
/** SessionEnd — a reconciliation hint only; it is never process-lifetime authority. */
onSessionEnd: (sessionId: string, reason: string | undefined) => void
/** Ensure a matching process-owned agent exists before a hook binds its mutable engine session. */
resolveHookAgent?: (session: {
engine: RegisteredSession['engine']
tmuxPane?: string
runtimeHints: HookTerminalHint[]
callerPid?: number
/** Called once the resolution has to wait for the agent to record its process
* (core/engines/hooks.ts): the hook is answered then, before the wait. */
onWait?: () => void
}) => Promise<RegisteredSession | null>
/** A turn is now running (Command Code's PreToolUse — its only live turn-open signal). Idempotent:
* it fires once per tool call, and every call after the first in a turn must be a no-op. */
onTurnStart?: (body: { sessionId: string }) => void
/** Core lifecycle admission fence; Stop owns the pane before its first asynchronous capture. */
hookAdmissionBlocked?: (agentId: string) => boolean
onAdmissionHeld?: (agentId: string, reason: string | undefined) => void
/** Retain an uncorrelated native Stop before attaching a newly admitted conversation. */
onAdmissionStop?: (entry: RegisteredSession, unmatched: boolean) => boolean
/** Captured before a same-conversation registration waits; Cancel or forget supersedes that Stop. */
captureAdmissionStop?: (entry: RegisteredSession) => () => boolean
onPromptSubmitted?: (agentId: string, prompt: string) => void
/** A session's UserPromptSubmit hook, and when its engine ran it (`X-Harness-Hook-Fired-At`): what a Stop
* that arrives late is told apart from the turn the prompt opened by (core/turns/turnHooks.ts). */
onPromptHook?: (sessionId: string, firedAt: number) => void
onToolStart?: (body: {
sessionId: string
toolUseId: string
toolName: string
input: unknown
}) => void
onTurnStop?: (body: {
sessionId: string
status?: string
transcriptPath?: string
/** When the engine ran the hook; absent from a hook client too old to say. */
firedAt?: number
}) => void
/** For the end-to-end suite only: how long a Stop hook is held before it is acted on, as the hook's own
* verification can take under load (`HARNESSD_TEST_STOP_HOOK_DELAY_MS`). */
stopHookDelayMs?: number
/** `harness pair <code>` from a second CLI process: run CPace toward the waiting browser. */
onPair?: (code: string) => Promise<PairOutcome>
/** `harness pairings` — list E2EE-paired browsers. */
onListPairs?: () => PairOutcome | Promise<PairOutcome>
/** `harness unpair <id>` — unpair one browser (by fingerprint/prefix/index). */
onRevoke?: (id: string) => PairOutcome | Promise<PairOutcome>
/** `harness unpair --all` — unpair every browser. */
onRevokeAll?: () => PairOutcome | Promise<PairOutcome>
/** `harness remote-password set` — stretch + persist a new persistent remote password on the
* running daemon's live E2EE state. */
onSetRemotePassword?: (password: string) => Promise<PairOutcome>
/** `harness remote-password clear` — remove the persistent remote password. */
onClearRemotePassword?: () => PairOutcome | Promise<PairOutcome>
/** `harness remote-password status` — whether one is set, and its fingerprint. */
onRemotePasswordStatus?: () => PairOutcome | Promise<PairOutcome>
/** `harness link connect` — the machine this one just linked pinned it back, so trust that machine
* here too (the mutual half of the link). Goes through the daemon: it holds paired.json in memory. */
onTrustLinkedPeer?: (peer: { pub: string; machineId: string; label: string }) => PairOutcome | Promise<PairOutcome>
/** `harness group list|sync|remove` — the trust group this machine belongs to (groupSyncer.ts). */
onGroupList?: () => PairOutcome | Promise<PairOutcome>
onGroupSync?: () => PairOutcome | Promise<PairOutcome>
onGroupRemove?: (selector: string) => PairOutcome | Promise<PairOutcome>
/** `harness devices list|remove|rebaseline` and the window's Devices list — the account's device key
* log as this machine verified it (lib/e2ee/deviceLogSyncer.ts). */
onDevicesList?: () => Promise<PairOutcome>
onDevicesRemove?: (pub: string) => Promise<PairOutcome>
onDevicesRebaseline?: (confirm: boolean, head?: { seq: number; hash: string }) => Promise<PairOutcome>
/** `harness devices history` and the window's History — every add and remove, as this machine verified it. */
onDevicesHistory?: () => Promise<PairOutcome>
/** `harness devices dismiss` and the window's "It's mine" / "Got it" — mark new devices as seen. */
onDevicesDismiss?: (body: { pub?: string; pubs?: string[]; baseline?: boolean }) => PairOutcome | Promise<PairOutcome>
/** The daemon's status (GET /api/status): what `harness status`, the desktop's discovery and scripts read. */
onStatus?: () => Record<string, unknown> | Promise<Record<string, unknown>>
/** GET /api/machines — proxy the user's full machine list from backend using this daemon's own
* saved SSO session, so a local GUI client never needs a token of its own. */
onMachinesList?: () => Promise<PairOutcome>
/** PATCH /api/machines/:machineId — proxy a rename to backend the same way. */
onMachineRename?: (machineId: string, name: string) => Promise<PairOutcome>
/** DELETE /api/machines/:machineId — proxy a delete to backend the same way. */
onMachineDelete?: (machineId: string) => Promise<PairOutcome>
/** GET /api/auth/me — proxy the signed-in user's profile from backend. */
onAuthMe?: () => Promise<PairOutcome>
/** PATCH /api/auth/me — the signed-in person's own account name (`{ name }`, task #2654), passed to the backend, which
* validates it and answers the profile as GET does; a local write, so CSRF-guarded like the desk's ops. */
onAuthMeUpdate?: (body: unknown) => Promise<PairOutcome>
/** POST /api/auth/handoff — a one-time code that signs a phone in to this account (the desktop's
* Add Phone QR), minted by backend against this daemon's own session. */
onAuthHandoff?: () => Promise<PairOutcome>
/** POST /api/daemon/stop — `harness stop` on Windows (core/daemonStopRoute.ts). Trusted local only: over TCP any
* process on the machine, another user's included, could stop this user's daemon. Given on Windows only; without
* it the route does not exist (404), as before on a Mac or Linux. */
onDaemonStop?: () => Promise<PairOutcome>
onSharedHarnesses?: () => Promise<PairOutcome>
/** GET /api/desk — the account's tabs, the same on every computer; proxied like the machine list. */
onDeskRead?: () => Promise<PairOutcome>
/** POST /api/desk/ops — the window's tab edits, applied on the backend (its routes/desk.ts); a
* local write, so CSRF-guarded like a rename. */
onDeskOps?: (body: unknown) => Promise<PairOutcome>
/** GET /api/agent-messages — the account's tabs and who is in each (docs/design/2026-10-10-agent-messages.md),
* proxied like the desk without starting the experiment's process. An older window draws each tab's chat icon
* from its flag, which no daemon reads now: the account's experiment decides (lib/agentSettings.ts). */
onAgentMessagesRead?: () => Promise<PairOutcome>
/** PATCH /api/agent-messages/tabs/:tabId — an older window's tab switch, passed to the backend so it gets the
* answer it expects, and deciding nothing; a local write, so CSRF-guarded like the desk's ops. */
onAgentMessagesWrite?: (tabId: string, body: unknown) => Promise<PairOutcome>
/** GET/PATCH /api/agent-settings — what the person lets agents do (lib/agentSettings.ts): the account's experiments
* as this computer keeps them, and a change written through to the account (`harness settings`, and an older
* window's Settings ▸ Agents). The write is CSRF-guarded like the others. */
onAgentSettingsRead?: () => Promise<PairOutcome>
onAgentSettingsWrite?: (body: unknown) => Promise<PairOutcome>
/** The account's Experimental switches, proxied with the daemon's own identity; what they say of agents is kept
* here too (core/experiments.ts `createAgentSettingsSync`). */
onExperimentalRead?: () => Promise<PairOutcome>
onExperimentalWrite?: (body: unknown) => Promise<PairOutcome>
onProductFeedback?: (body: unknown) => Promise<PairOutcome>
/** The phone half of a sign-in (backend routes/qrSignIn.ts) for the desktop and web apps: approve a device
* that says its code aloud (a lamp, #1410) with this computer's own session, as the phone does. */
onSignInAnswer?: (action: 'lookup' | 'approve' | 'deny', body: { code: string }) => Promise<PairOutcome>
/** A Super Tab chat file from the native desktop, streamed on to the backend with this computer's account
* (lib/superTabAttachmentProxy.ts): the app's REST client holds no token of its own. Answers on `res` itself. */
onSuperTabAttachment?: (req: http.IncomingMessage, res: http.ServerResponse, path: string) => Promise<void>
/** A chat file over 10 MB goes straight to storage (superTabs/attach.ts): its link asked for, and its upload said complete,
* with this computer's account. Small JSON both ways; the bytes never pass through here. */
onSuperTabAttachmentUpload?: (path: string, body: Record<string, unknown>) => Promise<PairOutcome>
onProductUsageReport?: (body: unknown) => Promise<PairOutcome>
onProductUsageRead?: () => Promise<PairOutcome>
onProductUsageWrite?: (body: unknown) => Promise<PairOutcome>
/** /api/store/* — proxy the Harness Store's ratings and reviews to backend the same way: reads
* ungated like the machine list, writes (PUT/DELETE) CSRF-guarded like a rename. See storeProxy.ts. */
onStore?: StoreHandler
}
export { STORE_PATH_RE } from './lib/storeProxy.js'
const MAX_HOOK_BODY_BYTES = 256 * 1024
const HOOK_BODY_FIELDS = new Set([
'engine', 'launcherId', 'sessionId', 'transcriptPath', 'cwd', 'source', 'tmuxPane', 'title', 'model',
'cliVersion', 'runtimeHints', 'callerPid', 'hookEvent', 'pluginVersion', 'reason', 'status', 'toolUseId',
'toolName', 'input', 'prompt',
])
function optionalBoundedString(value: unknown, max: number): boolean {
return value === undefined || value === null || (typeof value === 'string'
&& value.length <= max && !/[\u0000-\u001f\u007f]/.test(value))
}
function optionalBoundedJson(value: unknown, max: number): boolean {
if (value === undefined) return true
try { return Buffer.byteLength(JSON.stringify(value)) <= max } catch { return false }
}
/**
* When the engine ran a hook: the hook process's own start (hook/notify.mjs sends it as a header, which a
* daemon that does not read it ignores, where an unknown body field is refused). Undefined from a client too
* old to say. Not the hook's arrival: under load a hook reached the daemon seconds after its engine had
* moved on to the next prompt (found by the soak run, e2e/endurance.e2e.ts).
*/
export function hookFiredAt(req: Pick<http.IncomingMessage, 'headers'>): number | undefined {
const value = Number(req.headers['x-harness-hook-fired-at'])
return Number.isSafeInteger(value) && value > 0 ? value : undefined
}
function validHookBody(value: unknown): value is BoundHookBody {
if (!value || typeof value !== 'object' || Array.isArray(value)) return false
const body = value as Record<string, unknown>
if (body.prompt !== undefined && (typeof body.prompt !== 'string' || Buffer.byteLength(body.prompt) > 128 * 1024)) return false
if (Object.keys(body).some((field) => !HOOK_BODY_FIELDS.has(field))) return false
if (body.engine !== undefined && (typeof body.engine !== 'string' || !ENGINES.includes(body.engine as AgentEngine))) return false
if (!optionalBoundedString(body.launcherId, 200)
|| !optionalBoundedString(body.sessionId, 200)
|| !optionalBoundedString(body.transcriptPath, 4_096)
|| !optionalBoundedString(body.cwd, 4_096)
|| !optionalBoundedString(body.source, 1_000)
|| !optionalBoundedString(body.tmuxPane, 32)
|| !optionalBoundedString(body.title, 1_000)
|| !optionalBoundedString(body.model, 200)
|| !optionalBoundedString(body.cliVersion, 200)
|| !optionalBoundedString(body.hookEvent, 100)
|| !optionalBoundedString(body.pluginVersion, 100)
|| !optionalBoundedString(body.reason, 500)
|| !optionalBoundedString(body.status, 100)
|| !optionalBoundedString(body.toolUseId, 200)
|| !optionalBoundedString(body.toolName, 200)
|| !optionalBoundedJson(body.input, 128 * 1024)) return false
if (body.callerPid !== undefined
&& (!Number.isSafeInteger(body.callerPid) || (body.callerPid as number) <= 0)) return false
if (body.runtimeHints !== undefined) {
if (!Array.isArray(body.runtimeHints) || body.runtimeHints.length > 4) return false
for (const value of body.runtimeHints) {
if (!value || typeof value !== 'object' || Array.isArray(value)) return false
const hint = value as Record<string, unknown>
if (hint.backend === 'tmux') {
if (Object.keys(hint).some((field) => field !== 'backend' && field !== 'paneId')
|| typeof hint.paneId !== 'string' || !/^%\d+$/.test(hint.paneId)) return false
} else if (hint.backend === 'ptyhost') {
// A Harness pty host pane, as its shell names itself (`HARNESS_PANE=<instance>:%N`, hook/notify.mjs): the
// instance and the pane, nothing else.
if (Object.keys(hint).some((field) => !['backend', 'instance', 'paneId'].includes(field))
|| typeof hint.instance !== 'string' || !PTY_HOST_INSTANCE.test(hint.instance)
|| typeof hint.paneId !== 'string' || !/^%\d{1,9}$/.test(hint.paneId)) return false
} else if (hint.backend === 'herdr') {
// A hook script installed by an earlier build still sends these from inside a Herdr pane. The
// backend is retired and `normalizedRuntimeHints` drops the hint, but the rest of the body is
// still good evidence, so the shape stays accepted rather than failing the whole request.
if (Object.keys(hint).some((field) => !['backend', 'paneId', 'sessionName', 'socketPath'].includes(field))
|| !optionalBoundedString(hint.paneId, 200) || !hint.paneId
|| !optionalBoundedString(hint.sessionName, 64)
|| !optionalBoundedString(hint.socketPath, 4_096)) return false
} else return false
}
}
return true
}
function readBody(req: http.IncomingMessage, maximum = MAX_HOOK_BODY_BYTES): Promise<string> {
return new Promise((resolve) => {
let data = ''
let bytes = 0
let oversized = false
req.setEncoding('utf8')
req.on('data', (chunk: string) => {
bytes += Buffer.byteLength(chunk)
if (bytes > maximum) { oversized = true; data = ''; return }
data += chunk
})
req.on('end', () => resolve(oversized ? '' : data))
req.on('error', () => resolve(''))
})
}
function normalizedRuntimeHints(body: RegisterInput): HookTerminalHint[] {
const hints: HookTerminalHint[] = []
if (Array.isArray(body.runtimeHints) && body.runtimeHints.length <= 4) {
for (const hint of body.runtimeHints) {
if (hint?.backend === 'tmux' && /^%\d+$/.test(hint.paneId)) hints.push({ backend: 'tmux', paneId: hint.paneId })
else if (hint?.backend === 'ptyhost' && PTY_HOST_INSTANCE.test(hint.instance) && /^%\d{1,9}$/.test(hint.paneId)) {
hints.push({ backend: 'ptyhost', instance: hint.instance, paneId: hint.paneId })
}
}
}
if (body.tmuxPane && /^%\d+$/.test(body.tmuxPane)
&& !hints.some((hint) => hint.backend === 'tmux' && hint.paneId === body.tmuxPane)) {
hints.push({ backend: 'tmux', paneId: body.tmuxPane })
}
return hints
}
type BoundHookBody = RegisterInput & {
prompt?: string
sessionId?: string
reason?: string
status?: string
toolUseId?: string
toolName?: string
input?: unknown
}
async function verifiedBoundMutation(
body: BoundHookBody,
handlers: HookServerHandlers,
): Promise<RegisteredSession | null> {
if (!body.sessionId || !body.engine) return null
const initial = registry.bySession(body.sessionId)
if (!initial || initial.engine !== body.engine) return null
const identity = paneReadIdentity(initial)
const runtimeHints = normalizedRuntimeHints(body)
if (!runtimeHints.length) return null
const processAgent = handlers.resolveHookAgent
? await handlers.resolveHookAgent({
engine: body.engine,
tmuxPane: body.tmuxPane,
runtimeHints,
callerPid: Number.isSafeInteger(body.callerPid) && body.callerPid! > 0 ? body.callerPid : undefined,
})
: body.tmuxPane ? registry.byPaneEngine(body.tmuxPane, body.engine) ?? null : null
return processAgent?.engine === body.engine && processAgent.sessionId === body.sessionId
&& processAgent.agentId === initial.agentId && paneReadIdentity(processAgent) === identity
&& paneReadIdentity(registry.byAgent(initial.agentId)) === identity
? registry.byAgent(initial.agentId)!
: null
}
/**
* Bind the localhost hook server on a FIXED `port` (no OS free-port fallback — a random fallback made
* a leftover daemon un-findable by `lsof :<port>`). Rejects with EADDRINUSE if the port is taken (the
* CLI reports it as "another adapter already running"). Resolves with the bound port.
*/
function admissionProcessScope(session: RegisteredSession | undefined): string | undefined {
if (!session?.active) return undefined
return session.processIdentity ? processIdentityKey(session.engine, session.processIdentity) : session.agentId
}
/** A failed native correction is incomplete evidence, never the original announcement. */
export function knownTranscriptFor(body: RegisterInput, agent: RegisteredSession | undefined): string | undefined {
return hooksFor(body.engine ?? 'claude')?.transcriptFor?.(body, agent) ?? body.transcriptPath
}
/** Read source evidence without binding. Unreadable stores never authorize a conversation. */
async function inspectHermesKind(sessionId: string, knownHome?: string): Promise<AdmissionDecision<string | undefined>> {
if (!HERMES_SOURCE.id.test(sessionId)) return { kind: 'accept', value: undefined }
try {
const found = await readStorePool(HERMES_HOMES, env.HERMES_HOME, {
sql: HERMES_SOURCE.query, params: [sessionId], maxRows: 1, maxBuffer: HERMES_SOURCE.maxBuffer,
columns: ['id', 'source'], pointKey: 'id', knownHome,
})
if (!found.length) return { kind: 'hold', reason: 'Waiting for the Hermes session source record; keeping the current conversation.' }
if (found.length !== 1) return { kind: 'hold', reason: 'Hermes session source is ambiguous across homes; keeping the current conversation.' }
const { home, aliases, row } = found[0]
if (knownHome && !aliases.includes(knownHome)) return { kind: 'hold', reason: 'Waiting for the Hermes source in its known home; keeping the current conversation.' }
const source = row[HERMES_SOURCE.column]
if (typeof source !== 'string' || source.length > 128) throw new IdentityReadUnavailable('the Hermes source record is invalid')
if (!isInteractiveSource(HERMES_SOURCE, source)) return { kind: 'reject', reason: 'hermes_subagent' }
return { kind: 'accept', value: knownHome ?? (home === env.HERMES_HOME ? undefined : home) }
} catch (error) {
if (!(error instanceof IdentityReadUnavailable)) throw error
return { kind: 'hold', reason: `Hermes session source is unavailable; keeping the current conversation. ${error.message}` }
}
}
export interface HookServerOptions {
/** Whether a TCP caller runs as this OS account (lib/peerAccount.ts). A test's stand-in for another account. */
peerAccount?: PeerAccount
/** Also serve on this Unix socket, or with pipeToken the Windows pipe (see lib/localSocket.ts). Null or absent: TCP only. */
socketPath?: string | null
/** Windows: the daemon's token. When given, `socketPath` is a pipe whose every request proves it (lib/localSocket.ts). */
pipeToken?: Buffer | null
/** A private socket identifies this user's daemon even when another OS user holds the TCP port. */
allowPortFallback?: boolean
/** Completed acknowledgements are retained for a live process, never evicted to admit another hook. */
admissionReceiptCapacity?: number
/** Bound native payload and provenance retained by pending admission or linked Stop. */
admissionBytesCapacity?: number
}
/** The `/api/status` fields a caller without the local credential is answered. */
// Which daemon this is (its pid and computer, as a takeover or a status check compares) and where its socket
// is — never the account, its folders or its connections.
const PUBLIC_STATUS_FIELDS = ['version', 'pid', 'corePid', 'computerId', 'localWs', 'localSocket', 'supported'] as const
function publicStatus(status: Record<string, unknown>): Record<string, unknown> {
const out: Record<string, unknown> = { credentialRequired: true }
for (const key of PUBLIC_STATUS_FIELDS) if (key in status) out[key] = status[key]
return out
}
export function startHookServer(
port: number,
handlers: HookServerHandlers,
options: HookServerOptions = {},
): Promise<{ server: http.Server; port: number; localSocket: LocalSocketServer | null }> {
const hookCredential = loadOrCreateHookCredential(env.ADAPTER_DATA_DIR)
const hookToken = loadOrCreateHookToken(env.ADAPTER_DATA_DIR)
const peerAccount: PeerAccount = options.peerAccount ?? peerIsThisAccount
const admissions = createPendingAdmissions({ isProcessCurrent: (key, scope) => admissionProcessScope(registry.byAgent(key)) === scope })
let admissionArrival = 0
const admissionHolds = new Map<string, Map<string, string>>()
type StopAcknowledgement = { status: number; reply: unknown }
type LinkedStop = (body: BoundHookBody, firedAt: number | undefined) => StopAcknowledgement | Promise<StopAcknowledgement>
type Receipt = { fingerprint: string; status: number; reply: unknown; pending: boolean; bytes: number; linkedStop?: LinkedStop }
const admissionReceipts = new Map<string, { scope: string; records: Map<string, Receipt> }>()
const resolvingStops = new Map<string, { fingerprint: string; stop: LinkedStop }>()
let receiptCount = 0, receiptBytes = 0
const saveReceipt = (records: Map<string, Receipt>, id: string, next?: Receipt) => {
const before = records.get(id)
if (before) { receiptCount--; receiptBytes -= before.bytes }
if (next) { records.set(id, next); receiptCount++; receiptBytes += next.bytes }
else records.delete(id)
}
const receiptCapacity = options.admissionReceiptCapacity ?? 65_536
const bytesCapacity = options.admissionBytesCapacity ?? 16 * 1024 * 1024
// Filled in once the port is bound: the Host a request must name is the port actually taken.
let hosts: ReadonlySet<string> = new Set()
let lastRefusalLogAt = 0
const handle: http.RequestListener = (req, res) => {
void (async () => {
const url = (req.url ?? '').split('?')[0]
const json = (code: number, body: unknown): void => {
res.writeHead(code, { 'Content-Type': 'application/json' })
res.end(JSON.stringify(body))
}
// Over the daemon's own socket the filesystem already said who this is, and over its Windows pipe the request
// proved the daemon's token; no browser can get to either. Everything else must prove it was addressed to
// this loopback server.
const trustedLocal = isTrustedLocal(req)
// Before any route, reads included. See lib/loopbackRequest.ts.
if (!trustedLocal && !isLoopbackRequest(req, hosts)) {
// At most one line a minute: enough to explain a client that was refused, not a lever for a
// page to flood the log. Host and Origin are the sender's, so they are escaped and bounded.
if (Date.now() - lastRefusalLogAt > 60_000) {
lastRefusalLogAt = Date.now()
const shown = (v: unknown) => JSON.stringify(String(v ?? '').slice(0, 80))
console.warn(`[hooks] refused ${req.method} ${url.slice(0, 80)} · host=${shown(req.headers.host)} origin=${shown(req.headers.origin)}`)
}
json(403, { error: 'FORBIDDEN_HOST' }); return
}
// 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 the CLI and the apps, which
// send it, can trigger actions. A local process could still call it — same trust level as the
// CLI, which is acceptable on loopback.
const localOk = req.headers['x-adapter-local'] === '1'
// An engine hook's token, which opens these hook routes and nothing else (lib/hookAuth.ts). The credential
// is still taken here: an engine's loaded plugin keeps the copy it started with until its pane restarts. A
// guest's harness will carry a token scoped to its own agent (docs/plans/2026-10-19-guest-machine-sharing-plan.md).
// Over TCP either may have been heard by another account that held this port during a restart (audit H1), which
// could then forge session ends or turn stops here, so it counts only from this one. Asked only once it matched.
const suppliedHookToken = req.headers['x-harness-hook-token']
const hookOk = trustedLocal || ((hookCredentialMatches(hookToken, suppliedHookToken) || hookCredentialMatches(hookCredential, suppliedHookToken)) && await peerAccount(req.socket))
// The loopback port takes any local OS user's process, so over TCP every route but the few below
// wants the daemon's local credential (lib/localCredential.ts): the 0600 file only this OS user can
// read. Over the daemon's Unix socket the filesystem already said who this is. Over TCP the credential may have
// been heard by another account that held this port during a restart (audit H1), so it counts only from this one.
const credentialOk = trustedLocal || (localCredentialMatches(hookCredential, req) && await peerAccount(req.socket))
// Open without it: liveness, the status a discovery reads (cut down, below), the hook routes (their
// own token, above) and the native device routes (their own bearer, just below).
const open = (req.method === 'GET' && (url === '/api/health' || url === '/api/status'))
|| url.startsWith('/api/hook/') || url.startsWith('/api/autonomous-device/')
if (!credentialOk && !open) { json(401, { error: LOCAL_CREDENTIAL_REQUIRED }); return }
if (url.startsWith('/api/autonomous-device/')) {
const peer = req.socket.remoteAddress
const loopback = trustedLocal || peer === '127.0.0.1' || peer === '::1' || peer === '::ffff:127.0.0.1'
const bearer = req.headers.authorization?.startsWith('Bearer ') ? req.headers.authorization.slice(7) : undefined
if (!loopback || req.headers.origin || !hookCredentialMatches(hookCredential, bearer) || !credentialOk) {
json(403, { error: { code: 'FORBIDDEN', message: 'Authenticated native loopback client required' } }); return
}
if (!handlers.onAutonomousDeviceRequest) { json(503, { error: { code: 'UNAVAILABLE', message: 'Autonomous device service unavailable' } }); return }
let body: unknown
if (req.method !== 'GET') {
try { body = JSON.parse(await readBody(req)) } catch { json(400, { error: { code: 'BAD_REQUEST', message: 'Invalid JSON body' } }); return }
}
const result = await handlers.onAutonomousDeviceRequest(req.method ?? '', req.url ?? '', body)
json(result.status, result.body); return
}
if (req.method === 'GET' && url === '/api/health') {
json(200, { ok: true, version: VERSION }); return
}
// The local web dashboard that `GET /` served, with its log tail (`/api/logs`) and stop button
// (`/api/stop`), is gone: no app, website, script or the backend opened it, and the web client
// it linked from retired with the browser setup links (#348). `harness stop` stops the daemon
// through its pid, never through here.
if (req.method === 'GET' && url === '/api/status') {
const status = handlers.onStatus ? await handlers.onStatus() : { supported: false }
// Without the credential, only what says a daemon is here and where its socket is: nothing about
// the account, its folders or its connections.
json(200, credentialOk ? status : publicStatus(status)); return
}
// SessionStart AND UserPromptSubmit both POST here (the catch hook re-registers so a session
// whose SessionStart the adapter missed still shows up on its first prompt).
if (req.method === 'POST' && url === '/api/hook/session-start') {
if (!hookOk) { json(401, { error: 'UNAUTHORIZED' }); return }
let body: BoundHookBody
try {
const parsed = JSON.parse(await readBody(req)) as unknown
if (!validHookBody(parsed)) { json(400, { error: 'invalid hook body' }); return }
body = parsed
} catch { json(400, { error: 'bad json' }); return }
// Every rejection below says WHY, out loud. They used to be silent, and a hook that arrives and
// is dropped looks exactly like a hook that never fired — which is precisely the confusion behind
// "the agent is running in my terminal but the list does not show it".
// Answered once: a hook answered before its resolution waited is only logged after it.
let answered = false
const answer = (code: number, reply: unknown): void => {
if (answered) return
answered = true
json(code, reply)
}
const ignore = (reason: string): void => {
console.log(`[hooks] ${sid(body.sessionId ?? '?')} ${body.hookEvent ?? 'session-start'} ignored · ${reason}`)
answer(200, { ignored: true, reason })
}
const runtimeHints = normalizedRuntimeHints(body)
if (!runtimeHints.length) { ignore('not_in_terminal'); return }
// A plugin/extension is loaded ONCE per engine process, so a pane opened before an update keeps
// running the old copy — silently, and for hours. Measured on amp: a pane started at 11:49 was
// still writing transcripts with no tool calls long after the fix reached disk. The engines that
// use shell hooks re-read the file on every call and cannot drift like this; these three can, so
// they stamp their build and the mismatch is said out loud instead of being discovered later.
const pluginVersion = (body as { pluginVersion?: unknown }).pluginVersion
if (typeof pluginVersion === 'string' && pluginVersion && pluginVersion !== VERSION) {
console.warn(`[hooks] ${sid(body.sessionId ?? '?')} ${body.engine ?? '?'} plugin is v${pluginVersion}`
+ ` but this machine is v${VERSION} — that pane loaded an older copy.`)
console.warn('[hooks] restart the pane (or reload its plugins) to pick up the current build')
}
const engine = body.engine ?? 'claude'
// Capture before process resolution yields. Native time is unchanged across client retries.
const admissionOrder = { firedAt: hookFiredAt(req), arrival: ++admissionArrival }
const fingerprint = createHash('sha256').update(JSON.stringify([body, admissionOrder.firedAt])).digest('hex')
const deliveryHeader = req.headers['x-harness-hook-delivery-id']
const nativeDeliveryId = typeof deliveryHeader === 'string' && /^[a-zA-Z0-9_-]{16,96}$/.test(deliveryHeader) ? deliveryHeader : undefined
const deliveryId = nativeDeliveryId ?? randomUUID()
const carriesStop = !!nativeDeliveryId && (engine === 'cursor' && body.hookEvent === 'stop'
|| engine === 'commandcode' && (body.hookEvent === 'Stop' || body.hookEvent === 'StopFailure'))
const stopProvenance = (value: BoundHookBody, firedAt: number | undefined) => JSON.stringify([
value.engine, value.sessionId, value.callerPid, normalizedRuntimeHints(value), firedAt, value.status,
])
const originalStop = stopProvenance(body, admissionOrder.firedAt)
const conflict = { status: 409, reply: { pending: false, error: 'HOOK_DELIVERY_CONFLICT' } }
const scopeOf = (row: RegisteredSession | undefined) => row && JSON.stringify([
row.agentId, row.engine, row.processIdentity ? processIdentityKey(row.engine, row.processIdentity) : null,
])
const resolving = resolvingStops.get(deliveryId)
if (resolving) {
const reply = resolving.fingerprint === fingerprint ? await resolving.stop(body, admissionOrder.firedAt) : conflict
answer(reply.status, reply.reply); return
}
// A preliminary lookup grants no binding authority. It only remembers
// cancellation before process resolution yields; the proved owner below
// must match this exact process/conversation before the witness applies.
const preliminary = carriesStop && body.sessionId ? registry.bySession(body.sessionId) : undefined
const stopScope = preliminary?.engine === engine ? scopeOf(preliminary) : undefined
const stopWitness = stopScope ? handlers.captureAdmissionStop?.(preliminary!) : undefined
let deferred = false
if (carriesStop) resolvingStops.set(deliveryId, { fingerprint, stop: (stop, firedAt) => {
if (stopProvenance(stop, firedAt) !== originalStop) return conflict
deferred = true
return { status: 202, reply: { pending: false, retry: true, detail: 'Waiting for the engine process record; Stop admission is not queued yet.' } }
} })
let processAgent: RegisteredSession | null
try { processAgent = handlers.resolveHookAgent
? await handlers.resolveHookAgent({
engine,
tmuxPane: body.tmuxPane,
runtimeHints,
callerPid: Number.isSafeInteger(body.callerPid) && body.callerPid! > 0 ? body.callerPid : undefined,
// A relaunch records its engine's process a moment after the engine starts, and a hook in that
// moment waits for the record, up to 20s. Its client does not: the engine's hook command gives
// up on a reply after 500ms and then writes the registry itself, as for a daemon that is down
// (hook/notify.mjs, fallbackRegister), with a row of its own in place of the agent's, which
// the running daemon's next save took in. Told the registration is pending, it writes nothing,
// as for a transcript not yet written below, and the wait goes on here.
// Hermes admission has a separate bounded queue after resolution. Do not
// claim a slot before one exists: its hook client can retry this live hold.
onWait: () => { deferred = true; answer(202, { pending: false, retry: true, detail: 'Waiting for the engine process record; admission is not queued yet.' }) },
})
: body.tmuxPane ? registry.byPaneEngine(body.tmuxPane, engine) ?? null : null
} finally { if (carriesStop) resolvingStops.delete(deliveryId) }
if (!processAgent || processAgent.engine !== engine) { ignore('no_matching_engine_process'); return }
// Own the process incarnation. Each inspection refreshes its routing,
// but can never follow the original hinted pane to a replacement process.
body.processIdentity = processAgent.processIdentity ? { ...processAgent.processIdentity } : undefined
body.runtimes = processAgent.runtimes.map(runtime => ({ ...runtime }))
body.primaryRuntimeKey = processAgent.primaryRuntimeKey
if (isRecentlyDeleted(body.sessionId)) { ignore('deleted'); return }
const scope = scopeOf(processAgent)!
if (carriesStop && stopScope !== scope) deferred = true
if (scopeOf(registry.byAgent(processAgent.agentId)) !== scope) { ignore('stale_hook'); return }
// Pending jobs and completed receipts survive routing observations within
// this process incarnation. Native hints are rechecked before every commit.
const receiptScope = scopeOf
for (const [id, history] of admissionReceipts) if (receiptScope(registry.byAgent(id)) !== history.scope) {
for (const delivery of history.records.keys()) saveReceipt(history.records, delivery)
admissionReceipts.delete(id)
}
const history = admissionReceipts.get(processAgent.agentId) ?? { scope: receiptScope(processAgent)!, records: new Map() }
admissionReceipts.set(processAgent.agentId, history)
const completed = history.records.get(deliveryId)
if (completed) {
if (completed.fingerprint === fingerprint) answer(completed.status, completed.reply)
else answer(409, { pending: false, error: 'HOOK_DELIVERY_CONFLICT' })
return
}
// Strings can occupy two bytes per code unit; include the immutable
// process snapshot and fixed closure/record overhead in this admission budget.
const retainedBytes = 2 * (JSON.stringify(body).length + JSON.stringify(processAgent).length) + 2_048
if (receiptCount >= receiptCapacity || receiptBytes + retainedBytes > bytesCapacity) {
answer(429, { pending: false, error: 'HOOK_ADMISSION_BUSY', detail: 'Hook acknowledgement storage is full; this delivery was not queued.' })
return
}
let inspectionIdentity: string | undefined
let prepared: RegisterInput = body
let committed: ReturnType<typeof registry.register> = null
let settled = false, stopRetained = false, stopUnmatched = false, stopInvocationClaimed = false
const stopCurrent = processAgent.sessionId === body.sessionId && stopScope === scope ? stopWitness : undefined
let followupFingerprint: string | undefined, committedIdentity: string | undefined
const live = () => registry.byAgent(processAgent.agentId)
const current = () => !isRecentlyDeleted(processAgent.agentId) && !isRecentlyDeleted(body.sessionId)
&& live()?.active !== false && scopeOf(live()) === scope
const publishHold = () => {
const reason = [...admissionHolds.get(processAgent.agentId)?.values() ?? []].at(-1)
try { handlers.onAdmissionHeld?.(processAgent.agentId, reason) }
catch (error) { console.warn('[hooks] admission status notification failed', error) }
}
const held = (reason: string) => {
deferred = true
const holds = admissionHolds.get(processAgent.agentId) ?? new Map<string, string>()
holds.set(deliveryId, reason); admissionHolds.set(processAgent.agentId, holds)
publishHold()
console.log(`[hooks] ${sid(body.sessionId ?? '?')} ${body.hookEvent ?? 'session-start'} held · ${reason}`)
answer(200, { pending: true })
}
const clearHold = () => {
const holds = admissionHolds.get(processAgent.agentId)
if (!holds?.delete(deliveryId)) return
if (!holds.size) admissionHolds.delete(processAgent.agentId)
publishHold()
}
const completedReply = (status: number, reply: unknown) => {
// A pruned old process cannot reinsert its receipts from a late callback.
if (admissionReceipts.get(processAgent.agentId) === history) saveReceipt(history.records, deliveryId,
{ ...history.records.get(deliveryId)!, status, reply, pending: false, bytes: carriesStop ? retainedBytes : 0 })
settled = true
answer(status, reply)
}
const linkedStop: LinkedStop = async (stop, firedAt) => {
if (stopProvenance(stop, firedAt) !== originalStop) return conflict
const sent = createHash('sha256').update(JSON.stringify(stop)).digest('hex')
if (followupFingerprint && sent !== followupFingerprint) return conflict
followupFingerprint = sent
// The registration itself owns this native Stop, even if its second
// HTTP delivery outruns source recovery. Never close a later live turn.
if (!settled || stopRetained) {
deferred = true
return { status: 200, reply: { pending: true } }
}
if (stopCurrent && !stopCurrent()) stopInvocationClaimed = true
if (stopInvocationClaimed) return { status: 200, reply: { ok: true, duplicate: true } }
const owner = await verifiedBoundMutation(stop, handlers)
if (stopCurrent && !stopCurrent()) stopInvocationClaimed = true
if (stopInvocationClaimed) return { status: 200, reply: { ok: true, duplicate: true } }
if (stopRetained) return { status: 200, reply: { pending: true } }
if (!current() || live()?.sessionId !== body.sessionId) {
return { status: 403, reply: { error: 'UNBOUND_HOOK' } }
}
if (!owner || paneReadIdentity(owner) !== committedIdentity) {
// The original delivery still belongs to this process/conversation,
// but its parser or routing was rebuilt. Preserve completion without
// applying it to whichever turn the replacement happened to load.
stopRetained = handlers.onAdmissionStop?.(live()!, true) ?? false
return stopRetained ? { status: 200, reply: { pending: true } }
: { status: 202, reply: { pending: false, retry: true, detail: 'Waiting for core ownership of the unmatched Stop.' } }
}
if (!stopInvocationClaimed) {
// Claim after the final authority fence, before optional async drains.
stopInvocationClaimed = true
handlers.onTurnStop?.({ sessionId: owner.sessionId, status: stop.status,
transcriptPath: stop.transcriptPath, ...(firedAt ? { firedAt } : {}) })
return { status: 200, reply: { ok: true } }
}
return { status: 200, reply: { ok: true, duplicate: true } }
}
const prepare = (): AdmissionDecision<string | undefined> | null => {
if (!current()) return { kind: 'reject', reason: 'stale_hook' }
if (handlers.hookAdmissionBlocked?.(processAgent.agentId)) return { kind: 'hold', reason: 'Waiting for Stop to settle before admitting the hook.' }
const row = live()!
if (!runtimeHints.some(hint => row.runtimes.some(runtime => runtime.backend === hint.backend && runtime.paneId === hint.paneId
// A paneId is only unique within one pty host.
&& (hint.backend !== 'ptyhost' || (runtime.backend === 'ptyhost' && runtime.instance === hint.instance))))) {
return { kind: 'hold', reason: 'Waiting for the original hook pane to belong to its engine process.' }
}
inspectionIdentity = paneReadIdentity(row)
prepared = { ...body, processIdentity: row.processIdentity ? { ...row.processIdentity } : undefined,
runtimes: row.runtimes.map(runtime => ({ ...runtime })), primaryRuntimeKey: row.primaryRuntimeKey,
transcriptPath: knownTranscriptFor(body, row) }
const admission = admitHook(engine, prepared)
if (!admission.accepted) return admission.reason === 'engine_hook_failed'
? { kind: 'hold', reason: 'Waiting for complete native hook evidence.' } : { kind: 'reject', reason: admission.reason }
return null
}
const commit = (hermesHome: string | undefined): AdmissionDecision<string | undefined> => {
if (!current() || paneReadIdentity(live()) !== inspectionIdentity) return { kind: 'hold', reason: 'Waiting for fresh evidence after the binding changed.' }
if (handlers.hookAdmissionBlocked?.(processAgent.agentId)) return { kind: 'hold', reason: 'Waiting for Stop to settle before admitting the hook.' }
const prior = live()
const before = prior && { sessionId: prior.sessionId, transcriptPath: prior.transcriptPath,
held: !!(prior.identityHold || prior.interpretationHold) }
committed = registry.register(hermesHome ? { ...prepared, hermesHome } : prepared, { verifiedNativeSource: true })
if (stopCurrent && !stopCurrent()) stopInvocationClaimed = true
if (committed && carriesStop && !stopRetained && !stopInvocationClaimed) {
stopUnmatched ||= deferred || before?.sessionId !== committed.entry.sessionId
|| before?.transcriptPath !== committed.entry.transcriptPath || before?.held === true
if (!handlers.onAdmissionStop && stopUnmatched) return { kind: 'hold', reason: 'Waiting for core ownership of the unmatched Stop.' }
stopRetained = handlers.onAdmissionStop?.(committed.entry, stopUnmatched) ?? false
if (stopUnmatched && !stopRetained) return { kind: 'hold', reason: 'Waiting for core ownership of the unmatched Stop.' }
}
if (committed) committedIdentity = paneReadIdentity(committed.entry)
return committed ? { kind: 'accept', value: hermesHome } : { kind: 'reject', reason: 'invalid_session_registration' }
}
const notify = () => {
const result = committed!
clearHold()
console.log(`[hooks] ${sid(result.entry.sessionId)} ${body.hookEvent ?? 'session-start'} · engine=${result.entry.engine} · isNew=${result.isNew}`
+ (engine === 'hermes' ? ` · after a source check${result.entry.hermesHome ? ` · home=${result.entry.hermesHome}` : ''}` : ''))
const optional = (call: () => void | Promise<void>) => {
try { void Promise.resolve(call()).catch(error => console.warn('[hooks] committed admission notification failed', error)) }
catch (error) { console.warn('[hooks] committed admission notification failed', error) }
}
// Native prompt credit follows the durable bind, never an attempted one.
if (body.hookEvent === 'UserPromptSubmit') {
optional(() => handlers.onPromptSubmitted?.(result.entry.agentId, body.prompt ?? ''))
if (admissionOrder.firedAt && body.sessionId) optional(() => handlers.onPromptHook?.(body.sessionId!, admissionOrder.firedAt!))
}
optional(() => handlers.onRegistered(result.entry, { isNew: result.isNew, evicted: result.evicted, rebound: result.rebound,
orphaned: result.orphaned, hookEvent: body.hookEvent }))
}
const enqueue = () => {
saveReceipt(history.records, deliveryId, { fingerprint, status: 200, reply: { pending: true }, pending: true, bytes: retainedBytes,
...(carriesStop ? { linkedStop } : {}) })
const queued = admissions.submit(processAgent.agentId, deliveryId, {
conversationId: body.sessionId,
order: { ...admissionOrder, scope: admissionProcessScope(processAgent) ?? processAgent.agentId },
binding: () => { const row = live(); return row && { id: row.sessionId, at: row.boundAt } },
current,
inspect: async () => prepare() ?? (engine === 'hermes' && body.sessionId
? await inspectHermesKind(body.sessionId, live()?.hermesHome ?? undefined) : { kind: 'accept', value: undefined }),
commit,
held,
reject: reason => {
clearHold()
console.log(`[hooks] ${sid(body.sessionId ?? '?')} ${body.hookEvent ?? 'session-start'} ignored · ${reason}`)
if (reason === 'invalid_session_registration') completedReply(400, { error: 'invalid session registration' })
else completedReply(200, { ignored: true, reason })
},
accept: () => { completedReply(200, { ok: true }); notify() },
})
if (queued) {
// Synchronous native admission settles in this turn's microtasks. A
// queued predecessor or asynchronous source gets an owned pending reply.
if (engine === 'hermes') answer(200, { pending: true })
else setImmediate(() => { if (!settled) deferred = true; answer(200, { pending: true }) })
} else {
saveReceipt(history.records, deliveryId)
const detail = 'Too many unverified hooks are pending; this hook was not queued. Retry after recovery.'
console.log(`[hooks] ${sid(body.sessionId ?? '?')} held · ${detail}`)
answer(429, { pending: false, error: 'HOOK_ADMISSION_BUSY', detail })
}
}
enqueue()
return
}
if (req.method === 'POST' && url === '/api/hook/session-end') {
if (!hookOk) { json(401, { error: 'UNAUTHORIZED' }); return }
let body: BoundHookBody
try {
const parsed = JSON.parse(await readBody(req)) as unknown
if (!validHookBody(parsed)) { json(400, { error: 'invalid hook body' }); return }
body = parsed
} catch { json(400, { error: 'bad json' }); return }
if (!await verifiedBoundMutation(body, handlers)) { json(403, { error: 'UNBOUND_HOOK' }); return }
if (body.sessionId) {
console.log(`[hooks] ${sid(body.sessionId)} session-end${body.reason ? ` · reason=${body.reason}` : ''}`)
handlers.onSessionEnd(body.sessionId, body.reason)
}
json(200, { ok: true })
return
}
if (req.method === 'POST' && url === '/api/hook/tool-start') {
if (!hookOk) { json(401, { error: 'UNAUTHORIZED' }); return }
let body: BoundHookBody
try {
const parsed = JSON.parse(await readBody(req)) as unknown
if (!validHookBody(parsed)) { json(400, { error: 'invalid hook body' }); return }
body = parsed
} catch { json(400, { error: 'bad json' }); return }
if (!await verifiedBoundMutation(body, handlers)) { json(403, { error: 'UNBOUND_HOOK' }); return }
if (body.sessionId && body.toolUseId && body.toolName) {
console.log(`[hooks] ${sid(body.sessionId)} tool-start · tool=${body.toolName}`)
handlers.onToolStart?.({
sessionId: body.sessionId,
toolUseId: body.toolUseId,
toolName: body.toolName,
input: body.input,
})
}
json(200, { ok: true })
return
}
if (req.method === 'POST' && url === '/api/hook/turn-start') {
if (!hookOk) { json(401, { error: 'UNAUTHORIZED' }); return }
let body: BoundHookBody
try {
const parsed = JSON.parse(await readBody(req)) as unknown
if (!validHookBody(parsed)) { json(400, { error: 'invalid hook body' }); return }
body = parsed
} catch { json(400, { error: 'bad json' }); return }
if (!await verifiedBoundMutation(body, handlers)) { json(403, { error: 'UNBOUND_HOOK' }); return }
if (body.sessionId) handlers.onTurnStart?.({ sessionId: body.sessionId })
json(200, { ok: true })
return
}
if (req.method === 'POST' && url === '/api/hook/turn-stop') {
if (!hookOk) { json(401, { error: 'UNAUTHORIZED' }); return }
let body: BoundHookBody
try {
const parsed = JSON.parse(await readBody(req)) as unknown
if (!validHookBody(parsed)) { json(400, { error: 'invalid hook body' }); return }
body = parsed
} catch { json(400, { error: 'bad json' }); return }
const delivery = req.headers['x-harness-hook-delivery-id']
if (typeof delivery === 'string') {
const pending = resolvingStops.get(delivery)?.stop ?? [...admissionReceipts.values()]
.map(history => history.records.get(delivery)?.linkedStop).find(Boolean)
const acknowledgement = await pending?.(body, hookFiredAt(req))
if (acknowledgement) { json(acknowledgement.status, acknowledgement.reply); return }
if (/^[a-zA-Z0-9_-]{16,96}$/.test(delivery) && (body.engine === 'cursor' || body.engine === 'commandcode')) {
// These native clients register this same delivery before Stop. A
// refused queue or a restarted core has no completion authority yet.
json(202, { pending: false, retry: true, detail: 'Waiting for the linked Stop registration to be admitted.' }); return
}
}
const owner = await verifiedBoundMutation(body, handlers)
if (!owner) { json(403, { error: 'UNBOUND_HOOK' }); return }
if (body.sessionId) {
const identity = paneReadIdentity(owner)
console.log(`[hooks] ${sid(body.sessionId)} turn-stop${body.status ? ` · status=${body.status}` : ''}`)
const fired = hookFiredAt(req)
const stop = { sessionId: body.sessionId, status: body.status, transcriptPath: body.transcriptPath, ...(fired ? { firedAt: fired } : {}) }
if (handlers.stopHookDelayMs) setTimeout(() => {
if (paneReadIdentity(registry.byAgent(owner.agentId)) === identity) handlers.onTurnStop?.(stop)
}, handlers.stopHookDelayMs)
else handlers.onTurnStop?.(stop)
}
json(200, { ok: true })
return
}
// `harness pair <code>` → run CPace toward the browser that is waiting to pair. Long-polls until
// the handshake completes/fails (bounded by the manager's round timers). Loopback-only; the PAKE
// itself is the security (a local process can trigger, but only the real code completes pairing).
if (req.method === 'POST' && url === '/api/pair') {
if (!localOk) { json(403, { error: 'FORBIDDEN' }); return }
if (!handlers.onPair) { json(503, { error: 'PAIRING_UNAVAILABLE' }); return }
let body: { code?: string }
try { body = JSON.parse(await readBody(req)) as { code?: string } } catch { json(400, { error: 'bad json' }); return }
if (!body.code) { json(400, { error: 'MISSING_CODE' }); return }
try { const out = await handlers.onPair(body.code); json(out.status, out.body) }
catch (e) { json(500, { error: e instanceof Error ? e.message : 'INTERNAL' }) }
return
}
// `harness remote-password set` → stretch + persist a new persistent remote password on the
// running daemon's live E2EE state (so an in-progress `harness link connect` from another
// machine sees it immediately, with no daemon restart needed).
if (req.method === 'POST' && url === '/api/remote-password/set') {
if (!localOk) { json(403, { error: 'FORBIDDEN' }); return }
if (!handlers.onSetRemotePassword) { json(503, { error: 'UNAVAILABLE' }); return }
let body: { password?: string }
try { body = JSON.parse(await readBody(req)) as { password?: string } } catch { json(400, { error: 'bad json' }); return }
if (!body.password) { json(400, { error: 'MISSING_PASSWORD' }); return }
try { const out = await handlers.onSetRemotePassword(body.password); json(out.status, out.body) }
catch (e) { json(500, { error: e instanceof Error ? e.message : 'INTERNAL' }) }
return
}
// `harness remote-password clear` → remove the persistent remote password.
if (req.method === 'POST' && url === '/api/remote-password/clear') {
if (!localOk) { json(403, { error: 'FORBIDDEN' }); return }
if (!handlers.onClearRemotePassword) { json(503, { error: 'UNAVAILABLE' }); return }
const out = await handlers.onClearRemotePassword(); json(out.status, out.body); return
}
// `harness link connect` → trust the machine just linked back, on the daemon's live E2EE state.
if (req.method === 'POST' && url === '/api/link/trust-peer') {
if (!localOk) { json(403, { error: 'FORBIDDEN' }); return }
if (!handlers.onTrustLinkedPeer) { json(503, { error: 'UNAVAILABLE' }); return }
let body: { pub?: unknown; machineId?: unknown; label?: unknown }
try { body = JSON.parse(await readBody(req)) as typeof body } catch { json(400, { error: 'bad json' }); return }
const isKey = typeof body.pub === 'string' && /^[A-Za-z0-9+/]{43}=$/.test(body.pub) // 32-byte Ed25519, base64
if (!isKey || typeof body.machineId !== 'string' || !/^[a-f0-9]{32}$/.test(body.machineId)) { json(400, { error: 'BAD_PEER' }); return }
const label = typeof body.label === 'string' && body.label.trim() ? body.label.trim().slice(0, 60) : body.machineId
const out = await handlers.onTrustLinkedPeer({ pub: body.pub as string, machineId: body.machineId, label })
json(out.status, out.body); return
}
// `harness group list` → the trust group's members. Read-only (keys and labels, no secrets).
if (req.method === 'GET' && url === '/api/group') {
if (!handlers.onGroupList) { json(503, { error: 'UNAVAILABLE' }); return }
const out = await handlers.onGroupList(); json(out.status, out.body); return
}
// `harness group sync` → compare rosters with every reachable member now.
if (req.method === 'POST' && url === '/api/group/sync') {
if (!localOk) { json(403, { error: 'FORBIDDEN' }); return }
if (!handlers.onGroupSync) { json(503, { error: 'UNAVAILABLE' }); return }
const out = await handlers.onGroupSync(); json(out.status, out.body); return
}
// `harness group remove <id|#|fp>` / `harness link unlink` → drop a member everywhere.
if (req.method === 'POST' && url === '/api/group/remove') {
if (!localOk) { json(403, { error: 'FORBIDDEN' }); return }
if (!handlers.onGroupRemove) { json(503, { error: 'UNAVAILABLE' }); return }
let body: { selector?: unknown }
try { body = JSON.parse(await readBody(req)) as typeof body } catch { json(400, { error: 'bad json' }); return }
if (typeof body.selector !== 'string' || !body.selector.trim()) { json(400, { error: 'MISSING_SELECTOR' }); return }
const out = await handlers.onGroupRemove(body.selector.trim()); json(out.status, out.body); return
}
// `harness devices list` / the window's Devices list → the account's devices, as this machine's
// verified copy of the device key log has them. Read-only (public keys and labels).
if (req.method === 'GET' && url === '/api/devices') {
if (!handlers.onDevicesList) { json(503, { error: 'UNAVAILABLE' }); return }
const out = await handlers.onDevicesList(); json(out.status, out.body); return
}
// `harness devices remove <fp>` / Remove in the window → out of the log, signed by this machine.
if (req.method === 'POST' && url === '/api/devices/remove') {
if (!localOk) { json(403, { error: 'FORBIDDEN' }); return }
if (!handlers.onDevicesRemove) { json(503, { error: 'UNAVAILABLE' }); return }
let body: { pub?: unknown }
try { body = JSON.parse(await readBody(req)) as typeof body } catch { json(400, { error: 'bad json' }); return }
if (typeof body.pub !== 'string' || !body.pub) { json(400, { error: 'MISSING_PUB' }); return }
const out = await handlers.onDevicesRemove(body.pub); json(out.status, out.body); return
}
// `harness devices rebaseline` → what trusting the backend's log again would change; `confirm`
// does it (the only way out of a frozen log).
if (req.method === 'POST' && url === '/api/devices/rebaseline') {
if (!localOk) { json(403, { error: 'FORBIDDEN' }); return }
if (!handlers.onDevicesRebaseline) { json(503, { error: 'UNAVAILABLE' }); return }
let body: { confirm?: unknown; head?: unknown }
try { body = JSON.parse(await readBody(req)) as typeof body } catch { json(400, { error: 'bad json' }); return }
if (!body || typeof body !== 'object') { json(400, { error: 'bad json' }); return }
// The head the person was shown in the preview: a confirm only goes ahead on that same list.
let head: { seq: number; hash: string } | undefined
if (body.head !== undefined) {
const h = body.head as { seq?: unknown; hash?: unknown } | null
if (!h || typeof h !== 'object' || typeof h.seq !== 'number' || !Number.isSafeInteger(h.seq) || h.seq < 0
|| typeof h.hash !== 'string' || h.hash.length > 128) { json(400, { error: 'BAD_HEAD' }); return }
head = { seq: h.seq, hash: h.hash }
}
const out = await handlers.onDevicesRebaseline(body.confirm === true, head); json(out.status, out.body); return
}
// `harness devices history` → the log's adds and removes, newest first. Local only: it is the
// account's whole device story, and the fetch behind it is a backend call as this machine.
if (req.method === 'GET' && url === '/api/devices/history') {
if (!localOk) { json(403, { error: 'FORBIDDEN' }); return }
if (!handlers.onDevicesHistory) { json(503, { error: 'UNAVAILABLE' }); return }
const out = await handlers.onDevicesHistory(); json(out.status, out.body); return
}
// `harness devices dismiss [<fp>]` / "It's mine" / "Got it" → new devices marked as seen here.
if (req.method === 'POST' && url === '/api/devices/dismiss') {
if (!localOk) { json(403, { error: 'FORBIDDEN' }); return }
if (!handlers.onDevicesDismiss) { json(503, { error: 'UNAVAILABLE' }); return }
let body: { pub?: unknown; pubs?: unknown; baseline?: unknown; confirm?: unknown }
try { body = JSON.parse(await readBody(req)) as typeof body } catch { json(400, { error: 'bad json' }); return }
if (!body || typeof body !== 'object') { json(400, { error: 'bad json' }); return }
if (body.pub !== undefined && (typeof body.pub !== 'string' || !body.pub)) { json(400, { error: 'MISSING_PUB' }); return }
// The keys a window displayed, so a key accepted since the window read the list is not cleared unseen.
if (body.pubs !== undefined && (!Array.isArray(body.pubs) || body.pubs.length > 256
|| body.pubs.some((k) => typeof k !== 'string' || !k || k.length > 256))) { json(400, { error: 'BAD_PUBS' }); return }
const out = await handlers.onDevicesDismiss({
...(typeof body.pub === 'string' ? { pub: body.pub } : {}),
...(Array.isArray(body.pubs) ? { pubs: body.pubs as string[] } : {}),
...(body.baseline === true ? { baseline: true } : {}),
// "It's mine" for one device: the account's other devices are told too (deviceLogSyncer `dismiss`).
...(body.confirm === true ? { confirm: true } : {}),
}); json(out.status, out.body); return
}
// `harness remote-password status` → whether one is set, and its fingerprint. Read-only, same
// gating tier as /api/pairs.
if (req.method === 'GET' && url === '/api/remote-password/status') {
if (!handlers.onRemotePasswordStatus) { json(503, { error: 'UNAVAILABLE' }); return }
const out = await handlers.onRemotePasswordStatus(); json(out.status, out.body); return
}
// Local GUI clients (e.g. the desktop app): read the full machine list / rename or delete one /
// read the signed-in profile through this daemon's own SSO session, so the local caller never
// 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') {
const list = handlers.onMachinesList
if (!list) { json(503, { error: 'UNAVAILABLE' }); return }
await proxied(list); return
}
if (req.method === 'GET' && url === '/api/harness-shares') {
if (!handlers.onSharedHarnesses) { json(503, { error: 'UNAVAILABLE' }); return }
await proxied(handlers.onSharedHarnesses); return
}
if (req.method === 'GET' && url === '/api/desk') {
if (!handlers.onDeskRead) { json(503, { error: 'UNAVAILABLE' }); return }
await proxied(handlers.onDeskRead); return
}
if (req.method === 'POST' && url === '/api/desk/ops') {
if (!localOk) { json(403, { error: 'FORBIDDEN' }); return }
if (!handlers.onDeskOps) { json(503, { error: 'UNAVAILABLE' }); return }
let body: unknown
try { body = JSON.parse(await readBody(req)) } catch { json(400, { error: { code: 'BAD_REQUEST', message: 'Invalid JSON body' } }); return }
await proxied(() => handlers.onDeskOps!(body)); return
}
if (req.method === 'GET' && url === '/api/agent-messages') {
if (!handlers.onAgentMessagesRead) { json(503, { error: 'UNAVAILABLE' }); return }
await proxied(handlers.onAgentMessagesRead); return
}
const agentMessagesTab = req.method === 'PATCH' ? /^\/api\/agent-messages\/tabs\/([A-Za-z0-9_-]{1,64})$/.exec(url) : null
if (agentMessagesTab) {
if (!localOk) { json(403, { error: 'FORBIDDEN' }); return }
if (!handlers.onAgentMessagesWrite) { json(503, { error: 'UNAVAILABLE' }); return }
let body: unknown
try { body = JSON.parse(await readBody(req)) } catch { json(400, { error: { code: 'BAD_REQUEST', message: 'Invalid JSON body' } }); return }
await proxied(() => handlers.onAgentMessagesWrite!(agentMessagesTab[1], body)); return
}
if (req.method === 'GET' && url === '/api/agent-settings') {
if (!handlers.onAgentSettingsRead) { json(503, { error: 'UNAVAILABLE' }); return }
await proxied(handlers.onAgentSettingsRead); return
}
if (req.method === 'PATCH' && url === '/api/agent-settings') {
if (!localOk) { json(403, { error: 'FORBIDDEN' }); return }
if (!handlers.onAgentSettingsWrite) { json(503, { error: 'UNAVAILABLE' }); return }
let body: unknown
try { body = JSON.parse(await readBody(req)) } catch { json(400, { error: { code: 'BAD_REQUEST', message: 'Invalid JSON body' } }); return }
await proxied(() => handlers.onAgentSettingsWrite!(body)); return
}
if (req.method === 'GET' && url === '/api/experimental-settings') {
if (!handlers.onExperimentalRead) { json(503, { error: 'UNAVAILABLE' }); return }
await proxied(handlers.onExperimentalRead); return
}
if (req.method === 'POST' && url === '/api/product-usage/report') {
// On every answer, a refusal too: the Desktop counts names newer than revision 1 only after
// reading it here, because a proxy that predates a name refused the whole report.
res.setHeader(APP_USAGE_VOCABULARY_HEADER, String(APP_USAGE_VOCABULARY))
if (!localOk) { json(403, { error: 'FORBIDDEN' }); return }
if (!handlers.onProductUsageReport) { json(503, { error: 'UNAVAILABLE' }); return }
let body: unknown
try {
const raw = await readBody(req, 8192)
body = JSON.parse(raw)
} catch { json(400, { error: 'BAD_REQUEST' }); return }
// Without the names this contract does not know yet; see lib/appProductUsageReport.ts.
const report = appProductUsageReport(body)
if (!report) {
json(400, { error: 'BAD_REQUEST' }); return
}
try {
const result = await handlers.onProductUsageReport(report)
// The Desktop waits a busy answer out (desktop/lib/measurement/product_measurement.dart).
if (result.retryAfterMs !== undefined) res.setHeader('Retry-After', String(Math.ceil(result.retryAfterMs / 1000)))
json(result.status, result.body)
} catch { json(502, { success: false, error: { code: 'USAGE_UNAVAILABLE', message: 'Product usage unavailable' } }) }
return
}
// A profile picture (`/avatars`) too: without it the daemon answered 404 and Desktop's Upload picture… failed
// with only "Could not upload the file".
const attachment = req.method === 'POST' ? /^\/api\/super-tabs\/[A-Za-z0-9_-]{1,160}\/(attachments|avatars)$/.exec(url) : null
if (attachment) {
if (!localOk) { json(403, { error: 'FORBIDDEN' }); return }
if (!handlers.onSuperTabAttachment) { json(503, { error: 'UNAVAILABLE' }); return }
// The body is the file, read by the handler as a stream: never readBody, which holds 256 KiB of text. An agent's
// `post --attach` names itself; the backend checks that this account runs that agent.
const asAgentId = new URLSearchParams((req.url ?? '').split('?')[1] ?? '').get('asAgentId')
const agent = asAgentId && /^[A-Za-z0-9_-]{1,160}$/.test(asAgentId) ? `?asAgentId=${asAgentId}` : ''
await handlers.onSuperTabAttachment(req, res, `${url}${agent}`); return
}
const direct = req.method === 'POST'
? /^\/api\/super-tabs\/[A-Za-z0-9_-]{1,160}\/attachments\/uploads(\/[A-Za-z0-9_-]{1,160}\/complete)?$/.exec(url) : null
if (direct) {
if (!localOk) { json(403, { error: 'FORBIDDEN' }); return }
if (!handlers.onSuperTabAttachmentUpload) { json(503, { error: 'UNAVAILABLE' }); return }
// A link's request names the file ({conversationId, name, mime, size}); a completion's is {}, and may be empty.
let body: unknown
try { const raw = await readBody(req, 8192); body = direct[1] && !raw.trim() ? {} : JSON.parse(raw) } catch { body = null }
if (!body || typeof body !== 'object' || Array.isArray(body)) { json(400, { error: 'BAD_REQUEST' }); return }
const asAgentId = new URLSearchParams((req.url ?? '').split('?')[1] ?? '').get('asAgentId')
const agent = asAgentId && /^[A-Za-z0-9_-]{1,160}$/.test(asAgentId) ? `?asAgentId=${asAgentId}` : ''
// Only the fields a link's request has: nothing else the page sends reaches the backend with this account's token.
const { conversationId, name, mime, size } = body as Record<string, unknown>
await proxied(() => handlers.onSuperTabAttachmentUpload!(`${url}${agent}`, direct[1] ? {} : { conversationId, name, mime, size })); return
}
const signInAnswer = req.method === 'POST' ? /^\/api\/auth\/qr\/(lookup|approve|deny)$/.exec(url) : null
if (signInAnswer) {
if (!localOk) { json(403, { error: 'FORBIDDEN' }); return }
if (!handlers.onSignInAnswer) { json(503, { error: 'UNAVAILABLE' }); return }
let body: unknown
try { body = JSON.parse(await readBody(req)) } catch { json(400, { error: 'BAD_REQUEST' }); return }
// The code and nothing else: whose account approves is this computer's session, never the caller's.
const code = (body as { code?: unknown } | null)?.code
if (!body || typeof body !== 'object' || Object.keys(body).length !== 1
|| typeof code !== 'string' || code.length < 1 || code.length > 128) {
json(400, { error: 'BAD_REQUEST' }); return
}
const action = signInAnswer[1] as 'lookup' | 'approve' | 'deny'
await proxied(() => handlers.onSignInAnswer!(action, { code })); return
}
if (req.method === 'POST' && url === '/api/product-usage/feedback') {
if (!localOk) { json(403, { error: 'FORBIDDEN' }); return }
if (!handlers.onProductFeedback) { json(503, { error: 'UNAVAILABLE' }); return }
let body: unknown
try { body = JSON.parse(await readBody(req)) } catch { json(400, { error: 'BAD_REQUEST' }); return }
const feedback = body as { answer?: unknown; id?: unknown } | null
if (!feedback || typeof feedback !== 'object' || Object.keys(feedback).length !== 2
|| !PRODUCT_FEEDBACK.includes(feedback.answer as never) || typeof feedback.id !== 'string'
|| !/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/i.test(feedback.id)) {
json(400, { error: 'BAD_REQUEST' }); return
}
await proxied(() => handlers.onProductFeedback!(feedback)); return
}
if (req.method === 'GET' && url === '/api/product-usage/settings') {
if (!handlers.onProductUsageRead) { json(503, { error: 'UNAVAILABLE' }); return }
await proxied(handlers.onProductUsageRead); return
}
if (req.method === 'POST' && url === '/api/product-usage/settings') {
if (!localOk) { json(403, { error: 'FORBIDDEN' }); return }
if (!handlers.onProductUsageWrite) { json(503, { error: 'UNAVAILABLE' }); return }
let body: unknown
try { body = JSON.parse(await readBody(req)) } catch { json(400, { error: 'BAD_REQUEST' }); return }
if (!body || typeof body !== 'object' || Object.keys(body).length !== 1 || typeof (body as { enabled?: unknown }).enabled !== 'boolean') {
json(400, { error: 'BAD_REQUEST' }); return
}
await proxied(() => handlers.onProductUsageWrite!(body)); return
}
if (req.method === 'PATCH' && url === '/api/experimental-settings') {
if (!localOk) { json(403, { error: 'FORBIDDEN' }); return }
if (!handlers.onExperimentalWrite) { json(503, { error: 'UNAVAILABLE' }); return }
let body: unknown
try { body = JSON.parse(await readBody(req)) } catch { json(400, { error: { code: 'BAD_REQUEST', message: 'Invalid JSON body' } }); return }
await proxied(() => handlers.onExperimentalWrite!(body)); return
}
if (req.method === 'GET' && url === '/api/auth/me') {
const me = handlers.onAuthMe
if (!me) { json(503, { error: 'UNAVAILABLE' }); return }
await proxied(me); return
}
if (req.method === 'PATCH' && url === '/api/auth/me') {
if (!localOk) { json(403, { error: 'FORBIDDEN' }); return }
if (!handlers.onAuthMeUpdate) { json(503, { error: 'UNAVAILABLE' }); return }
let body: unknown
try { body = JSON.parse(await readBody(req)) } catch { json(400, { error: { code: 'BAD_REQUEST', message: 'Invalid JSON body' } }); return }
await proxied(() => handlers.onAuthMeUpdate!(body)); return
}
// Add Phone: a code that SIGNS A PHONE IN to this account — the one local route whose answer is
// a credential. So not the CSRF header, which any local process can send, but the daemon's
// owner-only socket: the filesystem has already said this is the user who signed in. Another
// account on a shared computer reaches the loopback port, never the socket. A client on TCP is
// refused, and the Add Phone QR goes without the code (the phone asks for an emailed one).
if (req.method === 'POST' && url === '/api/auth/handoff') {
if (!trustedLocal || !localOk) { json(403, { error: 'FORBIDDEN' }); return }
if (!handlers.onAuthHandoff) { json(503, { error: 'UNAVAILABLE' }); return }
await proxied(handlers.onAuthHandoff); return
}
// Stopping the daemon ends every agent's link to it: like the phone code above, the daemon's own trusted
// endpoint only (the owner's socket; on Windows its pipe, with the token's proof, lib/localSocket.ts).
// Windows only: the route exists when its handler is given (core/daemonStopRoute.ts daemonStopRoute).
if (req.method === 'POST' && url === '/api/daemon/stop' && handlers.onDaemonStop) {
if (!trustedLocal || !localOk) { json(403, { error: 'FORBIDDEN' }); return }
await proxied(handlers.onDaemonStop); return
}
if (req.method === 'PATCH' && url.startsWith('/api/machines/')) {
if (!localOk) { json(403, { error: 'FORBIDDEN' }); 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 }
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 }
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 }
await proxied(() => remove(machineId)); return
}
// The Harness Store: ratings and reviews in the backend, through this daemon's own session. The
// rules (reads ungated, writes behind the local header, the paths it forwards) are storeProxy.ts's.
if (url.startsWith('/api/store/')) {
// A request an http.Server hands over always has its url; `url` above is it without the query.
const route = await routeStoreRequest({ method: req.method, url: req.url as string, localOk, readBody: () => readBody(req) }, handlers.onStore)
if ('forward' in route) await proxied(route.forward)
else json(route.status, route.body)
return
}
// `harness pairings` — list paired browsers.
if (req.method === 'GET' && url === '/api/pairs') {
if (!handlers.onListPairs) { json(503, { error: 'UNAVAILABLE' }); return }
const out = await handlers.onListPairs(); json(out.status, out.body); return
}
// `harness unpair <id>` — unpair one browser; signals it (if online) to re-pair.
if (req.method === 'POST' && url === '/api/revoke') {
if (!localOk) { json(403, { error: 'FORBIDDEN' }); return }
if (!handlers.onRevoke) { json(503, { error: 'UNAVAILABLE' }); return }
let body: { id?: string }
try { body = JSON.parse(await readBody(req)) as { id?: string } } catch { json(400, { error: 'bad json' }); return }
if (!body.id) { json(400, { error: 'MISSING_ID' }); return }
const out = await handlers.onRevoke(body.id); json(out.status, out.body); return
}
// `harness unpair --all` — unpair every browser.
if (req.method === 'POST' && url === '/api/revoke-all') {
if (!localOk) { json(403, { error: 'FORBIDDEN' }); return }
if (!handlers.onRevokeAll) { json(503, { error: 'UNAVAILABLE' }); return }
const out = await handlers.onRevokeAll(); json(out.status, out.body); return
}
json(404, { error: 'not found' })
})().catch((error: unknown) => {
// Whatever a handler throws, the request is answered: an engine's hook that waits on this server
// holds up that engine's turn until its own timeout, and the desktop waits out thirty seconds.
console.error(`[hooks] ${req.method} ${(req.url ?? '').split('?')[0].slice(0, 80)} failed:`, error instanceof Error ? error.message : error)
if (!res.headersSent) {
res.writeHead(500, { 'Content-Type': 'application/json' })
res.end(JSON.stringify({ error: 'INTERNAL' }))
} else if (!res.writableEnded) res.end()
})
}
const server = http.createServer(handle)
server.once('close', () => admissions.close())
return new Promise((resolve, reject) => {
let fellBack = false
const failed = (err: NodeJS.ErrnoException): void => {
if (err.code === 'EADDRINUSE' && !fellBack && options.allowPortFallback && options.socketPath) {
fellBack = true
console.log(`[hooks] control port ${port} unavailable; assigning a separate port for this user`)
server.once('error', failed)
server.listen(0, '127.0.0.1')
return
}
if (err.code === 'EADDRINUSE') {
console.error(`[hooks] 127.0.0.1:${port} is already in use — another adapter is probably running.`)
console.error(' Use a different PORT; no other user\'s daemon was stopped.')
} else {
console.error('[hooks] listen failed:', err)
}
reject(err)
}
server.once('error', failed)
server.once('listening', () => {
const actual = (server.address() as AddressInfo).port
hosts = loopbackHosts(actual)
console.log(`[hooks] listening on 127.0.0.1:${actual} (SessionStart/SessionEnd callbacks)`)
const socketPath = options.socketPath
if (!socketPath) { resolve({ server, port: actual, localSocket: null }); return }
// The private socket is mandatory when opting into multi-user startup. A duplicate daemon
// must not survive on a random port while another one owns this user's socket.
listenLocalSocket(handle, socketPath, { token: options.pipeToken ?? undefined }).then(
(localSocket) => {
console.log(`[hooks] listening on ${socketPath}`)
resolve({ server, port: actual, localSocket })
},
(error: unknown) => {
if (options.allowPortFallback) {
server.closeAllConnections()
server.close()
reject(error)
return
}
console.warn(`[hooks] local socket unavailable (${socketPath}): ${error instanceof Error ? error.message : error}`)
resolve({ server, port: actual, localSocket: null })
},
)
})
server.listen(port, '127.0.0.1')
})
}