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/judge.js ADDED
@@ -0,0 +1,278 @@
1
+ // The AI judge: cheap rules decide *when* to look, a model decides *what is going on*.
2
+ // stuck - a rule saw a pattern (repeated failure, thrashing, drift); is the agent really stuck,
3
+ // and what specific nudge would help?
4
+ // screen - an agent went idle and no known prompt matched; is it asking something, finished,
5
+ // or broken?
6
+ // review - an agent says (or looks) done; does the work meet the intent and brief?
7
+ // clash - two agents in one repo touch the same files or folders; will their work collide,
8
+ // and which should land first?
9
+ // dispatch- the backlog has free slots; which queued item next, which must wait for another,
10
+ // which is too big and should be split?
11
+ // alert - a Slack alert is about to go out; now, in the next digest, or not at all?
12
+ // Every call is one tool-less one-shot request returning JSON. When the judge is off, over its
13
+ // daily budget, or the call fails, callers keep the rule-based result. The person's reactions
14
+ // (dismissed, nudged, sent back, accepted) are kept and shown to the judge as recent examples,
15
+ // so it calibrates to how this person works.
16
+ import crypto from 'node:crypto';
17
+ import fs from 'node:fs';
18
+ import path from 'node:path';
19
+ import { contextBlock, parseJsonReply } from './brief.js';
20
+ import { paths } from './config.js';
21
+
22
+ export const JUDGE_DEFAULTS = { enabled: true, engine: null, model: null, dailyCalls: 300, concurrency: 2, timeoutSec: 120, idleSec: 20, warmupSec: 15, digestMin: 60 };
23
+ const FEEDBACK_KEEP = 60;
24
+ const file = () => path.join(paths.home, 'judge.json');
25
+ const today = () => new Date().toISOString().slice(0, 10);
26
+ export const hash = (s) => crypto.createHash('sha1').update(String(s)).digest('hex').slice(0, 16);
27
+
28
+ export function loadJudgeState() {
29
+ try {
30
+ return JSON.parse(fs.readFileSync(file(), 'utf8'));
31
+ } catch {
32
+ return {};
33
+ }
34
+ }
35
+
36
+ const RULES = [
37
+ 'Reply with one JSON object only, no prose around it.',
38
+ 'Judge from the evidence below; do not invent facts. When the evidence is thin, say so with a low confidence.',
39
+ 'confidence is a number from 0 to 1.',
40
+ ].join('\n');
41
+
42
+ const examples = (list) =>
43
+ list.length
44
+ ? ['<recent_decisions_by_this_person>', ...list.map((f) => `- ${f.summary} → AI said: ${f.verdict}; the person ${f.outcome}`), '</recent_decisions_by_this_person>', 'Calibrate to these: if the person keeps dismissing a kind of call, be more conservative about it.']
45
+ : [];
46
+
47
+ /** Recent tool calls, one line each, oldest first. */
48
+ export function activityLines(events = [], n = 40) {
49
+ return events
50
+ .slice(-n)
51
+ .map((e) => {
52
+ const at = new Date(e.t).toISOString().slice(11, 19);
53
+ if (e.kind === 'cmd') return `${at} run \`${e.cmd?.slice(0, 160)}\`${e.result === undefined ? '' : e.failed ? ` → FAILED: ${e.shown ?? ''}` : ' → ok'}`;
54
+ if (e.kind === 'edit') return `${at} edit ${e.file}${e.edits?.length ? ` (${e.edits.length} change${e.edits.length > 1 ? 's' : ''})` : ''}`;
55
+ return `${at} ${e.name ?? 'tool'}`;
56
+ })
57
+ .join('\n');
58
+ }
59
+
60
+ export function stuckPrompt(ctx, finding, events, past = []) {
61
+ return [
62
+ 'You supervise an AI coding agent for a person. A cheap heuristic flagged that the agent may be stuck.',
63
+ 'Decide whether it really is stuck (going in circles, not converging) or making reasonable progress',
64
+ '(for example: reading a large codebase, a long but converging debug loop, an expected failing test it is fixing).',
65
+ 'If it is stuck, write a short, specific nudge the person can send: name the likely root cause or the different',
66
+ 'approach to try, based on the activity. Speak to the agent directly, two to four sentences.',
67
+ RULES,
68
+ 'Shape: {"stuck": true|false, "confidence": 0.0, "title": "short headline", "diagnosis": "one or two sentences", "nudge": "message to the agent, or empty"}',
69
+ '',
70
+ '<heuristic_finding>',
71
+ `${finding.title}. ${finding.detail}`,
72
+ '</heuristic_finding>',
73
+ '<recent_tool_calls>',
74
+ activityLines(events) || '(none recorded)',
75
+ '</recent_tool_calls>',
76
+ ...contextBlock(ctx),
77
+ ...examples(past),
78
+ ].join('\n');
79
+ }
80
+
81
+ export function screenPrompt(ctx, screen, past = []) {
82
+ return [
83
+ 'You supervise an AI coding agent running in a terminal. It has stopped producing output.',
84
+ 'Read the end of its terminal screen and decide what state it is in:',
85
+ '- "question": it asked the person something and is waiting for an answer (a choice, approval, missing info)',
86
+ '- "done": it says it finished the task it was given',
87
+ '- "error": it crashed, hit an error it cannot recover from, or a limit (rate limit, auth, quota)',
88
+ '- "idle": finished a step and is simply waiting for the next instruction, nothing specific to answer',
89
+ 'For "question", copy the question in plain words and list the choices it offered, if any.',
90
+ RULES,
91
+ 'Shape: {"state": "question|done|error|idle", "confidence": 0.0, "summary": "one line for an inbox", "question": "or empty", "choices": ["..."]}',
92
+ '',
93
+ '<terminal_screen>',
94
+ screen,
95
+ '</terminal_screen>',
96
+ '<intent>',
97
+ ctx.intent || '(none)',
98
+ '</intent>',
99
+ ...examples(past),
100
+ ].join('\n');
101
+ }
102
+
103
+ export function reviewPrompt(ctx, past = []) {
104
+ return [
105
+ 'You review an AI coding agent\'s work before a person looks at it. Compare what was asked (intent, brief)',
106
+ 'with what was done (conversation, repository changes, checks). Be concrete and skeptical: unverified claims',
107
+ 'are not met. Only list missing items that matter for the stated intent.',
108
+ '- "complete": the intent is met and verified well enough to hand to the person',
109
+ '- "partial": real progress, but named items are missing or unverified',
110
+ '- "not_done": the main ask is not done',
111
+ RULES,
112
+ 'Shape: {"verdict": "complete|partial|not_done", "confidence": 0.0, "summary": "two sentences", "met": ["..."], "missing": ["..."], "risks": ["..."]}',
113
+ '',
114
+ ...contextBlock(ctx),
115
+ ...examples(past),
116
+ ].join('\n');
117
+ }
118
+
119
+ const files = (c) =>
120
+ Object.entries(c?.files ?? {})
121
+ .slice(0, 40)
122
+ .map(([f, x]) => `${f} (+${x.added ?? 0} -${x.removed ?? 0})`)
123
+ .join('\n') || '(none)';
124
+
125
+ /** a/b: { name, intent, brief, changes: { files } } */
126
+ export function clashPrompt(a, b, past = []) {
127
+ const side = (tag, x) => [`<agent_${tag}>`, `name: ${x.name}`, `intent: ${x.intent || '(none)'}`, 'changed files:', files(x.changes), x.brief ? `brief:\n${x.brief.slice(0, 1200)}` : '', `</agent_${tag}>`];
128
+ return [
129
+ 'Two AI coding agents work on separate branches of the same repository and will both merge into it.',
130
+ 'Decide whether their work will collide: a textual merge conflict, or a semantic one (changing the same',
131
+ 'function, API, schema, config or behavior in incompatible ways, even from different files).',
132
+ 'Touching the same file in unrelated places is not a real collision. If they collide, say which should land',
133
+ 'first (usually the one others build on, or the smaller, more finished one) and give each agent one sentence of advice.',
134
+ RULES,
135
+ 'Shape: {"conflict": true|false, "confidence": 0.0, "reason": "one or two sentences", "mergeFirst": "A|B|", "orderReason": "", "adviceA": "", "adviceB": ""}',
136
+ '',
137
+ ...side('A', a),
138
+ ...side('B', b),
139
+ ...examples(past),
140
+ ].join('\n');
141
+ }
142
+
143
+ /** queued: [{ id, title, priority, project }], active: [{ id, title, project, changes }] */
144
+ export function dispatchPrompt(queued, active, past = []) {
145
+ return [
146
+ 'You schedule a backlog of coding tasks that AI agents pick up in parallel, each on its own branch.',
147
+ 'Priority (P0 highest) always wins; within a priority, put first what others depend on. Hold an item back',
148
+ 'when it depends on another open item or would collide with one being worked on now (same code, same files).',
149
+ 'Suggest splitting an item only when it clearly bundles several independent tasks.',
150
+ 'Use the ids exactly as given.',
151
+ RULES,
152
+ 'Shape: {"order": ["id", ...], "hold": [{"id": "", "after": "id of the item it waits for", "reason": ""}], "split": [{"id": "", "reason": "", "parts": ["task title", ...]}]}',
153
+ '',
154
+ '<queued>',
155
+ ...queued.map((q) => `- ${q.id} [P${q.priority}] (${q.project}) ${q.title}`),
156
+ '</queued>',
157
+ '<in_progress>',
158
+ ...(active.length ? active.map((x) => `- ${x.id} (${x.project}) ${x.title}\n changed: ${files(x.changes).split('\n').slice(0, 12).join(', ')}`) : ['(nothing)']),
159
+ '</in_progress>',
160
+ ...examples(past),
161
+ ].join('\n');
162
+ }
163
+
164
+ /** What should happen to one Slack alert. */
165
+ export function alertPrompt({ kind, what, agent, recent }, past = []) {
166
+ return [
167
+ 'You triage alerts about AI coding agents for a busy person, who should be interrupted only when it matters.',
168
+ '- "now": they should act soon (the agent is blocked on them, burning time, about to cause damage, or high priority work)',
169
+ '- "digest": worth knowing, can wait for a periodic summary',
170
+ '- "skip": noise (duplicates a recent alert, or nothing to do)',
171
+ RULES,
172
+ 'Shape: {"urgency": "now|digest|skip", "confidence": 0.0, "line": "the alert rewritten as one short line"}',
173
+ '',
174
+ `<alert kind="${kind}">${what}</alert>`,
175
+ `<agent>name: ${agent.name}; priority: P${agent.priority ?? 2}; status: ${agent.status}; intent: ${String(agent.intent ?? '').slice(0, 300)}</agent>`,
176
+ '<recent_alerts>',
177
+ ...(recent.length ? recent.map((r) => `- ${r.at} ${r.kind} ${r.agent}${r.urgency ? ` (${r.urgency})` : ''}`) : ['(none)']),
178
+ '</recent_alerts>',
179
+ ...examples(past),
180
+ ].join('\n');
181
+ }
182
+
183
+ /** The message that sends an agent back to finish what the review found missing. */
184
+ export function finishMessage(review) {
185
+ const items = (review.missing ?? []).map((m) => `- ${m}`).join('\n');
186
+ return `A review of your work against the task found these items still missing or unverified:\n${items}\nPlease finish them, verify each one, and update the brief when done.`;
187
+ }
188
+
189
+ export class Judge {
190
+ /** call(agent, prompt, { timeoutMs }) runs one one-shot request and resolves to its text. */
191
+ constructor({ config, call }) {
192
+ this.config = config;
193
+ this.call = call;
194
+ this.state = loadJudgeState();
195
+ this.running = 0;
196
+ this.queue = [];
197
+ this.inflight = new Map(); // cache key -> promise
198
+ }
199
+
200
+ get settings() {
201
+ return { ...JUDGE_DEFAULTS, ...this.config.judge };
202
+ }
203
+
204
+ get enabled() {
205
+ return Boolean(this.settings.enabled);
206
+ }
207
+
208
+ save() {
209
+ try {
210
+ fs.writeFileSync(file(), JSON.stringify(this.state, null, 2));
211
+ } catch {}
212
+ }
213
+
214
+ usage() {
215
+ if (this.state.day !== today()) Object.assign(this.state, { day: today(), calls: 0, failures: 0 });
216
+ return { day: this.state.day, calls: this.state.calls, failures: this.state.failures ?? 0, cap: this.settings.dailyCalls };
217
+ }
218
+
219
+ status() {
220
+ return { enabled: this.enabled, ...this.usage(), running: this.running, queued: this.queue.length, feedback: (this.state.feedback ?? []).length };
221
+ }
222
+
223
+ slot() {
224
+ if (this.running < this.settings.concurrency) {
225
+ this.running++;
226
+ return Promise.resolve();
227
+ }
228
+ return new Promise((resolve) => this.queue.push(resolve));
229
+ }
230
+
231
+ release() {
232
+ const next = this.queue.shift();
233
+ if (next) next();
234
+ else this.running--;
235
+ }
236
+
237
+ /**
238
+ * Ask once per cache key at a time; resolves to the parsed JSON, or null when the judge is off,
239
+ * over budget, or the reply was unusable (the caller then keeps its rule-based answer).
240
+ */
241
+ ask(key, agent, prompt, validate = () => true) {
242
+ if (!this.enabled) return Promise.resolve(null);
243
+ if (this.inflight.has(key)) return this.inflight.get(key);
244
+ const run = (async () => {
245
+ await this.slot();
246
+ try {
247
+ const u = this.usage();
248
+ if (u.calls >= u.cap) return null;
249
+ this.state.calls++;
250
+ const data = parseJsonReply(await this.call(agent, prompt, { timeoutMs: this.settings.timeoutSec * 1000 }));
251
+ if (!validate(data)) throw new Error('reply did not have the expected shape');
252
+ data.confidence = Math.max(0, Math.min(1, Number(data.confidence) || 0));
253
+ return data;
254
+ } catch (err) {
255
+ this.state.failures = (this.state.failures ?? 0) + 1;
256
+ this.state.lastError = { at: new Date().toISOString(), key: key.split(':')[0], message: String(err.message).slice(0, 300) };
257
+ return null;
258
+ } finally {
259
+ this.save();
260
+ this.release();
261
+ }
262
+ })().finally(() => this.inflight.delete(key));
263
+ this.inflight.set(key, run);
264
+ return run;
265
+ }
266
+
267
+ /** Remember how the person reacted to a judgment, for future calibration. */
268
+ feedback(kind, { summary, verdict, outcome }) {
269
+ const list = (this.state.feedback ??= []);
270
+ list.push({ kind, summary: String(summary).slice(0, 200), verdict: String(verdict).slice(0, 80), outcome, at: new Date().toISOString() });
271
+ if (list.length > FEEDBACK_KEEP) list.splice(0, list.length - FEEDBACK_KEEP);
272
+ this.save();
273
+ }
274
+
275
+ examples(kind, n = 6) {
276
+ return (this.state.feedback ?? []).filter((f) => f.kind === kind).slice(-n);
277
+ }
278
+ }