ai-agentmanager 1.2.1 → 1.3.1

package/src/landing.js

@@ -0,0 +1,212 @@
+// Landing: getting agents' pull requests merged. Failing checks and requested changes are sent
+// back to the agent that owns the PR (a few times per PR at most), a branch that fell behind is
+// brought up to date with the branch it targets, and ready PRs are merged with one click.
+import os from 'node:os';
+import * as git from './git.js';
+import { NO_REPO } from './manager.js';
+import { ghBin } from './tracker.js';
+import { parseBaseRef } from './review.js';
+
+export const MERGE_METHODS = ['squash', 'merge', 'rebase'];
+export const LANDING_DEFAULTS = { fixChecks: true, fixReviews: true, maxFixes: 3, mergeMethod: 'squash', deleteBranch: true };
+const LAND_ORDER = ['ready', 'fix', 'behind', 'waiting', 'draft'];
+
+const err = (status, message) => Object.assign(new Error(message), { status });
+
+/** Settings from config.json's "landing", with defaults and sane bounds. */
+export function landingSettings(config = {}) {
+  const c = { ...LANDING_DEFAULTS, ...config.landing };
+  const n = Number(c.maxFixes);
+  return {
+    fixChecks: c.fixChecks !== false,
+    fixReviews: c.fixReviews !== false,
+    maxFixes: Number.isFinite(n) && n >= 0 ? Math.min(20, Math.floor(n)) : LANDING_DEFAULTS.maxFixes,
+    mergeMethod: MERGE_METHODS.includes(c.mergeMethod) ? c.mergeMethod : LANDING_DEFAULTS.mergeMethod,
+    deleteBranch: c.deleteBranch !== false,
+  };
+}
+
+export function checksMessage(pr) {
+  const names = pr.checks?.failed?.length ? pr.checks.failed.join(', ') : 'some checks';
+  return [
+    `CI is failing on your pull request ${pr.url} (${names}).`,
+    `Look at the failures (\`gh pr checks ${pr.number ?? pr.url}\`, and \`gh run view <run id> --log-failed\` for the logs), fix the cause, run the relevant tests locally, then commit and push.`,
+    'If a failure is unrelated to your change (a flaky test or a broken main), say so instead of changing unrelated code.',
+  ].join('\n');
+}
+
+export function reviewMessage(pr) {
+  return [
+    `A reviewer requested changes on your pull request ${pr.url}.`,
+    `Read the review and its comments (\`gh pr view ${pr.number ?? pr.url} --comments\`, and \`gh api repos/{owner}/{repo}/pulls/${pr.number ?? '<number>'}/comments\` for line comments), address each one, then commit and push and reply on the PR with what you changed.`,
+  ].join('\n');
+}
+
+export function updateMessage(base) {
+  return `Your branch is behind ${base}. Merge ${base} into it (git fetch, then git merge ${base}), resolve any conflicts keeping both sides' intent, run the tests, then commit and push.`;
+}
+
+export class Landing {
+  constructor({ manager, store, config = {}, log = (m) => console.log(`[agentmgr] ${m}`) }) {
+    this.manager = manager;
+    this.store = store;
+    this.config = config;
+    this.log = log;
+    this.onPrs = (agent) => this.react(agent).catch((e) => this.log(`landing: ${e.message}`));
+    manager.on('prs', this.onPrs);
+    // Running agents' PRs are refreshed by the manager; closed agents with an open PR every few minutes.
+    this.timer = setInterval(() => this.refreshClosed().catch(() => {}), (config.landingRefreshMin ?? 6) * 60_000);
+    this.timer.unref?.();
+  }
+
+  close() {
+    clearInterval(this.timer);
+    this.manager.off('prs', this.onPrs);
+  }
+
+  get settings() {
+    return landingSettings(this.config);
+  }
+
+  update(patch = {}) {
+    if (patch.mergeMethod !== undefined && !MERGE_METHODS.includes(patch.mergeMethod)) throw err(400, `mergeMethod must be one of ${MERGE_METHODS.join(', ')}`);
+    if (patch.maxFixes !== undefined && !(Number(patch.maxFixes) >= 0)) throw err(400, 'maxFixes must be 0 or more');
+    const next = landingSettings({ landing: { ...this.config.landing, ...patch } });
+    this.config.landing = next;
+    return next;
+  }
+
+  /** Open PRs that the agent opened or that were found on its branch (not ones it only mentioned). */
+  openPrs(agent) {
+    return Object.values(agent.prs ?? {}).filter((p) => p.state === 'OPEN' && p.source !== 'mentioned');
+  }
+
+  /** After a PR refresh: send failing checks and requested changes back to the agent, once per commit. */
+  async react(agent) {
+    const s = this.settings;
+    if (!this.store.get(agent.id) || NO_REPO.has(agent.kind) || !s.maxFixes) return;
+    agent.landing ??= { sent: {} };
+    let sent = false;
+    for (const pr of this.openPrs(agent)) {
+      if (!pr.head) continue;
+      const count = Object.keys(agent.landing.sent).filter((k) => k.startsWith(`${pr.url}#`)).length;
+      if (count >= s.maxFixes) continue;
+      const send = (kind, text) => {
+        const key = `${pr.url}#${kind}@${pr.head}`;
+        if (agent.landing.sent[key]) return;
+        agent.landing.sent[key] = new Date().toISOString();
+        this.manager.tell(agent.id, text, { source: 'landing' });
+        this.log(`landing: told ${agent.name} about ${kind} on ${pr.url}`);
+        sent = true;
+      };
+      if (s.fixChecks && pr.checks?.state === 'failed') send('checks', checksMessage(pr));
+      else if (s.fixReviews && pr.review === 'CHANGES_REQUESTED') send('review', reviewMessage(pr));
+    }
+    if (sent) this.store.save();
+  }
+
+  async refreshClosed() {
+    for (const agent of this.store.list()) {
+      if (this.manager.runtimes.get(agent.id)?.pty || !agent.workdir || !this.openPrs(agent).length) continue;
+      await this.manager.refresh(agent.id, { withPrs: true }).catch(() => {});
+    }
+  }
+
+  /** Every agent's open pull request with where it stands, ready ones first. */
+  list() {
+    const rows = [];
+    for (const agent of this.store.list()) {
+      const view = this.manager.view(agent);
+      for (const pr of view.prs.filter((p) => p.state === 'OPEN' && p.source !== 'mentioned')) {
+        const fixes = Object.keys(agent.landing?.sent ?? {}).filter((k) => k.startsWith(`${pr.url}#`)).length;
+        rows.push({ agent: { id: agent.id, name: agent.name, priority: view.priority, busy: view.runtime.busy, running: view.runtime.running }, pr, land: pr.land ?? 'waiting', fixes });
+      }
+    }
+    const rank = (r) => (LAND_ORDER.includes(r.land) ? LAND_ORDER.indexOf(r.land) : LAND_ORDER.length);
+    return { settings: this.settings, rows: rows.sort((a, b) => rank(a) - rank(b) || a.agent.priority - b.agent.priority) };
+  }
+
+  agentPr(ref, url) {
+    const agent = this.manager.mustGet(ref);
+    const open = this.openPrs(agent);
+    const pr = url ? open.find((p) => p.url === url) : open[0];
+    if (!pr) throw err(404, url ? 'That pull request is not open on this agent' : 'This agent has no open pull request');
+    return { agent, pr };
+  }
+
+  /**
+   * Bring the branch up to date with the one it targets: merge it in here when the agent is idle
+   * and its worktree clean (and push), else ask the agent. A conflict is aborted and handed to the agent.
+   */
+  async updateBranch(ref, { via = 'auto' } = {}) {
+    const agent = this.manager.mustGet(ref);
+    if (!agent.workdir || NO_REPO.has(agent.kind)) throw err(400, 'This agent has no repository');
+    const dir = agent.workdir;
+    const opts = { cwd: dir, timeout: 120_000 };
+    const b = parseBaseRef(agent.baseRef);
+    const target = b?.ref && b.ref !== 'HEAD' ? b.ref : (await git.resolveBase(dir).catch(() => null))?.ref;
+    if (!target || target === 'HEAD') throw err(409, "Couldn't tell which branch this one should follow");
+    const ask = (why) => {
+      this.manager.tell(agent.id, updateMessage(target), { source: 'landing' });
+      return { asked: true, why, target };
+    };
+    if (via === 'agent') return ask('asked');
+    const rt = this.manager.runtimes.get(agent.id);
+    if (rt?.pty && rt.busy) return ask('the agent is working');
+    if ((await git.run('git', ['status', '--porcelain'], opts)).trim()) return ask('it has uncommitted changes');
+    if (target.startsWith('origin/')) await git.fetch(dir).catch(() => {});
+    const behind = Number(await git.run('git', ['rev-list', '--count', `HEAD..${target}`], opts).catch(() => '0')) || 0;
+    if (!behind) return { upToDate: true, target };
+    try {
+      await git.run('git', ['merge', '--no-edit', target], { ...opts, env: { GIT_MERGE_AUTOEDIT: 'no' } });
+    } catch (e) {
+      await git.run('git', ['merge', '--abort'], opts).catch(() => {});
+      return { ...ask('the merge has conflicts'), conflict: true };
+    }
+    let pushed = false;
+    const upstream = await git.run('git', ['rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{u}'], opts).catch(() => '');
+    if (upstream) {
+      await git.run('git', ['push'], opts);
+      pushed = true;
+    }
+    this.manager.refresh(agent.id, { withPrs: true }).catch(() => {});
+    return { merged: behind, target, pushed };
+  }
+
+  /** Ask the agent to fix what stands in the way: failing checks, requested changes, conflicts. */
+  fix(ref, { url } = {}) {
+    const { agent, pr } = this.agentPr(ref, url);
+    const parts = [];
+    if (pr.checks?.state === 'failed') parts.push(checksMessage(pr));
+    if (pr.review === 'CHANGES_REQUESTED') parts.push(reviewMessage(pr));
+    if (pr.mergeable === 'CONFLICTING' || pr.mergeState === 'DIRTY' || pr.mergeState === 'BEHIND') {
+      const b = parseBaseRef(agent.baseRef);
+      parts.push(updateMessage(b?.ref && b.ref !== 'HEAD' ? b.ref : 'the base branch'));
+    }
+    if (!parts.length) throw err(409, 'Nothing to fix on this pull request right now');
+    this.manager.tell(agent.id, parts.join('\n\n'), { source: 'landing' });
+    return { sent: parts.length };
+  }
+
+  /** Merge the PR with gh (or turn on auto-merge so GitHub merges it once it may). */
+  async merge(ref, { url, method, auto = false } = {}) {
+    const { agent, pr } = this.agentPr(ref, url);
+    const s = this.settings;
+    method = method ?? s.mergeMethod;
+    if (!MERGE_METHODS.includes(method)) throw err(400, `method must be one of ${MERGE_METHODS.join(', ')}`);
+    this.manager.plugins.check('agent.merge', { agent: this.manager.auditView(agent), url: pr.url, method, auto: Boolean(auto) });
+    const args = ['pr', 'merge', pr.url, `--${method}`];
+    if (auto) args.push('--auto');
+    if (s.deleteBranch && !auto) args.push('--delete-branch');
+    try {
+      // Outside the worktree, so gh deletes only the remote branch and leaves the worktree alone.
+      await git.run(ghBin(), args, { cwd: os.tmpdir(), timeout: 120_000 });
+    } catch (e) {
+      throw err(502, e.message.replace(/^\S+ pr merge .*? failed: /, ''));
+    }
+    this.manager.plugins.emit('agent.merge', { agent: this.manager.auditView(agent), url: pr.url, method, auto: Boolean(auto) });
+    this.log(`landing: ${auto ? 'auto-merge on for' : 'merged'} ${pr.url}`);
+    await this.manager.refresh(agent.id, { withPrs: true }).catch(() => {});
+    return { url: pr.url, merged: !auto, auto: Boolean(auto) };
+  }
+}

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,94 @@ 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);
-    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;
+    const running = this.refreshing.get(id);
+    if (running) {
+      if (!withPrs) return running.promise.then(() => this.store.get(id) && this.view(this.store.get(id)));
+      // A pull request check runs again after the one in progress, which may have read PRs from
+      // before this request; callers arriving meanwhile share that next run.
+      running.next ??= running.promise.catch(() => {}).then(() => this.refresh(id, { withPrs }));
+      return running.next;
+    }
+    // Cleared before anyone waiting on it continues, so the next run starts afresh.
+    const entry = { withPrs };
+    entry.promise = this.doRefresh(id, { withPrs }).finally(() => {
+      if (this.refreshing.get(id) === entry) this.refreshing.delete(id);
+    });
+    this.refreshing.set(id, entry);
+    return entry.promise;
+  }
+
+  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)}` : '';