ai-agentmanager 1.1.0 → 1.3.0

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,6 +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, // 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.
@@ -264,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:' }[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();
+      }
+    }
+  }
+}

package/src/review.js

@@ -0,0 +1,209 @@
+// Review an agent's changes: the diff against where its branch started, line comments sent
+// back to the agent as one message, and commit / push / open a pull request from the UI.
+import * as git from './git.js';
+import { NO_REPO } from './manager.js';
+import { ghBin } from './tracker.js';
+
+const err = (status, message) => Object.assign(new Error(message), { status });
+const MAX_COMMENTS = 100;
+
+/** "origin/main @ 1a2b3c4d5" -> { ref: 'origin/main', sha: '1a2b3c4d5' } */
+export function parseBaseRef(baseRef) {
+  const m = /^(.*) @ ([0-9a-f]{4,40})$/.exec(baseRef ?? '');
+  return m ? { ref: m[1], sha: m[2] } : null;
+}
+
+/** The branch a pull request should target, from the ref the agent branched from. */
+export function prBase(ref) {
+  if (!ref || ref === 'HEAD' || /^[0-9a-f]{7,40}$/.test(ref)) return null;
+  return ref.replace(/^origin\//, '');
+}
+
+/** One message for the agent with every comment, its place and the line it is about. */
+export function commentsMessage(comments, note = '') {
+  const lines = ['Review of your changes. Please address each comment, then say what you changed.', ''];
+  comments.forEach((c, i) => {
+    const where = c.file ? `${c.file}${c.line ? `:${c.line}` : ''}` : 'General';
+    lines.push(`${i + 1}. ${where}${c.side === 'old' ? ' (removed line)' : ''}`);
+    if (c.code) lines.push(`   > ${String(c.code).trim().slice(0, 200)}`);
+    lines.push(`   ${String(c.text).trim().replace(/\n/g, '\n   ')}`);
+  });
+  if (note.trim()) lines.push('', note.trim());
+  return lines.join('\n');
+}
+
+/** Per-file status from `git diff --name-status` plus untracked files. */
+function fileStatuses(nameStatus, untracked) {
+  const out = {};
+  const kinds = { A: 'added', D: 'deleted', M: 'modified', T: 'modified' };
+  for (const line of nameStatus.split('\n').filter(Boolean)) {
+    const [code, ...paths] = line.split('\t');
+    out[paths.at(-1)] = kinds[code[0]] ?? (code[0] === 'R' ? 'renamed' : 'modified');
+  }
+  for (const f of untracked) out[f] = 'added';
+  return out;
+}
+
+function addedLines(diff, file) {
+  const start = diff.indexOf(`diff --git a/${file} b/${file}\n`);
+  if (start < 0) return null;
+  const end = diff.indexOf('\ndiff --git ', start + 1);
+  const part = diff.slice(start, end < 0 ? undefined : end);
+  if (/^Binary files /m.test(part)) return null;
+  return part.split('\n').filter((l) => l.startsWith('+') && !l.startsWith('+++')).length;
+}
+
+export class Review {
+  constructor({ manager }) {
+    this.manager = manager;
+  }
+
+  agentWithRepo(ref) {
+    const agent = this.manager.mustGet(ref);
+    if (!agent.workdir || NO_REPO.has(agent.kind)) {
+      throw err(400, 'This agent has no repository to review');
+    }
+    return agent;
+  }
+
+  /** Where the diff starts: the merge base with the branch it came from, else the recorded commit. */
+  async base(agent) {
+    const b = parseBaseRef(agent.baseRef);
+    const opts = { cwd: agent.workdir, timeout: 30_000 };
+    if (b?.ref && b.ref !== 'HEAD') {
+      const mb = await git.run('git', ['merge-base', 'HEAD', b.ref], opts).catch(() => null);
+      if (mb) return { ref: b.ref, sha: mb };
+    }
+    if (b?.sha) return { ref: b.ref, sha: b.sha };
+    // No record (imported folders): the remote default branch, if there is one.
+    const r = await git.resolveBase(agent.workdir).catch(() => null);
+    if (r && r.ref !== 'HEAD') {
+      const mb = await git.run('git', ['merge-base', 'HEAD', r.ref], opts).catch(() => null);
+      if (mb) return { ref: r.ref, sha: mb };
+    }
+    return null;
+  }
+
+  async get(ref) {
+    const agent = this.agentWithRepo(ref);
+    const dir = agent.workdir;
+    if (!(await git.isGitRepo(dir))) throw err(400, 'The agent folder is not a git repository');
+    const opts = { cwd: dir, timeout: 30_000 };
+    const safe = (p) => p.catch(() => '');
+    const base = await this.base(agent);
+    const branch = await safe(git.run('git', ['rev-parse', '--abbrev-ref', 'HEAD'], opts));
+    const from = base?.sha ?? 'HEAD';
+    const [nameStatus, numstat, untrackedOut, log, status, upstream] = await Promise.all([
+      safe(git.run('git', ['diff', '--name-status', from], opts)),
+      safe(git.run('git', ['diff', '--numstat', from], opts)),
+      safe(git.run('git', ['ls-files', '--others', '--exclude-standard'], opts)),
+      base ? safe(git.run('git', ['log', '--format=%h%x09%s%x09%cI', '-n', '50', `${base.sha}..HEAD`], opts)) : '',
+      safe(git.run('git', ['status', '--porcelain'], opts)),
+      safe(git.run('git', ['rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{u}'], opts)),
+    ]);
+    const untracked = untrackedOut.split('\n').filter(Boolean);
+    const statuses = fileStatuses(nameStatus, untracked);
+    const counts = {};
+    for (const line of numstat.split('\n').filter(Boolean)) {
+      const [a, d, ...p] = line.split('\t');
+      counts[p.join('\t').replace(/^.*=> /, '').replace(/[{}]/g, '')] = { added: a === '-' ? null : Number(a), removed: d === '-' ? null : Number(d) };
+    }
+    const diff = await git.fullDiff(dir, from);
+    const files = Object.entries(statuses)
+      .map(([path, st]) => ({ path, status: st, ...(counts[path] ?? { added: null, removed: 0 }), untracked: untracked.includes(path) }))
+      .sort((x, y) => (x.path < y.path ? -1 : 1));
+    // New files git doesn't count yet: their added lines, from the diff.
+    for (const f of files.filter((x) => x.untracked && x.added == null)) f.added = addedLines(diff, f.path);
+    let ahead = 0;
+    if (upstream) ahead = Number(await safe(git.run('git', ['rev-list', '--count', `${upstream}..HEAD`], opts))) || 0;
+    const rt = this.manager.runtimes.get(agent.id);
+    return {
+      id: agent.id,
+      name: agent.name,
+      branch,
+      base,
+      prBase: prBase(base?.ref),
+      commits: log.split('\n').filter(Boolean).map((l) => {
+        const [sha, subject, at] = l.split('\t');
+        return { sha, subject, at };
+      }),
+      files,
+      uncommitted: status ? status.split('\n').length : 0,
+      upstream: upstream || null,
+      unpushed: upstream ? ahead : null,
+      hasRemote: await git.hasRemote(dir),
+      prs: Object.values(agent.prs ?? {}),
+      busy: Boolean(rt?.pty && rt.busy),
+      diff,
+      truncated: diff.endsWith('… (diff truncated)'),
+    };
+  }
+
+  /** Send the comments to the agent as one message (typed in when it is idle). */
+  comment(ref, { comments = [], note = '' } = {}) {
+    const agent = this.agentWithRepo(ref);
+    const list = (Array.isArray(comments) ? comments : []).filter((c) => String(c?.text ?? '').trim()).slice(0, MAX_COMMENTS);
+    if (!list.length && !String(note).trim()) throw err(400, 'Add a comment first');
+    const text = commentsMessage(list, String(note));
+    this.manager.tell(agent.id, text, { source: 'review' });
+    agent.reviewsSent = [...(agent.reviewsSent ?? []), { at: new Date().toISOString(), comments: list.length }].slice(-20);
+    this.manager.store.save();
+    return { sent: list.length, text };
+  }
+
+  /** Commit everything in the worktree (new files included) with the person's git identity. */
+  async commit(ref, { message } = {}) {
+    const agent = this.agentWithRepo(ref);
+    message = String(message ?? '').trim();
+    if (!message) throw err(400, 'A commit message is required');
+    this.manager.plugins.check('agent.commit', { agent: this.manager.auditView(agent), message });
+    const opts = { cwd: agent.workdir, timeout: 60_000 };
+    const status = await git.run('git', ['status', '--porcelain'], opts);
+    if (!status.trim()) throw err(409, 'Nothing to commit');
+    await git.run('git', ['add', '-A'], opts);
+    await git.run('git', ['commit', '-m', message], opts);
+    const sha = await git.run('git', ['rev-parse', '--short', 'HEAD'], opts);
+    this.manager.plugins.emit('agent.commit', { agent: this.manager.auditView(agent), message, sha });
+    this.manager.refresh(agent.id).catch(() => {});
+    return { sha, files: status.split('\n').length };
+  }
+
+  /** Push the branch and open a pull request (or return the one already open). */
+  async pr(ref, { title = '', body = '', draft = false } = {}) {
+    const agent = this.agentWithRepo(ref);
+    const dir = agent.workdir;
+    this.manager.plugins.check('agent.pr', { agent: this.manager.auditView(agent), title: String(title), draft: Boolean(draft) });
+    const opts = { cwd: dir, timeout: 120_000 };
+    if (!(await git.hasRemote(dir))) throw err(409, 'The repository has no "origin" remote to push to');
+    const branch = await git.run('git', ['rev-parse', '--abbrev-ref', 'HEAD'], opts);
+    if (!branch || branch === 'HEAD') throw err(409, 'The worktree is not on a branch');
+    const dirty = await git.run('git', ['status', '--porcelain'], opts);
+    if (dirty.trim()) throw err(409, 'There are uncommitted changes: commit them first');
+    const base = await this.base(agent);
+    const target = prBase(base?.ref);
+    if (target && branch === target) throw err(409, `The worktree is on ${branch} itself; a pull request needs its own branch`);
+    await git.run('git', ['push', '-u', 'origin', `HEAD:refs/heads/${branch}`], opts);
+    const open = Object.values(agent.prs ?? {}).find((p) => p.state === 'OPEN');
+    if (open) {
+      this.manager.refresh(agent.id, { withPrs: true }).catch(() => {});
+      return { url: open.url, pushed: true, existing: true };
+    }
+    const args = ['pr', 'create', '--head', branch];
+    if (target) args.push('--base', target);
+    if (String(title).trim()) args.push('--title', String(title).trim(), '--body', String(body ?? ''));
+    else args.push('--fill');
+    if (draft) args.push('--draft');
+    let out;
+    try {
+      out = await git.run(ghBin(), args, opts);
+    } catch (e) {
+      const m = /https:\/\/\S+\/pull\/\d+/.exec(e.message);
+      if (m && /already exists/i.test(e.message)) out = m[0];
+      else throw err(502, `Pushed, but opening the pull request failed: ${e.message.replace(/^gh .*? failed: /, '')}`);
+    }
+    const url = /https:\/\/\S+\/pull\/\d+/.exec(out)?.[0];
+    if (url) this.manager.addLink(agent.id, { type: 'pr', value: url });
+    this.manager.plugins.emit('agent.pr', { agent: this.manager.auditView(agent), url });
+    return { url: url ?? null, pushed: true, existing: false };
+  }
+}