ai-agentmanager 1.4.0 → 1.6.0

package/src/manager.js

@@ -8,6 +8,12 @@ import { expandHome, paths } from './config.js';
 import { DEFAULT_ENGINE, ENGINES, engineOf, installed, notInstalled } from './engines/index.js';
 import {
   DOC_KINDS,
+  diagramsOnly,
+  diagramsPrompt,
+  walkthroughFrom,
+  walkthroughHunks,
+  walkthroughMarkdown,
+  walkthroughPrompt,
   briefDir,
   briefPath,
   briefPrompt,
@@ -33,13 +39,60 @@ const SUMMARIES = {
   insights: { field: 'insights', prompt: insightsPrompt },
   ...Object.fromEntries(Object.keys(DOC_KINDS).map((k) => [k, { doc: k, prompt: (ctx) => docPrompt(k, ctx) }])),
   humanai: { doc: 'humanai', run: 'runHumanAi' },
+  diagrams: { doc: 'diagrams', run: 'runDiagrams' },
+  walkthrough: { doc: 'walkthrough', run: 'runWalkthrough' },
 };
 /** Read / write where a summary of `kind` is kept on the agent record. */
 const getSummary = (agent, kind) => (SUMMARIES[kind].doc ? agent.docs?.[kind] : agent[SUMMARIES[kind].field]);
 const summaryPatch = (agent, kind, value) =>
   SUMMARIES[kind].doc ? { docs: { ...agent.docs, [kind]: value } } : { [SUMMARIES[kind].field]: value };
+
+const stagedDir = () => path.join(paths.uploads, 'staged');
+const safeName = (name) => path.basename(String(name || 'file')).replace(/[^\w.@+-]+/g, '_').slice(-120) || 'file';
+
+/** Staged uploads named in a request, checked to be files in the staging folder. */
+function stagedFiles(list) {
+  if (list == null) return [];
+  if (!Array.isArray(list)) throw Object.assign(new Error('attachments must be a list of uploaded files'), { status: 400 });
+  const root = path.resolve(stagedDir()) + path.sep;
+  return list.slice(0, 20).map((p) => {
+    const file = path.resolve(String(p ?? ''));
+    if (!file.startsWith(root) || !fs.existsSync(file) || !fs.statSync(file).isFile()) {
+      throw Object.assign(new Error(`Not an uploaded file: ${path.basename(file)} (attach it again)`), { status: 400 });
+    }
+    return file;
+  });
+}
+
+/** Copy staged files into an agent's uploads folder (a copy each: one upload can serve several agents). */
+function copyAttachments(files, agentId) {
+  const dir = path.join(paths.uploads, agentId);
+  fs.mkdirSync(dir, { recursive: true });
+  return files.map((f) => {
+    // Drop the staging prefix (time and a random tag) to get the name it was attached with.
+    const dest = path.join(dir, path.basename(f).replace(/^\d{4}-\d\d-\d\dT[\d-]+Z-[0-9a-f]{6}-/, ''));
+    fs.copyFileSync(f, dest);
+    return dest;
+  });
+}
+
+/** The part of the request that lists attached files. */
+export const attachmentNote = (files) => `Attached files (part of this request; read them):\n${files.map((f) => `- ${f}`).join('\n')}`;
+
+/** The folders of a repo with how many files each holds, two levels deep: a map for drawing it. */
+async function repoLayout(dir) {
+  const files = (await git.run('git', ['ls-files'], { cwd: dir, timeout: 20_000 })).split('\n').filter(Boolean);
+  const counts = new Map();
+  for (const f of files) {
+    const parts = f.split('/');
+    const key = parts.length > 2 ? `${parts[0]}/${parts[1]}/` : parts.length === 2 ? `${parts[0]}/` : f;
+    counts.set(key, (counts.get(key) ?? 0) + 1);
+  }
+  return [...counts].slice(0, 150).map(([k, n]) => (k.endsWith('/') ? `${k} (${n} files)` : k)).join('\n');
+}
 import { spawn } from 'node:child_process';
 import * as git from './git.js';
+import { parseDiff } from '../public/review.js';
 import { conflictMessage, findConflicts, related, repoKey, summarize as summarizeConflicts } from './conflicts.js';
 import { answerMessage, loadQuestions, questionsPath, questionsPrompt } from './inbox.js';
 import { STUCK_DEFAULTS, detectStuck } from './stuck.js';
@@ -501,9 +554,9 @@ export class AgentManager extends EventEmitter {
     );
   }
 
-  /** A general Claude session with no repo or folder; the question (if any) is its first prompt. */
-  createGeneral({ question, name, permissionMode, model } = {}) {
-    return this.create({ kind: 'general', intent: question, name, permissionMode, model });
+  /** A general session with no repo or folder, on any engine; the question (if any) is its first prompt. */
+  createGeneral({ question, name, permissionMode, model, engine, attachments } = {}) {
+    return this.create({ kind: 'general', intent: question, name, permissionMode, model, engine, attachments });
   }
 
   create({
@@ -529,8 +582,10 @@ export class AgentManager extends EventEmitter {
     imported,
     startedBy,
     trigger,
+    attachments,
   }) {
     intent = (intent ?? '').trim();
+    const staged = stagedFiles(attachments);
     const engineDef = engineOf(engine || this.config.engine || DEFAULT_ENGINE);
     const engineId = engineDef.id;
     this.plugins.check('agent.create', {
@@ -554,7 +609,7 @@ export class AgentManager extends EventEmitter {
       base ??= entry.base ?? undefined;
       project = entry.key.startsWith('custom:') ? entry.name : null;
     }
-    if (!intent && !general) throw Object.assign(new Error('Intent is required'), { status: 400 });
+    if (!intent && !general && !staged.length) throw Object.assign(new Error('Intent is required'), { status: 400 });
     const id = crypto.randomBytes(3).toString('hex');
     // An imported session keeps its ID, so the first start resumes it.
     const sessionId = adopt || crypto.randomUUID();
@@ -562,6 +617,8 @@ export class AgentManager extends EventEmitter {
     const jiraKey = !name?.trim() && intent ? leadingJiraKey(intent) : null;
     const slug = name || intent ? slugify(name || jiraKey || intent) : `general-${id}`;
     const refs = extractRefs(intent, this.config.bugPatterns);
+    // Attached files (a screenshot, a log) go in the agent's own uploads folder, listed in its request.
+    if (staged.length) intent = [intent, attachmentNote(copyAttachments(staged, id))].filter(Boolean).join('\n\n');
 
     const agent = {
       id,
@@ -847,15 +904,15 @@ export class AgentManager extends EventEmitter {
         resume = true;
       }
     }
-    const args = engine.launchArgs({
-      ...this.launchOptions(agent),
-      sessionId: sid,
-      resume,
-      name: agent.name,
-      // A team member's first message is its first step, not just the problem.
-      prompt: resume ? (handoff ? handoffMessage(agent) : null) : (agent.kickoff ?? agent.intent),
-    });
+    // A team member's first message is its first step, not just the problem.
+    const prompt = resume ? (handoff ? handoffMessage(agent) : null) : (agent.kickoff ?? agent.intent);
+    const args = engine.launchArgs({ ...this.launchOptions(agent), sessionId: sid, resume, name: agent.name, prompt });
     const proc = this.spawnAgent(agent, agent.workdir, args);
+    // Engines whose resume takes no message get it typed once the session is idle.
+    if (resume && prompt && engine.supports.resumePrompt === false) {
+      if (!this.outbox.has(agent.id)) this.outbox.set(agent.id, []);
+      this.outbox.get(agent.id).unshift({ text: prompt, source: 'system', at: now() });
+    }
 
     const session = agent.sessions.find((s) => s.id === sid);
     if (session) {
@@ -927,6 +984,12 @@ export class AgentManager extends EventEmitter {
       }
     }
     // Appended system prompts last only for the process they're passed to, so they go on every launch.
+    // Files attached for it (at creation or in its terminal): readable without a permission prompt.
+    const uploads = path.join(paths.uploads, agent.id);
+    if (fs.existsSync(uploads)) {
+      const dir = fs.realpathSync(uploads);
+      writableDir = writableDir ? [writableDir, dir].flat() : dir;
+    }
     return { extra: engine.extraArgs(this.config), permissionMode: agent.permissionMode, model: agent.model, writableDir, instructions: prompts.join('\n\n') || null, agents, allowedTools };
   }
 
@@ -1102,7 +1165,8 @@ export class AgentManager extends EventEmitter {
         done.dispose();
         resolve(this.view(this.store.get(agent.id) ?? agent));
       });
-      rt.pty.kill('SIGHUP');
+      // A hangup, as when a terminal closes, unless the engine shuts down cleanly on another signal.
+      rt.pty.kill(engineOf(agent).stopSignal ?? 'SIGHUP');
       rt.killTimer = setTimeout(() => rt.pty?.kill('SIGKILL'), timeoutMs);
     });
   }
@@ -1168,7 +1232,7 @@ export class AgentManager extends EventEmitter {
   }
 
   childEnv(agent) {
-    const env = { ...process.env, ...(agent ? { AGENTMGR_AGENT_ID: agent.id } : {}), TERM: 'xterm-256color', COLORTERM: 'truecolor' };
+    const env = { ...process.env, ...(agent ? { AGENTMGR_AGENT_ID: agent.id } : {}), TERM: 'xterm-256color', COLORTERM: 'truecolor', AGENTMGR_TERMINAL: '1' };
     for (const key of STRIP_ENV) delete env[key];
     return env;
   }
@@ -1613,9 +1677,35 @@ export class AgentManager extends EventEmitter {
   }
 
   /** Save a file the user attached in the UI, so its path can be handed to Claude. */
+  /**
+   * A request with its attachments listed, for work that starts several agents from one request
+   * (a team, a race): the files are copied once to a shared folder they all read.
+   */
+  withSharedAttachments(intent, attachments) {
+    const staged = stagedFiles(attachments);
+    if (!staged.length) return intent;
+    const files = copyAttachments(staged, path.join('shared', crypto.randomBytes(4).toString('hex')));
+    return [String(intent ?? '').trim(), attachmentNote(files)].filter(Boolean).join('\n\n');
+  }
+
+  /** A file attached before its agent exists (New agents, Ask); create() copies it to the agent. */
+  stageUpload(name, data) {
+    fs.mkdirSync(stagedDir(), { recursive: true });
+    // Staged files nobody used are dropped after 30 days (a backlog item may wait that long).
+    const old = Date.now() - 30 * 86_400_000;
+    for (const f of fs.readdirSync(stagedDir())) {
+      try {
+        if (fs.statSync(path.join(stagedDir(), f)).mtimeMs < old) fs.rmSync(path.join(stagedDir(), f), { force: true });
+      } catch {}
+    }
+    const file = path.join(stagedDir(), `${new Date().toISOString().replace(/[:.]/g, '-')}-${crypto.randomBytes(3).toString('hex')}-${safeName(name)}`);
+    fs.writeFileSync(file, data);
+    return { path: file, name: safeName(name), size: data.length };
+  }
+
   saveUpload(ref, name, data) {
     const agent = this.mustGet(ref);
-    const safe = path.basename(String(name || 'file')).replace(/[^\w.@+-]+/g, '_').slice(-120) || 'file';
+    const safe = safeName(name);
     const dir = path.join(paths.uploads, agent.id);
     fs.mkdirSync(dir, { recursive: true });
     const file = path.join(dir, `${new Date().toISOString().replace(/[:.]/g, '-')}-${safe}`);
@@ -1926,8 +2016,10 @@ export class AgentManager extends EventEmitter {
 
   /** One tool-less, read-only call to an engine; resolves to its text output. */
   oneShot(agent, text, { engine, model, timeoutMs = 300_000 }) {
-    // Some engines take the prompt as an argument instead of on stdin.
-    const args = [...engine.extraArgs(this.config), ...engine.oneShotArgs(this.config, { model, prompt: text })];
+    // Some engines take the prompt as an argument instead of on stdin, and some need their extra
+    // arguments after a subcommand (oneShotExtra: they place them).
+    const extra = engine.extraArgs(this.config);
+    const args = engine.oneShotExtra ? engine.oneShotArgs(this.config, { model, prompt: text, extra }) : [...extra, ...engine.oneShotArgs(this.config, { model, prompt: text })];
     return new Promise((resolve, reject) => {
       const child = spawn(engine.bin(this.config), args, { cwd: paths.home, env: this.childEnv(agent), stdio: ['pipe', 'pipe', 'pipe'] });
       let out = '';
@@ -1945,6 +2037,68 @@ export class AgentManager extends EventEmitter {
     });
   }
 
+  /**
+   * The agent's changes explained one by one for review. `changesSource` (set by the server) gives
+   * the same diff the review screen shows; the result is keyed by file and hunk header.
+   */
+  async runWalkthrough(agent, ctx) {
+    if (!this.changesSource) throw new Error('Changes are not available here');
+    const data = await this.changesSource(agent.id);
+    const { hunks, cut } = walkthroughHunks(parseDiff(data.diff));
+    if (!hunks.length) throw Object.assign(new Error('No changes to explain yet'), { status: 400 });
+    const writer = this.writerFor(agent);
+    const result = walkthroughFrom(parseJsonReply(await this.oneShot(agent, walkthroughPrompt({ ...ctx, hunks }), writer)), hunks);
+    const cur = this.store.get(agent.id);
+    if (!cur) return null;
+    return this.view(
+      this.patch(
+        agent.id,
+        summaryPatch(cur, 'walkthrough', {
+          data: result,
+          cut,
+          diffHash: hash(data.diff),
+          markdown: walkthroughMarkdown(result, cur.name),
+          writer: `${writer.engine.label}${writer.model ? ` (${writer.model})` : ''}`,
+          at: now(),
+          briefUpdatedAt: cur.brief?.updatedAt ?? null,
+          pending: false,
+          error: null,
+        }),
+      ),
+    );
+  }
+
+  /** Diagrams only: the problem and its solution drawn from the documents already written and the live context. */
+  async runDiagrams(agent, ctx) {
+    const cur0 = this.store.get(agent.id) ?? agent;
+    const written = [
+      ...['analysis', 'design', 'flow', 'proposal'].map((k) => [DOC_KINDS[k].title, cur0.docs?.[k]?.markdown]),
+      ['Implementation plan', cur0.planReview?.markdown],
+      ['Explanation', cur0.explanation?.markdown],
+    ].filter(([, md]) => md);
+    const documents = written.map(([title, md]) => `<document title="${title}">\n${md.slice(0, 12_000)}\n</document>`).join('\n');
+    const repoMap = agent.workdir ? await repoLayout(agent.workdir).catch(() => '') : '';
+    const writer = this.writerFor(agent);
+    const markdown = diagramsOnly(await this.oneShot(agent, diagramsPrompt({ ...ctx, documents, repoMap }), writer));
+    const cur = this.store.get(agent.id);
+    if (!cur) return null;
+    const from = written.map(([title]) => title);
+    return this.view(
+      this.patch(
+        agent.id,
+        summaryPatch(cur, 'diagrams', {
+          markdown,
+          from,
+          writer: `${writer.engine.label}${writer.model ? ` (${writer.model})` : ''}`,
+          at: now(),
+          briefUpdatedAt: cur.brief?.updatedAt ?? null,
+          pending: false,
+          error: null,
+        }),
+      ),
+    );
+  }
+
   /** Human vs AI: the writer splits and answers the open questions, then another model double-checks it. */
   async runHumanAi(agent, ctx) {
     const writer = this.writerFor(agent);

package/src/review.js

@@ -1,6 +1,7 @@
 // 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 { hash } from './judge.js';
 import { NO_REPO } from './manager.js';
 import { ghBin } from './tracker.js';
 
@@ -135,6 +136,8 @@ export class Review {
       prs: Object.values(agent.prs ?? {}),
       busy: Boolean(rt?.pty && rt.busy),
       diff,
+      // Matches a walkthrough's diffHash while the changes are the ones it explained.
+      diffHash: hash(diff),
       truncated: diff.endsWith('… (diff truncated)'),
     };
   }

package/src/server.js

@@ -32,6 +32,7 @@ import { Notifier, isWorkflowUrl, loadNotify, publicNotify, saveNotify, sendSlac
 import { Previews, parseUrl } from './preview.js';
 import { LiveBrowser } from './livebrowser.js';
 import * as remote from './remote.js';
+import * as service from './service.js';
 import { Store } from './store.js';
 import { about, latestRelease } from './about.js';
 
@@ -59,7 +60,7 @@ function isAllowedOrigin(origin, port) {
 }
 
 const PUBLIC_REMOTE_API = new Set(['POST /api/login', 'GET /api/session']);
-const LOCAL_ONLY_API = /^\/api\/(remote(\/|$)|notify(\/|$)|hub(\/|$)|triggers(\/|$)|update(\/|$)|editors$|agents\/[\w-]+\/open-in$|shutdown$)/;
+const LOCAL_ONLY_API = /^\/api\/(remote(\/|$)|notify(\/|$)|hub(\/|$)|triggers(\/|$)|update(\/|$)|service$|editors$|agents\/[\w-]+\/open-in$|shutdown$)/;
 const HOOK_PATH = '/api/hooks/agents';
 const NO_REPO_KINDS = new Set(['general', 'assistant']);
 
@@ -73,6 +74,8 @@ export async function startServer({ port = PORT, host = HOST } = {}) {
   const backlog = new Backlog({ manager, store, config });
   const races = new Races({ manager, store });
   const review = new Review({ manager });
+  // The walkthrough explains the same diff the review screen shows.
+  manager.changesSource = (id) => review.get(id);
   const studio = new Studio({ manager, review });
   const teams = new Teams({ manager, store, config });
   const cleanup = new Cleanup({ manager, store, config, teams });
@@ -259,6 +262,15 @@ export async function startServer({ port = PORT, host = HOST } = {}) {
   api.post('/agents/:id/shell/close', wrap((req) => manager.closeShell(req.params.id, req.body?.n ? Number(req.body.n) : undefined)));
   api.post('/agents/:id/shell/new', wrap((req) => ({ n: manager.nextShellNumber(manager.mustGet(req.params.id).id) })));
   api.post('/agents/:id/shell/drop', wrap((req) => manager.dropShell(req.params.id, Number(req.body?.n) || 1)));
+  // A file attached before its agent exists (New agents, Ask). Raw body, name in the query.
+  api.post(
+    '/uploads',
+    express.raw({ type: () => true, limit: '50mb' }),
+    wrap((req) => {
+      if (!Buffer.isBuffer(req.body) || !req.body.length) throw fail(400, 'Empty file');
+      return manager.stageUpload(req.query.name, req.body);
+    }),
+  );
   // Raw file body; the name comes in the query. Returns the saved path to paste into a terminal.
   api.post(
     '/agents/:id/upload',
@@ -466,7 +478,9 @@ export async function startServer({ port = PORT, host = HOST } = {}) {
   api.post('/agents/:id/fork', wrap((req) => manager.fork(req.params.id, req.body ?? {})));
 
   api.get('/races', wrap(() => races.list()));
-  api.post('/races', wrap((req) => races.create(req.body ?? {})));
+  // Attachments: copied once to a shared folder and listed in the request every attempt gets.
+  const withFiles = ({ attachments, ...body } = {}) => ({ ...body, intent: manager.withSharedAttachments(body.intent, attachments) });
+  api.post('/races', wrap((req) => races.create(withFiles(req.body ?? {}))));
   api.get('/races/:id', wrap((req) => races.view(req.params.id)));
   api.post('/races/:id/tests', wrap((req) => races.runTests(req.params.id, req.body ?? {})));
   api.get('/races/:id/diff/:agent', wrap((req) => races.diff(req.params.id, req.params.agent)));
@@ -494,6 +508,20 @@ export async function startServer({ port = PORT, host = HOST } = {}) {
   api.get('/agents/:id/memory', wrap((req) => memory.read(req.params.id)));
   api.put('/agents/:id/memory', wrap((req) => memory.write(req.params.id, req.body?.text)));
   api.post('/agents/:id/learn', wrap((req) => memory.learn(req.params.id, req.body?.text, { by: req.headers['x-agentmgr-agent'] ? undefined : 'you' })));
+  // Start at login: the login service (launchd or systemd) that brings the daemon back after a reboot.
+  const serviceSupported = ['darwin', 'linux'].includes(process.platform);
+  const serviceView = async () => ({ supported: serviceSupported, ...(serviceSupported ? await service.status().catch(() => ({ installed: false, loaded: false })) : { installed: false, loaded: false }) });
+  api.get('/service', wrap(serviceView));
+  api.put(
+    '/service',
+    wrap(async (req) => {
+      if (!serviceSupported) throw fail(400, `Start at login isn't supported on ${process.platform}`);
+      // Installing loads it; its own copy finds this daemon running and exits cleanly (no restart),
+      // so it takes over at the next login.
+      const res = req.body?.enabled === true ? await service.install() : await service.uninstall();
+      return { ...(await serviceView()), note: res.note ?? null };
+    }),
+  );
   // The first-run checklist: what is set up, and what this machine is missing.
   api.get('/setup', wrap(async () => {
     const checks = (await doctor().catch(() => [])).filter((c) => c.status === 'fail' || c.status === 'warn').filter((c) => c.name !== 'Daemon');
@@ -506,6 +534,8 @@ export async function startServer({ port = PORT, host = HOST } = {}) {
         assistant: agentsNow.some((a) => a.kind === 'assistant') || Boolean(config.triggers?.github?.enabled || config.triggers?.webhook?.enabled),
         remote: Boolean(remote.loadSettings().enabled),
         budget: Boolean(config.budgets?.perAgentUsd || config.budgets?.perDayUsd),
+        // Only where it can be set up (macOS, Linux); elsewhere there's nothing to do.
+        service: serviceSupported ? Boolean((await service.status().catch(() => ({}))).installed) : true,
       },
     };
   }));
@@ -544,7 +574,7 @@ export async function startServer({ port = PORT, host = HOST } = {}) {
     return cleanup.run({ close: b.close !== false, delete: b.delete !== false, ids: Array.isArray(b.ids) ? b.ids : null });
   }));
   api.get('/teams', wrap(() => teams.list()));
-  api.post('/teams', wrap((req) => teams.create(req.body ?? {})));
+  api.post('/teams', wrap((req) => teams.create(withFiles(req.body ?? {}))));
   api.get('/teams/:id', wrap((req) => teams.view(req.params.id)));
   api.get('/teams/:id/files/:name', wrap((req) => teams.file(req.params.id, req.params.name)));
   api.post('/teams/:id/resume', wrap((req) => teams.resume(req.params.id, req.body ?? {})));