ai-agentmanager 1.2.1 → 1.3.0

package/src/manager.js

@@ -47,10 +47,12 @@ import { findLocalUrls, findSignInLinks, parseCallback, parseUrl } from './previ
 import { Plugins } from './plugins.js';
 import { leadPrompt, subagents, teamDir, teamPrompt } from './teams.js';
 import { assistantDir, assistantPrompt, assistantSettings } from './assistant.js';
+import { learnCommand, memoryKey, memoryPrompt, memoryText } from './memory.js';
 import { runningClaude, scanClaudeSessions } from './sessions.js';
 import {
   bugFromRef,
   extractRefs,
+  landState,
   leadingJiraKey,
   prDetails,
   prFromUrl,
@@ -204,7 +206,7 @@ export class AgentManager extends EventEmitter {
     this.shells = new Map(); // agent id -> ancillary shell runtime in the agent's folder
     this.cursors = new Map(); // session id -> transcript scan cursor
     this.locks = new Map();
-    this.refreshing = new Set();
+    this.refreshing = new Map(); // agent id -> the refresh in progress
     this.lastPrCheck = new Map();
     this.changeSets = new Map(); // agent id -> { files, baseSha, at }: what its branch changed (conflict radar)
     this.conflicts = new Map(); // agent id -> [conflict]
@@ -283,7 +285,7 @@ export class AgentManager extends EventEmitter {
       usage,
       // Claude Code's own cost figure from the transcripts (absent until it records one).
       costUsd: costs.length ? costs.reduce((a, b) => a + b, 0) : null,
-      prs: Object.values(agent.prs ?? {}),
+      prs: Object.values(agent.prs ?? {}).map((p) => ({ ...p, land: landState(p) })),
       bugs: Object.values(agent.bugs ?? {}),
       conflicts: this.conflictGroups(agent),
       stuck: this.activeStuck(agent),
@@ -522,6 +524,7 @@ export class AgentManager extends EventEmitter {
     sessionId: adopt,
     imported,
     startedBy,
+    trigger,
   }) {
     intent = (intent ?? '').trim();
     const engineDef = engineOf(engine || this.config.engine || DEFAULT_ENGINE);
@@ -563,6 +566,7 @@ export class AgentManager extends EventEmitter {
       project: project?.trim() || null,
       priority: parsePriority(priority),
       ...(startedBy ? { startedBy } : {}),
+      ...(trigger ? { trigger } : {}),
       name: name?.trim() || jiraKey || slug,
       slug,
       intent,
@@ -891,6 +895,12 @@ export class AgentManager extends EventEmitter {
       prompts.push(agent.planReview.status === 'approved' ? planApprovedPrompt(file) : planReviewPrompt(file));
     }
     if (planning) prompts.push(planningPrompt(agent));
+    // What earlier agents learned in this repo, and the one command to add to it.
+    let allowedTools = null;
+    if (task && this.config.memory !== false) {
+      prompts.push(memoryPrompt(memoryText(memoryKey(agent))));
+      allowedTools = [`Bash(${learnCommand()}:*)`];
+    }
     if (agent.kind === 'assistant') {
       fs.mkdirSync(assistantDir(), { recursive: true });
       const dir = fs.realpathSync(assistantDir());
@@ -911,7 +921,7 @@ export class AgentManager extends EventEmitter {
       }
     }
     // Appended system prompts last only for the process they're passed to, so they go on every launch.
-    return { extra: engine.extraArgs(this.config), permissionMode: agent.permissionMode, model: agent.model, writableDir, instructions: prompts.join('\n\n') || null, agents };
+    return { extra: engine.extraArgs(this.config), permissionMode: agent.permissionMode, model: agent.model, writableDir, instructions: prompts.join('\n\n') || null, agents, allowedTools };
   }
 
   /** Spawn the agent's engine in a PTY, reusing its terminal clients and scrollback. */
@@ -1235,6 +1245,14 @@ export class AgentManager extends EventEmitter {
     if ('model' in fields) allowed.model = String(fields.model ?? '').trim() || null;
     // Keep: clean up never closes or deletes it.
     if ('keep' in fields) allowed.keep = Boolean(fields.keep);
+    if ('budgetUsd' in fields) {
+      // Its own spending limit in US dollars; empty for the default (budgets.perAgentUsd).
+      const raw = fields.budgetUsd;
+      const b = raw === null || raw === '' ? null : Number(raw);
+      if (b !== null && !(Number.isFinite(b) && b > 0)) throw Object.assign(new Error('budgetUsd must be a positive number of dollars, or empty'), { status: 400 });
+      allowed.budgetUsd = b === null ? null : Math.round(b * 100) / 100;
+      allowed.budgetHit = null;
+    }
     if ('priority' in fields) {
       const p = parsePriority(fields.priority, null);
       if (p === null) throw Object.assign(new Error('priority must be P0, P1, P2 or P3'), { status: 400 });
@@ -1971,80 +1989,93 @@ export class AgentManager extends EventEmitter {
 
   async refresh(ref, { withPrs = false } = {}) {
     const id = this.mustGet(ref).id;
-    if (this.refreshing.has(id)) return this.view(this.store.get(id));
-    this.refreshing.add(id);
+    const running = this.refreshing.get(id);
+    if (running) {
+      // A pull request check asked for during a plain refresh runs right after it.
+      if (!withPrs || running.withPrs) return running.promise.then(() => this.store.get(id) && this.view(this.store.get(id)));
+      await running.promise.catch(() => {});
+      return this.refresh(id, { withPrs });
+    }
+    const promise = this.doRefresh(id, { withPrs });
+    this.refreshing.set(id, { promise, withPrs });
     try {
-      this.reloadBrief(id);
-      const agent = this.store.get(id);
-      // Before handoff, a planning session's transcript lives in the planning folder.
-      const planningOnly = agent?.planning && !agent.planning.handedOffAt && !agent.workdir;
-      const sessionDir = planningOnly ? agent.planning.dir : agent?.workdir;
-      if (!sessionDir) return agent && this.view(agent);
-      let changed = agent.workdir ? this.adoptSessions(agent) : false;
-
-      const info = agent.workdir ? await git.gitInfo(agent.workdir) : agent.git;
-      if (!this.store.get(id)) return null;
-      if (info !== undefined && JSON.stringify({ ...info, updatedAt: 0 }) !== JSON.stringify({ ...agent.git, updatedAt: 0 })) {
-        agent.git = info;
+      return await promise;
+    } finally {
+      this.refreshing.delete(id);
+    }
+  }
+
+  async doRefresh(id, { withPrs }) {
+    this.reloadBrief(id);
+    const agent = this.store.get(id);
+    // Before handoff, a planning session's transcript lives in the planning folder.
+    const planningOnly = agent?.planning && !agent.planning.handedOffAt && !agent.workdir;
+    const sessionDir = planningOnly ? agent.planning.dir : agent?.workdir;
+    if (!sessionDir) return agent && this.view(agent);
+    let changed = agent.workdir ? this.adoptSessions(agent) : false;
+
+    const info = agent.workdir ? await git.gitInfo(agent.workdir) : agent.git;
+    if (!this.store.get(id)) return null;
+    if (info !== undefined && JSON.stringify({ ...info, updatedAt: 0 }) !== JSON.stringify({ ...agent.git, updatedAt: 0 })) {
+      agent.git = info;
+      changed = true;
+    }
+
+    const engine = engineOf(agent);
+    for (const session of agent.sessions) {
+      const file = engine.sessionFile(sessionDir, session.id);
+      const key = `${session.id}:${file}`; // the transcript moves at handoff; rescan the new copy
+      const cursor = this.cursors.get(key) ?? { offset: 0 };
+      this.cursors.set(key, cursor);
+      const res = engine.scan(file, cursor, this.config.bugPatterns);
+      const subMaps = engine.subagentFiles(sessionDir, session.id).map((sub) => {
+        const c = this.cursors.get(sub) ?? { offset: 0 };
+        this.cursors.set(sub, c);
+        engine.scan(sub, c);
+        return c.usage;
+      });
+      const usage = sumUsage(cursor.usage, ...subMaps);
+      if (usage.requests && JSON.stringify(session.usage) !== JSON.stringify(usage)) {
+        session.usage = usage;
         changed = true;
       }
-
-      const engine = engineOf(agent);
-      for (const session of agent.sessions) {
-        const file = engine.sessionFile(sessionDir, session.id);
-        const key = `${session.id}:${file}`; // the transcript moves at handoff; rescan the new copy
-        const cursor = this.cursors.get(key) ?? { offset: 0 };
-        this.cursors.set(key, cursor);
-        const res = engine.scan(file, cursor, this.config.bugPatterns);
-        const subMaps = engine.subagentFiles(sessionDir, session.id).map((sub) => {
-          const c = this.cursors.get(sub) ?? { offset: 0 };
-          this.cursors.set(sub, c);
-          engine.scan(sub, c);
-          return c.usage;
-        });
-        const usage = sumUsage(cursor.usage, ...subMaps);
-        if (usage.requests && JSON.stringify(session.usage) !== JSON.stringify(usage)) {
-          session.usage = usage;
+      for (const key of ['title', 'lastPrompt', 'cost', 'lastActivity', 'lastMessageAt']) {
+        if (res[key] != null && JSON.stringify(session[key]) !== JSON.stringify(res[key])) {
+          session[key] = res[key];
           changed = true;
         }
-        for (const key of ['title', 'lastPrompt', 'cost', 'lastActivity', 'lastMessageAt']) {
-          if (res[key] != null && JSON.stringify(session[key]) !== JSON.stringify(res[key])) {
-            session[key] = res[key];
-            changed = true;
-          }
-        }
-        const prs = res.prs.map((p) => ({ ...p, sessionId: session.id }));
-        changed = this.mergeLinks(agent, agent.prs, prs, (p) => p.url) || changed;
-        changed = this.mergeLinks(agent, agent.bugs, res.bugs, (b) => b.key) || changed;
       }
-
-      if (withPrs) {
-        this.lastPrCheck.set(id, Date.now());
-        // A shared worktree's pull requests belong to the agent that owns it.
-        const branchPrs = agent.sharedWith ? [] : await prsForBranch(agent.workdir, info?.branch);
-        changed = this.mergeLinks(agent, agent.prs, branchPrs, (p) => p.url) || changed;
-        // Fill in title/state for PRs we only know by URL, and keep open ones current.
-        const stale = Object.values(agent.prs).filter(
-          (p) => p.source !== 'branch' && (!p.state || p.state === 'OPEN'),
-        );
-        for (const pr of stale.slice(0, 10)) {
-          const d = await prDetails(pr.url);
-          if (d) changed = this.mergeLinks(agent, agent.prs, [{ ...d, source: pr.source }], (p) => p.url) || changed;
-        }
+      const prs = res.prs.map((p) => ({ ...p, sessionId: session.id }));
+      changed = this.mergeLinks(agent, agent.prs, prs, (p) => p.url) || changed;
+      changed = this.mergeLinks(agent, agent.bugs, res.bugs, (b) => b.key) || changed;
+    }
+
+    if (withPrs) {
+      this.lastPrCheck.set(id, Date.now());
+      // A shared worktree's pull requests belong to the agent that owns it.
+      const branchPrs = agent.sharedWith ? [] : await prsForBranch(agent.workdir, info?.branch);
+      changed = this.mergeLinks(agent, agent.prs, branchPrs, (p) => p.url) || changed;
+      // Fill in title/state for PRs we only know by URL, and keep open ones current.
+      const stale = Object.values(agent.prs).filter(
+        (p) => p.source !== 'branch' && (!p.state || p.state === 'OPEN'),
+      );
+      for (const pr of stale.slice(0, 10)) {
+        const d = await prDetails(pr.url);
+        if (d) changed = this.mergeLinks(agent, agent.prs, [{ ...d, source: pr.source }], (p) => p.url) || changed;
       }
+      // Landing reacts to failing checks and requested changes.
+      this.emit('prs', agent);
+    }
 
-      await this.updateChanges(agent);
-      this.updateStuck(agent, sessionDir);
+    await this.updateChanges(agent);
+    this.updateStuck(agent, sessionDir);
 
-      if (changed && this.store.get(id)) {
-        agent.updatedAt = now();
-        this.store.save();
-        this.changed(agent);
-      }
-      return this.view(agent);
-    } finally {
-      this.refreshing.delete(id);
+    if (changed && this.store.get(id)) {
+      agent.updatedAt = now();
+      this.store.save();
+      this.changed(agent);
     }
+    return this.view(agent);
   }
 
   // ------------------------------------------------------ telling an agent

package/src/memory.js

@@ -0,0 +1,106 @@
+// Shared memory per repository: what agents learned working in it (how to build and test,
+// gotchas, where things are), so the next agent there starts with it instead of finding it out
+// again. One Markdown file per repo under ~/.agentmanager/memory, read by every agent in that
+// repo, added to with `agentmgr learn "<one line>"`, and editable by people in the UI.
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { paths } from './config.js';
+import { NO_REPO, projectOf } from './manager.js';
+
+export const memoryText = (key) => {
+  try {
+    return fs.readFileSync(memoryFile(key), 'utf8');
+  } catch {
+    return '';
+  }
+};
+
+const BIN = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'bin', 'agentmgr.js');
+export const MAX_BYTES = 16_000;
+const err = (status, message) => Object.assign(new Error(message), { status });
+
+/** The repo an agent works in, ignoring where it is listed (moved or custom project). */
+export const memoryKey = (agent) => {
+  const key = projectOf({ ...agent, projectMove: null, project: null }).key;
+  if (!key.startsWith('dir:')) return key;
+  // The same folder by any path (macOS /var is /private/var) is one repo.
+  try {
+    return `dir:${fs.realpathSync(key.slice(4))}`;
+  } catch {
+    return key;
+  }
+};
+export const memoryFile = (key) => path.join(paths.home, 'memory', `${String(key).replace(/[^\w.-]+/g, '_').slice(0, 120)}.md`);
+
+export const learnCommand = (bin = `node ${BIN}`) => `${bin} learn`;
+
+/** What earlier agents learned here (inlined, so no file access is needed), and how to add to it. */
+export function memoryPrompt(text, bin = `node ${BIN}`) {
+  const known = String(text ?? '').trim();
+  return [
+    known
+      ? `What earlier agents learned working in this repository (shared memory; trust it, but check anything that looks out of date):\n${known}`
+      : 'There is a shared memory for this repository, empty so far.',
+    `When you learn something non-obvious that would save the next agent in this repo real time (how to build or run the tests, a gotcha, where something lives, a convention that isn't written down), and it isn't already above or in CLAUDE.md or the README, record it as one short line: ${learnCommand(bin)} "<the learning>". ` +
+      'Record facts about the repo, not about your task; never secrets, tokens or personal data.',
+  ].join('\n\n');
+}
+
+/** One line, trimmed, without Markdown that could break the list. */
+export function cleanLearning(text) {
+  const t = String(text ?? '').replace(/\s+/g, ' ').replace(/^[-*#>\s]+/, '').trim();
+  if (!t) throw err(400, 'Nothing to learn: give one line of text');
+  if (t.length > 400) throw err(400, 'Keep a learning to one short line (400 characters at most)');
+  return t;
+}
+
+export class Memory {
+  constructor({ manager, config = {} }) {
+    this.manager = manager;
+    this.config = config;
+  }
+
+  get enabled() {
+    return this.config.memory !== false;
+  }
+
+  agentKey(ref) {
+    const agent = this.manager.mustGet(ref);
+    if (NO_REPO.has(agent.kind)) throw err(400, 'This agent has no repository');
+    return { agent, key: memoryKey(agent) };
+  }
+
+  read(ref) {
+    const { key } = this.agentKey(ref);
+    const file = memoryFile(key);
+    const text = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
+    return { key, file, text, entries: text.split('\n').filter((l) => l.startsWith('- ')).length, bytes: Buffer.byteLength(text), max: MAX_BYTES };
+  }
+
+  write(ref, text) {
+    const { key } = this.agentKey(ref);
+    text = String(text ?? '');
+    if (Buffer.byteLength(text) > MAX_BYTES) throw err(413, `Keep the memory under ${MAX_BYTES / 1000} KB; it is read by every agent in the repo`);
+    const file = memoryFile(key);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    if (!text.trim()) fs.rmSync(file, { force: true });
+    else fs.writeFileSync(file, text.endsWith('\n') ? text : `${text}\n`);
+    return this.read(ref);
+  }
+
+  /** Append one learning from an agent (or a person), skipping one already there. */
+  learn(ref, text, { by } = {}) {
+    const { agent, key } = this.agentKey(ref);
+    const line = cleanLearning(text);
+    const file = memoryFile(key);
+    const cur = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : `# What agents learned in ${projectOf(agent).full ?? projectOf(agent).name}\n\n`;
+    const norm = (s) => s.toLowerCase().replace(/[^a-z0-9]+/g, ' ').trim();
+    if (cur.split('\n').some((l) => l.startsWith('- ') && norm(l.replace(/ \([^)]*\)$/, '')).includes(norm(line)))) return { ...this.read(ref), added: false };
+    const entry = `- ${line} (${by ?? agent.name}, ${new Date().toISOString().slice(0, 10)})\n`;
+    if (Buffer.byteLength(cur + entry) > MAX_BYTES) throw err(413, 'The repo memory is full; ask the person to tidy it (Memory on the agent)');
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, cur.endsWith('\n') ? cur + entry : `${cur}\n${entry}`);
+    return { ...this.read(ref), added: true };
+  }
+}

package/src/notify.js

@@ -16,7 +16,8 @@ export const EVENT_DEFAULTS = {
   stuck: true, // going in circles: same failure, undoing its edits, or long stretches without changes
   conflict: true, // changing the same files as another agent in the same repo
   question: true, // asked a question in the decision inbox
-  assistant: true, // the assistant started an agent for new work
+  assistant: true, // an agent was started for new work (assistant, GitHub label, webhook)
+  budget: true, // an agent neared or reached its budget, or today's spend reached the daily limit
 };
 
 // Alerts the AI judge may hold for the digest or drop; the rest are always sent at once.
@@ -265,7 +266,7 @@ export class Notifier {
 
   deliver(kind, agent, what, n, urgency = null) {
     if (!n.enabled || !n.events[kind]) return;
-    const icon = { needsInput: ':raised_hand:', review: ':white_check_mark:', error: ':x:', waiting: ':hourglass_flowing_sand:', blocked: ':no_entry:', stuck: ':repeat:', conflict: ':crossed_swords:', question: ':question:', assistant: ':robot_face:' }[kind];
+    const icon = { needsInput: ':raised_hand:', review: ':white_check_mark:', error: ':x:', waiting: ':hourglass_flowing_sand:', blocked: ':no_entry:', stuck: ':repeat:', conflict: ':crossed_swords:', question: ':question:', assistant: ':robot_face:', budget: ':moneybag:' }[kind];
     const project = agent.projectInfo?.name ? ` (${agent.projectInfo.name})` : '';
     const link = this.linkFor(agent.id);
     const intent = n.includeIntent && agent.intent ? `\n> ${agent.intent.replace(/\s+/g, ' ').slice(0, 200)}` : '';

package/src/playbooks.js

@@ -0,0 +1,178 @@
+// Playbooks: saved requests you run again, by hand or on a schedule. One playbook is a request
+// (with {{placeholders}} filled in at run time), the projects to run it in (one agent each), and
+// optionally a model, permission mode and schedule: "upgrade dependency X in every repo",
+// "every weekday at 9:00, triage the flaky tests".
+import crypto from 'node:crypto';
+
+const err = (status, message) => Object.assign(new Error(message), { status });
+export const EVERY = ['hour', 'day', 'weekday', 'week'];
+const DAYS = ['sun', 'mon', 'tue', 'wed', 'thu', 'fri', 'sat'];
+
+/** "{{name}}" placeholders in a request, in order, once each. */
+export function placeholders(text) {
+  return [...new Set([...String(text ?? '').matchAll(/\{\{\s*([\w-]+)\s*\}\}/g)].map((m) => m[1]))];
+}
+
+export function render(text, vars = {}) {
+  return String(text).replace(/\{\{\s*([\w-]+)\s*\}\}/g, (m, k) => (vars[k] != null && String(vars[k]).trim() ? String(vars[k]).trim() : m));
+}
+
+/** A schedule, checked: { every: hour|day|weekday|week, at: "HH:MM", day: "mon".."sun" } or null. */
+export function cleanSchedule(s) {
+  if (!s || !s.every) return null;
+  if (!EVERY.includes(s.every)) throw err(400, `schedule.every must be one of ${EVERY.join(', ')}`);
+  const at = String(s.at ?? '09:00').trim();
+  if (!/^([01]?\d|2[0-3]):[0-5]\d$/.test(at)) throw err(400, 'schedule.at must be HH:MM');
+  const day = s.every === 'week' ? String(s.day ?? 'mon').toLowerCase().slice(0, 3) : undefined;
+  if (day !== undefined && !DAYS.includes(day)) throw err(400, 'schedule.day must be mon..sun');
+  const [h, m] = at.split(':').map(Number);
+  return { every: s.every, at: `${String(h).padStart(2, '0')}:${String(m).padStart(2, '0')}`, ...(day ? { day } : {}) };
+}
+
+/** The first time the schedule fires strictly after `after` (local time). */
+export function nextRun(schedule, after = new Date()) {
+  if (!schedule) return null;
+  const [h, m] = schedule.at.split(':').map(Number);
+  const t = new Date(after);
+  if (schedule.every === 'hour') {
+    t.setSeconds(0, 0);
+    t.setMinutes(m);
+    if (t <= after) t.setHours(t.getHours() + 1);
+    return t;
+  }
+  t.setHours(h, m, 0, 0);
+  for (let i = 0; i < 9; i += 1) {
+    const ok =
+      t > after &&
+      (schedule.every === 'day' ||
+        (schedule.every === 'weekday' && t.getDay() >= 1 && t.getDay() <= 5) ||
+        (schedule.every === 'week' && DAYS[t.getDay()] === schedule.day));
+    if (ok) return t;
+    t.setDate(t.getDate() + 1);
+  }
+  return null;
+}
+
+export class Playbooks {
+  constructor({ manager, store, log = (m) => console.log(`[agentmgr] ${m}`) }) {
+    this.manager = manager;
+    this.store = store;
+    this.log = log;
+    store.data.playbooks ??= {};
+    this.timer = setInterval(() => this.tick().catch((e) => this.log(`playbooks: ${e.message}`)), 60_000);
+    this.timer.unref?.();
+  }
+
+  close() {
+    clearInterval(this.timer);
+  }
+
+  get all() {
+    return this.store.data.playbooks;
+  }
+
+  view(p) {
+    return { ...p, placeholders: placeholders(p.intent), nextRunAt: p.enabled && p.schedule ? nextRun(p.schedule, new Date(Math.max(Date.now(), Date.parse(p.lastRunAt ?? 0) || 0)))?.toISOString() ?? null : null };
+  }
+
+  list() {
+    return Object.values(this.all)
+      .map((p) => this.view(p))
+      .sort((a, b) => a.name.localeCompare(b.name));
+  }
+
+  get(id) {
+    const p = this.all[id] ?? Object.values(this.all).find((x) => x.name.toLowerCase() === String(id).toLowerCase());
+    if (!p) throw err(404, `No playbook "${id}"`);
+    return p;
+  }
+
+  clean(input, prev = {}) {
+    const name = String(input.name ?? prev.name ?? '').trim().slice(0, 80);
+    if (!name) throw err(400, 'A name is required');
+    const intent = String(input.intent ?? prev.intent ?? '').trim();
+    if (!intent) throw err(400, 'The request is required');
+    const projects = (Array.isArray(input.projects) ? input.projects : String(input.projects ?? '').split(/[\s,]+/)).map((x) => String(x).trim().replace(/^@/, '')).filter(Boolean);
+    const list = input.projects === undefined ? prev.projects ?? [] : projects;
+    for (const p of list) if (!this.manager.resolveProject(p)) throw err(400, `No project "${p}" (agentmgr project ls)`);
+    if (!list.length) throw err(400, 'Pick at least one project to run it in');
+    const schedule = input.schedule === undefined ? prev.schedule ?? null : cleanSchedule(input.schedule);
+    if (schedule && placeholders(intent).some((k) => !(input.defaults ?? prev.defaults ?? {})[k])) {
+      throw err(400, 'A scheduled playbook needs a default value for each {{placeholder}}');
+    }
+    return {
+      name,
+      intent,
+      projects: list,
+      model: (input.model ?? prev.model ?? '') || null,
+      permissionMode: (input.permissionMode ?? prev.permissionMode ?? '') || null,
+      priority: input.priority ?? prev.priority ?? 2,
+      defaults: input.defaults ?? prev.defaults ?? {},
+      schedule,
+      enabled: input.enabled ?? prev.enabled ?? true,
+    };
+  }
+
+  create(input = {}) {
+    const p = { id: crypto.randomBytes(3).toString('hex'), ...this.clean(input), createdAt: new Date().toISOString(), runs: [] };
+    if (Object.values(this.all).some((x) => x.name.toLowerCase() === p.name.toLowerCase())) throw err(409, `A playbook named "${p.name}" exists`);
+    this.all[p.id] = p;
+    this.store.save();
+    return this.view(p);
+  }
+
+  update(id, input = {}) {
+    const p = this.get(id);
+    Object.assign(p, this.clean(input, p));
+    this.store.save();
+    return this.view(p);
+  }
+
+  remove(id) {
+    const p = this.get(id);
+    delete this.all[p.id];
+    this.store.save();
+    return { ok: true };
+  }
+
+  /** One agent per project, with the placeholders filled in. */
+  run(id, { vars = {}, by = 'person' } = {}) {
+    const p = this.get(id);
+    const values = { ...p.defaults, ...vars };
+    const intent = render(p.intent, values);
+    const missing = placeholders(intent);
+    if (missing.length) throw err(400, `Fill in ${missing.map((k) => `{{${k}}}`).join(', ')}`);
+    const run = { at: new Date().toISOString(), by, agents: [], failed: [] };
+    for (const project of p.projects) {
+      try {
+        const [a] = this.manager.createMany([intent], { project, model: p.model ?? undefined, permissionMode: p.permissionMode ?? undefined, priority: p.priority });
+        this.manager.patch(a.id, { playbook: { id: p.id, name: p.name, at: run.at } });
+        run.agents.push({ id: a.id, name: a.name, project });
+      } catch (e) {
+        run.failed.push({ project, reason: e.message });
+      }
+    }
+    p.lastRunAt = run.at;
+    p.runs = [...(p.runs ?? []), run].slice(-20);
+    this.store.save();
+    this.log(`playbooks: ran "${p.name}" (${by}): ${run.agents.length} agent(s)${run.failed.length ? `, ${run.failed.length} failed` : ''}`);
+    return run;
+  }
+
+  /** Run what is due. A run missed while the daemon was down runs once when it is back. */
+  async tick(now = new Date()) {
+    for (const p of Object.values(this.all)) {
+      if (!p.enabled || !p.schedule) continue;
+      const since = new Date(Date.parse(p.lastRunAt ?? p.createdAt) || now.getTime());
+      const due = nextRun(p.schedule, since);
+      if (!due || due > now) continue;
+      try {
+        this.run(p.id, { by: 'schedule' });
+      } catch (e) {
+        p.lastRunAt = now.toISOString();
+        p.runs = [...(p.runs ?? []), { at: p.lastRunAt, by: 'schedule', agents: [], failed: [{ project: '*', reason: e.message }] }].slice(-20);
+        this.store.save();
+      }
+    }
+  }
+}