ai-agentmanager 1.1.0 → 1.3.0

package/src/server.js

@@ -10,8 +10,17 @@ import { ensureHome, HOST, loadConfig, paths, PORT, saveConfig } from './config.
 import { AgentManager, shellNumber } from './manager.js';
 import { Backlog } from './backlog.js';
 import { Races } from './races.js';
+import { Review } from './review.js';
 import { Teams } from './teams.js';
+import { Assistant } from './assistant.js';
 import { Cleanup } from './cleanup.js';
+import { Landing } from './landing.js';
+import { Budgets } from './budgets.js';
+import { stats } from './stats.js';
+import { Playbooks } from './playbooks.js';
+import { Memory } from './memory.js';
+import { doctor } from './doctor.js';
+import { Triggers, tokenMatches } from './triggers.js';
 import { listEngines, registerEngine } from './engines/index.js';
 import { Plugins, pluginSpecs } from './plugins.js';
 import { HubLink, linkUrls } from './hublink.js';
@@ -46,7 +55,9 @@ function isAllowedOrigin(origin, port) {
 }
 
 const PUBLIC_REMOTE_API = new Set(['POST /api/login', 'GET /api/session']);
-const LOCAL_ONLY_API = /^\/api\/(remote(\/|$)|notify(\/|$)|hub(\/|$)|shutdown$)/;
+const LOCAL_ONLY_API = /^\/api\/(remote(\/|$)|notify(\/|$)|hub(\/|$)|triggers(\/|$)|shutdown$)/;
+const HOOK_PATH = '/api/hooks/agents';
+const NO_REPO_KINDS = new Set(['general', 'assistant']);
 
 export async function startServer({ port = PORT, host = HOST } = {}) {
   ensureHome();
@@ -57,8 +68,11 @@ export async function startServer({ port = PORT, host = HOST } = {}) {
   const manager = new AgentManager({ store, config, plugins });
   const backlog = new Backlog({ manager, store, config });
   const races = new Races({ manager, store });
+  const review = new Review({ manager });
   const teams = new Teams({ manager, store, config });
   const cleanup = new Cleanup({ manager, store, config, teams });
+  const landing = new Landing({ manager, store, config });
+  const assistant = new Assistant({ manager, store, config });
   // Alerts link to the phone address when remote access is on, else the local UI.
   const notifier = new Notifier({
     manager,
@@ -69,6 +83,10 @@ export async function startServer({ port = PORT, host = HOST } = {}) {
       return `${phone ? phone.url : `http://127.0.0.1:${port}/`}#${id}/term`;
     },
   });
+  const triggers = new Triggers({ manager, store, config, notifier });
+  const budgets = new Budgets({ manager, store, config, notifier });
+  const playbooks = new Playbooks({ manager, store });
+  const memory = new Memory({ manager, config });
   let remoteServer = null;
   let remotePort = null;
   // Live browser tabs: what a page does is saved on the agent's tab; popups become new tabs.
@@ -135,9 +153,13 @@ export async function startServer({ port = PORT, host = HOST } = {}) {
     res.setHeader('X-Frame-Options', 'DENY');
     res.setHeader('Referrer-Policy', 'no-referrer');
     res.setHeader('X-Content-Type-Options', 'nosniff');
+    // The webhook signs in with its token instead of a device session or the client header.
+    const bearer = /^Bearer (.+)$/i.exec(req.headers.authorization ?? '')?.[1];
+    const hook = req.method === 'POST' && req.url.split('?')[0] === HOOK_PATH && tokenMatches(req.headers['x-agentmgr-token'] ?? bearer, config.triggers?.webhook?.enabled ? config.triggers.webhook.token : null);
     const why = denied(req);
-    if (why) return res.status(why === 'Sign in required' ? 401 : 403).json({ error: why });
-    if (!['GET', 'HEAD'].includes(req.method) && req.headers[CLIENT_HEADER] !== '1') {
+    if (why && !(hook && why === 'Sign in required')) return res.status(why === 'Sign in required' ? 401 : 403).json({ error: why });
+    if (req.url.split('?')[0] === HOOK_PATH && !hook) return res.status(401).json({ error: 'Bad or missing token' });
+    if (!hook && !['GET', 'HEAD'].includes(req.method) && req.headers[CLIENT_HEADER] !== '1') {
       return res.status(403).json({ error: `Missing ${CLIENT_HEADER} header` });
     }
     next();
@@ -177,8 +199,16 @@ export async function startServer({ port = PORT, host = HOST } = {}) {
   api.post(
     '/agents',
     wrap((req) => {
-      const { intents, intent, ...opts } = req.body ?? {};
-      return manager.createMany(Array.isArray(intents) ? intents : [intent], opts);
+      const { intents, intent, startedBy, ...opts } = req.body ?? {};
+      if (opts.kind === 'assistant') throw fail(400, 'Start the assistant with POST /assistant/start');
+      const list = (Array.isArray(intents) ? intents : [intent]).map((i) => String(i ?? '').trim()).filter(Boolean);
+      // Agents the assistant's own session starts: its limits apply, and they are marked as its.
+      const extra = assistant.admit(req.headers['x-agentmgr-agent'], list, opts);
+      const created = manager.createMany(list, { ...opts, ...extra });
+      if (extra.startedBy) {
+        for (const a of created) notifier.send('assistant', a, `was started by the assistant: ${a.intent.replace(/\s+/g, ' ').slice(0, 160)}`);
+      }
+      return created;
     }),
   );
   api.post('/general', wrap((req) => manager.createGeneral(req.body ?? {})));
@@ -393,6 +423,10 @@ export async function startServer({ port = PORT, host = HOST } = {}) {
     await manager.checkpoint(id);
     return manager.get(id);
   }));
+  api.get('/agents/:id/changes', wrap((req) => review.get(req.params.id)));
+  api.post('/agents/:id/changes/comments', wrap((req) => review.comment(req.params.id, req.body ?? {})));
+  api.post('/agents/:id/changes/commit', wrap((req) => review.commit(req.params.id, req.body ?? {})));
+  api.post('/agents/:id/changes/pr', wrap((req) => review.pr(req.params.id, req.body ?? {})));
   api.post('/agents/:id/fork', wrap((req) => manager.fork(req.params.id, req.body ?? {})));
 
   api.get('/races', wrap(() => races.list()));
@@ -404,6 +438,65 @@ export async function startServer({ port = PORT, host = HOST } = {}) {
   api.delete('/races/:id', wrap((req) => races.remove(req.params.id)));
 
   // Clean up old agents: the strategy and days (kept in config.json), what a run would do, run now.
+  api.get('/assistant', wrap(() => assistant.status()));
+  api.put('/assistant', wrap((req) => {
+    const next = assistant.update(req.body ?? {});
+    saveConfig({ assistant: next });
+    return assistant.status();
+  }));
+  api.post('/assistant/start', wrap(() => assistant.start()));
+  api.post('/assistant/pause', wrap(() => assistant.pause()));
+  api.post('/assistant/check', wrap(() => assistant.check()));
+  api.get('/triggers', wrap(() => triggers.view()));
+  api.put('/triggers', wrap((req) => {
+    const { saved, token } = triggers.update(req.body ?? {});
+    saveConfig({ triggers: saved });
+    return { ...triggers.view(), ...(token ? { token } : {}) };
+  }));
+  api.post('/triggers/poll', wrap(async () => ({ ...(await triggers.poll()), ...triggers.view() })));
+  api.post('/hooks/agents', wrap((req) => triggers.hook(req.body ?? {})));
+  api.get('/agents/:id/memory', wrap((req) => memory.read(req.params.id)));
+  api.put('/agents/:id/memory', wrap((req) => memory.write(req.params.id, req.body?.text)));
+  api.post('/agents/:id/learn', wrap((req) => memory.learn(req.params.id, req.body?.text, { by: req.headers['x-agentmgr-agent'] ? undefined : 'you' })));
+  // The first-run checklist: what is set up, and what this machine is missing.
+  api.get('/setup', wrap(async () => {
+    const checks = (await doctor().catch(() => [])).filter((c) => c.status === 'fail' || c.status === 'warn').filter((c) => c.name !== 'Daemon');
+    const agentsNow = store.list();
+    return {
+      checks,
+      steps: {
+        agent: agentsNow.some((a) => !NO_REPO_KINDS.has(a.kind)),
+        alerts: Boolean(loadNotify().enabled),
+        assistant: agentsNow.some((a) => a.kind === 'assistant') || Boolean(config.triggers?.github?.enabled || config.triggers?.webhook?.enabled),
+        remote: Boolean(remote.loadSettings().enabled),
+        budget: Boolean(config.budgets?.perAgentUsd || config.budgets?.perDayUsd),
+      },
+    };
+  }));
+  api.get('/playbooks', wrap(() => playbooks.list()));
+  api.post('/playbooks', wrap((req) => playbooks.create(req.body ?? {})));
+  api.put('/playbooks/:id', wrap((req) => playbooks.update(req.params.id, req.body ?? {})));
+  api.delete('/playbooks/:id', wrap((req) => playbooks.remove(req.params.id)));
+  api.post('/playbooks/:id/run', wrap((req) => playbooks.run(req.params.id, { vars: req.body?.vars ?? {} })));
+  api.get('/stats', wrap((req) => {
+    const days = req.query.days === undefined ? 30 : Math.max(0, Math.min(3650, Math.floor(Number(req.query.days)) || 0));
+    return stats(store.list(), { days, projectOf: (a) => manager.projectInfo(a)?.name ?? null });
+  }));
+  api.get('/budgets', wrap(() => budgets.status()));
+  api.put('/budgets', wrap((req) => {
+    const next = budgets.update(req.body ?? {});
+    saveConfig({ budgets: next });
+    return budgets.status();
+  }));
+  api.get('/landing', wrap(() => landing.list()));
+  api.put('/landing', wrap((req) => {
+    const next = landing.update(req.body ?? {});
+    saveConfig({ landing: next });
+    return landing.list();
+  }));
+  api.post('/agents/:id/land/update', wrap((req) => landing.updateBranch(req.params.id, req.body ?? {})));
+  api.post('/agents/:id/land/fix', wrap((req) => landing.fix(req.params.id, req.body ?? {})));
+  api.post('/agents/:id/land/merge', wrap((req) => landing.merge(req.params.id, req.body ?? {})));
   api.get('/cleanup', wrap(() => cleanup.status()));
   api.put('/cleanup', wrap(async (req) => {
     const next = cleanup.update(req.body ?? {});
@@ -756,6 +849,11 @@ export async function startServer({ port = PORT, host = HOST } = {}) {
     if (closing) return;
     closing = true;
     cleanup.close();
+    landing.close();
+    triggers.close();
+    budgets.close();
+    playbooks.close();
+    assistant.close();
     console.log(`[agentmgr] shutting down (${reason}); closing agents so their sessions are saved`);
     await manager.stopAll({ final: true });
     await manager.flush().catch((err) => console.error(`[agentmgr] final flush failed: ${err.message}`));
@@ -792,6 +890,11 @@ export async function startServer({ port = PORT, host = HOST } = {}) {
     manager,
     teams,
     cleanup,
+    landing,
+    triggers,
+    budgets,
+    playbooks,
+    assistant,
     backlog,
     live,
     url: `http://${host}:${port}`,

package/src/stats.js

@@ -0,0 +1,107 @@
+// Results across agents for a period: how many started and from where, pull requests opened and
+// merged, the merge rate, time to a first PR and to merge, cost per merged PR, and the same by
+// engine and model and by project. Everything comes from what agentmgr already records.
+import { costOf } from './budgets.js';
+
+const HOUR = 3_600_000;
+
+const median = (xs) => {
+  if (!xs.length) return null;
+  const s = [...xs].sort((a, b) => a - b);
+  const m = Math.floor(s.length / 2);
+  return s.length % 2 ? s[m] : (s[m - 1] + s[m]) / 2;
+};
+const round = (n, d = 2) => (n == null ? null : Math.round(n * 10 ** d) / 10 ** d);
+
+/** Where an agent came from. */
+export function sourceOf(a) {
+  if (a.kind === 'assistant') return 'assistant session';
+  if (a.startedBy) return 'assistant';
+  if (a.trigger) return a.trigger.source === 'github' ? 'GitHub label' : 'webhook';
+  if (a.playbook) return 'playbook';
+  if (a.backlogItem) return 'backlog';
+  if (a.team) return 'team';
+  if (a.race) return 'race';
+  if (a.forkOf) return 'fork';
+  if (a.imported) return 'imported';
+  return 'you';
+}
+
+/** PRs an agent opened or that were found on its branch (not ones it only mentioned). */
+const ownPrs = (a) => Object.values(a.prs ?? {}).filter((p) => p.source !== 'mentioned');
+
+function bucket() {
+  return { agents: 0, withPr: 0, merged: 0, closed: 0, open: 0, cost: 0, toPrH: [], toMergeH: [], fixes: 0 };
+}
+
+function add(b, a) {
+  const prs = ownPrs(a);
+  const created = Date.parse(a.createdAt);
+  b.agents += 1;
+  b.cost += costOf(a);
+  if (prs.length) b.withPr += 1;
+  b.merged += prs.filter((p) => p.state === 'MERGED').length;
+  b.closed += prs.filter((p) => p.state === 'CLOSED').length;
+  b.open += prs.filter((p) => p.state === 'OPEN').length;
+  const opened = prs.map((p) => Date.parse(p.openedAt)).filter(Number.isFinite).sort((x, y) => x - y)[0];
+  if (opened && created && opened >= created) b.toPrH.push((opened - created) / HOUR);
+  for (const p of prs.filter((x) => x.state === 'MERGED' && x.mergedAt)) {
+    const m = Date.parse(p.mergedAt);
+    if (created && m >= created) b.toMergeH.push((m - created) / HOUR);
+  }
+  b.fixes += Object.keys(a.landing?.sent ?? {}).length;
+}
+
+function finish(b) {
+  const decided = b.merged + b.closed;
+  return {
+    agents: b.agents,
+    withPr: b.withPr,
+    merged: b.merged,
+    closed: b.closed,
+    open: b.open,
+    mergeRate: decided ? round(b.merged / decided, 3) : null,
+    cost: round(b.cost),
+    costPerMerged: b.merged ? round(b.cost / b.merged) : null,
+    medianHoursToPr: round(median(b.toPrH), 1),
+    medianHoursToMerge: round(median(b.toMergeH), 1),
+    fixesSent: b.fixes,
+  };
+}
+
+/** Results for agents created in the last `days` days (0: all of them). */
+export function stats(agents, { days = 30, now = Date.now(), projectOf = () => null } = {}) {
+  const since = days ? now - days * 24 * HOUR : 0;
+  const list = agents.filter((a) => a.kind !== 'general' && a.kind !== 'assistant' && Date.parse(a.createdAt) >= since);
+  const total = bucket();
+  const by = { source: new Map(), engine: new Map(), project: new Map() };
+  const put = (map, key, a) => {
+    if (!map.has(key)) map.set(key, bucket());
+    add(map.get(key), a);
+  };
+  for (const a of list) {
+    add(total, a);
+    put(by.source, sourceOf(a), a);
+    put(by.engine, `${a.engine ?? 'claude'}${a.model ? ` · ${a.model}` : ''}`, a);
+    put(by.project, projectOf(a) ?? 'none', a);
+  }
+  const rows = (map) =>
+    [...map.entries()]
+      .map(([key, b]) => ({ key, ...finish(b) }))
+      .sort((x, y) => y.agents - x.agents)
+      .slice(0, 20);
+  // Agents per day, for a small chart.
+  const perDay = {};
+  for (const a of list) {
+    const d = new Date(a.createdAt).toISOString().slice(0, 10);
+    perDay[d] = (perDay[d] ?? 0) + 1;
+  }
+  return {
+    days,
+    total: finish(total),
+    bySource: rows(by.source),
+    byEngine: rows(by.engine),
+    byProject: rows(by.project),
+    perDay: Object.entries(perDay).sort(([a], [b]) => (a < b ? -1 : 1)).map(([day, n]) => ({ day, agents: n })),
+  };
+}

package/src/tracker.js

@@ -72,8 +72,9 @@ export function recentSessionFiles(cwd, sinceMs) {
 const URL_TOKEN = /https?:\/\/[^\s"'<>`\\)\]]+/g;
 const PR_PATH = /^https?:\/\/[\w.-]+\/([\w.-]+\/[\w.-]+)\/pull\/(\d+)/;
 const GH_ISSUE_PATH = /^https?:\/\/[\w.-]+\/([\w.-]+\/[\w.-]+)\/issues\/(\d+)(?:[/?#]|$)/;
-// Jira keys in links: /browse/KEY-1, ?selectedIssue=KEY-1 (boards, Polaris ideas), /issues/KEY-1.
-const JIRA_KEY = /(?:\/browse\/|[?&]selectedIssue=|\/issues\/)([A-Z][A-Z0-9_]+-\d+)\b/;
+// Issue keys in links: Jira /browse/KEY-1 and ?selectedIssue=KEY-1 (boards, Polaris ideas),
+// /issues/KEY-1, and Linear /issue/KEY-1.
+const JIRA_KEY = /(?:\/browse\/|[?&]selectedIssue=|\/issues?\/)([A-Z][A-Z0-9_]+-\d+)\b/;
 
 const trimUrl = (url) => url.replace(/[.,;:!?'"]+$/, '');
 
@@ -95,7 +96,7 @@ export function bugFromRef(ref, source) {
   return { key: ref, url: null, source };
 }
 
-/** The Jira key when the text starts with a Jira link ("https://x.atlassian.net/browse/ABC-1 fix it" → "ABC-1"). */
+/** The issue key when the text starts with a Jira or Linear link ("https://x.atlassian.net/browse/ABC-1 fix it" → "ABC-1"). */
 export function leadingJiraKey(text) {
   const first = String(text ?? '').trimStart().match(/^<?(https?:\/\/\S+)/);
   return first?.[1].match(JIRA_KEY)?.[1] ?? null;
@@ -218,17 +219,69 @@ export function scanTranscript(file, cursor, bugPatterns = []) {
   return result;
 }
 
+/** The gh CLI to run (AGENTMGR_GH_BIN points the tests at a fake one). */
+export const ghBin = () => process.env.AGENTMGR_GH_BIN || 'gh';
+
+const PR_FIELDS = 'number,title,url,state,isDraft,headRefOid,reviewDecision,mergeable,mergeStateStatus,statusCheckRollup,createdAt,mergedAt';
+const FAILED = new Set(['FAILURE', 'ERROR', 'TIMED_OUT', 'CANCELLED', 'ACTION_REQUIRED', 'STARTUP_FAILURE']);
+const PASSED = new Set(['SUCCESS', 'NEUTRAL', 'SKIPPED']);
+
+/** gh's statusCheckRollup -> { state: passed|failed|running|none, failed: [names], running, total } */
+export function checkSummary(rollup) {
+  const list = Array.isArray(rollup) ? rollup : [];
+  const failed = [];
+  let running = 0;
+  for (const c of list) {
+    // Check runs have status/conclusion; commit statuses have state.
+    const result = c.conclusion || (c.status && c.status !== 'COMPLETED' ? 'PENDING' : null) || c.state || 'PENDING';
+    if (FAILED.has(result)) failed.push(c.name || c.context || 'check');
+    else if (!PASSED.has(result)) running += 1;
+  }
+  const state = !list.length ? 'none' : failed.length ? 'failed' : running ? 'running' : 'passed';
+  return { state, failed: failed.slice(0, 10), running, total: list.length };
+}
+
+/** Where a pull request stands on its way in: merged, closed, draft, fix, behind, ready or waiting. */
+export function landState(pr) {
+  if (!pr?.state) return null;
+  if (pr.state === 'MERGED') return 'merged';
+  if (pr.state === 'CLOSED') return 'closed';
+  if (pr.isDraft) return 'draft';
+  const checks = pr.checks?.state;
+  if (checks === 'failed' || pr.review === 'CHANGES_REQUESTED' || pr.mergeable === 'CONFLICTING' || pr.mergeState === 'DIRTY') return 'fix';
+  if (pr.mergeState === 'BEHIND') return 'behind';
+  if (checks === 'running') return 'waiting';
+  if (pr.mergeState === 'CLEAN' || pr.mergeState === 'HAS_HOOKS' || pr.mergeState === 'UNSTABLE') return 'ready';
+  if (pr.review === 'APPROVED' && pr.mergeable === 'MERGEABLE') return 'ready';
+  return 'waiting';
+}
+
+/** Keep what we use from gh's PR JSON, small enough to store per agent. */
+export function compactPr(p) {
+  if (!p) return p;
+  const { statusCheckRollup, reviewDecision, mergeStateStatus, headRefOid, mergeable, createdAt, mergedAt, ...rest } = p;
+  const out = { ...rest };
+  if (createdAt) out.openedAt = createdAt;
+  if (mergedAt) out.mergedAt = mergedAt;
+  if (statusCheckRollup !== undefined) out.checks = checkSummary(statusCheckRollup);
+  if (reviewDecision !== undefined) out.review = reviewDecision || null;
+  if (mergeable !== undefined) out.mergeable = mergeable || null;
+  if (mergeStateStatus !== undefined) out.mergeState = mergeStateStatus || null;
+  if (headRefOid) out.head = headRefOid;
+  return out;
+}
+
 /** PRs whose head is `branch`, via the gh CLI. Returns [] when gh is missing or unauthenticated. */
 export async function prsForBranch(cwd, branch) {
   if (process.env.AGENTMGR_NO_GH) return [];
   if (!branch || branch === 'HEAD' || ['main', 'master', 'develop', 'trunk'].includes(branch)) return [];
   try {
     const out = await run(
-      'gh',
-      ['pr', 'list', '--head', branch, '--state', 'all', '--limit', '20', '--json', 'number,title,url,state,isDraft'],
+      ghBin(),
+      ['pr', 'list', '--head', branch, '--state', 'all', '--limit', '20', '--json', PR_FIELDS],
       { cwd, timeout: 30_000 },
     );
-    return JSON.parse(out || '[]').map((p) => ({ ...prFromUrl(p.url, 'branch'), ...p }));
+    return JSON.parse(out || '[]').map((p) => ({ ...prFromUrl(p.url, 'branch'), ...compactPr(p) }));
   } catch {
     return [];
   }
@@ -238,8 +291,8 @@ export async function prsForBranch(cwd, branch) {
 export async function prDetails(url) {
   if (process.env.AGENTMGR_NO_GH) return null;
   try {
-    const out = await run('gh', ['pr', 'view', url, '--json', 'number,title,url,state,isDraft'], { timeout: 30_000 });
-    return JSON.parse(out);
+    const out = await run(ghBin(), ['pr', 'view', url, '--json', PR_FIELDS], { timeout: 30_000 });
+    return compactPr(JSON.parse(out));
   } catch {
     return null;
   }

package/src/triggers.js

@@ -0,0 +1,258 @@
+// Triggers: start agents and pass on instructions from where the work lives, with no model
+// watching (no tokens spent). Three sources:
+// - GitHub label: open issues with a label (default "agentmgr") in the repos or owners you list
+//   each get an agent in that repo. Labeling needs triage access, so it is the go-ahead.
+// - "/agent" comments on an agent's own pull request, by the repo's owners, members or
+//   collaborators, are typed into that agent.
+// - Webhook: POST /api/hooks/agents with the secret token creates an agent (Jira automation,
+//   CI, scripts). Off until a token is set; reachable from other machines only with remote access.
+import crypto from 'node:crypto';
+import { run } from './git.js';
+import { ghBin } from './tracker.js';
+
+export const TRIGGER_DEFAULTS = {
+  github: { enabled: false, label: 'agentmgr', repos: [], owners: [], everyMin: 5, comment: false },
+  prCommands: { enabled: true, prefix: '/agent' },
+  webhook: { enabled: false, token: null, repos: [] },
+  maxPerDay: 20,
+};
+const TRUSTED = new Set(['OWNER', 'MEMBER', 'COLLABORATOR']);
+const REPO_RE = /^[\w.-]+\/[\w.-]+$/;
+
+const err = (status, message) => Object.assign(new Error(message), { status });
+const list = (v) => (Array.isArray(v) ? v : String(v ?? '').split(/[\s,]+/)).map((x) => String(x).trim()).filter(Boolean);
+
+/** Settings from config.json's "triggers", with defaults; the webhook token is never returned by `view`. */
+export function triggerSettings(config = {}) {
+  const t = config.triggers ?? {};
+  const gh = { ...TRIGGER_DEFAULTS.github, ...t.github };
+  const pc = { ...TRIGGER_DEFAULTS.prCommands, ...t.prCommands };
+  const wh = { ...TRIGGER_DEFAULTS.webhook, ...t.webhook };
+  const every = Number(gh.everyMin);
+  const max = Number(t.maxPerDay ?? TRIGGER_DEFAULTS.maxPerDay);
+  return {
+    github: {
+      enabled: Boolean(gh.enabled),
+      label: String(gh.label || 'agentmgr').trim(),
+      repos: list(gh.repos).filter((r) => REPO_RE.test(r)),
+      owners: list(gh.owners).filter((o) => /^[\w.-]+$/.test(o)),
+      everyMin: Number.isFinite(every) && every >= 1 ? Math.min(1440, Math.floor(every)) : 5,
+      comment: Boolean(gh.comment),
+    },
+    prCommands: { enabled: pc.enabled !== false, prefix: String(pc.prefix || '/agent').trim() },
+    webhook: { enabled: Boolean(wh.enabled && wh.token), token: wh.token || null, repos: list(wh.repos) },
+    maxPerDay: Number.isFinite(max) && max >= 0 ? Math.min(500, Math.floor(max)) : TRIGGER_DEFAULTS.maxPerDay,
+  };
+}
+
+/** The request for an agent started from a GitHub issue. */
+export function issueIntent(issue) {
+  const body = String(issue.body ?? '').trim();
+  return `${issue.url}\n\n${issue.title}${body ? `\n\n${body.slice(0, 6000)}` : ''}\n\nWhen you are done, open a pull request that says "Fixes #${issue.number}".`;
+}
+
+/** A PR comment for the agent, or null when it isn't a command from someone trusted. */
+export function prCommand(comment, prefix = '/agent') {
+  const body = String(comment?.body ?? '').trim();
+  if (!body.toLowerCase().startsWith(prefix.toLowerCase())) return null;
+  if (!TRUSTED.has(comment.authorAssociation)) return null;
+  const text = body.slice(prefix.length).trim();
+  return text || null;
+}
+
+/** Same length and same bytes, without leaking where they differ. */
+export function tokenMatches(given, expected) {
+  if (!given || !expected) return false;
+  const a = Buffer.from(String(given));
+  const b = Buffer.from(String(expected));
+  return a.length === b.length && crypto.timingSafeEqual(a, b);
+}
+
+export class Triggers {
+  constructor({ manager, store, config = {}, notifier = null, log = (m) => console.log(`[agentmgr] ${m}`) }) {
+    this.manager = manager;
+    this.store = store;
+    this.config = config;
+    this.notifier = notifier;
+    this.log = log;
+    store.data.triggers ??= { issues: {}, comments: {}, started: [], lastPoll: null, lastError: null };
+    this.schedule();
+  }
+
+  get state() {
+    return this.store.data.triggers;
+  }
+
+  get settings() {
+    return triggerSettings(this.config);
+  }
+
+  schedule() {
+    clearInterval(this.timer);
+    this.timer = setInterval(() => this.poll().catch((e) => this.fail(e)), this.settings.github.everyMin * 60_000);
+    this.timer.unref?.();
+  }
+
+  close() {
+    clearInterval(this.timer);
+  }
+
+  fail(e) {
+    this.state.lastError = { at: new Date().toISOString(), message: e.message.split('\n')[0].slice(0, 300) };
+    this.log(`triggers: ${this.state.lastError.message}`);
+  }
+
+  /** Settings for the UI: the token is replaced by whether one is set. */
+  view() {
+    const s = this.settings;
+    const today = this.startedToday();
+    return {
+      ...s,
+      webhook: { enabled: s.webhook.enabled, hasToken: Boolean(s.webhook.token), repos: s.webhook.repos },
+      startedToday: today.length,
+      recent: this.state.started.slice(-20).reverse(),
+      lastPoll: this.state.lastPoll,
+      lastError: this.state.lastError,
+    };
+  }
+
+  update(patch = {}) {
+    const cur = this.config.triggers ?? {};
+    const next = {
+      github: { ...cur.github, ...patch.github },
+      prCommands: { ...cur.prCommands, ...patch.prCommands },
+      webhook: { ...cur.webhook, ...patch.webhook },
+      maxPerDay: patch.maxPerDay ?? cur.maxPerDay,
+    };
+    if (patch.webhook?.newToken) {
+      next.webhook.token = crypto.randomBytes(24).toString('base64url');
+      delete next.webhook.newToken;
+    }
+    if (next.github.enabled && !list(next.github.repos).length && !list(next.github.owners).length) {
+      throw err(400, 'List the repos (owner/name) or owners to watch, so issues elsewhere on GitHub never start agents');
+    }
+    const s = triggerSettings({ triggers: next });
+    this.config.triggers = { github: s.github, prCommands: s.prCommands, webhook: { enabled: s.webhook.enabled, token: s.webhook.token, repos: s.webhook.repos }, maxPerDay: s.maxPerDay };
+    this.schedule();
+    return { saved: this.config.triggers, token: patch.webhook?.newToken ? s.webhook.token : undefined };
+  }
+
+  startedToday() {
+    const since = Date.now() - 86_400_000;
+    return this.state.started.filter((x) => Date.parse(x.at) > since);
+  }
+
+  /** Create one agent for a trigger, within the daily cap. */
+  start({ source, url, intent, repo, name, project, priority }) {
+    if (this.startedToday().length >= this.settings.maxPerDay) throw err(429, `Triggers started ${this.settings.maxPerDay} agents in the last day (triggers.maxPerDay)`);
+    const [agent] = this.manager.createMany([intent], {
+      repo,
+      name,
+      project,
+      priority,
+      trigger: { source, url: url ?? null, at: new Date().toISOString() },
+    });
+    this.state.started = [...this.state.started, { at: new Date().toISOString(), source, url: url ?? null, agent: agent.id, name: agent.name }].slice(-200);
+    this.store.save();
+    this.notifier?.send?.('assistant', agent, `was started from ${source === 'github' ? 'a GitHub label' : 'a webhook'}${url ? `: ${url}` : ''}`);
+    this.log(`triggers: started ${agent.name} from ${source}${url ? ` (${url})` : ''}`);
+    return agent;
+  }
+
+  async gh(args) {
+    return run(ghBin(), args, { timeout: 60_000 });
+  }
+
+  /** One pass: labeled issues, then commands on agents' pull requests. */
+  async poll() {
+    if (process.env.AGENTMGR_NO_GH) return { issues: 0, commands: 0 };
+    const s = this.settings;
+    let issues = 0;
+    let commands = 0;
+    if (s.github.enabled && (s.github.repos.length || s.github.owners.length)) issues = await this.pollIssues(s.github);
+    if (s.prCommands.enabled) commands = await this.pollPrCommands(s.prCommands.prefix);
+    this.state.lastPoll = { at: new Date().toISOString(), issues, commands };
+    this.state.lastError = null;
+    this.store.save();
+    return { issues, commands };
+  }
+
+  async pollIssues(g) {
+    const scopes = [...g.repos.map((r) => ['--repo', r]), ...g.owners.map((o) => ['--owner', o])];
+    let started = 0;
+    for (const scope of scopes) {
+      const out = await this.gh(['search', 'issues', '--label', g.label, '--state', 'open', ...scope, '--limit', '30', '--json', 'number,title,body,url,repository']);
+      for (const issue of JSON.parse(out || '[]')) {
+        if (this.state.issues[issue.url]) continue;
+        const nwo = issue.repository?.nameWithOwner;
+        if (!nwo || !REPO_RE.test(nwo)) continue;
+        // Mark first: a failure must not start the same issue again on every pass.
+        this.state.issues[issue.url] = { at: new Date().toISOString() };
+        try {
+          // A project already on this repo reuses its clone and settings.
+          const project = this.projectFor(nwo);
+          const agent = this.start({ source: 'github', url: issue.url, intent: issueIntent(issue), ...(project ? { project: project.shortcut } : { repo: `https://github.com/${nwo}` }), name: `${issue.repository.name}#${issue.number}` });
+          this.state.issues[issue.url].agent = agent.id;
+          started += 1;
+          if (g.comment) {
+            await this.gh(['issue', 'comment', issue.url, '--body', `AI Agent Manager started an agent on this (\`${agent.name}\`). It will open a pull request.`]).catch(() => {});
+          }
+        } catch (e) {
+          this.state.issues[issue.url].error = e.message;
+          if (e.status === 429) break;
+        }
+      }
+    }
+    return started;
+  }
+
+  projectFor(nwo) {
+    const re = new RegExp(`github\\.com[:/]${nwo.replace(/[.]/g, '\\.')}(\\.git)?/?$`, 'i');
+    return Object.values(this.store.data.projects ?? {}).find((p) => p.repo && re.test(p.repo) && p.shortcut) ?? null;
+  }
+
+  async pollPrCommands(prefix) {
+    let sent = 0;
+    for (const agent of this.store.list()) {
+      for (const pr of Object.values(agent.prs ?? {})) {
+        if (pr.state !== 'OPEN' || pr.source === 'mentioned') continue;
+        const out = await this.gh(['pr', 'view', pr.url, '--json', 'comments']).catch(() => null);
+        if (!out) continue;
+        const comments = JSON.parse(out).comments ?? [];
+        const seen = (this.state.comments[pr.url] ??= { ids: [], since: new Date().toISOString() });
+        for (const c of comments) {
+          const id = c.id ?? c.url ?? `${c.author?.login}:${c.createdAt}`;
+          if (seen.ids.includes(id)) continue;
+          seen.ids = [...seen.ids, id].slice(-200);
+          // Comments from before we started watching this PR are history, not commands.
+          if (Date.parse(c.createdAt) < Date.parse(seen.since)) continue;
+          const text = prCommand(c, prefix);
+          if (!text) continue;
+          try {
+            this.manager.tell(agent.id, `${c.author?.login ?? 'Someone'} asked on your pull request ${pr.url}:\n${text}\n\nDo it, push, and reply on the pull request when done.`, { source: 'github' });
+            sent += 1;
+          } catch (e) {
+            this.log(`triggers: couldn't pass a comment to ${agent.name}: ${e.message}`);
+          }
+        }
+      }
+    }
+    return sent;
+  }
+
+  /** The webhook: { intent, repo?, project?, name?, priority? } with the token. */
+  hook(body = {}) {
+    const s = this.settings;
+    if (!s.webhook.enabled) throw err(404, 'Not found');
+    const intent = String(body.intent ?? '').trim();
+    if (!intent) throw err(400, 'intent is required');
+    const repo = body.repo ? String(body.repo).trim() : undefined;
+    const project = body.project ? String(body.project).trim() : undefined;
+    if (!repo && !project) throw err(400, 'repo or project is required');
+    if (s.webhook.repos.length && repo && !s.webhook.repos.some((r) => repo === r || repo.endsWith(`/${r}`) || repo.endsWith(`/${r}.git`))) {
+      throw err(403, 'That repo is not in triggers.webhook.repos');
+    }
+    const agent = this.start({ source: 'webhook', url: body.url ? String(body.url) : null, intent, repo, project, name: body.name ? String(body.name) : undefined, priority: body.priority });
+    return { id: agent.id, name: agent.name };
+  }
+}