ai-agentmanager 1.7.0 → 1.9.0

package/public/review.js

@@ -1,7 +1,8 @@
 // Review screen: an agent's changes file by file, line comments sent back to the agent as one
 // message, and Commit / Push & open PR. Comments not sent yet are kept per agent in this browser.
 // With a walkthrough, each hunk shows its explanation and ◀ / ▶ step through them in reading order.
-import { cardHtml, explainButton, stepOf, walkthroughOf } from './walkthrough.js';
+import { cardHtml, explainButton, listenParts as walkParts, stepOf, walkthroughOf } from './walkthrough.js';
+import { listenHtml, now as speaking, stop as stopSpeaking } from './speak.js';
 
 /** Unified diff -> [{ path, status, binary, hunks: [{ head, lines: [{ t, old, new, text }] }] }] */
 export function parseDiff(text) {
@@ -163,7 +164,7 @@ export function initReview({ api, esc, toast, agents, $ }) {
     const nav = n
       ? `<span class="rv-walk"><button type="button" class="small ghost" data-rv-step="-1" title="Previous change ([)">◀</button><span class="hint">${st.step == null ? `${n} changes` : `${st.step + 1} of ${n}`}</span><button type="button" class="small ghost" data-rv-step="1" title="Next change (])">▶</button></span>`
       : '';
-    return `${nav}${explainButton(w, 'data-rv-explain')}`;
+    return `${nav}${n ? listenHtml(`walk:${st.id}`, { title: 'Hear the changes one by one; each is shown as it is read' }) : ''}${explainButton(w, 'data-rv-explain')}`;
   }
 
   function walkNote() {
@@ -432,6 +433,7 @@ export function initReview({ api, esc, toast, agents, $ }) {
 
   $('#review-close').onclick = () => dlg.close();
   dlg.addEventListener('close', () => {
+    if (speaking()?.id.startsWith('walk:')) stopSpeaking();
     st.id = null;
     st.note = st.msg = st.prTitle = '';
   });
@@ -447,5 +449,13 @@ export function initReview({ api, esc, toast, agents, $ }) {
     render();
   }
 
-  return { open, agentChanged, get openId() { return dlg.open ? st.id : null; } };
+  /** What Listen reads: the summary, then each change still in the diff, shown as it is read. */
+  function listenParts() {
+    const w = walk();
+    if (!w.doc) return [];
+    const ok = new Set(present(w));
+    return walkParts(w.doc.data, (i) => (ok.has(i) ? () => gotoStep(i) : null)).filter((p) => typeof p === 'string' || ok.has(p.i));
+  }
+
+  return { open, agentChanged, listenParts, get openId() { return dlg.open ? st.id : null; } };
 }

package/public/share.js

@@ -24,7 +24,7 @@ async function main() {
   document.title = (d.markdown.match(/^#\s+(.+)$/m)?.[1] ?? `${kind} · ${a.name}`).slice(0, 120);
   if (blocks.length) {
     const mermaid = (await import('/vendor/mermaid/mermaid.esm.min.mjs')).default;
-    mermaid.initialize({ startOnLoad: false, securityLevel: 'strict', theme: 'default' });
+    mermaid.initialize({ startOnLoad: false, securityLevel: 'strict', theme: 'default', htmlLabels: false, flowchart: { htmlLabels: false } });
     for (const el of document.querySelectorAll('.diagram')) {
       try {
         el.innerHTML = (await mermaid.render(`d${el.dataset.i}`, blocks[Number(el.dataset.i)])).svg;

package/public/side.js

@@ -2,10 +2,13 @@
 // pane shows the same agent's Code, its Docs (Diagrams by default) or its Changes explained one by
 // one. On, the tab and the document are remembered in this browser.
 import { parseDiff } from '/review.js';
-import { cardHtml, explainButton, walkthroughOf } from '/walkthrough.js';
+import { cardHtml, explainButton, listenParts as walkParts, walkthroughOf } from '/walkthrough.js';
 
 const DOCS = [
   ['diagrams', 'Diagrams'],
+  ['intent', 'Intent'],
+  ['spec', 'Spec'],
+  ['plan', 'Plan'],
   ['design', 'Design'],
   ['flow', 'Flow'],
   ['analysis', 'Analysis'],
@@ -27,14 +30,23 @@ const pref = {
   },
 };
 
-export function initSide({ api, esc, toast, $, agents, codeUi, docHtml, renderDiagrams, mainKind, setMain, refit }) {
+export function initSide({ api, esc, toast, $, agents, codeUi, docHtml, renderDiagrams, listenHtml, mainKind, setMain, refit }) {
   const pane = $('#side-pane');
   const body = $('#side-body');
   const code = $('#code');
   const codeHome = $('#term-main');
   const st = { on: pref.get('on', '0') === '1', tab: pref.get('tab', 'docs'), doc: pref.get('doc', 'diagrams'), agentId: null, changes: null, sig: '', loading: false };
 
-  const docOf = (a, kind) => (kind === 'explain' ? a?.explanation : a?.docs?.[kind]);
+  // Intent, spec and plan are files the daemon reads on request; the rest live on the agent.
+  const FILES = new Set(['intent', 'spec', 'plan']);
+  const files = new Map(); // "<agent>:<kind>" -> { markdown, at }
+  const docOf = (a, kind) => (FILES.has(kind) ? files.get(`${a?.id}:${kind}`) : kind === 'explain' ? a?.explanation : a?.docs?.[kind]);
+  async function loadFile(kind) {
+    const id = st.agentId;
+    const r = await api('GET', `/agents/${id}/specs/${kind}`).catch(() => null);
+    files.set(`${id}:${kind}`, { markdown: r?.markdown ?? null, at: r?.updatedAt ?? null, loaded: true });
+    if (st.agentId === id && st.doc === kind) renderDocs(true);
+  }
 
   function show() {
     const on = st.on && Boolean(st.agentId);
@@ -56,22 +68,37 @@ export function initSide({ api, esc, toast, $, agents, codeUi, docHtml, renderDi
   // ------------------------------------------------------------ Docs
   function renderDocs(force) {
     const a = agents.get(st.agentId);
-    const d = docOf(a, st.doc);
+    let d = docOf(a, st.doc);
+    // A file that changed on disk (or was never read): read it, then draw.
+    if (FILES.has(st.doc) && (!d || (d.at ?? null) !== (a?.specDocs?.[st.doc] ?? null))) {
+      if (!d?.loading) {
+        files.set(`${st.agentId}:${st.doc}`, { ...d, loading: true });
+        loadFile(st.doc);
+      }
+      d = d?.loaded ? d : null;
+      if (!d) {
+        body.innerHTML = '<p class="hint side-pad">Loading…</p>';
+        return;
+      }
+    }
     const sig = `docs|${st.agentId}|${st.doc}|${d?.at}|${d?.pending}|${d?.error}`;
     if (!force && sig === st.sig) return;
     st.sig = sig;
     const label = DOCS.find(([k]) => k === st.doc)?.[1] ?? st.doc;
     const picker = `<select data-side-doc>${DOCS.map(([k, l]) => `<option value="${k}" ${k === st.doc ? 'selected' : ''}>${l}${docOf(a, k)?.markdown ? ' ✓' : ''}</option>`).join('')}</select>`;
     const stale = d?.markdown && a?.brief?.updatedAt && d.briefUpdatedAt !== a.brief.updatedAt;
-    const action = d?.pending
+    const action = FILES.has(st.doc)
+      ? ''
+      : d?.pending
       ? `<span class="hint">Writing…</span>`
       : `<button type="button" class="small ${d?.markdown ? 'ghost' : 'primary'}" data-side-write>${d?.markdown ? 'Again' : st.doc === 'diagrams' ? 'Draw' : 'Write'}</button>`;
     let content;
     if (d?.pending && !d?.markdown) content = `<p class="hint">Writing the ${esc(label.toLowerCase())} from the agent's work so far…</p>`;
     else if (d?.error && !d?.markdown) content = `<p class="error">Couldn't write it: ${esc(d.error)}</p>`;
     else if (d?.markdown) content = `<div class="md ${st.doc === 'diagrams' ? 'diagrams-view' : ''}">${docHtml(d.markdown)}</div>`;
-    else content = `<p class="hint">No ${esc(label.toLowerCase())} for this agent yet.</p>`;
-    body.innerHTML = `<div class="side-tools">${picker}<span class="spacer"></span>${stale ? '<span class="hint">brief changed since</span>' : ''}${action}</div><div class="side-scroll">${content}</div>`;
+    else content = `<p class="hint">No ${esc(label.toLowerCase())} for this agent yet.${FILES.has(st.doc) && st.doc !== 'intent' ? ' The agent writes it as it works.' : ''}</p>`;
+    const listen = d?.markdown && st.doc !== 'diagrams' ? listenHtml(`doc:${st.agentId}:${st.doc}`, { title: 'Read it aloud' }) : '';
+    body.innerHTML = `<div class="side-tools">${picker}<span class="spacer"></span>${stale ? '<span class="hint">brief changed since</span>' : ''}${listen}${action}</div><div class="side-scroll">${content}</div>`;
     renderDiagrams(body);
   }
 
@@ -107,7 +134,7 @@ export function initSide({ api, esc, toast, $, agents, codeUi, docHtml, renderDi
     const sig = `changes|${st.agentId}|${a?.docs?.walkthrough?.at}|${w.pending}|${w.error}|${st.changes.diffHash}`;
     if (!force && sig === st.sig) return;
     st.sig = sig;
-    const tools = `<div class="side-tools">${explainButton(w, 'data-side-explain')}<span class="spacer"></span><button type="button" class="small ghost" data-side-reload title="Load the changes again">⟳</button></div>`;
+    const tools = `<div class="side-tools">${explainButton(w, 'data-side-explain')}${w.doc ? listenHtml(`sidewalk:${st.agentId}`, { title: 'Hear the changes one by one' }) : ''}<span class="spacer"></span><button type="button" class="small ghost" data-side-reload title="Load the changes again">⟳</button></div>`;
     let content;
     if (st.changes.error) content = `<p class="error">${esc(st.changes.error)}</p>`;
     else if (!st.changes.files.length) content = '<p class="hint">No changes yet.</p>';
@@ -115,7 +142,7 @@ export function initSide({ api, esc, toast, $, agents, codeUi, docHtml, renderDi
     else {
       const list = w.doc.data.changes;
       content = `<p class="hint">${esc(w.doc.data.summary)}${w.stale ? ' <b>The changes moved since this was written.</b>' : ''}</p>${list
-        .map((c, i) => `<section class="sd-step"><div class="sd-file"><code>${esc(c.file)}</code></div>${cardHtml(c, i, list.length, esc)}${hunkHtml(c.file, c.head)}</section>`)
+        .map((c, i) => `<section class="sd-step" id="sd-step-${i}"><div class="sd-file"><code>${esc(c.file)}</code></div>${cardHtml(c, i, list.length, esc)}${hunkHtml(c.file, c.head)}</section>`)
         .join('')}`;
     }
     body.innerHTML = `${tools}<div class="side-scroll">${content}</div>`;
@@ -182,6 +209,17 @@ export function initSide({ api, esc, toast, $, agents, codeUi, docHtml, renderDi
       }
     },
     showing: (tab) => st.on && Boolean(st.agentId) && st.tab === tab,
+    /** What Listen reads in Changes: each change, scrolled to and marked as it is read. */
+    listenParts() {
+      const w = walkthroughOf(agents.get(st.agentId), st.changes?.diffHash);
+      if (!w.doc) return [];
+      return walkParts(w.doc.data, (i) => () => {
+        body.querySelectorAll('.sd-step.current').forEach((el) => el.classList.remove('current'));
+        const el = body.querySelector(`#sd-step-${i}`);
+        el?.classList.add('current');
+        el?.scrollIntoView({ block: 'start', behavior: 'smooth' });
+      });
+    },
     agentChanged(a) {
       if (!st.on || a.id !== st.agentId) return;
       if (st.tab === 'docs') renderDocs(false);

package/public/speak.js

@@ -0,0 +1,171 @@
+// Listening instead of reading: Explain, the documents and the change walkthrough read aloud with
+// the browser's own speech (nothing leaves the device; it works on phones). Text goes in short
+// pieces, since some browsers stop a long utterance partway. One thing plays at a time.
+
+const RATES = [0.85, 1, 1.25, 1.5, 1.75];
+const RATE_KEY = 'agentmgr.speechRate';
+
+export const canSpeak = () => typeof window !== 'undefined' && 'speechSynthesis' in window && 'SpeechSynthesisUtterance' in window;
+
+/** Markdown as something to say: no code, diagrams, links' addresses or markup. */
+export function speakable(markdown) {
+  return String(markdown ?? '')
+    .replace(/```[\s\S]*?```/g, ' ')
+    .replace(/`([^`]+)`/g, '$1')
+    .replace(/!\[[^\]]*\]\([^)]*\)/g, ' ')
+    .replace(/\[([^\]]+)\]\([^)]*\)/g, '$1')
+    .replace(/https?:\/\/\S+/g, 'a link')
+    .replace(/^#{1,6}\s+(.*)$/gm, '$1.')
+    .replace(/^\s*[-*+]\s+/gm, '')
+    .replace(/^\s*\d+\.\s+/gm, '')
+    .replace(/[*_~>|]/g, '')
+    .replace(/\.\.+/g, '.')
+    .replace(/[ \t]+/g, ' ')
+    .trim();
+}
+
+/** Text in pieces of a few sentences (under ~220 characters), on paragraph and sentence breaks. */
+export function pieces(text, max = 220) {
+  const out = [];
+  for (const para of String(text).split(/\n\s*\n|\n/)) {
+    const sentences = para.match(/[^.!?]+[.!?]*\s*/g) ?? [];
+    let cur = '';
+    for (const s of sentences) {
+      if ((cur + s).length > max && cur) {
+        out.push(cur.trim());
+        cur = '';
+      }
+      cur += s;
+    }
+    if (cur.trim()) out.push(cur.trim());
+  }
+  return out.filter((p) => /\w/.test(p));
+}
+
+let session = null; // { id, parts: [{ text, onStart }], i, paused, onEnd, onState }
+
+function rate() {
+  try {
+    const r = Number(localStorage.getItem(RATE_KEY));
+    return RATES.includes(r) ? r : 1;
+  } catch {
+    return 1;
+  }
+}
+
+function playNext() {
+  const s = session;
+  if (!s) return;
+  if (s.i >= s.parts.length) return stop(true);
+  const part = s.parts[s.i];
+  const u = new SpeechSynthesisUtterance(part.text);
+  u.rate = rate();
+  u.onstart = () => part.onStart?.();
+  u.onend = () => {
+    if (session !== s || s.paused) return;
+    s.i++;
+    playNext();
+  };
+  u.onerror = (e) => {
+    if (session !== s || e.error === 'interrupted' || e.error === 'canceled') return;
+    stop(false);
+  };
+  speechSynthesis.speak(u);
+}
+
+/**
+ * Play `parts` (strings, or { text, onStart } to follow along, e.g. highlight a change) under `id`.
+ * `onState(state)` hears 'playing' | 'paused' | 'stopped'.
+ */
+export function play(id, parts, { onState, onEnd } = {}) {
+  stop(false);
+  if (!canSpeak()) return false;
+  const list = parts.flatMap((p) => {
+    const text = typeof p === 'string' ? p : p.text;
+    const chunks = pieces(text);
+    return chunks.map((c, k) => ({ text: c, onStart: k === 0 && typeof p !== 'string' ? p.onStart : null }));
+  });
+  if (!list.length) return false;
+  session = { id, parts: list, i: 0, paused: false, onState, onEnd };
+  onState?.('playing');
+  notify();
+  playNext();
+  return true;
+}
+
+export function pause() {
+  if (!session || session.paused) return;
+  session.paused = true;
+  // Cancel rather than speechSynthesis.pause(): pausing is unreliable on Chrome and iOS. Resume
+  // restarts the piece that was playing.
+  speechSynthesis.cancel();
+  session.onState?.('paused');
+  notify();
+}
+
+export function resume() {
+  if (!session?.paused) return;
+  session.paused = false;
+  session.onState?.('playing');
+  notify();
+  playNext();
+}
+
+export function stop(finished = false) {
+  const s = session;
+  session = null;
+  if (canSpeak()) speechSynthesis.cancel();
+  if (s) {
+    s.onState?.('stopped');
+    if (finished) s.onEnd?.();
+    notify();
+  }
+}
+
+/** What is playing: { id, paused } or null. */
+export const now = () => (session ? { id: session.id, paused: session.paused } : null);
+
+export function cycleRate() {
+  const next = RATES[(RATES.indexOf(rate()) + 1) % RATES.length];
+  try {
+    localStorage.setItem(RATE_KEY, String(next));
+  } catch {}
+  notify();
+  return next;
+}
+export const rateLabel = () => `${rate()}×`;
+
+// Buttons anywhere on the page redraw themselves from this.
+const listeners = new Set();
+export const onChange = (fn) => listeners.add(fn);
+const notify = () => listeners.forEach((fn) => fn(now()));
+
+/**
+ * A Listen control for `id`: 🔊 Listen, or ⏸ / ▶ with ■ and the speed while that id plays.
+ * Clicks are handled by `bindListen`; `data-say` names what to read.
+ */
+export function listenHtml(id, { title = 'Read it aloud' } = {}) {
+  if (!canSpeak()) return '';
+  const cur = now();
+  if (cur?.id !== id) return `<span class="say" data-say="${id}"><button type="button" class="small ghost" data-say-act="play" title="${title}">🔊 Listen</button></span>`;
+  return `<span class="say on" data-say="${id}"><button type="button" class="small" data-say-act="${cur.paused ? 'resume' : 'pause'}" title="${cur.paused ? 'Resume' : 'Pause'}">${cur.paused ? '▶' : '⏸'}</button><button type="button" class="small ghost" data-say-act="stop" title="Stop">■</button><button type="button" class="small ghost" data-say-act="rate" title="Speed">${rateLabel()}</button></span>`;
+}
+
+/** Handle Listen controls: `start(id)` begins playing that id (it knows what to read). */
+export function bindListen(start) {
+  document.addEventListener('click', (e) => {
+    const b = e.target.closest('[data-say-act]');
+    if (!b) return;
+    const id = b.closest('[data-say]').dataset.say;
+    const act = b.dataset.sayAct;
+    if (act === 'play') start(id);
+    else if (act === 'pause') pause();
+    else if (act === 'resume') resume();
+    else if (act === 'stop') stop(false);
+    else if (act === 'rate') cycleRate();
+  });
+  // Keep every visible control in step with what is playing.
+  onChange(() => {
+    for (const el of document.querySelectorAll('[data-say]')) el.outerHTML = listenHtml(el.dataset.say);
+  });
+}

package/public/style.css

@@ -15,8 +15,9 @@
   --mono: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
   color-scheme: light;
 }
+/* Dark: the system's setting unless the page is set to Light, or always when set to Dark (☰ menu). */
 @media (prefers-color-scheme: dark) {
-  :root {
+  :root:not([data-theme="light"]) {
     --bg: #0d0f14;
     --panel: #151821;
     --panel-2: #1c202b;
@@ -31,6 +32,20 @@
     color-scheme: dark;
   }
 }
+:root[data-theme="dark"] {
+  --bg: #0d0f14;
+  --panel: #151821;
+  --panel-2: #1c202b;
+  --border: #2a2f3c;
+  --text: #e5e8ef;
+  --muted: #8b93a7;
+  --accent: #6d8bff;
+  --accent-text: #0d0f14;
+  --green: #3ecf8e;
+  --yellow: #e6b450;
+  --red: #ff6b6b;
+  color-scheme: dark;
+}
 
 * { box-sizing: border-box; }
 [hidden] { display: none !important; }
@@ -873,3 +888,21 @@ form.dropping { outline: 2px dashed var(--accent, #6b8cff); outline-offset: 4px;
 .sd-add { background: rgba(46, 160, 67, .15); }
 .sd-del { background: rgba(248, 81, 73, .15); }
 #term-split-btn.on { background: #262c38; }
+
+/* Theme switch in the menu: Auto / Light / Dark. */
+.menu-theme { display: flex; align-items: center; gap: 6px; padding: 6px 12px; }
+.menu-theme .seg { display: inline-flex; border: 1px solid var(--border); border-radius: 6px; overflow: hidden; margin-left: auto; }
+.menu-theme .seg button { border: 0; border-radius: 0; padding: 3px 9px; font-size: 12px; background: transparent; }
+.menu-theme .seg button.on { background: var(--accent); color: var(--accent-text); }
+
+/* Diagram export buttons: on each drawn diagram, shown on hover (always on touch screens). */
+.diagram { position: relative; }
+.dg-tools { position: absolute; top: 6px; right: 6px; display: flex; gap: 4px; opacity: 0; transition: opacity .15s; z-index: 1; }
+.diagram:hover .dg-tools, .diagram:focus-within .dg-tools { opacity: 1; }
+@media (hover: none) { .dg-tools { opacity: 1; position: static; justify-content: flex-end; margin-bottom: 4px; } }
+.dg-tools button { background: var(--panel); }
+/* Listen controls. */
+.say { display: inline-flex; gap: 4px; align-items: center; vertical-align: middle; }
+.say.on button:first-child { min-width: 30px; }
+.explain-foot { display: flex; align-items: center; gap: 8px; flex-wrap: wrap; }
+.sd-step.current { box-shadow: 0 0 0 2px var(--accent, #6b8cff); }

package/public/update.js

@@ -1,9 +1,9 @@
 // Updating from the app: a button in the top bar when a newer release is out, and "Update and
 // restart" in About. The daemon installs it (git checkout of the release tag, or npm install -g)
-// and restarts onto it; this page then waits for it to come back and reloads.
+// and restarts onto it; this page then waits for it to come back and reloads. It works the same
+// from a phone over remote access: the install runs on the computer.
 
 export function initUpdate({ api, esc, toast, $ }) {
-  const remote = () => document.body.classList.contains('remote');
   let state = null;
 
   function show(s) {
@@ -20,7 +20,6 @@ export function initUpdate({ api, esc, toast, $ }) {
   }
 
   async function load() {
-    if (remote()) return;
     try {
       show(await api('GET', '/update'));
     } catch {
@@ -62,9 +61,8 @@ export function initUpdate({ api, esc, toast, $ }) {
     }
   }
 
-  /** "Check for updates" in About: the daemon's check where it can update itself. */
+  /** "Check for updates" in About: the daemon's check, and whether it can update itself. */
   async function check() {
-    if (remote()) return null;
     const s = await api('POST', '/update/check');
     show(s);
     if (!s.newer) return `You have the newest release (${esc(s.current)}).`;

package/public/walkthrough.js

@@ -34,3 +34,19 @@ export function explainButton(w, attrs = 'data-wt-explain') {
   return `<button type="button" class="small ${w.doc && !w.stale ? 'ghost' : 'primary'}" ${attrs} ${w.pending ? 'disabled' : ''}
     title="Explain each change one by one: what, why, the risk and what to check, in the order to read them (a separate one-off call; the agent isn't interrupted)">${label}</button>`;
 }
+
+/** What Listen reads for a walkthrough: the summary, then each change; `follow(i)` runs as change i starts. */
+export function listenParts(data, follow = () => null) {
+  const n = data.changes.length;
+  return [
+    data.summary ? `${data.summary} ${n} change${n === 1 ? '' : 's'} to go through.` : `${n} changes to go through.`,
+    ...data.changes.map((c, i) => ({
+      i,
+      text: c.unexplained ? `Change ${i + 1} of ${n}, in ${spokenFile(c.file)}, has no explanation.` : `Change ${i + 1} of ${n}: ${c.title}. In ${spokenFile(c.file)}. ${c.what} ${c.why && c.why !== 'Not stated' ? `Why: ${c.why}` : ''} Risk: ${c.risk}. ${c.check ? `Check: ${c.check}` : ''}`,
+      onStart: follow(i),
+    })),
+  ];
+}
+
+/** "src/server/auth.js" read as "auth.js". */
+const spokenFile = (f) => String(f).split('/').pop();

package/src/brief.js

@@ -654,3 +654,82 @@ export function loadPlanFile(agentId, prev) {
   if (prev && prev.mtimeMs === st.mtimeMs) return null;
   return { markdown: fs.readFileSync(planPath(agentId), 'utf8').slice(0, 200_000), mtimeMs: st.mtimeMs, updatedAt: st.mtime.toISOString() };
 }
+
+// ------------------------------------------------------------------ intent, spec and plan
+
+// Three files per agent, next to the brief, for reviewers (people, other agents, AI review):
+//   INTENT.md - what was asked, written by AI Agent Manager when the agent is created
+//   SPEC.md   - what done means (requirements, acceptance criteria), written by the agent first
+//   PLAN.md   - how it gets there, step by step, kept by the agent (the plan review uses it too)
+// Push & open PR puts them in the pull request's description.
+export const INTENT_FILE = 'INTENT.md';
+export const SPEC_FILE = 'SPEC.md';
+export const intentPath = (agentId) => path.join(briefDir(agentId), INTENT_FILE);
+export const specPath = (agentId) => path.join(briefDir(agentId), SPEC_FILE);
+export const SPEC_DOCS = { intent: intentPath, spec: specPath, plan: planPath };
+
+/** INTENT.md: the request as given, and where it came from. */
+export function intentMarkdown(agent) {
+  const by = agent.startedBy ? 'the assistant' : agent.trigger ? (agent.trigger.source === 'github' ? 'a labeled GitHub issue' : 'a webhook') : agent.playbook ? `the playbook ${agent.playbook.name}` : agent.team ? `team ${agent.team.id} (${agent.team.role})` : agent.raceId ? `race ${agent.raceId}` : 'you';
+  const out = [`# Intent: ${agent.name}`, ''];
+  if (agent.synopsis?.text) out.push(`**${agent.synopsis.source === 'jira' ? `${agent.synopsis.key}: ` : ''}${agent.synopsis.text}**`, '');
+  out.push('## Request', '', agent.intent || '(none)', '');
+  const ctx = [
+    `- Started by: ${by}${agent.trigger?.url ? ` (${agent.trigger.url})` : ''}`,
+    agent.repo || agent.requestedDir ? `- Where: ${agent.repo || agent.requestedDir}${agent.base ? ` (from ${agent.base})` : ''}` : null,
+    agent.engine ? `- Engine: ${agent.engine}${agent.model ? ` (${agent.model})` : ''}` : null,
+    `- Created: ${agent.createdAt}`,
+  ].filter(Boolean);
+  out.push('## Context', '', ...ctx, '');
+  return out.join('\n');
+}
+
+/** The agent's instructions for SPEC.md and PLAN.md (the plan only when the plan review isn't on). */
+export const specPrompt = (specFile, planFile, { withPlan = true } = {}) =>
+  `Before you change any code, write a short spec of the task to ${specFile} (Markdown), so reviewers (people and other agents) ` +
+  'can check the work against it:\n# Spec: <short name>\n## Requirements\nWhat must be true when it is done, as a list.\n' +
+  '## Acceptance criteria\nHow each requirement is checked: a command, a test or an observable behavior.\n## Out of scope\n## Open questions\n' +
+  (withPlan
+    ? `Then write your plan to ${planFile}: "# Plan: <short name>", then "## Steps" as a task list ("- [ ]" to do, "- [x]" done), ` +
+      'small enough to check, and "## Files to change". Keep both current: tick steps as you finish them, and update the spec ' +
+      'if the requirements change (say why). Do not stop to wait for approval; carry on with the work. '
+    : 'Keep it current if the requirements change (say why). ') +
+  'Both files are outside the repository: never copy them into the repo or commit them.';
+
+/** One of the three (intent, spec, plan): its Markdown and when it changed, or null. */
+export function readSpecDoc(agentId, name) {
+  const file = SPEC_DOCS[name]?.(agentId);
+  if (!file) return null;
+  try {
+    const st = fs.statSync(file);
+    return { name, path: file, markdown: fs.readFileSync(file, 'utf8').slice(0, 200_000), updatedAt: st.mtime.toISOString() };
+  } catch {
+    return null;
+  }
+}
+
+/** Which of the three exist, and when they changed (for the page's buttons). */
+export function specDocsInfo(agentId) {
+  const out = {};
+  for (const [name, fn] of Object.entries(SPEC_DOCS)) {
+    try {
+      out[name] = fs.statSync(fn(agentId)).mtime.toISOString();
+    } catch {}
+  }
+  return out;
+}
+
+/** The pull request description's sections: the intent in full, the spec and plan folded. */
+export function prSections(agentId, read = (n) => readSpecDoc(agentId, n)?.markdown) {
+  const doc = (n) => read(n)?.trim();
+  // Demote the files' own headings under the description's.
+  const demote = (md) => md.replace(/^(#{1,4}) /gm, '#$1 ').replace(/^## (Intent|Spec|Plan): .*\n+/m, '');
+  const parts = [];
+  const intent = doc('intent');
+  if (intent) parts.push('## Intent', '', demote(intent), '');
+  for (const [name, label] of [['spec', 'Spec'], ['plan', 'Plan']]) {
+    const md = doc(name);
+    if (md) parts.push(`<details><summary><b>${label}</b></summary>`, '', demote(md), '', '</details>', '');
+  }
+  return parts.length ? [...parts, '<sub>Intent, spec and plan kept by AI Agent Manager.</sub>'].join('\n') : '';
+}

package/src/jira.js

@@ -0,0 +1,100 @@
+// The summary of the Jira issue a request starts with, so an agent created from a link shows what
+// the issue is about instead of the link. Fetched from Jira Cloud's REST API in the background;
+// when it can't be fetched, the words after the link stand in for it.
+//
+// Only Atlassian Cloud sites (*.atlassian.net) and the site set here are contacted, and the email
+// and API token go only to that site: requests can come from outside (GitHub issues, the
+// assistant), and a link in one must not receive your token or reach internal addresses.
+import fs from 'node:fs';
+import path from 'node:path';
+import { paths } from './config.js';
+import { leadingJiraKey } from './tracker.js';
+
+const file = () => path.join(paths.home, 'jira.json');
+
+/** Saved settings ({ site, email, token }), with JIRA_SITE / JIRA_EMAIL / JIRA_API_TOKEN as fallbacks. */
+export function loadJira(env = process.env) {
+  let saved = {};
+  try {
+    saved = JSON.parse(fs.readFileSync(file(), 'utf8'));
+  } catch {}
+  return {
+    site: normSite(saved.site || env.JIRA_SITE || ''),
+    email: saved.email || env.JIRA_EMAIL || '',
+    token: saved.token || env.JIRA_API_TOKEN || '',
+  };
+}
+
+/** What the page shows: never the token itself. */
+export const jiraView = (j = loadJira()) => ({ site: j.site, email: j.email, hasToken: Boolean(j.token) });
+
+/** Save settings; an empty token keeps the saved one unless `clearToken`. */
+export function saveJira({ site, email, token, clearToken = false } = {}) {
+  const cur = (() => {
+    try {
+      return JSON.parse(fs.readFileSync(file(), 'utf8'));
+    } catch {
+      return {};
+    }
+  })();
+  const next = {
+    site: site === undefined ? cur.site ?? '' : normSite(site),
+    email: email === undefined ? cur.email ?? '' : String(email).trim(),
+    token: clearToken ? '' : token ? String(token).trim() : cur.token ?? '',
+  };
+  if (next.site && !/^https:\/\/[\w.-]+$/.test(next.site)) throw Object.assign(new Error('The Jira site is an https address, like https://yourcompany.atlassian.net'), { status: 400 });
+  fs.mkdirSync(paths.home, { recursive: true });
+  fs.writeFileSync(file(), JSON.stringify(next, null, 2) + '\n', { mode: 0o600 });
+  return jiraView(loadJira());
+}
+
+function normSite(s) {
+  const v = String(s ?? '').trim().replace(/\/+$/, '');
+  if (!v) return '';
+  return /^https?:\/\//.test(v) ? v : `https://${v}`;
+}
+
+/** The issue a request starts with: { key, site } from its leading link, or null. */
+export function leadingIssue(text) {
+  const key = leadingJiraKey(text);
+  if (!key) return null;
+  const url = String(text).trimStart().match(/^<?(https?:\/\/\S+)/)[1];
+  try {
+    return { key, site: new URL(url).origin };
+  } catch {
+    return null;
+  }
+}
+
+/** The person's own words after the leading link ("…/browse/ABC-1 fix the timeout" → "fix the timeout"). */
+export function wordsAfterLink(text) {
+  const rest = String(text ?? '').trimStart().replace(/^<?https?:\/\/\S+>?/, '').trim();
+  return rest.replace(/^[-:–—,\s]+/, '').split('\n')[0].trim().slice(0, 200) || null;
+}
+
+/**
+ * The issue's summary, or null when it can't be had (not a site we contact, no access, offline).
+ * `fetchImpl` and `allow` are for tests.
+ */
+export async function issueSummary({ key, site }, { jira = loadJira(), fetchImpl = fetch, timeoutMs = 6000, allow = null } = {}) {
+  const host = (() => {
+    try {
+      return new URL(site).host;
+    } catch {
+      return '';
+    }
+  })();
+  const configured = jira.site && new URL(jira.site).host === host;
+  const allowed = configured || /\.atlassian\.net$/.test(host) || allow?.(site);
+  if (!allowed) return null;
+  const headers = { accept: 'application/json' };
+  if (configured && jira.email && jira.token) headers.authorization = `Basic ${Buffer.from(`${jira.email}:${jira.token}`).toString('base64')}`;
+  try {
+    const res = await fetchImpl(`${site}/rest/api/3/issue/${encodeURIComponent(key)}?fields=summary`, { headers, redirect: 'error', signal: AbortSignal.timeout(timeoutMs) });
+    if (!res.ok) return null;
+    const summary = (await res.json())?.fields?.summary;
+    return typeof summary === 'string' && summary.trim() ? summary.trim().slice(0, 300) : null;
+  } catch {
+    return null;
+  }
+}