@amenophis1er/foreman 0.1.7 → 0.1.9

package/src/services.test.ts

@@ -1,7 +1,8 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import http from 'node:http';
-import { ServiceRegistry, parseServicePath, portOpen, proxyToService, servicePath } from './services.js';
+import { ServiceRegistry, parseServicePath, portOpen, proxyToService, servicePath, servicesHandler } from './services.js';
+import { requestAllowed } from './guard.js';
 
 test('service paths round-trip and reject junk', () => {
   assert.equal(servicePath('run-1', 8934), '/svc/run-1/8934/');
@@ -51,3 +52,37 @@ test('proxyToService streams a response and reports a dead port as 502', async (
     front.close();
   }
 });
+
+test('the services port serves only /svc/ — everything else is a 404', async () => {
+  const registry = new ServiceRegistry();
+  // The guard checks the Host against the port it is given, and the port is
+  // only known after listen(), so it is read out of a box the listener fills.
+  let port = 0;
+  const server = http.createServer(servicesHandler({
+    registry,
+    allowed: (req) => requestAllowed(req, { port, tailnet: null }),
+  }));
+  await new Promise<void>((r) => server.listen(0, '127.0.0.1', r));
+  port = (server.address() as { port: number }).port;
+  try {
+    const other = await fetch(`http://127.0.0.1:${port}/anything`);
+    assert.equal(other.status, 404);
+    assert.deepEqual(await other.json(), { error: 'not found' });
+
+    const undeclared = await fetch(`http://127.0.0.1:${port}/svc/run-1/3000/`);
+    assert.equal(undeclared.status, 404);
+    assert.deepEqual(await undeclared.json(), { error: 'no such service' });
+
+    // And the guard still runs first: a rebound Host never reaches the proxy.
+    // Raw http, not fetch — undici refuses to let a caller set Host.
+    const rebound = await new Promise<number>((resolve, reject) => {
+      const r = http.request({ host: '127.0.0.1', port, path: '/svc/run-1/3000/', headers: { host: 'evil.example' } },
+        (res2) => { res2.resume(); resolve(res2.statusCode ?? 0); });
+      r.on('error', reject);
+      r.end();
+    });
+    assert.equal(rebound, 421);
+  } finally {
+    server.close();
+  }
+});

package/src/services.ts

@@ -1,7 +1,13 @@
 /**
  * Services the crew exposes: a dev server it started to test its work, made
- * reachable through Foreman's own address — so the human on the phone can
- * open it over the tailnet without the agent opening a port to the world.
+ * reachable through Foreman's machine — so the human on the phone can open it
+ * over the tailnet without the agent opening a port to the world.
+ *
+ * These pages are served on their own port (FOREMAN_SERVICES_PORT, PORT + 1 by
+ * default), never on the dashboard's. Whatever the crew wrote runs in a
+ * browser, and if it ran on Foreman's origin the same-origin policy would let
+ * it call every Foreman API as the operator. A different port is a different
+ * origin, so it cannot.
  *
  * The proxy is deliberately narrow. Only ports a run declared, only on
  * loopback, only under `/svc/<run>/<port>/`. Nothing is guessed: a request
@@ -10,11 +16,12 @@
  */
 import http from 'node:http';
 import net from 'node:net';
+import type { GuardVerdict } from './guard.js';
 
 export interface ExposedService {
   port: number;
   label: string;
-  /** `/svc/<runId>/<port>/` — the path under Foreman's origin. */
+  /** `/svc/<runId>/<port>/` — the path under the services origin, not Foreman's. */
   path: string;
   since: number;
 }
@@ -100,3 +107,53 @@ export function proxyToService(
   });
   req.pipe(up);
 }
+
+/**
+ * The whole of the services port: the guard, the proxy, and nothing else.
+ *
+ * It is a function of its dependencies rather than a closure over the server's
+ * module scope so a test can start one on an ephemeral port with its own
+ * registry — importing server.ts would start listening for real. `allowed` is
+ * passed in for the same reason: the guard has to be told the port it is
+ * defending, which the test only learns after listen().
+ */
+export function servicesHandler(deps: {
+  registry: ServiceRegistry;
+  allowed: (req: http.IncomingMessage) => GuardVerdict;
+}): http.RequestListener {
+  const jsonErr = (res: http.ServerResponse, status: number, error: string) => {
+    const body = JSON.stringify({ error });
+    res.writeHead(status, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' });
+    res.end(body);
+  };
+  return (req, res) => {
+    // A DNS-rebound page must not reach the proxy either: it would be talking
+    // to the crew's dev server from an origin of the attacker's choosing.
+    const verdict = deps.allowed(req);
+    if (!verdict.ok) { jsonErr(res, verdict.status, verdict.error); return; }
+    const url = new URL(req.url ?? '/', `http://127.0.0.1`);
+    // Services the crew exposed: /svc/<run>/<port>/… goes to 127.0.0.1:<port>,
+    // but only for a pair a run declared. A page served this way asks for its
+    // absolute-path assets (`/app.js`) against this server's root; those arrive
+    // as sub-resource requests carrying the service page as Referer, and are
+    // routed to the same service. Documents never are — a typed URL is not.
+    const svc = parseServicePath(url.pathname);
+    if (svc) {
+      if (!deps.registry.has(svc.runId, svc.port)) { jsonErr(res, 404, 'no such service'); return; }
+      proxyToService(req, res, svc.port, svc.rest, url.search, servicePath(svc.runId, svc.port));
+      return;
+    }
+    const ref = req.headers.referer;
+    const dest = String(req.headers['sec-fetch-dest'] ?? '');
+    if (ref && dest && dest !== 'document' && dest !== 'empty' && !url.pathname.startsWith(SVC_PREFIX)) {
+      try {
+        const via = parseServicePath(new URL(ref).pathname);
+        if (via && deps.registry.has(via.runId, via.port)) {
+          proxyToService(req, res, via.port, url.pathname, url.search, servicePath(via.runId, via.port));
+          return;
+        }
+      } catch { /* not a URL we can read — fall through to the 404 */ }
+    }
+    jsonErr(res, 404, 'not found');
+  };
+}

package/src/store.test.ts

@@ -117,3 +117,21 @@ test('projects: concurrent adds do not lose writes', async () => {
   assert.equal((await store.listProjects()).length, 8);
   await rm(root, { recursive: true, force: true });
 });
+
+test('archiveChat retires a conversation: gone from the project, kept on disk, and idempotent', async () => {
+  const { store, root } = await tmpStore();
+  await store.appendChat('p-abc', { ts: 1, event: 'chat_message', data: { text: 'hi' } });
+  await store.writeChatMeta({ projectId: 'p-abc', costUsd: 1, createdAt: 1, updatedAt: 1 });
+  assert.deepEqual(await store.listChatIds(), ['p-abc']);
+
+  await store.archiveChat('p-abc', '1700000000000-deadbeef');
+  assert.deepEqual(await store.listChatIds(), []);
+  assert.equal(await store.readChatMeta('p-abc'), null);
+  assert.deepEqual(await store.readChatEvents('p-abc'), []);
+  const archived = path.join(root, 'chats', '_archive', 'p-abc-1700000000000-deadbeef', 'events.jsonl');
+  assert.ok((await import('node:fs/promises')).readFile(archived, 'utf8'));
+
+  // Nothing to archive is not an error.
+  await store.archiveChat('p-abc', 'again');
+  await rm(root, { recursive: true, force: true });
+});

package/src/store.ts

@@ -19,7 +19,7 @@
  *    previous process: it appends a synthetic `run_finished` event and marks
  *    the run interrupted, so replaying a log always terminates cleanly.
  */
-import { appendFile, mkdir, readFile, readdir, rename, rm, writeFile } from 'node:fs/promises';
+import { appendFile, mkdir, readFile, readdir, rename, rm, stat, writeFile } from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 import crypto from 'node:crypto';
@@ -327,6 +327,21 @@ export class RunStore {
     await rm(this.chatDir(projectId), { recursive: true, force: true });
   }
 
+  /**
+   * Retires a conversation that produced a mission: the log moves under
+   * `chats/_archive/<project>-<run>/`, where `listChatIds` does not look, and
+   * the project starts its next visit with a blank page. Kept rather than
+   * deleted because it is the story of how that mission came to exist; the
+   * run itself is the continuation, and "Plan the next step" forks from it.
+   */
+  async archiveChat(projectId: string, runId: string): Promise<void> {
+    const from = this.chatDir(projectId);
+    if (!(await stat(from).catch(() => null))) return;
+    const archive = path.join(this.chatsDir, '_archive');
+    await mkdir(archive, { recursive: true });
+    await rename(from, path.join(archive, `${projectId}-${runId.replace(/[^A-Za-z0-9_-]/g, '')}`));
+  }
+
   /**
    * Marks runs left in status "running" by a dead process as interrupted,
    * appending a synthetic `run_finished` so replayed logs terminate cleanly.

package/src/track-record.test.ts

@@ -0,0 +1,46 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { budgetAnchor, modelRecords, projectRecord, recordLine } from './track-record.js';
+import type { RunMeta } from './types.js';
+
+const run = (o: Partial<RunMeta>): RunMeta => ({
+  id: 'r', folder: '/x', mission: 'm', budgetUsd: 5, status: 'done', costUsd: 1, createdAt: 0, endedAt: 10 * 60_000, workers: [], costBasis: 'priced', ...o,
+} as RunMeta);
+
+test('modelRecords: directors by outcome with median cost and minutes; workers by finish', () => {
+  const runs = [
+    run({ directorModel: 'sonnet', workerModel: 'gemma4:12b', costUsd: 0.78, endedAt: 18 * 60_000, workers: [{ id: 'w1', status: 'done', costUsd: 0, task: '' }, { id: 'w2', status: 'error', costUsd: 0, task: '' }] }),
+    run({ directorModel: 'sonnet', costUsd: 0.22, endedAt: 1 * 60_000 }),
+    run({ directorModel: 'sonnet', status: 'interrupted', costUsd: 4.96 }),
+    run({ directorModel: 'ornith-1.5:9b', workerModel: 'ornith-1.5:9b', status: 'interrupted', costBasis: 'free', costUsd: 0, workers: [{ id: 'w1', status: 'done', costUsd: 0, task: '' }, { id: 'w2', status: 'done', costUsd: 0, task: '' }, { id: 'w3', status: 'error', costUsd: 0, task: '' }] }),
+    run({ directorModel: 'opus', status: 'running' }),
+  ] as RunMeta[];
+  const m = modelRecords(runs);
+  const sonnet = m.get('sonnet')!;
+  assert.equal(sonnet.runs, 3); assert.equal(sonnet.done, 2); assert.equal(sonnet.interrupted, 1);
+  assert.equal(sonnet.medianCostUsd, 0.5); assert.equal(sonnet.medianMinutes, 10);
+  assert.equal(m.get('gemma4:12b')!.workers, 2); assert.equal(m.get('gemma4:12b')!.workersDone, 1);
+  const ornith = m.get('ornith-1.5:9b')!;
+  assert.equal(ornith.runs, 1); assert.equal(ornith.done, 0); assert.equal(ornith.workers, 3); assert.equal(ornith.workersFailed, 1);
+  assert.equal(ornith.medianCostUsd, undefined);
+  assert.equal(m.has('opus'), false, 'a running run is not a record yet');
+});
+
+test('recordLine says it in one line, or nothing', () => {
+  const m = modelRecords([run({ directorModel: 'sonnet', workerModel: 'gemma4:12b', costUsd: 0.78, endedAt: 18 * 60_000, workers: [{ id: 'w1', status: 'done', costUsd: 0, task: '' }, { id: 'w2', status: 'error', costUsd: 0, task: '' }] })] as RunMeta[]);
+  assert.equal(recordLine(m.get('sonnet')), 'here: director 1/1 done (~$0.78, ~18 min)');
+  assert.equal(recordLine(m.get('gemma4:12b')), 'here: workers 1/2 finished');
+  assert.equal(recordLine(undefined), undefined);
+});
+
+test('projectRecord and budgetAnchor: quartiles, cap hits, and silence when there is too little', () => {
+  const few = projectRecord([run({ costUsd: 2 })]);
+  assert.equal(budgetAnchor(few, few, 'P'), '');
+  const runs = [1, 2, 3, 4, 4.9].map((c) => run({ costUsd: c, budgetUsd: 5 }));
+  const p = projectRecord(runs);
+  assert.equal(p.done, 5); assert.equal(p.medianCostUsd, 3); assert.equal(p.costLowUsd, 2); assert.equal(p.costHighUsd, 4); assert.equal(p.capHits, 1);
+  const a = budgetAnchor(p, projectRecord([...runs, run({ costUsd: 10, budgetUsd: 20 })]), 'Tick');
+  assert.match(a, /In "Tick", finished missions cost \$2\.0–\$4\.0 \(median \$3\.0\), ~10 min, over 5 finished missions; 1 ended within 5% of the cap\./);
+  assert.match(a, /Across the fleet: /);
+  assert.match(a, /anchor above it, not on it/);
+});

package/src/track-record.ts

@@ -0,0 +1,149 @@
+/**
+ * What the run ledger says, read back: how models have done here, and what
+ * missions in a project have cost. Foreman already keeps every run's model,
+ * outcome, spend and crew; nobody was reading it. This is the safe kind of
+ * learning — statistics, deterministic and explainable — and it feeds three
+ * places without any agent writing anything: the planner's budget anchor,
+ * the model picker's second line, and the front desk's reports.
+ */
+import type { RunMeta } from './types.js';
+
+/** A model's record in one role. */
+export interface ModelRecord {
+  model: string;
+  /** As director: runs and how they ended. */
+  runs: number;
+  done: number;
+  interrupted: number;
+  error: number;
+  /** Median priced spend of done runs; undefined when nothing was priced. */
+  medianCostUsd?: number;
+  /** Median wall clock of done runs, in minutes. */
+  medianMinutes?: number;
+  /** As worker: workers spawned on it and how they ended. */
+  workers: number;
+  workersDone: number;
+  workersFailed: number;
+}
+
+/** A project's record. */
+export interface ProjectRecord {
+  runs: number;
+  done: number;
+  /** Priced spend of done runs, low and high (interquartile-ish: 25th and 75th). */
+  costLowUsd?: number;
+  costHighUsd?: number;
+  medianCostUsd?: number;
+  medianMinutes?: number;
+  /** Done runs that ended within 5% of their cap. */
+  capHits: number;
+}
+
+const median = (xs: number[]): number | undefined => {
+  if (!xs.length) return undefined;
+  const s = [...xs].sort((a, b) => a - b);
+  const m = Math.floor(s.length / 2);
+  return s.length % 2 ? s[m] : (s[m - 1] + s[m]) / 2;
+};
+const quantile = (xs: number[], q: number): number | undefined => {
+  if (!xs.length) return undefined;
+  const s = [...xs].sort((a, b) => a - b);
+  return s[Math.min(s.length - 1, Math.max(0, Math.round((s.length - 1) * q)))];
+};
+const finished = (r: RunMeta) => r.status !== 'running';
+const priced = (r: RunMeta) => r.costBasis === 'priced' || (r.costBasis === undefined && r.metered !== false);
+const minutes = (r: RunMeta) => (typeof r.endedAt === 'number' && typeof r.createdAt === 'number' ? (r.endedAt - r.createdAt) / 60_000 : undefined);
+
+/** Every model's record across the runs given, keyed by model id. */
+export function modelRecords(runs: RunMeta[]): Map<string, ModelRecord> {
+  const out = new Map<string, ModelRecord>();
+  const get = (model: string) => {
+    let r = out.get(model);
+    if (!r) { r = { model, runs: 0, done: 0, interrupted: 0, error: 0, workers: 0, workersDone: 0, workersFailed: 0 }; out.set(model, r); }
+    return r;
+  };
+  const costs = new Map<string, number[]>();
+  const mins = new Map<string, number[]>();
+  for (const run of runs) {
+    if (!finished(run)) continue;
+    const d = run.directorModel ? String(run.directorModel) : undefined;
+    if (d) {
+      const r = get(d);
+      r.runs += 1;
+      if (run.status === 'done') {
+        r.done += 1;
+        if (priced(run)) costs.set(d, [...(costs.get(d) ?? []), run.costUsd]);
+        const m = minutes(run);
+        if (m !== undefined) mins.set(d, [...(mins.get(d) ?? []), m]);
+      } else if (run.status === 'interrupted') r.interrupted += 1;
+      else if (run.status === 'error') r.error += 1;
+    }
+    const w = run.workerModel ? String(run.workerModel) : undefined;
+    if (w) {
+      const r = get(w);
+      for (const wk of run.workers ?? []) {
+        if (wk.status === 'running') continue;
+        r.workers += 1;
+        if (wk.status === 'done' && !wk.isError) r.workersDone += 1; else r.workersFailed += 1;
+      }
+    }
+  }
+  for (const [model, r] of out) {
+    r.medianCostUsd = median(costs.get(model) ?? []);
+    const mm = median(mins.get(model) ?? []);
+    r.medianMinutes = mm === undefined ? undefined : Math.round(mm);
+  }
+  return out;
+}
+
+/** One project's record from its runs. */
+export function projectRecord(runs: RunMeta[]): ProjectRecord {
+  const fin = runs.filter(finished);
+  const done = fin.filter((r) => r.status === 'done');
+  const costs = done.filter(priced).map((r) => r.costUsd);
+  const mins = done.map(minutes).filter((m): m is number => m !== undefined);
+  const mm = median(mins);
+  return {
+    runs: fin.length, done: done.length,
+    costLowUsd: quantile(costs, 0.25), costHighUsd: quantile(costs, 0.75), medianCostUsd: median(costs),
+    medianMinutes: mm === undefined ? undefined : Math.round(mm),
+    capHits: done.filter((r) => priced(r) && r.budgetUsd > 0 && r.costUsd >= r.budgetUsd * 0.95).length,
+  };
+}
+
+const usd = (n: number) => `$${n < 1 ? n.toFixed(2) : n.toFixed(n < 10 ? 1 : 0)}`;
+
+/** The picker's second line for a model, or undefined when there is nothing to say yet. */
+export function recordLine(r: ModelRecord | undefined): string | undefined {
+  if (!r || (r.runs === 0 && r.workers === 0)) return undefined;
+  const bits: string[] = [];
+  if (r.runs > 0) {
+    let s = `director ${r.done}/${r.runs} done`;
+    const extras = [r.medianCostUsd !== undefined ? `~${usd(r.medianCostUsd)}` : null, r.medianMinutes !== undefined ? `~${r.medianMinutes} min` : null].filter(Boolean);
+    if (extras.length) s += ` (${extras.join(', ')})`;
+    bits.push(s);
+  }
+  if (r.workers > 0) bits.push(`workers ${r.workersDone}/${r.workers} finished`);
+  return `here: ${bits.join(' · ')}`;
+}
+
+/**
+ * The planner's budget anchor from history, replacing the generic ladder
+ * when a project (or the fleet) has enough finished missions to say
+ * something. Returns '' when there is nothing worth anchoring on.
+ */
+export function budgetAnchor(project: ProjectRecord, fleet: ProjectRecord, projectName?: string): string {
+  const lines: string[] = [];
+  const fmt = (p: ProjectRecord) => {
+    if (p.medianCostUsd === undefined) return null;
+    const range = p.costLowUsd !== undefined && p.costHighUsd !== undefined && p.costHighUsd > p.costLowUsd
+      ? `${usd(p.costLowUsd)}–${usd(p.costHighUsd)} (median ${usd(p.medianCostUsd)})` : `about ${usd(p.medianCostUsd)}`;
+    return `${range}${p.medianMinutes !== undefined ? `, ~${p.medianMinutes} min` : ''}, over ${p.done} finished mission${p.done === 1 ? '' : 's'}${p.capHits ? `; ${p.capHits} ended within 5% of the cap` : ''}`;
+  };
+  const pj = project.done >= 2 ? fmt(project) : null;
+  const fl = fleet.done >= 3 ? fmt(fleet) : null;
+  if (pj) lines.push(`In ${projectName ? `"${projectName}"` : 'this project'}, finished missions cost ${pj}.`);
+  if (fl && (!pj || fleet.done > project.done)) lines.push(`Across the fleet: ${fl}.`);
+  if (!lines.length) return '';
+  return `\nWHAT MISSIONS HAVE COST (from Foreman's own records — use these to anchor the budget before the generic ladder):\n  ${lines.join('\n  ')}\n  A cap that was hit is a mission that ran out, not one that fit; anchor above it, not on it.\n`;
+}

package/src/types.ts

@@ -298,6 +298,12 @@ export interface RunMeta {
   claudeInstance?: ClaudeInstanceRef;
   /** Number of times this run was resumed after an interruption. */
   resumes?: number;
+  /**
+   * The branch this mission runs on, when the folder is a repository and the
+   * project runs missions on branches of their own. Foreman made it from
+   * `base` at start and commits on it at the end; it never merges or pushes.
+   */
+  git?: { branch: string; base: string; baseHead: string | null; commits?: number; commit?: string; /** The pull request the human opened from this run, once they did. */ pr?: string; /** Its fate, once known to be final (merged or closed); open is re-asked. */ prState?: 'merged' | 'closed' };
   /** Tools the human granted "always allow" for this run (survives resume). */
   allowedTools?: string[];
   /**
@@ -319,6 +325,12 @@ export interface RunMeta {
   askTimeoutMs?: number;
   /** Give agents a headless Playwright browser (navigate, click, screenshot). */
   browserTools?: boolean;
+  /**
+   * Which cap ended the last attempt, when one did. The dashboard reads it
+   * to offer the one action that helps — raise the budget and resume — and
+   * a resume clears it. Absent when the run ended for any other reason.
+   */
+  stopReason?: 'budget' | 'turns' | 'time' | 'tokens';
   folder: string;
   mission: string;
   budgetUsd: number;
@@ -339,6 +351,17 @@ export interface RunMeta {
   maxTurns?: number;
   /** Wall-clock cap. Matters most exactly where dollars matter least. */
   maxSeconds?: number;
+  /**
+   * Total tokens — input, output and cache alike — before the run winds down.
+   *
+   * The third bound, and the one that was missing: a run that costs nothing
+   * per token, or that Foreman cannot price, has only turns and the clock to
+   * stop it. Neither notices a chatty director whose turns are cheap and
+   * enormous, re-reading a large context a hundred and fifty times inside the
+   * time cap. Tokens are the resource actually being consumed there, so they
+   * are what the cap should count.
+   */
+  maxTokens?: number;
   /**
    * How long a worker may produce nothing before it is treated as stalled and
    * stopped. Absent means the orchestrator's default. Raise it for slow local