ai-agentmanager 0.0.0-stage → 1.0.0

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.
Files changed (58) hide show
  1. package/LICENSE +202 -0
  2. package/NOTICE +4 -0
  3. package/README.md +767 -2
  4. package/SECURITY.md +44 -0
  5. package/bin/agentmgr-hub.js +16 -0
  6. package/bin/agentmgr.js +4 -0
  7. package/docs/architecture.md +67 -0
  8. package/docs/distributed.md +147 -0
  9. package/docs/engines.md +177 -0
  10. package/docs/images/agents.jpg +0 -0
  11. package/docs/images/conflict-radar.jpg +0 -0
  12. package/docs/plugins.md +81 -0
  13. package/package.json +56 -4
  14. package/public/app.js +3083 -0
  15. package/public/hub/hub.css +230 -0
  16. package/public/hub/hub.js +766 -0
  17. package/public/hub/index.html +146 -0
  18. package/public/hub/term.js +147 -0
  19. package/public/index.html +342 -0
  20. package/public/share.html +34 -0
  21. package/public/share.js +41 -0
  22. package/public/style.css +541 -0
  23. package/public/touchscroll.js +73 -0
  24. package/public/transport.js +78 -0
  25. package/scripts/build-release.sh +58 -0
  26. package/scripts/fix-pty.js +15 -0
  27. package/src/backlog.js +413 -0
  28. package/src/brief.js +512 -0
  29. package/src/cli.js +1447 -0
  30. package/src/client.js +49 -0
  31. package/src/config.js +109 -0
  32. package/src/conflicts.js +105 -0
  33. package/src/engines/antigravity.js +296 -0
  34. package/src/engines/claude.js +98 -0
  35. package/src/engines/codex.js +331 -0
  36. package/src/engines/index.js +37 -0
  37. package/src/fleet.js +176 -0
  38. package/src/git.js +340 -0
  39. package/src/hub.js +857 -0
  40. package/src/hubactions.js +107 -0
  41. package/src/hubbacklog.js +373 -0
  42. package/src/hublink.js +437 -0
  43. package/src/inbox.js +94 -0
  44. package/src/judge.js +278 -0
  45. package/src/livebrowser.js +637 -0
  46. package/src/manager.js +2554 -0
  47. package/src/notify.js +284 -0
  48. package/src/plugins.js +119 -0
  49. package/src/preview.js +334 -0
  50. package/src/races.js +192 -0
  51. package/src/remote.js +284 -0
  52. package/src/server.js +759 -0
  53. package/src/service.js +150 -0
  54. package/src/sessions.js +160 -0
  55. package/src/store.js +104 -0
  56. package/src/stuck.js +160 -0
  57. package/src/tracker.js +311 -0
  58. package/src/trust.js +44 -0
package/src/server.js ADDED
@@ -0,0 +1,759 @@
1
+ import fs from 'node:fs';
2
+ import http from 'node:http';
3
+ import https from 'node:https';
4
+ import path from 'node:path';
5
+ import { createRequire } from 'node:module';
6
+ import { fileURLToPath } from 'node:url';
7
+ import express from 'express';
8
+ import { WebSocketServer } from 'ws';
9
+ import { ensureHome, HOST, loadConfig, paths, PORT, saveConfig } from './config.js';
10
+ import { AgentManager, shellNumber } from './manager.js';
11
+ import { Backlog } from './backlog.js';
12
+ import { Races } from './races.js';
13
+ import { listEngines, registerEngine } from './engines/index.js';
14
+ import { Plugins, pluginSpecs } from './plugins.js';
15
+ import { HubLink, linkUrls } from './hublink.js';
16
+ import { Notifier, isWorkflowUrl, loadNotify, publicNotify, saveNotify, sendSlack } from './notify.js';
17
+ import { Previews, parseUrl } from './preview.js';
18
+ import { LiveBrowser } from './livebrowser.js';
19
+ import * as remote from './remote.js';
20
+ import { Store } from './store.js';
21
+
22
+ const __dirname = path.dirname(fileURLToPath(import.meta.url));
23
+ const require = createRequire(import.meta.url);
24
+ export const CLIENT_HEADER = 'x-agentmgr';
25
+
26
+ /**
27
+ * The API drives real terminals, so callers are restricted.
28
+ *
29
+ * Local listener (127.0.0.1): Host must be loopback (blocks DNS rebinding), a
30
+ * browser Origin must be this server (blocks cross-site WebSockets), and writes
31
+ * need a custom header (browsers cannot send one cross-origin without a CORS
32
+ * preflight we never grant).
33
+ *
34
+ * Remote listener (opt-in HTTPS on the LAN): the same, with this machine's own
35
+ * addresses as the only valid Host, and a signed-in device session on every API
36
+ * call except login. Managing remote access and shutting down stay local-only.
37
+ */
38
+ function isLocalHost(host, port) {
39
+ return [`127.0.0.1:${port}`, `localhost:${port}`, `[::1]:${port}`].includes(host);
40
+ }
41
+ function isAllowedOrigin(origin, port) {
42
+ return !origin || [`http://127.0.0.1:${port}`, `http://localhost:${port}`, `http://[::1]:${port}`].includes(origin);
43
+ }
44
+
45
+ const PUBLIC_REMOTE_API = new Set(['POST /api/login', 'GET /api/session']);
46
+ const LOCAL_ONLY_API = /^\/api\/(remote(\/|$)|notify(\/|$)|hub(\/|$)|shutdown$)/;
47
+
48
+ export async function startServer({ port = PORT, host = HOST } = {}) {
49
+ ensureHome();
50
+ const config = loadConfig();
51
+ const store = new Store(paths.state);
52
+ const plugins = await new Plugins({ log: (m) => console.log(`[agentmgr] ${m}`) }).load(pluginSpecs(config), { config, base: paths.home });
53
+ for (const { def } of plugins.engines) registerEngine(def);
54
+ const manager = new AgentManager({ store, config, plugins });
55
+ const backlog = new Backlog({ manager, store, config });
56
+ const races = new Races({ manager, store });
57
+ // Alerts link to the phone address when remote access is on, else the local UI.
58
+ const notifier = new Notifier({
59
+ manager,
60
+ backlog,
61
+ linkFor: (id) => {
62
+ const phone = remoteServer ? remote.remoteUrls(remotePort).find((u) => !u.vpn) : null;
63
+ return `${phone ? phone.url : `http://127.0.0.1:${port}/`}#${id}/term`;
64
+ },
65
+ });
66
+ let remoteServer = null;
67
+ let remotePort = null;
68
+ // Live browser tabs: what a page does is saved on the agent's tab; popups become new tabs.
69
+ const live = new LiveBrowser({
70
+ config,
71
+ onNavigate: (id, n, url) => {
72
+ try {
73
+ manager.setBrowser(id, n, url, { raw: true });
74
+ } catch {}
75
+ },
76
+ onPopup: (id, url) => {
77
+ try {
78
+ return manager.addBrowser(id, url, { mode: 'live', raw: true }).n;
79
+ } catch {
80
+ return null;
81
+ }
82
+ },
83
+ onClosed: (id, n) => {
84
+ try {
85
+ manager.dropBrowser(id, n);
86
+ } catch {}
87
+ },
88
+ });
89
+ const previews = new Previews({
90
+ tls: () => {
91
+ const { key, cert } = remote.certificatePaths();
92
+ return { key: fs.readFileSync(key), cert: fs.readFileSync(cert) };
93
+ },
94
+ allowedHosts: (p) => remote.allowedRemoteHosts(p),
95
+ signedIn: (cookies) => Boolean(remote.checkSession(remote.parseCookies(cookies)[remote.SESSION_COOKIE])),
96
+ cookieName: remote.SESSION_COOKIE,
97
+ reserved: () => [port, remotePort].filter(Boolean),
98
+ savedPorts: () => remote.loadSettings().relayPorts,
99
+ savePorts: (relayPorts) => remote.saveSettings({ relayPorts }),
100
+ ownHosts: () => new Set([...remote.lanAddresses().map((a) => a.address), remote.localHostname(), ...remote.loadSettings().extraHosts].map((h) => h.toLowerCase())),
101
+ });
102
+ const pkgVersion = JSON.parse(fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8')).version;
103
+ // "Open on this machine" links from the hub point at remote access, when it's on.
104
+ const hubLink = new HubLink({ manager, config, backlog, version: pkgVersion, urls: () => (remoteServer ? linkUrls(remote.remoteUrls(remotePort)) : []) });
105
+
106
+ /** Returns an error string if the request may not proceed, else null. Sets req.device for remote sessions. */
107
+ function denied(req) {
108
+ const host = (req.headers.host ?? '').toLowerCase();
109
+ const origin = req.headers.origin;
110
+ if (!req.remote) {
111
+ if (!isLocalHost(host, port) || !isAllowedOrigin(origin, port)) return 'Forbidden';
112
+ return null;
113
+ }
114
+ if (!remote.allowedRemoteHosts(remotePort).has(host)) return 'Unknown host';
115
+ if (origin && origin !== `https://${host}`) return 'Forbidden origin';
116
+ const pathname = req.url.split('?')[0];
117
+ const isApi = pathname.startsWith('/api/') || pathname.startsWith('/ws/');
118
+ if (!isApi) return null; // page, scripts and styles: no secrets
119
+ if (LOCAL_ONLY_API.test(pathname)) return 'Only available on this computer';
120
+ if (PUBLIC_REMOTE_API.has(`${req.method} ${pathname}`)) return null;
121
+ const cookie = remote.parseCookies(req.headers.cookie)[remote.SESSION_COOKIE];
122
+ req.device = remote.checkSession(cookie);
123
+ return req.device ? null : 'Sign in required';
124
+ }
125
+
126
+ const app = express();
127
+ app.disable('x-powered-by');
128
+ app.use((req, res, next) => {
129
+ res.setHeader('X-Frame-Options', 'DENY');
130
+ res.setHeader('Referrer-Policy', 'no-referrer');
131
+ res.setHeader('X-Content-Type-Options', 'nosniff');
132
+ const why = denied(req);
133
+ if (why) return res.status(why === 'Sign in required' ? 401 : 403).json({ error: why });
134
+ if (!['GET', 'HEAD'].includes(req.method) && req.headers[CLIENT_HEADER] !== '1') {
135
+ return res.status(403).json({ error: `Missing ${CLIENT_HEADER} header` });
136
+ }
137
+ next();
138
+ });
139
+ app.use(express.json({ limit: '1mb' }));
140
+
141
+ // Package root, found from its entry point (not every package exports package.json).
142
+ const pkgDir = (name) => {
143
+ let dir = path.dirname(require.resolve(name));
144
+ while (!fs.existsSync(path.join(dir, 'package.json')) || JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8')).name !== name) {
145
+ const up = path.dirname(dir);
146
+ if (up === dir) throw new Error(`Cannot find package root for ${name}`);
147
+ dir = up;
148
+ }
149
+ return dir;
150
+ };
151
+ app.use('/vendor/xterm', express.static(pkgDir('@xterm/xterm')));
152
+ app.use('/vendor/xterm-addon-fit', express.static(pkgDir('@xterm/addon-fit')));
153
+ app.use('/vendor/marked', express.static(path.join(pkgDir('marked'), 'lib')));
154
+ app.use('/vendor/dompurify', express.static(path.join(pkgDir('dompurify'), 'dist')));
155
+ app.use('/vendor/mermaid', express.static(path.join(pkgDir('mermaid'), 'dist')));
156
+ app.use(express.static(path.join(__dirname, '..', 'public')));
157
+
158
+ const api = express.Router();
159
+ const wrap = (fn) => async (req, res) => {
160
+ try {
161
+ res.json(await fn(req, res));
162
+ } catch (err) {
163
+ res.status(err.status || 500).json({ error: err.message });
164
+ }
165
+ };
166
+ const fail = (status, message) => Object.assign(new Error(message), { status });
167
+
168
+ api.get('/health', wrap(() => ({ ok: true, pid: process.pid, home: paths.home, claudeBin: config.claudeBin })));
169
+ api.get('/agents', wrap(() => manager.list()));
170
+ api.get('/engines', wrap(() => listEngines(config)));
171
+ api.post(
172
+ '/agents',
173
+ wrap((req) => {
174
+ const { intents, intent, ...opts } = req.body ?? {};
175
+ return manager.createMany(Array.isArray(intents) ? intents : [intent], opts);
176
+ }),
177
+ );
178
+ api.post('/general', wrap((req) => manager.createGeneral(req.body ?? {})));
179
+ api.get('/agents/:id/brief', wrap((req) => manager.briefFile(req.params.id)));
180
+ // ?background=1 starts the work and returns at once (watch the agent's events for the result).
181
+ const bg = (req) => req.query.background === '1' || req.body?.background === true;
182
+ api.post('/agents/:id/explain', wrap((req) => (bg(req) ? manager.summarizeInBackground(req.params.id, ['explain']) : manager.explain(req.params.id))));
183
+ api.post('/agents/:id/insights', wrap((req) => (bg(req) ? manager.summarizeInBackground(req.params.id, ['insights']) : manager.insights(req.params.id))));
184
+ const DOC_LIST = ['analysis', 'design', 'flow', 'proposal', 'humanai'];
185
+ api.post('/agents/:id/humanai/answers', wrap((req) => manager.humanAiAnswers(req.params.id, req.body?.answers, { send: req.body?.send === true })));
186
+ api.post(
187
+ '/agents/:id/docs/:kind',
188
+ wrap((req) => {
189
+ const kinds = req.params.kind === 'all' ? DOC_LIST : [req.params.kind];
190
+ if (bg(req) || kinds.length > 1) return manager.summarizeInBackground(req.params.id, kinds);
191
+ return manager.document(req.params.id, req.params.kind);
192
+ }),
193
+ );
194
+ api.post('/agents/:id/plan', wrap((req) => manager.startPlanning(req.params.id)));
195
+ api.post('/agents/:id/plan/approve', wrap((req) => manager.approvePlan(req.params.id, req.body?.note)));
196
+ api.post('/agents/:id/plan/changes', wrap((req) => manager.requestPlanChanges(req.params.id, req.body?.note)));
197
+ api.post('/agents/:id/plan/review', wrap((req) => manager.setPlanReview(req.params.id, req.body?.on === true)));
198
+ api.post('/agents/:id/handoff', wrap((req) => manager.maybeHandoff(manager.mustGet(req.params.id).id, { force: true })));
199
+ api.post('/agents/:id/shell/close', wrap((req) => manager.closeShell(req.params.id, req.body?.n ? Number(req.body.n) : undefined)));
200
+ api.post('/agents/:id/shell/new', wrap((req) => ({ n: manager.nextShellNumber(manager.mustGet(req.params.id).id) })));
201
+ api.post('/agents/:id/shell/drop', wrap((req) => manager.dropShell(req.params.id, Number(req.body?.n) || 1)));
202
+ // Raw file body; the name comes in the query. Returns the saved path to paste into a terminal.
203
+ api.post(
204
+ '/agents/:id/upload',
205
+ express.raw({ type: () => true, limit: '50mb' }),
206
+ wrap((req) => {
207
+ if (!Buffer.isBuffer(req.body) || !req.body.length) throw fail(400, 'Empty file');
208
+ return manager.saveUpload(req.params.id, req.query.name, req.body);
209
+ }),
210
+ );
211
+ api.get(
212
+ '/agents/:id',
213
+ wrap((req) => {
214
+ const agent = manager.get(req.params.id);
215
+ if (!agent) throw fail(404, `No agent matches "${req.params.id}"`);
216
+ return agent;
217
+ }),
218
+ );
219
+ api.patch('/agents/:id', wrap((req) => manager.update(req.params.id, req.body ?? {})));
220
+ api.post('/agents/:id/browsers', wrap((req) => manager.addBrowser(req.params.id, req.body?.url, { mode: req.body?.mode })));
221
+ api.patch(
222
+ '/agents/:id/browsers/:n',
223
+ wrap(async (req) => {
224
+ const n = Number(req.params.n);
225
+ const tab = manager.setBrowser(req.params.id, n, req.body?.url, { mode: req.body?.mode });
226
+ // A live tab that is open goes there now; one that isn't opens there next time.
227
+ if (req.body?.url !== undefined && live.tabs.has(live.key(req.params.id, n))) await live.navigate(req.params.id, n, tab.url).catch(() => {});
228
+ return tab;
229
+ }),
230
+ );
231
+ api.delete(
232
+ '/agents/:id/browsers/:n',
233
+ wrap(async (req) => {
234
+ await live.close(req.params.id, Number(req.params.n));
235
+ return manager.dropBrowser(req.params.id, Number(req.params.n));
236
+ }),
237
+ );
238
+
239
+ // Live browser tabs: a real browser on this machine, streamed (see livebrowser.js).
240
+ api.get('/browser', wrap(() => live.status()));
241
+ const liveArgs = (req) => {
242
+ const agent = manager.mustGet(req.params.id);
243
+ const n = Number(req.params.n);
244
+ if (!(agent.browsers ?? []).some((t) => t.n === n)) throw fail(404, `No browser tab ${n}`);
245
+ return [agent.id, n];
246
+ };
247
+ api.post('/agents/:id/browsers/:n/live/input', wrap(async (req) => ({ ok: true, ...(await live.input(...liveArgs(req), req.body?.events)) })));
248
+ api.post('/agents/:id/browsers/:n/live/resize', wrap(async (req) => (await live.resize(...liveArgs(req), req.body ?? {}), { ok: true })));
249
+ api.post('/agents/:id/browsers/:n/live/go', wrap(async (req) => (await live.go(...liveArgs(req), String(req.body?.where ?? '')), { ok: true })));
250
+ api.get('/agents/:id/browsers/:n/live/selection', wrap((req) => live.selection(...liveArgs(req))));
251
+ api.get('/agents/:id/browsers/:n/live/stream', async (req, res) => {
252
+ let args;
253
+ try {
254
+ args = liveArgs(req);
255
+ } catch (err) {
256
+ return res.status(err.status ?? 400).json({ error: err.message });
257
+ }
258
+ const tab = manager.mustGet(args[0]).browsers.find((t) => t.n === args[1]);
259
+ const write = sse(req, res);
260
+ // Frames are big: while the connection is backed up, keep only the newest and send it after.
261
+ let held = null;
262
+ res.on('drain', () => {
263
+ if (held) write(held);
264
+ held = null;
265
+ });
266
+ const client = {
267
+ audio: req.query.audio === '1', // this viewer wants the page's sound
268
+ send: (msg) => {
269
+ if (msg.t === 'frame' && res.writableNeedDrain) held = msg;
270
+ else write(msg);
271
+ },
272
+ };
273
+ let detach = null;
274
+ req.on('close', () => detach?.());
275
+ try {
276
+ const q = req.query;
277
+ detach = await live.view(args[0], args[1], tab.url, client, q.width ? { width: q.width, height: q.height, mobile: q.mobile, scale: q.scale } : undefined);
278
+ if (req.destroyed) detach();
279
+ } catch (err) {
280
+ write({ t: 'error', error: err.message });
281
+ res.end();
282
+ }
283
+ });
284
+ // Claude Code sessions started in a terminal, continued here.
285
+ api.get('/sessions/scan', wrap((req) => manager.scanSessions({ days: req.query.days })));
286
+ api.post('/sessions/import', wrap((req) => manager.importSessions(req.body?.sessions, { start: req.body?.start !== false, copy: Boolean(req.body?.copy) })));
287
+ api.get('/agents/:id/local-urls', wrap((req) => manager.localUrls(req.params.id)));
288
+ // A CLI's sign-in link: opened in a real browser window; its callback finished on this machine.
289
+ api.post('/agents/:id/signin', wrap((req) => manager.addSignIn(req.params.id, req.body?.url)));
290
+ api.post('/agents/:id/signin/finish', wrap((req) => manager.finishSignIn(req.params.id, req.body?.url)));
291
+ api.post('/agents/:id/signin/dismiss', wrap((req) => manager.dismissSignIn(req.params.id)));
292
+ // Where a browser tab loads an address: directly on this computer, through a relay from another device.
293
+ api.post(
294
+ '/preview',
295
+ wrap(async (req) => {
296
+ if (!req.remote) return { src: parseUrl(req.body?.url).href };
297
+ return { src: await previews.frameUrl(req.body?.url, req.headers.host) };
298
+ }),
299
+ );
300
+
301
+ api.delete(
302
+ '/agents/:id',
303
+ wrap((req) => manager.remove(req.params.id, { deleteWorkspace: req.query.deleteWorkspace === '1' })),
304
+ );
305
+ api.post('/agents/:id/start', wrap((req) => manager.start(req.params.id, req.body ?? {})));
306
+ api.post('/agents/:id/stop', wrap((req) => manager.stop(req.params.id)));
307
+ api.post('/agents/:id/refresh', wrap((req) => manager.refresh(req.params.id, { withPrs: true })));
308
+ api.post('/agents/:id/links', wrap((req) => manager.addLink(req.params.id, req.body ?? {})));
309
+ api.delete('/agents/:id/links', wrap((req) => manager.removeLink(req.params.id, req.query)));
310
+ api.post('/flush', wrap(() => manager.flush()));
311
+
312
+ // ---------------------------------------------------------- Slack alerts (local only)
313
+ const okUrl = (u) => /^https:\/\/[\w.-]+\//.test(u) || /^http:\/\/(127\.0\.0\.1|localhost)(:\d+)?\//.test(u);
314
+ api.get('/notify', wrap(() => ({ ...publicNotify(), workflow: isWorkflowUrl(loadNotify().slack.webhookUrl), recent: notifier.log, judge: judgeAlerts() })));
315
+ const judgeAlerts = () => (manager.judge.enabled ? { digestMin: manager.judge.settings.digestMin, pending: notifier.digest.length } : null);
316
+ api.post(
317
+ '/notify',
318
+ wrap((req) => {
319
+ const b = req.body ?? {};
320
+ const slack = {};
321
+ if (b.webhookUrl !== undefined) {
322
+ if (b.webhookUrl && !okUrl(b.webhookUrl)) throw fail(400, 'The webhook URL must be https://…');
323
+ slack.webhookUrl = b.webhookUrl || null;
324
+ }
325
+ if (b.botToken !== undefined) slack.botToken = b.botToken || null;
326
+ if (b.channel !== undefined) slack.channel = b.channel || null;
327
+ const patch = { slack };
328
+ for (const k of ['enabled', 'skipWhenWatching', 'includeIntent']) if (typeof b[k] === 'boolean') patch[k] = b[k];
329
+ for (const k of ['needsInputDelaySec', 'waitingDelaySec']) if (Number(b[k]) >= 0) patch[k] = Number(b[k]);
330
+ if (b.events && typeof b.events === 'object') patch.events = b.events;
331
+ const next = saveNotify(patch);
332
+ // Configuring Slack for the first time turns alerts on.
333
+ if (b.enabled === undefined && (slack.webhookUrl || (slack.botToken && (b.channel ?? next.slack.channel)))) saveNotify({ enabled: true });
334
+ return { ...publicNotify(), recent: notifier.log };
335
+ }),
336
+ );
337
+ api.post(
338
+ '/notify/test',
339
+ wrap(async () => {
340
+ await sendSlack(':wave: Test from Agent Manager: alerts will arrive here when an agent needs you.', loadNotify());
341
+ return { ok: true };
342
+ }),
343
+ );
344
+
345
+ // ---------------------------------------------------------- project shortcuts
346
+ api.get('/projects', wrap(() => manager.listProjects()));
347
+ api.post('/projects', wrap((req) => manager.addProject(req.body ?? {})));
348
+ api.patch('/projects/:ref', wrap((req) => manager.updateProject(req.params.ref, req.body ?? {})));
349
+ api.delete('/projects/:ref', wrap((req) => manager.removeProject(req.params.ref)));
350
+
351
+ // ---------------------------------------------------------- backlog
352
+ api.get('/backlog', wrap(() => backlog.view()));
353
+ api.post(
354
+ '/backlog',
355
+ wrap((req) => {
356
+ const { items, item, ...opts } = req.body ?? {};
357
+ return backlog.add(Array.isArray(items) ? items : [item], opts);
358
+ }),
359
+ );
360
+ // Everything waiting on the user: live prompts, agents' questions, stuck agents, overlaps.
361
+ api.get('/inbox', wrap(() => manager.inbox()));
362
+ api.post('/agents/:id/tell', wrap((req) => manager.tell(req.params.id, req.body?.text)));
363
+ api.post('/agents/:id/answer', wrap((req) => manager.answerQuestion(req.params.id, req.body?.question, req.body?.text)));
364
+ api.post('/agents/:id/prompt-key', wrap((req) => manager.answerPrompt(req.params.id, String(req.body?.key ?? ''))));
365
+ api.post('/agents/:id/stuck/dismiss', wrap((req) => manager.dismissStuck(req.params.id, req.body?.key)));
366
+ api.post('/agents/:id/stuck/nudge', wrap((req) => manager.nudge(req.params.id, req.body?.key, req.body?.text)));
367
+ // The AI judge: what it read on an idle screen, and its review of finished work.
368
+ api.post('/agents/:id/conflicts/dismiss', wrap((req) => manager.dismissConflict(req.params.id, req.body?.with)));
369
+ api.post('/agents/:id/waiting/answer', wrap((req) => manager.answerWaiting(req.params.id, req.body?.text)));
370
+ api.post('/agents/:id/waiting/dismiss', wrap((req) => manager.dismissWaiting(req.params.id)));
371
+ api.post('/agents/:id/review', wrap((req) => manager.requestReview(req.params.id, { force: true })));
372
+ api.post('/agents/:id/review/ack', wrap((req) => manager.ackReview(req.params.id, req.body?.action)));
373
+ api.get('/judge', wrap(() => manager.judge.status()));
374
+ // On or off for this daemon, kept in config.json. The judge spends calls on your own engine plan.
375
+ api.put('/judge', wrap((req) => {
376
+ const enabled = Boolean(req.body?.enabled);
377
+ manager.config.judge = { ...manager.config.judge, enabled };
378
+ saveConfig({ judge: { enabled } });
379
+ return manager.judge.status();
380
+ }));
381
+ api.post('/agents/:id/conflicts/warn', wrap((req) => manager.warnConflict(req.params.id, req.body?.with)));
382
+ api.post('/agents/:id/checkpoint', wrap(async (req) => {
383
+ const id = manager.mustGet(req.params.id).id;
384
+ manager.lastCheckpointTry?.delete(id); // on demand: skip the throttle
385
+ await manager.checkpoint(id);
386
+ return manager.get(id);
387
+ }));
388
+ api.post('/agents/:id/fork', wrap((req) => manager.fork(req.params.id, req.body ?? {})));
389
+
390
+ api.get('/races', wrap(() => races.list()));
391
+ api.post('/races', wrap((req) => races.create(req.body ?? {})));
392
+ api.get('/races/:id', wrap((req) => races.view(req.params.id)));
393
+ api.post('/races/:id/tests', wrap((req) => races.runTests(req.params.id, req.body ?? {})));
394
+ api.get('/races/:id/diff/:agent', wrap((req) => races.diff(req.params.id, req.params.agent)));
395
+ api.post('/races/:id/pick', wrap((req) => races.pick(req.params.id, req.body?.agent, { cleanup: Boolean(req.body?.cleanup) })));
396
+ api.delete('/races/:id', wrap((req) => races.remove(req.params.id)));
397
+
398
+ api.post('/backlog/settings', wrap((req) => backlog.settings(req.body ?? {})));
399
+ api.patch('/backlog/:id', wrap((req) => backlog.update(req.params.id, req.body ?? {})));
400
+ api.delete('/backlog/:id', wrap((req) => backlog.remove(req.params.id)));
401
+ api.post('/backlog/:id/start', wrap((req) => backlog.start(req.params.id)));
402
+ api.post('/backlog/:id/accept', wrap((req) => backlog.accept(req.params.id)));
403
+ api.post('/backlog/:id/reopen', wrap((req) => backlog.reopen(req.params.id, req.body ?? {})));
404
+ api.post('/backlog/:id/cancel', wrap((req) => backlog.cancel(req.params.id)));
405
+ api.post('/backlog/:id/move', wrap((req) => backlog.move(req.params.id, req.body?.where)));
406
+ api.post('/backlog/:id/split', wrap((req) => backlog.split(req.params.id, req.body?.parts)));
407
+ api.post('/backlog/:id/keep-whole', wrap((req) => backlog.keepWhole(req.params.id)));
408
+ api.post(
409
+ '/shutdown',
410
+ wrap(() => {
411
+ setTimeout(() => shutdown('api'), 50);
412
+ return { ok: true };
413
+ }),
414
+ );
415
+
416
+ // ---------------------------------------------------------- hub link (local only)
417
+ api.get('/hub', wrap(() => hubLink.status()));
418
+ api.post('/hub/join', wrap((req) => hubLink.join(req.body?.url, req.body?.code, req.body?.name)));
419
+ api.post('/hub/leave', wrap(() => hubLink.leave()));
420
+
421
+ // ---------------------------------------------------------- sessions (remote sign-in)
422
+
423
+ api.get('/session', wrap((req) => ({ remote: Boolean(req.remote), authenticated: !req.remote || Boolean(
424
+ remote.checkSession(remote.parseCookies(req.headers.cookie)[remote.SESSION_COOKIE]),
425
+ ) })));
426
+ api.post(
427
+ '/login',
428
+ wrap((req, res) => {
429
+ if (!req.remote) return { ok: true };
430
+ const ip = req.socket.remoteAddress;
431
+ if (!remote.loginAllowed(ip)) throw fail(429, 'Too many attempts; try again in 15 minutes');
432
+ const ticket = req.body?.ticket !== undefined;
433
+ if (ticket ? !remote.useTicket(req.body.ticket) : !remote.checkToken(req.body?.token)) {
434
+ remote.loginFailed(ip);
435
+ throw fail(401, ticket ? 'That sign-in link was used or has expired; open it from the hub again' : 'Wrong or expired access token');
436
+ }
437
+ const { secret, maxAgeSec } = remote.createSession({ ua: req.headers['user-agent'], ip, via: ticket ? 'hub' : undefined });
438
+ res.setHeader(
439
+ 'Set-Cookie',
440
+ `${remote.SESSION_COOKIE}=${secret}; Path=/; Max-Age=${maxAgeSec}; HttpOnly; Secure; SameSite=Strict`,
441
+ );
442
+ return { ok: true };
443
+ }),
444
+ );
445
+ api.post(
446
+ '/logout',
447
+ wrap((req, res) => {
448
+ remote.endSession(remote.parseCookies(req.headers.cookie)[remote.SESSION_COOKIE]);
449
+ res.setHeader('Set-Cookie', `${remote.SESSION_COOKIE}=; Path=/; Max-Age=0; HttpOnly; Secure; SameSite=Strict`);
450
+ return { ok: true };
451
+ }),
452
+ );
453
+
454
+ // ---------------------------------------------------------- remote access management (local only)
455
+
456
+ const remoteStatus = async () => {
457
+ const settings = remote.loadSettings();
458
+ const urls = remote.remoteUrls(settings.port);
459
+ return {
460
+ ...settings,
461
+ running: Boolean(remoteServer),
462
+ fingerprint: remote.certificateFingerprint(),
463
+ hostname: remote.localHostname(),
464
+ urls: await Promise.all(
465
+ urls.map(async (u) => ({ ...u, loginUrl: remote.loginLink(u.url), qr: await remote.qrSvg(remote.loginLink(u.url)) })),
466
+ ),
467
+ devices: remote.listSessions(),
468
+ };
469
+ };
470
+ api.get('/remote', wrap(remoteStatus));
471
+ api.post(
472
+ '/remote/enable',
473
+ wrap(async (req) => {
474
+ const p = Number(req.body?.port) || remote.loadSettings().port;
475
+ remote.saveSettings({ enabled: true, port: p });
476
+ await startRemote();
477
+ return remoteStatus();
478
+ }),
479
+ );
480
+ api.post(
481
+ '/remote/disable',
482
+ wrap(async () => {
483
+ remote.saveSettings({ enabled: false });
484
+ await stopRemote();
485
+ return remoteStatus();
486
+ }),
487
+ );
488
+ api.post(
489
+ '/remote/rotate',
490
+ wrap(() => {
491
+ remote.rotateToken();
492
+ return remoteStatus();
493
+ }),
494
+ );
495
+ api.delete(
496
+ '/remote/devices/:id',
497
+ wrap((req) => {
498
+ remote.revokeSession(req.params.id);
499
+ return remoteStatus();
500
+ }),
501
+ );
502
+
503
+ // ---------------------------------------------------------- streaming over plain HTTP (SSE)
504
+ // iOS Safari applies an accepted self-signed certificate to pages and fetches but not to
505
+ // WebSockets, so the phone UI streams with Server-Sent Events and sends input with POSTs.
506
+
507
+ const sse = (req, res) => {
508
+ res.writeHead(200, {
509
+ 'Content-Type': 'text/event-stream',
510
+ 'Cache-Control': 'no-cache, no-transform',
511
+ Connection: 'keep-alive',
512
+ 'X-Accel-Buffering': 'no',
513
+ });
514
+ res.write('retry: 2000\n\n');
515
+ const ping = setInterval(() => res.write(': ping\n\n'), 20_000);
516
+ req.on('close', () => clearInterval(ping));
517
+ return (msg) => res.write(`data: ${JSON.stringify(msg)}\n\n`);
518
+ };
519
+
520
+ const eventSinks = new Set();
521
+ api.get('/events/stream', (req, res) => {
522
+ const send = sse(req, res);
523
+ send({ t: 'snapshot', agents: manager.list(), backlog: backlog.view(), projects: manager.listProjects(), races: races.list() });
524
+ eventSinks.add(send);
525
+ req.on('close', () => eventSinks.delete(send));
526
+ });
527
+
528
+ const termKind = (q) => (shellNumber(q) ? `shell:${shellNumber(q)}` : 'claude');
529
+ const attachTerm = (id, kind, client) =>
530
+ shellNumber(kind) ? manager.attachShell(id, client, shellNumber(kind)) : manager.attach(id, client);
531
+ api.get('/agents/:id/term/stream', (req, res) => {
532
+ let agent;
533
+ const kind = termKind(req.query.kind);
534
+ try {
535
+ agent = manager.mustGet(req.params.id);
536
+ manager.plugins.check('terminal.open', { agent: manager.auditView(agent), kind });
537
+ } catch (err) {
538
+ return res.status(err.status || 404).json({ error: err.message });
539
+ }
540
+ const send = sse(req, res);
541
+ // Batch output so a busy terminal is a few events per second, not one per chunk.
542
+ let pending = '';
543
+ let timer = null;
544
+ const flush = () => {
545
+ timer = null;
546
+ if (pending) send({ t: 'o', d: pending });
547
+ pending = '';
548
+ };
549
+ const client = {
550
+ send: (msg) => {
551
+ if (msg.t === 'o') {
552
+ pending += msg.d;
553
+ timer ??= setTimeout(flush, 30);
554
+ } else {
555
+ flush();
556
+ send(msg);
557
+ }
558
+ },
559
+ close: () => res.end(),
560
+ };
561
+ let session;
562
+ try {
563
+ session = attachTerm(agent.id, kind, client);
564
+ } catch (err) {
565
+ send({ t: 'error', error: err.message });
566
+ return res.end();
567
+ }
568
+ send({ t: 'hello', id: agent.id, kind, running: session.running, backlog: session.backlog });
569
+ req.on('close', () => {
570
+ clearTimeout(timer);
571
+ session.detach();
572
+ });
573
+ });
574
+ api.post(
575
+ '/agents/:id/term/input',
576
+ wrap((req) => {
577
+ const agent = manager.mustGet(req.params.id);
578
+ if (typeof req.body?.d !== 'string') throw fail(400, 'd (string) is required');
579
+ manager.write(agent.id, req.body.d, termKind(req.body.kind));
580
+ return { ok: true };
581
+ }),
582
+ );
583
+ api.post(
584
+ '/agents/:id/term/resize',
585
+ wrap((req) => {
586
+ const agent = manager.mustGet(req.params.id);
587
+ manager.resize(agent.id, req.body?.cols | 0, req.body?.rows | 0, termKind(req.body?.kind));
588
+ return { ok: true };
589
+ }),
590
+ );
591
+ plugins.mount(api, express); // /api/ext/<plugin>, behind the same checks
592
+ app.use('/api', api);
593
+
594
+ // ---------------------------------------------------------- WebSockets (local UI and CLI)
595
+
596
+ const wss = new WebSocketServer({ noServer: true });
597
+ const onUpgrade = (isRemote) => (req, socket, head) => {
598
+ req.remote = isRemote;
599
+ if (denied(req)) {
600
+ socket.write('HTTP/1.1 403 Forbidden\r\n\r\n');
601
+ return socket.destroy();
602
+ }
603
+ wss.handleUpgrade(req, socket, head, (ws) => wss.emit('connection', ws, req));
604
+ };
605
+
606
+ const eventClients = new Set();
607
+ const broadcast = (msg) => {
608
+ const raw = JSON.stringify(msg);
609
+ for (const ws of eventClients) ws.send(raw);
610
+ for (const send of eventSinks) send(msg);
611
+ };
612
+ manager.on('change', (agent) => broadcast({ t: 'agent', agent }));
613
+ manager.on('removed', (id) => {
614
+ broadcast({ t: 'removed', id });
615
+ live.closeAgent(id).catch(() => {});
616
+ });
617
+ backlog.on('change', (view) => broadcast({ t: 'backlog', backlog: view }));
618
+ const raceTimers = new Map();
619
+ races.on('change', (id) => {
620
+ if (raceTimers.has(id)) return;
621
+ raceTimers.set(id, setTimeout(() => {
622
+ raceTimers.delete(id);
623
+ try {
624
+ broadcast({ t: 'race', race: races.view(id) });
625
+ } catch {}
626
+ }, 300));
627
+ });
628
+ races.on('removed', (id) => broadcast({ t: 'race-removed', id }));
629
+ manager.on('projects', (projects) => {
630
+ broadcast({ t: 'projects', projects });
631
+ broadcast({ t: 'backlog', backlog: backlog.view() });
632
+ });
633
+
634
+ wss.on('connection', (ws, req) => {
635
+ const url = new URL(req.url, 'http://x');
636
+ if (url.pathname === '/ws/events') {
637
+ eventClients.add(ws);
638
+ ws.send(JSON.stringify({ t: 'snapshot', agents: manager.list(), backlog: backlog.view(), projects: manager.listProjects(), races: races.list() }));
639
+ ws.on('close', () => eventClients.delete(ws));
640
+ return;
641
+ }
642
+
643
+ const m = url.pathname.match(/^\/ws\/term\/([\w-]+)$/);
644
+ if (!m) return ws.close(1008, 'unknown endpoint');
645
+ let session;
646
+ try {
647
+ const agent = manager.mustGet(m[1]);
648
+ const client = {
649
+ send: (msg) => ws.readyState === ws.OPEN && ws.send(JSON.stringify(msg)),
650
+ close: () => ws.close(1000, 'agent removed'),
651
+ };
652
+ const kind = termKind(url.searchParams.get('kind'));
653
+ session = attachTerm(agent.id, kind, client);
654
+ client.send({ t: 'hello', id: agent.id, kind, running: session.running, backlog: session.backlog });
655
+ ws.on('message', (raw) => {
656
+ let msg;
657
+ try {
658
+ msg = JSON.parse(raw.toString());
659
+ } catch {
660
+ return;
661
+ }
662
+ if (msg.t === 'i' && typeof msg.d === 'string') manager.write(agent.id, msg.d, kind);
663
+ else if (msg.t === 'r') manager.resize(agent.id, msg.cols | 0, msg.rows | 0, kind);
664
+ });
665
+ ws.on('close', () => session.detach());
666
+ } catch (err) {
667
+ ws.close(1008, err.message.slice(0, 120));
668
+ }
669
+ });
670
+
671
+ // ---------------------------------------------------------- listeners
672
+
673
+ const server = http.createServer(app);
674
+ // Outlive clients' idle keep-alive sockets (Node fetch keeps them ~4s+): with the 5s
675
+ // default, a request sent on a socket just as the server closes it fails with ECONNRESET.
676
+ server.keepAliveTimeout = 65_000;
677
+ server.headersTimeout = 66_000;
678
+ server.on('upgrade', onUpgrade(false));
679
+
680
+ async function startRemote() {
681
+ const settings = remote.loadSettings();
682
+ if (remoteServer && remotePort === settings.port) return;
683
+ await stopRemote();
684
+ const { key, cert } = await remote.ensureCertificate();
685
+ remote.accessToken(); // make sure one exists
686
+ const srv = https.createServer({ key: fs.readFileSync(key), cert: fs.readFileSync(cert) }, (req, res) => {
687
+ req.remote = true;
688
+ app(req, res);
689
+ });
690
+ srv.keepAliveTimeout = 65_000;
691
+ srv.headersTimeout = 66_000;
692
+ srv.on('upgrade', onUpgrade(true));
693
+ await new Promise((resolve, reject) => {
694
+ srv.once('error', reject);
695
+ srv.listen(settings.port, '0.0.0.0', resolve);
696
+ });
697
+ remoteServer = srv;
698
+ remotePort = settings.port;
699
+ console.log(`[agentmgr] remote access on ${remote.remoteUrls(settings.port).map((u) => u.url).join(', ')}`);
700
+ }
701
+
702
+ async function stopRemote() {
703
+ if (!remoteServer) return;
704
+ const srv = remoteServer;
705
+ remoteServer = null;
706
+ remotePort = null;
707
+ await previews.stopAll();
708
+ srv.closeAllConnections?.();
709
+ await new Promise((r) => srv.close(() => r()));
710
+ }
711
+
712
+ let closing = false;
713
+ async function shutdown(reason) {
714
+ if (closing) return;
715
+ closing = true;
716
+ console.log(`[agentmgr] shutting down (${reason}); closing agents so their sessions are saved`);
717
+ await manager.stopAll({ final: true });
718
+ await manager.flush().catch((err) => console.error(`[agentmgr] final flush failed: ${err.message}`));
719
+ try {
720
+ if (fs.readFileSync(paths.pid, 'utf8').trim() === String(process.pid)) fs.unlinkSync(paths.pid);
721
+ } catch {}
722
+ await stopRemote();
723
+ live.stop();
724
+ hubLink.stop();
725
+ server.close();
726
+ process.exit(0);
727
+ }
728
+ process.on('SIGINT', () => shutdown('SIGINT'));
729
+ process.on('SIGTERM', () => shutdown('SIGTERM'));
730
+
731
+ await new Promise((resolve, reject) => {
732
+ server.once('error', reject);
733
+ server.listen(port, host, resolve);
734
+ });
735
+ fs.writeFileSync(paths.pid, String(process.pid));
736
+ if (remote.loadSettings().enabled) {
737
+ await startRemote().catch((err) => console.error(`[agentmgr] remote access not started: ${err.message}`));
738
+ }
739
+ if (config.autoResume) {
740
+ manager.resumeAll().then((ids) => {
741
+ if (ids.length) console.log(`[agentmgr] resumed ${ids.length} agent(s) from before the restart: ${ids.join(', ')}`);
742
+ });
743
+ }
744
+ manager.refreshAll().catch(() => {});
745
+ hubLink.start();
746
+ return {
747
+ hubLink,
748
+ server,
749
+ manager,
750
+ backlog,
751
+ live,
752
+ url: `http://${host}:${port}`,
753
+ startRemote,
754
+ stopRemote,
755
+ get remoteServer() {
756
+ return remoteServer;
757
+ },
758
+ };
759
+ }