@guenbankhai/tools 0.0.0-stage → 0.1.0

package/agentmoni/lib/present.js

@@ -0,0 +1,184 @@
+// Presenter: collected state -> a plain JSON view model. The single source for the terminal and the web (no formatting, no UI).
+const { summarize, byDay, recordsOf, billingView } = require('./cost.js');
+const { repoKey, repoRoot } = require('./repokey.js');
+
+const windowsOf = (registry, id) => registry.find(a => a.id === id)?.windows ?? [];
+const agents = require('./agents/index.js');
+const LOW_LEFT = 15;   // account window with less than 15% left needs attention
+const RECENT_MAX = 50;
+const HISTORY_MAX = 300;
+const key = s => `${s.provider}:${s.id}`;
+
+// Share windows keep null parts when nothing was spent; show them as 0, except unsupported cache-write tokens (stay null).
+function shareOf(s, registry) {
+  if (s.billing === 'api') return {};
+  const out = {};
+  for (const { id: w } of windowsOf(registry, s.provider)) {
+    const x = s.share?.[w];
+    out[w] = x == null ? null : { total: x.total, input: x.input ?? 0, cacheRead: x.cacheRead ?? 0, cacheWrite: registry.find(a => a.id === s.provider)?.cacheWrite === false ? null : (x.cacheWrite ?? 0), output: x.output ?? 0 };
+  }
+  return out;
+}
+
+function quotaOf(account, now, declarations) {
+  const windows = {};
+  for (const { id: w, label } of declarations) {
+    const r = account?.windows?.[w];
+    const reset = !!r?.reset || (r?.resetsAt != null && r.resetsAt <= now);
+    const percent = reset ? null : r?.percent ?? null;
+    windows[w] = { label, percent, reset, source: r?.source ?? null, stale: !r || percent == null, resetInMs: r?.resetsAt > now ? r.resetsAt - now : null, readAt: r?.readAt ?? r?.at ?? null, low: percent != null && 100 - percent < LOW_LEFT };
+  }
+  return { windows, error: account?.error ?? null };
+}
+
+// A provider is shown only when it has a session, live or in history.
+const providersOf = (state, registry = agents) => registry.map(a => a.id).filter(p => [...state.sessions, ...(state.history ?? [])].some(s => s.provider === p));
+
+// All members count when their root is live, including ended workers.
+function quotaProvidersOf(state, registry = agents) {
+  const named = new Map([...(state.history ?? []), ...state.sessions].map(s => [key(s), s]));
+  const providers = new Set();
+  for (const s of named.values()) {
+    let root = s;
+    const seen = new Set([key(s)]);
+    while (named.has(root.parent) && !seen.has(root.parent)) {
+      seen.add(root.parent); root = named.get(root.parent);
+    }
+    if (root.state && root.state !== 'ended') providers.add(s.provider);
+  }
+  return registry.map(a => a.id).filter(p => providers.has(p));
+}
+
+// opts: { mode: 'quota'|'token', repo: repo key or null for all, now, catalog, limits: (provider, model) -> context limit or null }
+function present(state, { registry = agents, mode = 'quota', repo = null, now = Date.now(), catalog, limits, treeKey = null } = {}) {
+  catalog ??= require('./catalog.json');
+  const money = s => ({ ...billingView(s.billing), cost: summarize(recordsOf(s), catalog), costByDay: byDay(recordsOf(s), catalog) });
+  const named = new Map([...state.history, ...state.sessions].map(s => [key(s), s]));
+  // Resolve against the full history, before the web's 300-session limit hides ancestors.
+  const rootSession = s => {
+    const seen = new Set([key(s)]);
+    while (named.has(s.parent) && !seen.has(s.parent)) {
+      seen.add(s.parent); s = named.get(s.parent);
+    }
+    return s;
+  };
+  // Linked descendants belong in their leader's project even when they work in another cwd.
+  const inScope = s => {
+    if (repo == null) return true;
+    const seen = new Set();
+    for (let a = s; a && !seen.has(key(a)); a = named.get(a.parent)) {
+      if ((a.repo ?? repoKey(a.cwd)) === repo) return true;
+      seen.add(key(a));
+    }
+    return false;
+  };
+  const all = [...state.sessions.filter(inScope), ...state.history.filter(inScope)];
+  const target = treeKey && named.get(treeKey);
+  const treeRoot = target && rootSession(target);
+  const live = treeKey ? [...named.values()].filter(s => key(rootSession(s)) === key(treeRoot)) : state.sessions.filter(s => s.state !== 'ended' && inScope(s));
+  const liveKeys = new Set(live.map(key));
+
+  const nodes = new Map(live.map(s => {
+    // A limit below the observed context is wrong (e.g. 200k vs a 1M session): treat it as unknown, never warn on it.
+    let limit = limits?.(s.provider, s.model) ?? null;
+    if (limit != null && s.context != null && s.context > limit) limit = null;
+    const ratio = limit && s.context != null ? s.context / limit : null;
+    return [key(s), {
+      ...money(s), key: key(s), provider: s.provider, id: s.id, billing: s.billing ?? 'unknown', model: s.model ?? null, effort: s.effort ?? null, kind: s.kind, agentType: s.agentType ?? null, state: s.state, name: s.name ?? null,
+      cwd: s.cwd ?? null, parent: s.parent ?? null, startedAt: s.startedAt, lastActivityAt: s.lastActivityAt, endedAt: s.state === 'ended' ? s.lastActivityAt : null, turn: s.turn ?? null, orphan: !!s.orphan, resume: s.resume ?? 0,
+      link: s.link ? { kind: s.link.kind, label: s.link.label, evidence: s.link.evidence ?? null } : null,
+      context: { tokens: s.context ?? null, limit, warn: ratio != null && ratio >= (catalog?.contextWarn ?? 0.8) },
+      ...(s.tokens ? { tokens: { ...s.tokens } } : {}), share: shareOf(s, registry), runs: s.runs ?? [], done: 0, repo: s.repo ?? repoKey(s.cwd),
+      tree: null, children: [], _p: s.parent
+    }];
+  }));
+  for (const n of nodes.values()) {
+    const parent = n._p && liveKeys.has(n._p) ? nodes.get(n._p) : null;
+    if (parent) parent.children.push(n);
+  }
+  const sortedChildren = n => { n.children.sort((a, b) => a.startedAt - b.startedAt); n.children.forEach(sortedChildren); };
+
+  // Parent totals: the node plus all descendants of the same provider (separate accounts are never added), each once.
+  // Shares come from the collector's shareTree, which also covers ended children.
+  const treeSessions = [...named.values()];
+  const full = new Map(treeSessions.map(s => [key(s), s]));
+  const kids = new Map();
+  for (const s of treeSessions) if (s.parent) kids.set(s.parent, [...(kids.get(s.parent) ?? []), s]);
+  for (const n of nodes.values()) {
+    if (!kids.has(n.key)) continue;
+    const t = { input: 0, cacheRead: 0, cacheWrite: registry.find(a => a.id === n.provider)?.cacheWrite === false ? null : 0, output: 0 };
+    // Same walk as the collector's shareTree: every child session, ended ones too, each once.
+    const costRecords = [];
+    const seen = new Set(), walk = c => {
+      costRecords.push(...recordsOf(c));
+      seen.add(key(c));
+      if (c.provider === n.provider) for (const k of Object.keys(t)) if (t[k] != null && c.tokens?.[k] != null) t[k] += c.tokens[k];
+      for (const k of kids.get(key(c)) ?? []) if (!seen.has(key(k))) walk(k);
+    };
+    walk(full.get(n.key) ?? n);
+    const tree = full.get(n.key)?.shareTree?.[n.provider] ?? {};
+    n.tree = { cost: summarize(costRecords, catalog), costByDay: byDay(costRecords, catalog), ...(n.tokens ? { tokens: t } : {}), share: Object.fromEntries(windowsOf(registry, n.provider).map(({ id: w }) => [w, tree[w]?.total ?? null])) };
+  }
+
+  // A repo group is its roots' repo and counts the whole tree under each root, so a group never has a count without rows.
+  const byRepo = new Map();
+  const count = n => n.children.reduce((s, c) => s + count(c), 1);
+  const newest = n => Math.max(n.lastActivityAt, ...n.children.map(newest));
+  for (const n of nodes.values()) {
+    if (n._p && liveKeys.has(n._p)) continue;
+    if (!byRepo.has(n.repo)) byRepo.set(n.repo, { key: n.repo, name: n.repo.replace(/-[0-9a-f]{4}$/, ''), root: repoRoot(n.cwd), roots: [], active: 0, lastAt: 0 });
+    const r = byRepo.get(n.repo);
+    r.active += count(n); r.lastAt = Math.max(r.lastAt, newest(n));
+    r.roots.push(n);
+  }
+  const repos = [...byRepo.values()].sort((a, b) => b.lastAt - a.lastAt);
+  for (const r of repos) { r.roots.sort((a, b) => b.lastActivityAt - a.lastActivityAt); r.roots.forEach(sortedChildren); }
+
+  const quotaProviders = treeKey ? registry.map(a => a.id).filter(p => live.some(s => s.provider === p)) : quotaProvidersOf(state, registry);
+  const quota = Object.fromEntries(registry.map(a => [a.id, quotaOf(state.accounts[a.id], now, quotaProviders.includes(a.id) ? (all.some(s => s.provider === a.id && s.billing !== 'api') || state.accounts[a.id]?.billing === 'subscription') ? a.windows ?? [] : [] : [])]));
+  const attention = [];
+  for (const n of nodes.values()) {
+    if (n.orphan) attention.push({ type: 'orphan', key: n.key, repo: n.repo, provider: n.provider, model: n.model });
+    if (n.context.warn) attention.push({ type: 'context', key: n.key, repo: n.repo, provider: n.provider, model: n.model, tokens: n.context.tokens, limit: n.context.limit });
+  }
+  for (const p of quotaProviders) for (const w of Object.keys(quota[p].windows)) if (quota[p].windows[w].low) attention.push({ type: 'quota', provider: p, window: w, percent: quota[p].windows[w].percent });
+
+  const ended = all.filter(s => s.state === 'ended' && !liveKeys.has(key(s))).sort((a, b) => b.lastActivityAt - a.lastActivityAt);
+  const recent = { total: ended.length, items: ended.slice(0, RECENT_MAX).map(s => ({ key: key(s), provider: s.provider, model: s.model ?? null, kind: s.kind, turn: s.turn ?? null, label: s.kind === 'sub' ? (s.agentType ?? s.name ?? null) : null, endedAt: s.lastActivityAt })) };
+
+  // History for the web: every ended session in scope, with what the table and the detail drawer show.
+  const history = ended.slice(0, HISTORY_MAX).map(s => ({
+    ...money(s), key: key(s), provider: s.provider, id: s.id, billing: s.billing ?? 'unknown', model: s.model ?? null, effort: s.effort ?? null, kind: s.kind, turn: s.turn ?? null, agentType: s.agentType ?? null, name: s.name ?? null,
+    cwd: s.cwd ?? null, repo: s.repo ?? repoKey(s.cwd), rootRepo: rootSession(s).repo ?? repoKey(rootSession(s).cwd), rootPath: repoRoot(rootSession(s).cwd), parent: s.parent ?? null, startedAt: s.startedAt, endedAt: s.lastActivityAt, resume: s.resume ?? 0,
+    link: s.link ? { kind: s.link.kind, label: s.link.label, evidence: s.link.evidence ?? null } : null, ...(s.tokens ? { tokens: { ...s.tokens } } : {}), share: shareOf(s, registry), runs: s.runs ?? []
+  }));
+  // Count each visible History row for every live ancestor, matching the subtree filter.
+  for (const s of history) {
+    const seen = new Set([s.key]);
+    for (let p = s.parent; p && !seen.has(p); p = named.get(p)?.parent) {
+      seen.add(p);
+      if (nodes.has(p)) nodes.get(p).done++;
+    }
+  }
+
+  // Links the data could not decide, as short descriptions of the sessions involved (only those in scope).
+  const who = k => { const s = named.get(k); return { key: k, label: s ? `${s.provider} ${s.model ?? '?'}${s.name ? ' \u00b7 ' + s.name : ''}` : k }; };
+  const ambiguous = (state.ambiguous ?? []).filter(a => a.sessions.some(k => named.has(k) && inScope(named.get(k)))).map(a => ({ sessions: a.sessions.map(who), parents: a.parents.map(who) }));
+  if (ambiguous.length) attention.push({ type: 'links', count: ambiguous.length });
+
+  const strip = n => { delete n._p; n.children.forEach(strip); };
+  repos.forEach(r => r.roots.forEach(strip));
+  const costRecords = (treeKey ? live : all).flatMap(recordsOf);
+  const result = { cost: summarize(costRecords, catalog), costByDay: byDay(costRecords, catalog), mode, repo, now, providers: providersOf(state, registry), quotaProviders, quota, outside: Object.fromEntries(quotaProviders.map(p => [p, state.outside?.[p]])), repos, attention, recent, history, ambiguous, warnings: state.warnings ?? [] };
+  return result;
+}
+
+// The whole tree containing `key`, or null when the key is unknown or no root is found.
+function treeOf(state, k, opts) {
+  if (![...state.history, ...state.sessions].some(s => key(s) === k)) return null;
+  const view = present(state, { ...opts, treeKey: k });
+  const root = view.repos[0]?.roots[0];
+  return root ? { key: k, root, cost: view.cost, costByDay: view.costByDay, quota: Object.fromEntries(view.quotaProviders.map(p => [p, view.quota[p]])) } : null;
+}
+
+module.exports = { present, providersOf, quotaProvidersOf, treeOf };

package/agentmoni/lib/procs.js

@@ -0,0 +1,22 @@
+// Process sources (Windows). Both readers take their input as a parameter so tests can inject sample data.
+const agents = require('./agents/index.js');
+const { execFileSync } = require('node:child_process');
+
+// Keep the whole process tree, but capture command lines only for registered agent executables.
+const script = registry => `Get-CimInstance Win32_Process |
+  Select-Object ProcessId, ParentProcessId, Name, @{n='CommandLine';e={ if ($_.Name -in ${registry.flatMap(a => a.processNames).map(n => `'${n.replace(/'/g, "''")}'`).join(',')}) { $_.CommandLine } }}, @{n='Start';e={$_.CreationDate.ToUniversalTime().ToString('o')}} |
+  ConvertTo-Json -Compress`;
+
+// -> [{ pid, ppid, name, cmd, startMs }]; [] when the table cannot be read (the caller then sees every process as gone).
+function listProcesses(registry = agents) {
+  let out;
+  try { out = execFileSync('powershell', ['-NoProfile', '-NonInteractive', '-Command', script(registry)], { encoding: 'utf8', timeout: 15000, windowsHide: true }); }
+  catch { return []; }
+  if (!out.trim()) return [];
+  let rows;
+  try { rows = JSON.parse(out); } catch { return []; }
+  return [].concat(rows).map(r => ({ pid: r.ProcessId, ppid: r.ParentProcessId, name: String(r.Name ?? '').toLowerCase(),
+    cmd: r.CommandLine ?? '', startMs: Date.parse(r.Start) })).filter(p => Number.isSafeInteger(p.pid));
+}
+
+module.exports = { listProcesses };

package/agentmoni/lib/quota.js

@@ -0,0 +1,34 @@
+// Account sources are supplied by the agent registry.
+const agents = require('./agents/index.js');
+function orderedSources(sources) {
+  return {
+    async refresh(now, sessions) {
+      for (const q of sources) {
+        await q.refresh?.(now);
+        if (q.read(sessions, now)?.windows?.length) break;
+      }
+    },
+    read(sessions, now) {
+      let result;
+      for (const q of sources) { result = q.read(sessions, now); if (result?.windows?.length) return result; }
+      return result;
+    }
+  };
+}
+function createQuota(options = {}, registry = agents) {
+  const sources = registry.map(a => [a, a.createQuota?.(options)]);
+  return {
+    refresh: (now, providers = [], sessions = []) => Promise.all(sources.filter(([a]) => providers.includes(a.id)).map(([, q]) => q?.refresh?.(now, sessions))),
+    read: (sessions, now) => Object.fromEntries(sources.map(([a, q]) => {
+      const quota = q?.read(sessions, now);
+      const windows = Object.fromEntries((quota?.windows ?? []).map(w => {
+        const reset = w.reset || (w.resetsAt != null && w.resetsAt <= now);
+        return [w.id, { percent: reset ? null : w.usedPercent, resetsAt: w.resetsAt,
+          at: w.readAt ?? quota.readAt, readAt: w.readAt ?? quota.readAt, source: w.source ?? quota.source,
+          reset: !!reset, ...(reset || w.usedPercent == null ? { stale: true } : {}) }];
+      }));
+      return [a.id, { provider: a.id, billing: a.readBilling?.(options) ?? 'unknown', ...(quota ? { quota } : {}), windows, error: quota?.error ?? null }];
+    }))
+  };
+}
+module.exports = { createQuota, orderedSources };

package/agentmoni/lib/repokey.js

@@ -0,0 +1,44 @@
+// Repo key of a cwd: the git root (a worktree maps to its main repo), else the cwd itself, as `<basename>-<4 hex of the path hash>`.
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+
+const norm = p => path.resolve(p).replace(/\//g, '\\').replace(/\\+$/, '').toLowerCase();
+
+function gitRoot(cwd) {
+  let dir = path.resolve(cwd);
+  for (;;) {
+    let st = null;
+    try { st = fs.statSync(path.join(dir, '.git')); } catch { /* no .git here */ }
+    if (st?.isDirectory()) return dir;
+    if (st?.isFile()) {
+      // A linked worktree has a `.git` file: "gitdir: <main>/.git/worktrees/<name>".
+      let gitdir = null;
+      try { gitdir = /^gitdir:\s*(.+)$/m.exec(fs.readFileSync(path.join(dir, '.git'), 'utf8'))?.[1].trim(); } catch { /* unreadable: treat as its own repo */ }
+      if (gitdir) {
+        const g = path.resolve(dir, gitdir);
+        if (path.basename(path.dirname(g)) === 'worktrees') return path.dirname(path.dirname(path.dirname(g)));
+      }
+      return dir;   // submodule or unreadable file
+    }
+    const up = path.dirname(dir);
+    if (up === dir) return null;
+    dir = up;
+  }
+}
+
+const cache = new Map();
+// shortcut: a worktree whose folder is already deleted has no .git to follow, so it keys as a plain folder.
+function repoInfo(cwd) {
+  if (typeof cwd !== 'string' || !cwd) return { key: '_unknown', root: null };
+  if (cache.has(cwd)) return cache.get(cwd);
+  const root = gitRoot(cwd) ?? path.resolve(cwd);
+  const base = (path.basename(root) || 'root').toLowerCase().replace(/[^\w.-]/g, '_');
+  const info = { key: `${base}-${crypto.createHash('sha1').update(norm(root)).digest('hex').slice(0, 4)}`, root };
+  cache.set(cwd, info);
+  return info;
+}
+const repoKey = cwd => repoInfo(cwd).key;
+const repoRoot = cwd => repoInfo(cwd).root;
+
+module.exports = { repoKey, repoRoot };

package/agentmoni/lib/share.js

@@ -0,0 +1,106 @@
+// A session's share of its account windows: token x catalog weight / window capacity (cost.js),
+// counting only usage inside the window. Shares are approximate (the catalog weights are fitted, not published).
+const { windowIds } = require('./catalog.js');
+const { cost } = require('./cost.js');
+
+const DAY_MS = 86400e3;
+const key = s => `${s.provider}:${s.id}`;
+const zero = types => Object.fromEntries([...types.map(t => [t, null]), ['total', 0]]);
+
+// Current window of the account reading: [reset - length, end]; with no live reading, the latest rolling span.
+function span(reading, len, now, end = now) {
+  // A reset inside the latest window length means the current window began at that reset.
+  const start = reading?.resetsAt > now ? reading.resetsAt - len : Math.max(now - len, reading?.resetsAt ?? 0);
+  return [start, end];
+}
+
+// -> { share: { windowId: token parts and total | null }, unpriced: [model ids] }
+// A null window means some usage in it has no price (unknown model), so no honest number exists.
+// shortcut: usage is priced per (model, UTC day) with the weights valid at noon of that day, not per turn.
+function sessionShare(catalog, s, spans) {
+  const share = {}, unpriced = new Set(), TOKEN_TYPES = catalog.tokenTypes;
+  for (const [w, [start, end]] of Object.entries(spans)) {
+    const buckets = new Map();
+    for (const e of s.usage ?? []) {
+      if (e.at < start || e.at > end) continue;
+      const model = e.model ?? s.model, k = `${model}|${Math.floor(e.at / DAY_MS)}`;
+      const b = buckets.get(k) ?? buckets.set(k, { model, at: Math.floor(e.at / DAY_MS) * DAY_MS + DAY_MS / 2, tokens: Object.fromEntries(TOKEN_TYPES.map(t => [t, t === 'cacheWrite' ? null : 0])) }).get(k);
+      for (const t of TOKEN_TYPES) if (e.tokens?.[t] != null) b.tokens[t] = (b.tokens[t] ?? 0) + e.tokens[t];
+    }
+    let sum = zero(TOKEN_TYPES), ok = true;
+    for (const b of buckets.values()) {
+      let c = null;
+      try { c = cost(catalog, b.model, b.tokens, b.at); } catch { /* model not in the catalog */ }
+      if (!c || c.units == null || !c.parts[w]) { ok = false; unpriced.add(b.model); continue; }
+      for (const t of TOKEN_TYPES) if (c.parts[w][t] != null) sum[t] = (sum[t] ?? 0) + c.parts[w][t];
+      sum.total += c.percent[w];
+    }
+    share[w] = ok ? sum : null;
+  }
+  return { share, unpriced: [...unpriced] };
+}
+
+function add(a, b, types) {
+  if (!a || !b) return null;
+  const out = {};
+  for (const t of [...types, 'total']) out[t] = a[t] == null && b[t] == null ? null : (a[t] ?? 0) + (b[t] ?? 0);
+  return out;
+}
+
+// -> { sessions (with share and shareTree), outside, warnings }
+//  shareTree[provider][window]: the session plus all its descendants of that provider; each session counts once.
+//  Different providers are different accounts, so their percentages are never added together.
+//  outside[provider][window]: the account's rise in the current window minus the sessions' sum up to the reading, never negative.
+function computeShares({ catalog, sessions, history = [], accounts, now = Date.now() }) {
+  const warnings = new Set();
+  const windowSpan = (p, w, reading, end = now) => span(reading, catalog.agents[p].windows.find(x => x.id === w).durationMs, now, end);
+  const byKey = new Map(), kids = new Map();
+  const out = sessions.map(s => {
+    const spans = Object.fromEntries(windowIds(catalog, s.provider).map(w => [w, windowSpan(s.provider, w, accounts[s.provider]?.windows?.[w])]));
+    const r = sessionShare(catalog, s, spans);
+    for (const m of r.unpriced) warnings.add(`model ${m} has no price in the catalog: its share is unknown`);
+    const o = { ...s, share: r.share };
+    byKey.set(key(o), o);
+    return o;
+  });
+  for (const s of out) if (s.parent && byKey.has(s.parent)) kids.set(s.parent, [...(kids.get(s.parent) ?? []), s]);
+
+  function tree(s, seen) {
+    const t = { [s.provider]: { ...s.share } };
+    seen.add(key(s));
+    for (const c of kids.get(key(s)) ?? []) {
+      if (seen.has(key(c))) continue;
+      for (const [p, ws] of Object.entries(tree(c, seen))) {
+        t[p] = t[p] ? Object.fromEntries(windowIds(catalog, p).map(w => [w, add(t[p][w], ws[w], catalog.tokenTypes)])) : ws;
+      }
+    }
+    return t;
+  }
+  for (const s of out) s.shareTree = tree(s, new Set());
+
+  const outside = {};
+  for (const p of Object.keys(accounts)) {
+    outside[p] = {};
+    for (const w of windowIds(catalog, p)) {
+      const reading = accounts[p]?.windows?.[w];
+      outside[p][w] = null;
+      if (!reading || reading.percent == null || !(reading.resetsAt > now) || !Number.isFinite(reading.at)) continue;
+      const end = Math.min(reading.at, now);
+      let sum = 0, known = true;
+      for (const s of sessions.filter(x => x.provider === p)) {
+        const sh = sessionShare(catalog, s, { [w]: windowSpan(p, w, reading, end) }).share[w];
+        if (!sh) { known = false; break; }
+        sum += sh.total;
+      }
+      // Sessions known only from their summaries count when saved inside this window (their share was for it).
+      for (const h of history.filter(x => x.provider === p)) {
+        const sh = h.share?.[w];
+        if (h.writtenAt >= windowSpan(p, w, reading, end)[0]) { if (sh) sum += sh.total; else known = false; }
+      }
+      if (known) outside[p][w] = Math.max(0, reading.percent - sum);
+    }
+  }
+  return { sessions: out, outside, warnings: [...warnings] };
+}
+
+module.exports = { computeShares, span };

package/agentmoni/lib/state.js

@@ -0,0 +1,62 @@
+// Session lifecycle tracking shared by all agents.
+const agents = require('./agents/index.js');
+const START_SLACK_MS = 60000;
+function claim(candidates, session, claimed, owners = new Map()) {
+  const mine = `${session.provider}:${session.id}`;
+  let best = null;
+  for (const p of candidates) {
+    if (claimed.has(p.pid) || (owners.has(p.pid) && owners.get(p.pid) !== mine)) continue;
+    const d = Math.abs(p.startMs - session.startedAt);
+    if (d <= START_SLACK_MS && (!best || d < best.d)) best = { p, d };
+  }
+  if (best) claimed.add(best.p.pid);
+  return best?.p ?? null;
+}
+
+// Remembers each session's runs between refreshes: a run is one process (pid) or one hosted stay in the app-server.
+// A new run on an ended session is a resume. In memory only; the log (step 5) persists it.
+function createTracker() {
+  const runs = new Map();
+  return {
+    // pid -> "provider:id" for every run still open.
+    owners() {
+      const m = new Map();
+      for (const [k, list] of runs) if (list.at(-1)?.end === null && list.at(-1).pid != null) m.set(list.at(-1).pid, k);
+      return m;
+    },
+    // Gives back runs saved by an earlier monitor (an open run continues if its process is still the one running).
+    restore(k, saved) {
+      if (runs.has(k) || !Array.isArray(saved)) return;
+      const ok = r => Number.isFinite(r?.start) && (r.end === null || Number.isFinite(r.end));
+      runs.set(k, saved.filter(ok).map(r => ({ key: r.pid ?? 'hosted', pid: r.pid ?? null, start: r.start, end: r.end })));
+    },
+    observe(session, { state, pid }, procs, now) {
+      const list = runs.get(`${session.provider}:${session.id}`) ?? [];
+      runs.set(`${session.provider}:${session.id}`, list);
+      const open = list.at(-1)?.end === null ? list.at(-1) : null;
+      const want = state === 'ended' ? null : pid ?? 'hosted';
+      if (open && open.key !== want) open.end = now;
+      if (want != null && open?.key !== want) {
+        const proc = pid == null ? null : procs.find(p => p.pid === pid);
+        list.push({ key: want, pid, start: proc?.startMs ?? now, end: null });
+      }
+      return list.map(({ pid, start, end }) => ({ pid, start, end }));
+    }
+  };
+}
+
+// -> sessions with state, pid, runs, resume (number of times it came back) and orphan.
+function resolveStates({ sessions, procs, pidFiles, now = Date.now(), tracker = createTracker(), registry = agents }) {
+  const live = new Map(registry.flatMap(a => [...a.liveness({ sessions: sessions.filter(s => s.provider === a.id), procs, pidFiles, now, owners: tracker.owners(), claim })]));
+  const result = sessions.map(s => {
+    const l = live.get(`${s.provider}:${s.id}`);
+    const runs = tracker.observe(s, l, procs, now);
+    return { ...s, state: l.state, pid: l.pid, runs, resume: Math.max(0, runs.length - 1) };
+  });
+  const byKey = new Map(result.map(s => [`${s.provider}:${s.id}`, s]));
+  // A child still alive under an ended parent is an orphan (it keeps working with nobody waiting for it).
+  for (const s of result) s.orphan = s.state !== 'ended' && byKey.get(`${s.provider}:${s.parentId}`)?.state === 'ended';
+  return result;
+}
+
+module.exports = { resolveStates, createTracker };

package/agentmoni/lib/terminal.js

@@ -0,0 +1,143 @@
+// Terminal renderer: view model (present.js) -> text frame, per the Terminal section of docs/design.md.
+const { pct, tok, ctx, dur, hhmm, rise } = require('./format.js');
+const { ansi, partAnsi } = require('./colors.js');
+
+const C = { green: 32, yellow: 33, red: 31, dim: 90, bold: 1 };
+const NAMES = require('./colors.js').NAMES;
+const SYMBOL = { running: ['\u25cf', C.green], waiting: ['\u25d0', C.yellow] };
+const PARTS = [['I', 'input', 'i'], ['CR', 'cacheRead', 'cr'], ['CW', 'cacheWrite', 'cw'], ['O', 'output', 'o']];
+
+// Transcript text must not inject escape codes.
+const clean = v => String(v ?? '').replace(/[\u0000-\u001f\u007f-\u009f\u202a-\u202e\u2066-\u2069]/g, ' ');
+const short = m => m ? require('./colors.js').short(clean(m)) : '?';
+const color = (text, code, on) => on && code ? `\x1b[${code}m${text}\x1b[0m` : text;
+// Widths and cuts count visible code points (all frame characters are single-width); escape codes are skipped.
+// A cut keeps the colours before it and closes them with a reset.
+const ANSI = /\x1b\[[\d;]*m/g;
+const vlen = text => [...text.replace(ANSI, '')].length;
+function cut(text, cols) {
+  if (vlen(text) <= cols) return text;
+  let seen = 0, out = '';
+  for (const part of text.split(/(\x1b\[[\d;]*m)/)) {   // odd parts are escape codes
+    if (part.startsWith('\x1b')) { out += part; continue; }
+    const room = Math.max(0, cols - 1 - seen), cps = [...part];
+    out += cps.slice(0, room).join(''); seen += Math.min(room, cps.length);
+    if (cps.length > room) break;
+  }
+  return out + '\u2026' + (out.includes('\x1b') ? '\x1b[0m' : '');
+}
+const right = (left, tail, cols) => { const gap = cols - vlen(left) - vlen(tail); return gap >= 2 ? left + ' '.repeat(gap) + tail : left + '  ' + tail; };
+
+function bar(percent, on) {
+  const filled = percent == null ? 0 : Math.max(0, Math.min(10, Math.round(percent / 10)));
+  const code = percent == null ? C.dim : percent >= 85 ? C.red : percent >= 60 ? C.yellow : C.green;
+  return '[' + color('\u2501'.repeat(filled), code, on) + color('\u2500'.repeat(10 - filled), C.dim, on) + ']';
+}
+
+function quotaLines(view, on) {
+  const lines = [];
+  const providers = (view.quotaProviders ?? Object.keys(view.quota)).filter(p => Object.keys(view.quota[p].windows).length);
+  if (!providers.length) return lines;
+  providers.forEach((p, i) => {
+    const cells = Object.keys(view.quota[p].windows).map(w => {
+      const x = view.quota[p].windows[w];
+      return `${x.label ?? w} ${bar(x.percent, on)} ${x.percent == null ? '\u2014' : pct(x.percent) + '%'}${x.reset ? ' reset since read' : ''}${x.source ? ` (${x.source}, ${x.readAt == null ? '?' : dur(Math.max(0, view.now - x.readAt))})` : ''}${x.low ? ' \u26a0' : ''}${x.resetInMs != null ? ' reset ' + dur(x.resetInMs) : ''}`;
+    });
+    lines.push(`${i ? '     ' : 'QUOTA'}  ${color(NAMES[p] ?? p, ansi('provider', p), on)}${' '.repeat(Math.max(0, 6 - (NAMES[p] ?? p).length))} ${cells.join('   ')}`);
+  });
+  lines.push('       outside monitor: ' + providers.map(p => `${color(NAMES[p] ?? p, ansi('provider', p), on)} ${Object.keys(view.quota[p].windows).slice(0, 1).map(w => `${view.quota[p].windows[w].label ?? w} ${rise(view.outside?.[p]?.[w])}%`).join(' ')}`).join('  '));
+  return lines;
+}
+
+// Token lines are built plain (to measure and cut) and coloured like the web: label and value in the I/CR/CW/O legend
+// colour, window names dim, totals bold. Padding sits outside the colour so a trimmed line has no stray spaces.
+const cell = (label, v, key, on) => color(`${label} ${v}`, partAnsi(key), on) + ' '.repeat(Math.max(0, 3 - String(v).length));
+const total = (w, v, on) => color(w, C.dim, on) + '\u2248' + color(v == null ? '\u2014' : pct(v) + '%', C.bold, on);
+const shareText = (s, w, on) => s ? `${total(w, s.total, on)} [${PARTS.map(([l, k, c]) => cell(l, pct(s[k]), c, on)).join(' ').trimEnd()}]` : `${total(w, null, on)}`;
+const tokenText = (t, on) => t ? PARTS.map(([l, k, c]) => cell(l, tok(t[k]), c, on)).join(' ').trimEnd() : '';
+const moneyText = n => n.cost ? `${n.costKind === 'api' ? 'API' : 'API equivalent'} ${n.cost.costUSD == null ? '?' : '$' + n.cost.costUSD.toFixed(4)} (${n.cost.sources.join('+')})${n.cost.unknownRecords ? ` + ${n.cost.unknownRecords} unknown records/${n.cost.unknownModels.length} models` : ''}${n.cost.uncertainRecords ? ' (uncertain)' : ''}` : '';
+const quotaDetail = (n, mode, on) => mode === 'token' ? tokenText(n.tokens, on) : Object.keys(n.share).map(w => shareText(n.share[w], w, on)).join('   ');
+const detail = (n, mode, on) => [moneyText(n), n.showQuota === false && mode !== 'token' ? '' : quotaDetail(n, mode, on).trimEnd()].filter(Boolean).join('   ');
+const groupText = (n, mode, on) => mode === 'token' ? tokenText(n.tree.tokens, on) : Object.keys(n.tree.share).map(w => total(w, n.tree.share[w], on)).join('   ');
+const fit = (prefix, make, cols, on) => cut(prefix + make(on), cols);
+
+// One session = 2 lines (3 for a parent: group total). A block is droppable when waiting with nothing running below it.
+function nodeBlocks(n, view, cols, on, depth, last, trail, out) {
+  const [sym, code] = SYMBOL[n.state] ?? ['?', 0];
+  const branch = depth ? trail + (last ? ' \u2514 ' : ' \u251c ') : '';
+  const pad = depth ? trail + (last ? '   ' : ' \u2502 ') : '';
+  const age = n.state === 'waiting' ? `waiting ${dur(view.now - n.lastActivityAt)}` : dur(view.now - n.startedAt);
+  const head = `${n.provider} ${short(n.model)}${n.effort ? ' ' + clean(n.effort) : ''} \u00b7 ${n.kind} \u00b7 ${age}${n.orphan ? ' \u00b7 orphan' : ''}${n.resume ? ` \u00b7 resume ${n.resume}` : ''}`;
+  const c = n.context, limit = '/' + ctx(c.limit);
+  const tail = `ctx ${ctx(c.tokens)}${c.limit ? limit : '/\u2014'}`;
+  const title = n.name ? ` \u00b7 ${clean(n.name)}` : '';
+  const first = right(cut(branch + sym + ' ' + head + title, Math.max(10, cols - [...tail].length - 2)), tail, cols);
+  // Provider, model (by tier) and effort carry their colours; the ctx tail is dim, red past the warning mark.
+  const effort = n.effort ? ' ' + clean(n.effort) : '';
+  const who = `${n.provider} ${short(n.model)}${effort}`;
+  const paint = () => `${color(n.provider, ansi('provider', n.provider), on)} ${color(short(n.model), ansi('model', n.model), on)}${effort && ' ' + color(effort.slice(1), ansi('effort', n.effort, n.provider), on)}`;
+  const body = first.slice(0, first.length - tail.length) + color(tail, c.warn ? C.red : C.dim, on);
+  const lines = [body.replace(sym, color(sym, code, on)).replace(who, paint)];
+  lines.push(fit(`${pad}    `, o => detail(n, view.mode, o), cols, on));
+  if (n.tree) lines.push(fit(`${pad}    `, o => color('group:', C.dim, o) + ' ' + [n.showQuota === false ? '' : groupText(n, view.mode, o), moneyText({ ...n, cost: n.tree.cost })].filter(Boolean).join('   '), cols, on));
+  const runningBelow = m => m.state === 'running' || m.children.some(runningBelow);
+  out.push({ lines, droppable: n.state === 'waiting' && !runningBelow(n) });
+  n.children.forEach((k, i) => nodeBlocks(k, view, cols, on, depth + 1, i === n.children.length - 1, pad, out));
+}
+
+const whoText = (provider, model, on) => `${color(provider, ansi('provider', provider), on)} ${color(short(model), ansi('model', model), on)}`;
+function attentionText(a, on) {
+  const who = a.provider ? whoText(a.provider, a.model, on) : '';
+  if (a.type === 'orphan') return `\u26a0 ${who} orphan`;
+  if (a.type === 'links') return `\u26a0 ${a.count} unclear links`;
+  if (a.type === 'context') return `\u26a0 ${who} ctx ${ctx(a.tokens)}/${ctx(a.limit)}`;
+  return `\u26a0 ${color(NAMES[a.provider], ansi('provider', a.provider), on)} ${a.window} quota left ${pct(100 - a.percent)}%`;
+}
+
+// Wrap items into lines of at most `cols` characters.
+function wrap(prefix, items, cols) {
+  const lines = []; let line = prefix;
+  for (const it of items) {
+    const next = line === prefix ? line + it : line + '   ' + it;
+    if (vlen(next) > cols && line !== prefix) { lines.push(line); line = prefix + it; } else line = next;
+  }
+  lines.push(line);
+  return lines.map(l => cut(l, cols));
+}
+
+function recentLine(view, cols, on) {
+  const r = view.recent;
+  if (!r.total) return [];
+  const items = r.items.map(i => `${i.turn === 'aborted' ? '\u2298' : '\u2713'} ${whoText(i.provider, i.model, on)}${i.label ? ` (${cut(clean(i.label), 24)})` : ''}${i.turn === 'aborted' ? ' \u00b7 interrupted' : ''} ${hhmm(i.endedAt)}`);
+  const build = k => 'RECENT  ' + items.slice(0, k).join(' \u00b7 ') + (r.total > k ? `   (+${r.total - k})` : '');
+  let shown = items.length;
+  while (shown > 0 && vlen(build(shown)) > cols) shown--;
+  return [cut(build(shown), cols)];
+}
+
+// opts: { cols, rows (Infinity for none), color }. Trimming order when rows are short: RECENT, then waiting sessions
+// (last first), keeping running sessions and ATTENTION; if that is still not enough the session area is cut from the bottom.
+function renderFrame(view, { cols = 120, rows = Infinity, color: on = false } = {}) {
+  const top = quotaLines(view, on).map(l => cut(l, cols));
+  const attention = view.attention.length ? ['ATTENTION', ...wrap(' ', view.attention.map(a => attentionText(a, on)), cols)] : [];
+  const blocks = [];
+  for (const r of view.repos) {
+    blocks.push({ lines: [cut(`${clean(r.name)}  (${r.active} active)`, cols)], droppable: false });
+    r.roots.forEach(n => nodeBlocks(n, view, cols, on, 0, true, '', blocks));
+  }
+  if (!view.repos.length) blocks.push({ lines: [cut(`no active sessions${view.repo ? ' in this repo' : ''}`, cols)], droppable: false });
+  let recent = recentLine(view, cols, on);
+  const count = () => top.length + blocks.reduce((s, b) => s + b.lines.length, 0) + attention.length + recent.length;
+  if (count() > rows) recent = [];
+  let hidden = 0;
+  for (let i = blocks.length - 1; i >= 0 && count() + (hidden ? 1 : 0) > rows; i--) {
+    if (blocks[i].droppable) { blocks.splice(i, 1); hidden++; }
+  }
+  const body = blocks.flatMap(b => b.lines);
+  if (hidden) body.push(cut(`\u2026 ${hidden} waiting sessions hidden (--once prints all)`, cols));
+  const room = rows - top.length - attention.length - recent.length;
+  if (body.length > room) { body.length = Math.max(0, room - 1); body.push('\u2026'); }
+  return [...top, ...body, ...attention, ...recent].join('\n');
+}
+
+module.exports = { renderFrame };

package/agentmoni/lib/timeline.js

@@ -0,0 +1,40 @@
+// Turn and tool-call timeline of one transcript, read on demand for the detail drawer (never copied into the log).
+const { scan } = require('./jsonl.js');
+
+const MAX_ENTRIES = 300;
+const MAX_TEXT = 240;
+const clip = v => String(v ?? '').replace(/\s+/g, ' ').trim().slice(0, MAX_TEXT);
+// Injected context ("<...>" tags, the AGENTS.md preamble) is not what the user typed.
+const typed = t => typeof t === 'string' && t.trim() && !/^\s*(<|# AGENTS\.md)/.test(t);
+// Tool results and outputs are the huge lines and add nothing to the timeline: skip them before parsing.
+const want = l => !/"type":"tool_result"|"function_call_output"|"custom_tool_call_output"/.test(l);
+
+function toolText(name, input) {
+  let v = input;
+  if (typeof v === 'string') { try { v = JSON.parse(v); } catch { return `${name} ${clip(v)}`; } }
+  const arg = v?.command ?? v?.cmd ?? v?.file_path ?? v?.path ?? v?.description ?? v?.pattern ?? v?.prompt ?? (v && typeof v === 'object' ? JSON.stringify(v) : v);
+  return `${name} ${clip(Array.isArray(arg) ? arg.join(' ') : arg)}`;
+}
+
+const n = v => Number.isSafeInteger(v) && v >= 0 ? v : 0;
+
+// -> [{ at, kind: 'user'|'assistant'|'tool'|'turn', text, tokens? }] (last MAX_ENTRIES), plus the count of malformed lines.
+// tokens ({ input, cacheRead, cacheWrite, output }) sit on the last entry of a model message or on the entry before a token_count.
+function read(file, visit) {
+  const out = [];
+  const add = (r, kind, text) => { if (text) out.push({ at: Date.parse(r.timestamp) || null, kind, text }); };
+  const lastOf = new Map(), seen = new Set();   // message id -> its last entry (streaming repeats a message with growing output)
+  const bad = scan(file, want, r => {
+    visit(r, { out, add, lastOf, seen });
+  });
+  return { entries: out.slice(-MAX_ENTRIES), total: out.length, bad };
+}
+
+function readTimeline(file, provider) {
+  const registry = require('./agents/index.js');
+  if (provider) return registry.find(a => a.id === provider)?.readTimeline?.(file) ?? { entries: [], total: 0, bad: 0 };
+  // Standalone callers can omit the provider; each reader recognizes only its own records.
+  const results = registry.flatMap(a => a.readTimeline ? [a.readTimeline(file)] : []);
+  return results.find(r => r.total) ?? results[0] ?? { entries: [], total: 0, bad: 0 };
+}
+module.exports = { readTimeline, read, clip, typed, toolText, n };