ai-agentmanager 1.5.0 → 1.7.0

package/src/cli.js

@@ -1,5 +1,6 @@
 import { execFile } from 'node:child_process';
 import fs from 'node:fs';
+import path from 'node:path';
 import { Command, Option } from 'commander';
 import WebSocket from 'ws';
 import { HOST, PORT } from './config.js';
@@ -192,6 +193,20 @@ async function attach(ref, { resume = true, kind = 'claude' } = {}) {
   });
 }
 
+/** Upload local files for a request (a screenshot, a log); returns the staged paths the daemon gets. */
+async function uploadFiles(files = []) {
+  const out = [];
+  for (const f of files) {
+    const data = fs.readFileSync(f);
+    const res = await fetch(`${BASE}/api/uploads?name=${encodeURIComponent(path.basename(f))}`, { method: 'POST', headers: { 'content-type': 'application/octet-stream', 'x-agentmgr': '1' }, body: data });
+    const body = await res.json().catch(() => ({}));
+    if (!res.ok) throw new Error(`Could not attach ${f}: ${body.error || `HTTP ${res.status}`}`);
+    out.push(body.path);
+  }
+  return out.length ? out : undefined;
+}
+const collect = (v, list = []) => [...list, v];
+
 function readIntentsFile(file) {
   const text = file === '-' ? fs.readFileSync(0, 'utf8') : fs.readFileSync(file, 'utf8');
   return text
@@ -295,6 +310,11 @@ export async function main(argv) {
       const st = await api('GET', '/remote').catch(() => null);
       const phone = st?.running ? st.urls.find((u) => !u.vpn) : null;
       if (phone) console.log(dim(`phone: ${phone.url}  (sign-in QR: agentmgr remote status)`));
+      // Without the login service, nothing starts the daemon after a reboot.
+      if (['darwin', 'linux'].includes(process.platform)) {
+        const svc = await import('./service.js');
+        if (!(await svc.status().catch(() => ({ installed: true }))).installed) console.log(dim('tip: it won\'t start by itself after a restart; turn on Settings → Start at login, or run: agentmgr service install'));
+      }
       execFile(process.platform === 'darwin' ? 'open' : 'xdg-open', [BASE], () => {});
     });
 
@@ -321,7 +341,8 @@ export async function main(argv) {
       ]),
     )
     .option('-m, --model <model>', 'model (for the chosen engine)')
-    .option('-e, --engine <engine>', 'agent engine: claude (default) or codex')
+    .option('-e, --engine <engine>', 'agent engine: claude (default), codex, antigravity or muse')
+    .option('--file-attach <path>', 'attach a file to the request (a screenshot, a log); repeat for more', collect)
     .option('--plan', 'while a repo URL clones, plan the task with Claude (moves into the repo when ready)')
     .option('--no-start', 'create without launching')
     .option('-a, --attach', 'attach to the agent after launch (single intent only)')
@@ -332,8 +353,10 @@ export async function main(argv) {
       await daemon();
       // commander sets worktree=true for --no-worktree's default; only send it when the user chose.
       const worktreeSource = cmd.getOptionValueSource('worktree');
+      const attachments = await uploadFiles(opts.fileAttach);
       const created = await api('POST', '/agents', {
         intents,
+        attachments,
         repo: opts.repo,
         dir: opts.dir,
         name: opts.name,
@@ -362,14 +385,17 @@ export async function main(argv) {
 
   program
     .command('ask')
-    .description('Open a general Claude session (no repo or folder) and attach to it')
+    .description('Open a general session (no repo or folder) on any engine and attach to it')
     .argument('[question...]', 'optional first question')
     .option('-n, --name <name>', 'display name')
-    .option('-m, --model <model>', 'claude model')
+    .option('-m, --model <model>', 'model (for the chosen engine)')
+    .option('-e, --engine <engine>', 'agent engine: claude (default), codex, antigravity or muse')
+    .option('--file-attach <path>', 'attach a file to the question (a screenshot, a log); repeat for more', collect)
     .option('--no-attach', 'start it in the background only')
     .action(async (words, opts) => {
       await daemon();
-      let a = await api('POST', '/general', { question: words.join(' '), name: opts.name, model: opts.model });
+      const attachments = await uploadFiles(opts.fileAttach);
+      let a = await api('POST', '/general', { question: words.join(' '), name: opts.name, model: opts.model, engine: opts.engine, attachments });
       console.log(`${green('+')} ${bold(a.name)} ${dim(a.id)}  session ${cyan(a.sessionId)}`);
       for (let i = 0; i < 100 && a.status === 'preparing'; i++) {
         await new Promise((r) => setTimeout(r, 100));
@@ -404,9 +430,9 @@ export async function main(argv) {
 
   program
     .command('doc')
-    .description('Write a stakeholder document from the agent work: analysis, design, flow, proposal, humanai (Human vs AI) or diagrams (diagrams only)')
+    .description('Write a stakeholder document from the agent work: analysis, design, flow, proposal, humanai (Human vs AI), diagrams (diagrams only) or walkthrough (its changes explained one by one)')
     .argument('<agent>')
-    .argument('<kind>', 'analysis, design, flow, proposal, humanai, diagrams, or all (background; diagrams not included)')
+    .argument('<kind>', 'analysis, design, flow, proposal, humanai, diagrams, walkthrough, or all (background; diagrams and walkthrough not included)')
     .option('-o, --output <file>', 'also save the Markdown to this file')
     .option('--cached', 'print the last version instead of writing a new one')
     .option('-b, --background', 'start writing and return at once (kind "all" writes all five)')

package/src/manager.js

@@ -10,6 +10,10 @@ import {
   DOC_KINDS,
   diagramsOnly,
   diagramsPrompt,
+  walkthroughFrom,
+  walkthroughHunks,
+  walkthroughMarkdown,
+  walkthroughPrompt,
   briefDir,
   briefPath,
   briefPrompt,
@@ -36,12 +40,45 @@ const SUMMARIES = {
   ...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);
@@ -55,6 +92,7 @@ async function repoLayout(dir) {
 }
 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';
@@ -516,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({
@@ -544,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', {
@@ -569,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();
@@ -577,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,
@@ -942,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 };
   }
 
@@ -1629,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}`);
@@ -1963,6 +2037,37 @@ 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;

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 ?? {})));