Repository navigation
Expand file tree
/
Copy pathhook_server.ts
More file actions
422 lines (408 loc) · 21.1 KB
/
Copy pathhook_server.ts
File metadata and controls
422 lines (408 loc) · 21.1 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
/** Resident hook server: one long-lived process that answers hook calls and read-only CLI calls from an already-loaded module graph. Every hook call used to start Node and load token-goat's hook graph before a handler ran, about 60ms of a ~120ms call measured end to end; a warm process answers in the handler's own time. Up to {@link SERVER_SLOTS} of these run per data directory, each on its own pipe or socket and each serving one request at a time: a request is run with the caller's environment and working directory swapped in, which a process can only hold for one caller at once, so concurrency comes from more processes, never from interleaving inside one. The endpoint name doubles as the single-instance lock, so no pid file is needed. A server stops itself when it goes idle, when the bundle it was loaded from is replaced (the next call is then served by a fresh one), when the config turns it off, or when told to over the authenticated channel. */
import * as fs from 'node:fs'
import * as net from 'node:net'
import * as os from 'node:os'
import { serveOne, swapEnv } from './batch_serve.js'
import { hookServerEnabled } from './config.js'
import { configPath, ensureDataDirPrivate } from './constants.js'
import { limitDbWaitsForHook } from './db.js'
import { isAdapterHarness, noopFor, noopOutputs, runAdapter, type AdapterHarness } from './hook_adapters.js'
import {
bundleEntryFiles,
challengeMacV2,
configStamp,
doneFrameMac,
endpointFor,
ensureServerKey,
HARNESS_PROTOCOL_VERSION,
mac,
macMatches,
nonce,
outFrameMac,
PROTOCOL_VERSION,
readFrames,
removeMarker,
requestMacV2,
SERVER_SLOTS,
serverKeyPath,
touchMarker,
writeFrame,
type HarnessHookRequest,
type ServerReply,
type ServerRequest,
type ServerStatus,
} from './hook_ipc.js'
import { relayInProcess } from './relay.js'
import { primeHiddenRulesAhead, primeManagedPolicyAhead } from './rewrite_permission.js'
import { clearPerRequestCaches } from './reset.js'
import { VERSION } from './version.js'
/** The first slot stays up through a normal pause between turns; the overflow slots exist only for bursts of parallel tool calls and go away soon after one. */
const IDLE_EXIT_MS = { primary: 30 * 60_000, overflow: 3 * 60_000 }
/** How often a server checks that its key file is still there. Deleting it (`uninstall --purge`, or a test run cleaning up its data directory) retires every server keyed on it within this interval; one stat every two seconds costs an idle process nothing measurable. */
const KEY_CHECK_MS = 2_000
/** An unauthenticated connection that has not finished the handshake by now is dropped. */
const HANDSHAKE_IDLE_MS = 10_000
type RunCli = (argv: string[]) => Promise<void>
/** A request that does work, one at a time; status and stop are answered as they arrive. */
type WorkRequest = Extract<ServerRequest, { kind: 'hook' | 'cli' }>
function bundleStamp(): string {
return bundleEntryFiles()
.map((f) => {
try {
const st = fs.statSync(f)
return `${st.size}:${st.mtimeMs}`
} catch {
return '-'
}
})
.join('|')
}
/** {@link hookServerEnabled} as of the inputs it reads: the environment variable and config.toml, keyed on the file's path and modification time (configStamp, which the client's own autostart check keys on too). Every contact asks, and parsing config.toml each time cost about 1.5ms of a call the server answers. */
let enabledMemo: { key: string; enabled: boolean } | undefined
function stillEnabled(): boolean {
const key = `${process.env['TOKEN_GOAT_HOOK_SERVER'] ?? ''}|${configPath()}|${configStamp()}`
if (enabledMemo?.key !== key) enabledMemo = { key, enabled: hookServerEnabled() }
return enabledMemo.enabled
}
/** Why this server should stop taking requests, or `undefined` while it should keep serving. `judgeEnabled` is false while a request is in flight: that request runs under its caller's environment (swapEnv), and a TOKEN_GOAT_HOOK_SERVER there is the caller's, not this server's, so the switch is read again at the next contact between requests. */
function retirementReason(loadedStamp: string, judgeEnabled: boolean): string | undefined {
if (bundleStamp() !== loadedStamp) return 'bundle replaced'
if (judgeEnabled && !stillEnabled()) return 'disabled'
return undefined
}
/** Serve one request. `send` hands the answer to the caller's socket and returns at once: the server is free for the next call as soon as this returns, however long the caller takes to read what it was sent. */
async function handle(request: WorkRequest, runCli: RunCli, send: (res: ServerReply) => void): Promise<void> {
clearPerRequestCaches()
if (request.kind === 'cli') {
const res = await serveOne({ id: 0, argv: request.argv, cwd: request.cwd, env: request.env }, runCli, clearPerRequestCaches)
return send({ ok: true, stdout: res.stdout, stderr: res.stderr, status: res.status })
}
// A hook request is the agent's tool call, so its connections wait as a one-shot hook's do; the per-request reset in the finally below hands the patient waits back to the CLI requests this process serves next.
limitDbWaitsForHook()
const startedAt = performance.now()
const cwdBefore = process.cwd()
const restoreEnv = swapEnv(request.env)
const afterReply: (() => void)[] = []
try {
process.chdir(request.cwd)
const payload: unknown = JSON.parse(request.input)
// What the caller waited on is its own time up to sending this request plus the time spent here, not this process's age.
const stdout = await relayInProcess(request.event, payload, request.harnessWaitMs, { elapsedMs: () => request.elapsedMs + (performance.now() - startedAt), afterReply: (work) => afterReply.push(work) })
// The caller has its answer before the stats row is written and the connections are closed, and both still run under this request's environment and directory. The session state the next call reads was saved before the answer, so nothing a follow-up call depends on is left behind it.
send({ ok: true, stdout })
for (const work of afterReply) work()
} finally {
restoreEnv()
try {
process.chdir(cwdBefore)
} catch {
// the directory it sat in between requests is the temp directory, which outlives it
}
clearPerRequestCaches()
}
}
/** A v2 request body as sent, or `undefined` when it is not a well-formed hook request naming `harness`. */
function parseHarnessRequest(body: string, harness: AdapterHarness): HarnessHookRequest | undefined {
let r: unknown
try {
r = JSON.parse(body)
} catch {
return undefined
}
if (r === null || typeof r !== 'object') return undefined
const q = r as Record<string, unknown>
const env = q['env']
const wellFormed =
q['kind'] === 'hook' &&
q['harness'] === harness &&
typeof q['event'] === 'string' &&
typeof q['input'] === 'string' &&
typeof q['cwd'] === 'string' &&
typeof q['elapsedMs'] === 'number' &&
(q['harnessWaitMs'] === undefined || typeof q['harnessWaitMs'] === 'number') &&
(q['scriptDir'] === undefined || typeof q['scriptDir'] === 'string') &&
env !== null &&
typeof env === 'object' &&
!Array.isArray(env) &&
Object.values(env).every((v) => typeof v === 'string')
return wellFormed ? (q as unknown as HarnessHookRequest) : undefined
}
/** Serve one v2 request through its harness's adapter (hook_adapters.ts). `early` sends an `out` frame at once; `finish` sends the `done` frame, after which the stats row is written, as {@link handle} does for v1. */
async function handleHarness(request: HarnessHookRequest, harness: AdapterHarness, early: (data: string) => void, finish: (stdout: string, exit: number) => void): Promise<void> {
clearPerRequestCaches()
// Same short database waits as a hook request over the v1 protocol; see handle.
limitDbWaitsForHook()
const startedAt = performance.now()
const cwdBefore = process.cwd()
const restoreEnv = swapEnv(request.env)
const afterReply: (() => void)[] = []
const elapsedMs = (): number => request.elapsedMs + (performance.now() - startedAt)
try {
process.chdir(request.cwd)
const req = { event: request.event, input: request.input, ...(request.harnessWaitMs === undefined ? {} : { harnessWaitMs: request.harnessWaitMs }), ...(request.scriptDir === undefined ? {} : { scriptDir: request.scriptDir }) }
const result = await runAdapter(harness, req, {
// An early frame is where the harness stops waiting, so the wait it records is its own clock up to here.
early: (data) => {
early(data)
return elapsedMs()
},
// Only native/tg-hook speaks this protocol, so every call served here is one the native client had served.
relay: (event, payload, harnessWaitMs) => relayInProcess(event, payload, harnessWaitMs, { elapsedMs, afterReply: (work) => afterReply.push(work), detail: 'native' }),
})
finish(result.stdout, result.exit)
for (const work of afterReply) work()
} finally {
restoreEnv()
try {
process.chdir(cwdBefore)
} catch {
// the directory it sat in between requests is the temp directory, which outlives it
}
clearPerRequestCaches()
}
}
/** Listen on `endpoint`, replacing a Unix socket file left behind by a server that died. Resolves `false` when a live server already holds the endpoint. */
function listen(server: net.Server, endpoint: string): Promise<boolean> {
const tryListen = (): Promise<NodeJS.ErrnoException | undefined> =>
new Promise((resolve) => {
server.once('error', resolve)
server.listen({ path: endpoint, readableAll: false, writableAll: false }, () => {
server.removeListener('error', resolve)
resolve(undefined)
})
})
return tryListen().then(async (err) => {
if (err === undefined) return true
if (err.code !== 'EADDRINUSE' || process.platform === 'win32') return false
// A socket file with nobody behind it refuses the connection; one with a live server accepts it.
const alive = await new Promise<boolean>((resolve) => {
const probe = net.connect(endpoint)
probe.once('connect', () => {
probe.destroy()
resolve(true)
})
probe.once('error', () => resolve(false))
})
if (alive) return false
fs.rmSync(endpoint, { force: true })
return (await tryListen()) === undefined
})
}
/** Run a server on `slot` until it retires. `runCli` is the CLI entry point, passed in rather than imported because the CLI is what imports this module. */
export async function runHookServer(slot: number, runCli: RunCli): Promise<void> {
if (!Number.isInteger(slot) || slot < 0 || slot >= SERVER_SLOTS) throw new Error(`--slot must be an integer from 0 to ${SERVER_SLOTS - 1}`)
if (!hookServerEnabled()) {
touchMarker('disabled', configStamp())
return
}
ensureDataDirPrivate()
primeHiddenRulesAhead()
primeManagedPolicyAhead()
const key = ensureServerKey()
const keyPath = serverKeyPath()
const loadedStamp = bundleStamp()
const endpoint = endpointFor(slot)
// Relative paths anywhere below resolve against the caller's directory, which each request sets. Between requests the server sits in the temp directory: a working directory cannot be deleted on Windows, and the temp directory is the one place nothing ever tries to.
process.chdir(os.tmpdir())
const status: ServerStatus = { pid: process.pid, slot, version: VERSION, startedAt: Date.now(), lastUsedAt: Date.now(), served: 0, errors: 0 }
let busy = false
let retiring = false
let idleTimer: NodeJS.Timeout | undefined
// Answers still draining to callers. Serving the next call never waits on these; exiting does, so an answer already sent is never cut short.
const flushing = new Set<Promise<void>>()
// Callers holding a challenge whose request has not arrived. Such a caller counts its request as handed over once sent, and one never answered fails open to `{}`, so a server that stops tells each of them it is retiring, which they read as "run it yourself", rather than exiting under them.
const awaitingRequest = new Set<net.Socket>()
/** Send `frame` as the last word on `socket`, held in `flushing` until it has left this process. */
const endWith = (socket: net.Socket, frame: Record<string, unknown>): void => {
const flushed = new Promise<void>((resolve) => {
socket.once('close', () => resolve())
writeFrame(socket, frame)
socket.end(() => resolve())
})
flushing.add(flushed)
void flushed.then(() => flushing.delete(flushed))
}
// The inode of the socket file this server created. Two servers started past the same dead socket file each remove it and listen, leaving one on a file the other replaced: reachable by nobody, so it exits, and without the close that would unlink the other's socket. Named pipes on Windows have no file to lose.
let socketIno: bigint | undefined
const ownsEndpoint = (): boolean => {
if (socketIno === undefined) return true
try {
return fs.statSync(endpoint, { bigint: true, throwIfNoEntry: false })?.ino === socketIno
} catch {
// A path this server cannot even look at is not one to decide it has lost.
return true
}
}
const server = net.createServer((socket) => serveConnection(socket))
const exitOnceFlushed = (): void => void Promise.all(flushing).then(() => process.exit(0))
// Stop accepting at once, and exit as soon as no request is in flight; one that is finishes and exits on its way out.
const stop = (): void => {
retiring = true
if (idleTimer !== undefined) clearTimeout(idleTimer)
// Closing a Unix socket server unlinks its path, which by now may belong to another server; exiting without the close leaves that file alone.
if (ownsEndpoint()) server.close()
for (const socket of awaitingRequest) endWith(socket, { t: 'stale' })
awaitingRequest.clear()
if (!busy) exitOnceFlushed()
}
const armIdle = (): void => {
if (idleTimer !== undefined) clearTimeout(idleTimer)
idleTimer = setTimeout(stop, slot === 0 ? IDLE_EXIT_MS.primary : IDLE_EXIT_MS.overflow)
}
function serveConnection(socket: net.Socket): void {
let nc = ''
let ns = ''
// Set by a v2 hello: the harness whose adapter answers this connection.
let harness: AdapterHarness | undefined
socket.setTimeout(HANDSHAKE_IDLE_MS, () => socket.destroy())
socket.on('error', () => socket.destroy())
socket.once('close', () => awaitingRequest.delete(socket))
const onMessage = (msg: Record<string, unknown>): void => {
if (msg['t'] === 'hello' && nc === '') {
const v2 = msg['v'] === HARNESS_PROTOCOL_VERSION
if ((msg['v'] !== PROTOCOL_VERSION && !v2) || typeof msg['nc'] !== 'string' || msg['nc'] === '') return void socket.destroy()
if (v2) {
if (typeof msg['h'] !== 'string') return void socket.destroy()
// A harness this build has no adapter for is one it cannot answer for: the client runs its own fallback, which is the command wired today.
if (!isAdapterHarness(msg['h'])) return void endWith(socket, { t: 'refused', reason: 'unknown harness' })
harness = msg['h']
}
const reason = retiring ? 'retiring' : retirementReason(loadedStamp, !busy)
if (reason !== undefined) {
if (reason === 'disabled') touchMarker('disabled', configStamp())
// A newer build is on disk and this server started fine, so nothing argues for making the next call wait out the start throttle before the new build is running: an upgrade within half a minute of this server starting would otherwise leave every call cold until it lapsed.
if (reason === 'bundle replaced') removeMarker(`spawn-${slot}`)
writeFrame(socket, { t: 'stale' })
socket.end(() => {
if (!retiring) stop()
})
return
}
// A status or stop request is answered without waiting for the one in flight, so `hook-server stop` reaches a server mid-request.
if (busy && (harness !== undefined || msg['ctl'] !== true)) {
writeFrame(socket, { t: 'busy' })
return void socket.end()
}
nc = msg['nc']
ns = nonce()
if (harness === undefined) {
writeFrame(socket, { t: 'challenge', v: PROTOCOL_VERSION, ns, mac: mac(key, 'S', nc, ns) })
} else {
const { noop, noops } = noopOutputs(harness)
writeFrame(socket, { t: 'challenge', v: HARNESS_PROTOCOL_VERSION, ns, noop, noops, mac: challengeMacV2(key, nc, ns, harness, noop, noops) })
}
awaitingRequest.add(socket)
return
}
if (msg['t'] === 'req' && ns !== '' && harness !== undefined) {
const h = harness
const body = msg['body']
if (typeof body !== 'string' || !macMatches(requestMacV2(key, nc, ns, h, body), msg['mac'])) return void socket.destroy()
if (!awaitingRequest.delete(socket)) return
const request = parseHarnessRequest(body, h)
if (request === undefined) return void socket.destroy()
if (busy || retiring) {
writeFrame(socket, { t: retiring ? 'stale' : 'busy' })
return void socket.end()
}
busy = true
socket.setTimeout(0)
// `out` frames are numbered from 0 and `done` says how many there were, so a client verifying the MACs sees any frame dropped, reordered or replayed. Only the first `done` is sent: a failure after it has nothing left to answer.
let seq = 0
let finished = false
const early = (data: string): void => {
if (finished) return
writeFrame(socket, { t: 'out', seq, data, mac: outFrameMac(key, nc, ns, seq, data) })
seq++
}
const finish = (stdout: string, exit: number): void => {
if (finished) return
finished = true
endWith(socket, { t: 'done', stdout, exit, n: seq, mac: doneFrameMac(key, nc, ns, stdout, exit, seq) })
}
void (async () => {
try {
await handleHarness(request, h, early, finish)
status.served++
} catch {
status.errors++
// What this harness prints when a request is lost, which is what the v1 path fails open to once the shim has translated it.
finish(noopFor(h, request.event), 0)
}
busy = false
status.lastUsedAt = Date.now()
if (retiring) stop()
else armIdle()
})()
return
}
if (msg['t'] === 'req' && ns !== '') {
const body = msg['body']
if (typeof body !== 'string' || !macMatches(mac(key, 'C', nc, ns, body), msg['mac'])) return void socket.destroy()
// Already told it is retiring: the request crossed that answer on the wire, and the caller is running it itself.
if (!awaitingRequest.delete(socket)) return
let request: ServerRequest | undefined
let parseError: unknown
try {
request = JSON.parse(body) as ServerRequest
} catch (e) {
parseError = e
}
const kind = (request as { kind?: unknown } | null | undefined)?.kind
if (kind === 'status' || kind === 'stop') {
const resBody = JSON.stringify({ ok: true, info: { ...status } } satisfies ServerReply)
endWith(socket, { t: 'res', mac: mac(key, 'R', nc, ns, resBody), body: resBody })
// Exits once the answer has left, or once a request in flight has been answered.
if (kind === 'stop' && !retiring) stop()
return
}
// Another caller may have been dispatched between this one's challenge and its request, or asked this server to stop.
if (busy || retiring) {
writeFrame(socket, { t: retiring ? 'stale' : 'busy' })
return void socket.end()
}
busy = true
socket.setTimeout(0)
// Only the first reply is sent: a failure after it has nothing left to answer. The reply drains on this socket alone, so a caller slow to read it holds up nobody but itself; until it has left this process (or the caller hung up) it sits in `flushing`, which an exit waits on.
let replied = false
const reply = (res: ServerReply): void => {
if (replied) return
replied = true
const resBody = JSON.stringify(res)
endWith(socket, { t: 'res', mac: mac(key, 'R', nc, ns, resBody), body: resBody })
}
void (async () => {
try {
if (request === undefined) throw parseError
await handle(request as WorkRequest, runCli, reply)
status.served++
} catch (e) {
status.errors++
reply({ ok: false, error: e instanceof Error ? e.message : String(e) })
}
busy = false
status.lastUsedAt = Date.now()
if (retiring) stop()
else armIdle()
})()
return
}
socket.destroy()
}
readFrames(socket, onMessage, () => undefined)
}
if (!(await listen(server, endpoint))) return
if (process.platform !== 'win32') socketIno = fs.statSync(endpoint, { bigint: true }).ino
removeMarker('failed')
setInterval(() => {
if (!fs.existsSync(keyPath) || !ownsEndpoint()) stop()
}, KEY_CHECK_MS).unref()
if (process.platform !== 'win32') {
try {
fs.chmodSync(endpoint, 0o600)
} catch {
// the handshake, not the socket mode, is what keeps other users out
}
}
armIdle()
}