@xiangyixie/dsh-superagent 0.12.1 → 0.14.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/lib/console.js ADDED
@@ -0,0 +1,763 @@
1
+ /**
2
+ * dsh-superagent — a loopback conversation console.
3
+ *
4
+ * The page is a real conversation against a host Session (`sessionController`)
5
+ * and a live run panel beside it. This module owns the socket, the one-time
6
+ * token, the Host header check, and the SSE fan-out; it does not invent an
7
+ * assistant. When the host exposes no conversation session API the page says so
8
+ * and never pretends to be a chat.
9
+ *
10
+ * @module dsh-superagent/console
11
+ */
12
+ import { randomBytes } from 'node:crypto'
13
+ import fsp from 'node:fs/promises'
14
+ import { createServer } from 'node:http'
15
+ import path from 'node:path'
16
+ import {
17
+ errorPayload,
18
+ readJson,
19
+ sameToken,
20
+ send,
21
+ sendText,
22
+ statusFor,
23
+ WorkbenchError,
24
+ } from './workbench.js'
25
+
26
+ const DISCOVERY_FILE = 'console.json'
27
+ const MAX_CLIENTS = 16
28
+ const MAX_TEXT = 20_000
29
+ const MAX_FRAME_BYTES = 512 * 1024
30
+ const MAX_BUFFERED_BYTES = 4 * 1024 * 1024
31
+ const MAX_RECORDS = 400
32
+ const MAX_RECORD_BYTES = 1024 * 1024
33
+ const HEARTBEAT_MS = 15_000
34
+ const RUN_POLL_MS = 1_200
35
+ const REQUEST_TIMEOUT_MS = 30_000
36
+ const ROUTE_HINT = 'GET / serves the console; the JSON API is under /api/console.'
37
+
38
+ /** @param {unknown} value @returns {string} */
39
+ function messageOf(value) {
40
+ return value instanceof Error ? value.message : String(value)
41
+ }
42
+
43
+ /**
44
+ * Cap one SSE frame. A large history snapshot must not let one write pin the
45
+ * socket or grow without bound; the page is told what was dropped instead.
46
+ *
47
+ * @param {object} frame - frame produced by the host adapter.
48
+ * @returns {object} a JSON-safe frame, or a truncation marker.
49
+ */
50
+ function boundedFrame(frame) {
51
+ if (!frame || typeof frame !== 'object') return { type: 'error', code: 'bad-frame' }
52
+ let text
53
+ try {
54
+ text = JSON.stringify(frame)
55
+ } catch (error) {
56
+ return { type: 'error', code: 'unserializable-frame', message: messageOf(error) }
57
+ }
58
+ const bytes = Buffer.byteLength(text)
59
+ if (bytes > MAX_FRAME_BYTES) {
60
+ return {
61
+ type: 'truncated',
62
+ frameType: typeof frame.type === 'string' ? frame.type : 'unknown',
63
+ bytes,
64
+ limit: MAX_FRAME_BYTES,
65
+ }
66
+ }
67
+ return frame
68
+ }
69
+
70
+ /**
71
+ * Cap the opening history by trimming its oldest records rather than replacing
72
+ * the whole frame: a long conversation must still show what just happened.
73
+ *
74
+ * @param {object} frame - `stream.snapshot` frame from the host adapter.
75
+ * @returns {object} a frame that fits one SSE write.
76
+ */
77
+ function boundedSnapshot(frame) {
78
+ let records = Array.isArray(frame.records) ? frame.records.slice() : []
79
+ let dropped = Number.isInteger(frame.droppedRecords) ? frame.droppedRecords : 0
80
+ const build = () => ({
81
+ ...frame,
82
+ records,
83
+ ...(dropped > 0 ? { droppedRecords: dropped } : {}),
84
+ })
85
+ let text = JSON.stringify(build())
86
+ while (Buffer.byteLength(text) > MAX_FRAME_BYTES && records.length > 0) {
87
+ const cut = Math.max(1, Math.ceil(records.length / 4))
88
+ records = records.slice(cut)
89
+ dropped += cut
90
+ text = JSON.stringify(build())
91
+ }
92
+ return Buffer.byteLength(text) > MAX_FRAME_BYTES ? boundedFrame(frame) : build()
93
+ }
94
+
95
+ /**
96
+ * Create one loopback console.
97
+ *
98
+ * @param {object} options - dependencies.
99
+ * @param {number} options.port - 1–65535, or 0 for an ephemeral port.
100
+ * @param {string} options.stateRoot - plugin state directory for the discovery file.
101
+ * @param {object} options.host - host adapter; see README.
102
+ * @param {string} options.version - plugin version reported by `/api/health`.
103
+ * @param {(message: string) => void} [options.log] - diagnostics sink.
104
+ */
105
+ export function createConsole({ port, stateRoot, host, version, log = () => {} }) {
106
+ if (!host || typeof host !== 'object') throw new Error('createConsole needs a host adapter')
107
+ const token = randomBytes(32).toString('base64url')
108
+ const instanceId = randomBytes(6).toString('hex')
109
+ const discoveryPath = path.join(stateRoot, DISCOVERY_FILE)
110
+ const startedAt = new Date().toISOString()
111
+ const clients = new Set()
112
+ let boundPort = null
113
+ let server = null
114
+ let page = null
115
+ let starting = null
116
+ let closing = null
117
+ let stopRequested = false
118
+ let currentSessionId = null
119
+ let unsubscribe = null
120
+ let runTimer = null
121
+ let lastRuns = null
122
+ let lastRunsJson = ''
123
+ let seq = 0
124
+ // The host's follow opening is not a reliable transcript: after a turn its
125
+ // snapshot can come back with only the session's setup records, so a
126
+ // reconnect that trusted it showed an empty conversation. Keep our own
127
+ // bounded copy of the durable session events and rebuild the opening window
128
+ // from it instead.
129
+ const store = {
130
+ sessionId: null,
131
+ header: null,
132
+ cursor: -1,
133
+ dropped: 0,
134
+ entries: [],
135
+ bytes: 0,
136
+ seen: new Set(),
137
+ }
138
+
139
+ const url = () => `http://127.0.0.1:${boundPort}`
140
+ const allowedHosts = () => new Set([
141
+ `127.0.0.1:${boundPort}`,
142
+ `localhost:${boundPort}`,
143
+ `[::1]:${boundPort}`,
144
+ ])
145
+
146
+ function capabilities() {
147
+ try {
148
+ const value = host.capabilities()
149
+ if (!value || typeof value !== 'object') return { chat: false, reason: 'the host returned no capabilities' }
150
+ return {
151
+ chat: value.chat === true,
152
+ reason: typeof value.reason === 'string' && value.reason.trim() ? value.reason.trim() : null,
153
+ }
154
+ } catch (error) {
155
+ return { chat: false, reason: `cannot read host capabilities: ${messageOf(error)}` }
156
+ }
157
+ }
158
+
159
+ function authorize(req, { allowQuery = false } = {}) {
160
+ if (!boundPort) {
161
+ throw new WorkbenchError(503, 'the console is not listening yet', { id: 'not-ready' })
162
+ }
163
+ const hostHeader = String(req.headers.host ?? '').toLowerCase()
164
+ if (!allowedHosts().has(hostHeader)) {
165
+ throw new WorkbenchError(403, `unexpected Host header "${hostHeader}"; the console answers only on 127.0.0.1 and localhost`, {
166
+ id: 'forbidden-host',
167
+ hint: `open ${url()} directly.`,
168
+ })
169
+ }
170
+ const header = String(req.headers.authorization ?? '')
171
+ const match = /^Bearer\s+(\S+)$/i.exec(header)
172
+ let given = match?.[1] ?? ''
173
+ if (!given && allowQuery) {
174
+ const query = new URL(req.url ?? '/', 'http://127.0.0.1').searchParams.get('token')
175
+ if (query) given = query
176
+ }
177
+ if (!given || !sameToken(given, token)) {
178
+ throw new WorkbenchError(401, 'missing or wrong access token', {
179
+ id: 'unauthorized',
180
+ hint: `read the "token" field in ${discoveryPath}, then open "url?token=<token>" once. `
181
+ + 'The token is regenerated each time the host starts.',
182
+ })
183
+ }
184
+ }
185
+
186
+ function nextSeq() {
187
+ seq += 1
188
+ return seq
189
+ }
190
+
191
+ function writeFrame(res, frame) {
192
+ if (res.destroyed || res.writableEnded) return false
193
+ const body = JSON.stringify(frame)
194
+ res.write(`event: console\ndata: ${body}\n\n`)
195
+ // A `false` return is ordinary backpressure, not a dead socket. The socket
196
+ // keeps the bytes; only a tab that let its buffer grow past the cap is
197
+ // dropped, so one stalled reader cannot pin memory for everyone.
198
+ if (res.writableLength > MAX_BUFFERED_BYTES) {
199
+ log(`console: dropping a stream that stopped reading (${res.writableLength} bytes buffered)`)
200
+ res.destroy()
201
+ clients.delete(res)
202
+ return false
203
+ }
204
+ return true
205
+ }
206
+
207
+ function broadcast(frame) {
208
+ const withSeq = { ...boundedFrame(frame), seq: nextSeq(), at: new Date().toISOString() }
209
+ for (const res of clients) {
210
+ try {
211
+ writeFrame(res, withSeq)
212
+ } catch {
213
+ clients.delete(res)
214
+ }
215
+ }
216
+ return withSeq
217
+ }
218
+
219
+ function resetStore(sessionId = null) {
220
+ store.sessionId = sessionId
221
+ store.header = null
222
+ store.cursor = -1
223
+ store.dropped = 0
224
+ store.entries = []
225
+ store.bytes = 0
226
+ store.seen = new Set()
227
+ }
228
+
229
+ /**
230
+ * Add durable records to the transcript window, skipping ones already held.
231
+ *
232
+ * @param {Array<object>} records - `SessionHistoryRecord`s from the host.
233
+ * @returns {number} how many records were new.
234
+ */
235
+ function mergeRecords(records) {
236
+ if (!Array.isArray(records) || records.length === 0) return 0
237
+ let added = 0
238
+ for (const record of records) {
239
+ const eventSeq = record?.type === 'event' ? record.event?.seq : undefined
240
+ if (Number.isInteger(eventSeq)) {
241
+ if (store.seen.has(eventSeq)) continue
242
+ store.seen.add(eventSeq)
243
+ if (eventSeq > store.cursor) store.cursor = eventSeq
244
+ }
245
+ const size = Buffer.byteLength(JSON.stringify(record))
246
+ store.entries.push({ record, seq: Number.isInteger(eventSeq) ? eventSeq : -1, size })
247
+ store.bytes += size
248
+ added += 1
249
+ }
250
+ if (!added) return 0
251
+ store.entries.sort((left, right) => left.seq - right.seq)
252
+ while (store.entries.length > MAX_RECORDS || (store.bytes > MAX_RECORD_BYTES && store.entries.length > 1)) {
253
+ const entry = store.entries.shift()
254
+ store.bytes -= entry.size
255
+ if (entry.seq >= 0) store.seen.delete(entry.seq)
256
+ store.dropped += 1
257
+ }
258
+ return added
259
+ }
260
+
261
+ function transcriptFrame() {
262
+ if (!store.sessionId || store.entries.length === 0) return null
263
+ return {
264
+ type: 'stream.snapshot',
265
+ header: store.header ?? { id: store.sessionId },
266
+ cursor: store.cursor,
267
+ records: store.entries.map(entry => entry.record),
268
+ hasMore: false,
269
+ ...(store.dropped > 0 ? { droppedRecords: store.dropped } : {}),
270
+ }
271
+ }
272
+
273
+ function detach() {
274
+ if (runTimer) {
275
+ clearInterval(runTimer)
276
+ runTimer = null
277
+ }
278
+ if (typeof unsubscribe === 'function') {
279
+ try {
280
+ unsubscribe()
281
+ } catch (error) {
282
+ log(`console: cannot stop the session stream: ${messageOf(error)}`)
283
+ }
284
+ }
285
+ unsubscribe = null
286
+ lastRuns = null
287
+ lastRunsJson = ''
288
+ }
289
+
290
+ async function refreshRuns({ force = false } = {}) {
291
+ const sessionId = currentSessionId
292
+ if (!sessionId) return []
293
+ let runs
294
+ try {
295
+ runs = await host.listRuns(sessionId)
296
+ } catch (error) {
297
+ log(`console: cannot list runs for ${sessionId}: ${messageOf(error)}`)
298
+ if (force) {
299
+ throw new WorkbenchError(502, `cannot list runs for this conversation: ${messageOf(error)}`, {
300
+ id: 'runs-unavailable',
301
+ })
302
+ }
303
+ return []
304
+ }
305
+ const rows = Array.isArray(runs) ? runs : []
306
+ const json = JSON.stringify(rows)
307
+ lastRuns = rows
308
+ if (force || json !== lastRunsJson) {
309
+ lastRunsJson = json
310
+ broadcast({ type: 'runs', sessionId, runs: rows })
311
+ }
312
+ return rows
313
+ }
314
+
315
+ function attach(sessionId) {
316
+ if (typeof host.subscribe !== 'function' || unsubscribe) return
317
+ try {
318
+ unsubscribe = host.subscribe(sessionId, frame => {
319
+ if (currentSessionId !== sessionId) return
320
+ if (!frame || typeof frame !== 'object') return
321
+ if (frame.type === 'stream.snapshot') {
322
+ if (frame.header) store.header = frame.header
323
+ const added = mergeRecords(frame.records)
324
+ // Forward the opening only when it carried records we did not hold.
325
+ // Replaying the host's post-turn snapshot (usually just the setup
326
+ // records) would make the page clear the history it already has.
327
+ if (added > 0) {
328
+ const merged = transcriptFrame()
329
+ if (merged) broadcast(boundedSnapshot(merged))
330
+ }
331
+ return
332
+ }
333
+ if (frame.type === 'session.event' && frame.event) {
334
+ mergeRecords([{ type: 'event', event: frame.event }])
335
+ }
336
+ broadcast(frame)
337
+ })
338
+ } catch (error) {
339
+ log(`console: cannot subscribe to conversation ${sessionId}: ${messageOf(error)}`)
340
+ broadcast({
341
+ type: 'error',
342
+ code: 'stream-unavailable',
343
+ message: `the conversation stream could not start: ${messageOf(error)}`,
344
+ })
345
+ }
346
+ runTimer = setInterval(() => {
347
+ refreshRuns().catch(() => {})
348
+ }, RUN_POLL_MS)
349
+ runTimer.unref?.()
350
+ refreshRuns({ force: true }).catch(() => {})
351
+ }
352
+
353
+ async function createSession() {
354
+ const caps = capabilities()
355
+ if (!caps.chat) {
356
+ throw new WorkbenchError(503, caps.reason ?? 'the host exposes no conversation session API', {
357
+ id: 'console-unavailable',
358
+ hint: 'the host must mount sessionController; this page does not fake a conversation when it is missing.',
359
+ })
360
+ }
361
+ let created
362
+ try {
363
+ created = await host.createSession()
364
+ } catch (error) {
365
+ throw new WorkbenchError(502, `cannot create a conversation session: ${messageOf(error)}`, {
366
+ id: 'session-create-failed',
367
+ })
368
+ }
369
+ const sessionId = created?.sessionId
370
+ if (typeof sessionId !== 'string' || !sessionId) {
371
+ throw new WorkbenchError(502, 'the host created a session but returned no id', { id: 'session-create-failed' })
372
+ }
373
+ if (currentSessionId !== sessionId) {
374
+ detach()
375
+ currentSessionId = sessionId
376
+ resetStore(sessionId)
377
+ // The follow stream opens with a snapshot, so it starts when the first
378
+ // browser subscribes rather than when the session is created. Otherwise
379
+ // the snapshot is written to nobody.
380
+ broadcast({ type: 'session', sessionId, mode: 'chat' })
381
+ // A page that is already listening asked for the new conversation, so
382
+ // re-attach for it instead of waiting for another connection.
383
+ if (clients.size > 0) attach(sessionId)
384
+ }
385
+ return { sessionId, capabilities: caps }
386
+ }
387
+
388
+ async function ensureSession() {
389
+ if (currentSessionId) return { sessionId: currentSessionId, capabilities: capabilities() }
390
+ return createSession()
391
+ }
392
+
393
+ async function state() {
394
+ const caps = capabilities()
395
+ return {
396
+ mode: caps.chat ? 'chat' : 'unavailable',
397
+ capabilities: caps,
398
+ sessionId: currentSessionId,
399
+ runs: currentSessionId ? lastRuns ?? [] : [],
400
+ }
401
+ }
402
+
403
+ function openStream(req, res) {
404
+ const caps = capabilities()
405
+ if (!caps.chat) {
406
+ throw new WorkbenchError(503, caps.reason ?? 'the host exposes no conversation session API', {
407
+ id: 'console-unavailable',
408
+ })
409
+ }
410
+ if (clients.size >= MAX_CLIENTS) {
411
+ throw new WorkbenchError(503, 'too many console streams are already open', { id: 'too-many-streams' })
412
+ }
413
+ if (!currentSessionId) {
414
+ throw new WorkbenchError(409, 'create a conversation session before opening the event stream', {
415
+ id: 'no-session',
416
+ hint: 'POST /api/console/session first.',
417
+ })
418
+ }
419
+ res.writeHead(200, {
420
+ 'content-type': 'text/event-stream; charset=utf-8',
421
+ 'cache-control': 'no-cache, no-transform',
422
+ connection: 'keep-alive',
423
+ 'x-accel-buffering': 'no',
424
+ 'x-content-type-options': 'nosniff',
425
+ 'content-security-policy': "default-src 'none'",
426
+ })
427
+ res.flushHeaders?.()
428
+ clients.add(res)
429
+ writeFrame(res, {
430
+ type: 'hello',
431
+ seq: nextSeq(),
432
+ at: new Date().toISOString(),
433
+ sessionId: currentSessionId,
434
+ mode: 'chat',
435
+ capabilities: caps,
436
+ })
437
+ // Every tab — first, second, or a reconnect — starts from the transcript
438
+ // the console accumulated for this conversation, so a refresh shows the
439
+ // same history instead of an empty page.
440
+ const cached = store.sessionId === currentSessionId ? transcriptFrame() : null
441
+ if (cached) {
442
+ writeFrame(res, { ...boundedSnapshot(cached), seq: nextSeq(), at: new Date().toISOString() })
443
+ }
444
+ if (lastRuns) {
445
+ writeFrame(res, { type: 'runs', seq: nextSeq(), at: new Date().toISOString(), sessionId: currentSessionId, runs: lastRuns })
446
+ }
447
+ attach(currentSessionId)
448
+ const heartbeat = setInterval(() => {
449
+ if (res.destroyed || res.writableEnded) return
450
+ try {
451
+ res.write(': ping\n\n')
452
+ } catch {
453
+ // The close handler below removes the client.
454
+ }
455
+ }, HEARTBEAT_MS)
456
+ heartbeat.unref?.()
457
+ const cleanup = () => {
458
+ clearInterval(heartbeat)
459
+ clients.delete(res)
460
+ // With nobody watching there is no reason to keep the follow loop alive.
461
+ // The transcript stays cached so a reconnect can rebuild the page.
462
+ if (clients.size === 0) detach()
463
+ }
464
+ req.on('close', cleanup)
465
+ res.on('close', cleanup)
466
+ res.on('error', cleanup)
467
+ }
468
+
469
+ async function handle(req, res) {
470
+ try {
471
+ const parsed = new URL(req.url ?? '/', 'http://127.0.0.1')
472
+ const method = req.method ?? 'GET'
473
+ const pathname = parsed.pathname
474
+
475
+ if (pathname === '/' || pathname === '/console' || pathname === '/index.html') {
476
+ if (method !== 'GET') throw new WorkbenchError(405, 'only GET is allowed here', { id: 'method-not-allowed' })
477
+ authorize(req, { allowQuery: true })
478
+ sendText(res, 200, page, 'text/html; charset=utf-8', {
479
+ 'content-security-policy': "default-src 'none'; script-src 'unsafe-inline'; style-src 'unsafe-inline'; "
480
+ + "connect-src 'self'; img-src 'self' data:; base-uri 'none'; form-action 'none'; frame-ancestors 'none'",
481
+ })
482
+ return
483
+ }
484
+
485
+ authorize(req)
486
+ const parts = pathname.split('/').filter(Boolean)
487
+ if (parts[0] !== 'api' || parts[1] !== 'console') {
488
+ throw new WorkbenchError(404, `no route for ${method} ${pathname}`, { id: 'not-found', hint: ROUTE_HINT })
489
+ }
490
+ const leaf = parts[2] ?? ''
491
+
492
+ if (leaf === 'health' && parts.length === 3) {
493
+ if (method !== 'GET') throw new WorkbenchError(405, 'only GET is allowed here', { id: 'method-not-allowed' })
494
+ const caps = capabilities()
495
+ send(res, 200, {
496
+ ok: true,
497
+ data: {
498
+ service: 'dsh-superagent-console',
499
+ version,
500
+ pid: process.pid,
501
+ startedAt,
502
+ mode: caps.chat ? 'chat' : 'unavailable',
503
+ capabilities: caps,
504
+ sessionId: currentSessionId,
505
+ },
506
+ })
507
+ return
508
+ }
509
+
510
+ if (leaf === 'state' && parts.length === 3) {
511
+ if (method !== 'GET') throw new WorkbenchError(405, 'only GET is allowed here', { id: 'method-not-allowed' })
512
+ send(res, 200, { ok: true, data: await state() })
513
+ return
514
+ }
515
+
516
+ if (leaf === 'tools' && parts.length === 3) {
517
+ if (method !== 'GET') throw new WorkbenchError(405, 'only GET is allowed here', { id: 'method-not-allowed' })
518
+ const sessionId = currentSessionId
519
+ if (!sessionId) {
520
+ send(res, 200, { ok: true, data: { sessionId: null, tools: null, reason: 'no-session' } })
521
+ return
522
+ }
523
+ if (typeof host.listTools !== 'function') {
524
+ send(res, 200, { ok: true, data: { sessionId, tools: null, reason: 'this host cannot enumerate tools' } })
525
+ return
526
+ }
527
+ try {
528
+ const tools = await host.listTools(sessionId)
529
+ send(res, 200, { ok: true, data: { sessionId, tools, reason: null } })
530
+ } catch (error) {
531
+ send(res, 200, { ok: true, data: { sessionId, tools: null, reason: messageOf(error) } })
532
+ }
533
+ return
534
+ }
535
+
536
+ if (leaf === 'bootstrap' && parts.length === 3) {
537
+ if (method !== 'POST') throw new WorkbenchError(405, 'only POST is allowed here', { id: 'method-not-allowed' })
538
+ const created = await ensureSession()
539
+ send(res, 200, { ok: true, data: { ...(await state()), ...created } })
540
+ return
541
+ }
542
+
543
+ if (leaf === 'session' && parts.length === 3) {
544
+ if (method !== 'POST') throw new WorkbenchError(405, 'only POST is allowed here', { id: 'method-not-allowed' })
545
+ const created = await createSession()
546
+ send(res, 200, { ok: true, data: created })
547
+ return
548
+ }
549
+
550
+ if (leaf === 'message' && parts.length === 3) {
551
+ if (method !== 'POST') throw new WorkbenchError(405, 'only POST is allowed here', { id: 'method-not-allowed' })
552
+ const body = await readJson(req)
553
+ const text = typeof body.text === 'string' ? body.text.trim() : ''
554
+ if (!text) throw new WorkbenchError(400, 'text is required', { id: 'missing-text' })
555
+ if (text.length > MAX_TEXT) {
556
+ throw new WorkbenchError(413, `text is above the ${MAX_TEXT}-character limit`, { id: 'text-too-long' })
557
+ }
558
+ const mode = body.mode === 'steer' ? 'steer' : 'queue'
559
+ const ensured = await ensureSession()
560
+ if (typeof body.sessionId === 'string' && body.sessionId && body.sessionId !== ensured.sessionId) {
561
+ throw new WorkbenchError(409, 'the message targets a conversation this console is not showing', {
562
+ id: 'session-mismatch',
563
+ hint: 'reload the page; the console keeps one active conversation at a time.',
564
+ })
565
+ }
566
+ try {
567
+ await host.prompt({ sessionId: ensured.sessionId, text, mode })
568
+ } catch (error) {
569
+ throw new WorkbenchError(502, `the host refused the message: ${messageOf(error)}`, {
570
+ id: 'prompt-failed',
571
+ })
572
+ }
573
+ const accepted = broadcast({ type: 'accepted', sessionId: ensured.sessionId, text, mode })
574
+ refreshRuns().catch(() => {})
575
+ send(res, 200, { ok: true, data: { accepted: true, sessionId: ensured.sessionId, mode, seq: accepted.seq } })
576
+ return
577
+ }
578
+
579
+ if (leaf === 'events' && parts.length === 3) {
580
+ if (method !== 'GET') throw new WorkbenchError(405, 'only GET is allowed here', { id: 'method-not-allowed' })
581
+ openStream(req, res)
582
+ return
583
+ }
584
+
585
+ if (leaf === 'answer' && parts.length === 3) {
586
+ if (method !== 'POST') throw new WorkbenchError(405, 'only POST is allowed here', { id: 'method-not-allowed' })
587
+ const body = await readJson(req)
588
+ const runId = typeof body.runId === 'string' ? body.runId.trim() : ''
589
+ const attentionId = typeof body.attentionId === 'string' && body.attentionId.trim()
590
+ ? body.attentionId.trim()
591
+ : null
592
+ const answer = typeof body.answer === 'string' ? body.answer.trim() : ''
593
+ if (!runId) throw new WorkbenchError(400, 'runId is required', { id: 'missing-run-id' })
594
+ if (!answer) throw new WorkbenchError(400, 'answer is required', { id: 'missing-answer' })
595
+ const ensured = await ensureSession()
596
+ let result
597
+ try {
598
+ result = await host.answer({ sessionId: ensured.sessionId, runId, attentionId, answer })
599
+ } catch (error) {
600
+ throw new WorkbenchError(502, `the answer was not applied: ${messageOf(error)}`, {
601
+ id: 'answer-failed',
602
+ })
603
+ }
604
+ broadcast({ type: 'answered', sessionId: ensured.sessionId, runId, attentionId, answer })
605
+ await refreshRuns({ force: true }).catch(() => {})
606
+ send(res, 200, { ok: true, data: result ?? { runId, attentionId, answer } })
607
+ return
608
+ }
609
+
610
+ if (leaf === 'runs' && parts.length <= 4) {
611
+ if (method !== 'GET') throw new WorkbenchError(405, 'only GET is allowed here', { id: 'method-not-allowed' })
612
+ if (!currentSessionId) {
613
+ send(res, 200, { ok: true, data: { runs: [] } })
614
+ return
615
+ }
616
+ if (parts.length === 3) {
617
+ send(res, 200, { ok: true, data: { runs: await refreshRuns({ force: true }) } })
618
+ return
619
+ }
620
+ const runId = decodeURIComponent(parts[3])
621
+ if (typeof host.readRun !== 'function') {
622
+ throw new WorkbenchError(404, `no route for ${method} ${pathname}`, { id: 'not-found' })
623
+ }
624
+ const run = await host.readRun(currentSessionId, runId)
625
+ if (!run) throw new WorkbenchError(404, `no run ${runId} for this conversation`, { id: 'unknown-run' })
626
+ send(res, 200, { ok: true, data: run })
627
+ return
628
+ }
629
+
630
+ throw new WorkbenchError(404, `no route for ${method} ${pathname}`, { id: 'not-found', hint: ROUTE_HINT })
631
+ } catch (error) {
632
+ if (statusFor(error) >= 500) log(`console request failed: ${messageOf(error)}`)
633
+ send(res, statusFor(error), errorPayload(error))
634
+ }
635
+ }
636
+
637
+ async function writeDiscovery() {
638
+ const caps = capabilities()
639
+ const doc = {
640
+ service: 'dsh-superagent-console',
641
+ version,
642
+ url: url(),
643
+ token,
644
+ pid: process.pid,
645
+ instanceId,
646
+ startedAt,
647
+ mode: caps.chat ? 'chat' : 'unavailable',
648
+ }
649
+ const tmp = `${discoveryPath}.${process.pid}.${instanceId}.tmp`
650
+ const handle = await fsp.open(tmp, 'wx', 0o600)
651
+ try {
652
+ await handle.writeFile(`${JSON.stringify(doc, null, 2)}\n`, 'utf8')
653
+ } finally {
654
+ await handle.close()
655
+ }
656
+ await fsp.rename(tmp, discoveryPath)
657
+ try {
658
+ await fsp.chmod(discoveryPath, 0o600)
659
+ } catch {
660
+ // Windows ignores most mode bits; the file's ACL still applies.
661
+ }
662
+ }
663
+
664
+ async function removeDiscovery() {
665
+ try {
666
+ const current = JSON.parse(await fsp.readFile(discoveryPath, 'utf8'))
667
+ if (current?.instanceId !== instanceId) return
668
+ await fsp.unlink(discoveryPath)
669
+ } catch {
670
+ // Already gone, or replaced by another instance.
671
+ }
672
+ await fsp.unlink(`${discoveryPath}.${process.pid}.${instanceId}.tmp`).catch(() => {})
673
+ }
674
+
675
+ async function closeServer() {
676
+ if (!server) return
677
+ const instance = server
678
+ server = null
679
+ boundPort = null
680
+ await new Promise(resolve => {
681
+ instance.close(() => resolve())
682
+ instance.closeAllConnections?.()
683
+ })
684
+ }
685
+
686
+ return {
687
+ discoveryPath,
688
+ get token() {
689
+ return token
690
+ },
691
+ get port() {
692
+ return boundPort
693
+ },
694
+ get url() {
695
+ return boundPort ? url() : null
696
+ },
697
+
698
+ /** Bind the loopback port, load the page, and publish the discovery file. */
699
+ async start() {
700
+ if (server) return { port: boundPort, url: url() }
701
+ if (starting) return starting
702
+ if (stopRequested) throw new Error('the console has been stopped; a new instance is required')
703
+ const run = (async () => {
704
+ page = await fsp.readFile(new URL('../public/console.html', import.meta.url), 'utf8')
705
+ const instance = createServer((req, res) => {
706
+ handle(req, res).catch(error => {
707
+ log(`console handler crashed: ${messageOf(error)}`)
708
+ send(res, 500, errorPayload(error))
709
+ })
710
+ })
711
+ instance.requestTimeout = REQUEST_TIMEOUT_MS
712
+ instance.headersTimeout = 10_000
713
+ instance.keepAliveTimeout = 5_000
714
+ instance.maxConnections = 64
715
+ await new Promise((resolve, reject) => {
716
+ instance.once('error', reject)
717
+ instance.listen(port, '127.0.0.1', () => {
718
+ instance.off('error', reject)
719
+ resolve()
720
+ })
721
+ })
722
+ const address = instance.address()
723
+ if (!address || typeof address === 'string') throw new Error('the console listener has no TCP address')
724
+ boundPort = address.port
725
+ server = instance
726
+ await writeDiscovery()
727
+ return { port: boundPort, url: url() }
728
+ })()
729
+ starting = run
730
+ try {
731
+ return await run
732
+ } finally {
733
+ starting = null
734
+ }
735
+ },
736
+
737
+ /** Close the socket, stop the stream, and remove the discovery file. */
738
+ async stop() {
739
+ if (closing) return closing
740
+ stopRequested = true
741
+ closing = (async () => {
742
+ detach()
743
+ currentSessionId = null
744
+ for (const res of clients) {
745
+ try {
746
+ writeFrame(res, { type: 'closed', seq: nextSeq(), at: new Date().toISOString() })
747
+ res.end()
748
+ } catch {
749
+ // The socket is already gone.
750
+ }
751
+ }
752
+ clients.clear()
753
+ await closeServer()
754
+ await removeDiscovery()
755
+ })()
756
+ try {
757
+ await closing
758
+ } finally {
759
+ closing = null
760
+ }
761
+ },
762
+ }
763
+ }