@guenbankhai/tools 0.0.0-stage → 0.1.0

package/agentmoni/lib/log.js

@@ -0,0 +1,226 @@
+// Durable log, one writer at a time (lock file):
+//   _machine/quota-YYYY-MM-DD.jsonl            account quota, appended only when a number changes
+//   <repo-key>/sessions/<provider>-<id>.json   session summary, written atomically when the session changes
+//   <repo-key>/events-YYYY-MM-DD.jsonl         lifecycle marks only: start, end, resume, link, orphan
+// Events are start, end, resume, link and orphan only (running/waiting flips are not logged). No tool calls or per-turn usage are copied; transcripts stay the source for detail. A bad file or line is skipped with a warning.
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+
+const DAY_MS = 86400e3;
+const KEEP_DAYS = 30;
+const TICK_MS = 30 * 1000;   // minimum gap between rewrites of a summary that only gained tokens or activity
+const safe = s => String(s).replace(/[^\w.-]/g, '_');
+const day = ms => new Date(ms).toISOString().slice(0, 10);
+const fileDay = name => /(\d{4}-\d{2}-\d{2})\.jsonl$/.exec(name)?.[1];
+
+function pidAlive(pid) {
+  try { process.kill(pid, 0); return true; } catch (e) { return e.code === 'EPERM'; }
+}
+
+// Start time of a process (ms), or null when it cannot be read; used to tell a reused pid from the lock owner.
+function processStart(pid) {
+  try {
+    const out = execFileSync('powershell', ['-NoProfile', '-NonInteractive', '-Command', `(Get-CimInstance Win32_Process -Filter 'ProcessId=${Number(pid)}').CreationDate.ToUniversalTime().ToString('o')`], { encoding: 'utf8', timeout: 15000, windowsHide: true });
+    return Date.parse(out.trim()) || null;
+  } catch { return null; }
+}
+const LOCK_SLACK_MS = 5000;
+const STALE_TMP_MS = 3600e3;
+
+function atomicWrite(file, text) {
+  const temp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(temp, text);
+  fs.renameSync(temp, file);
+}
+
+function createLog({ dir, isAlive = pidAlive, startOf = processStart } = {}) {
+  const warnings = [];
+  const warn = m => { if (!warnings.includes(m)) warnings.push(m); };
+  const lockFile = path.join(dir, '.lock');
+  const webFile = path.join(dir, 'web.json');
+  const known = new Map();     // "provider:id" -> { summary, material, writtenAt }
+  const lastQuota = new Map(); // provider -> JSON of the last logged numbers
+  let owner = false;
+
+  // -> true when this process may write. Another live monitor holding the lock makes us read-only.
+  function acquire() {
+    fs.mkdirSync(dir, { recursive: true });
+    for (let attempt = 0; attempt < 2; attempt++) {
+      try { fs.writeFileSync(lockFile, JSON.stringify({ pid: process.pid, startMs: Math.round(Date.now() - process.uptime() * 1000) }), { flag: 'wx' }); owner = true;
+        try { fs.unlinkSync(webFile); } catch { /* no previous URL */ }
+        return true; }
+      catch (e) {
+        if (e.code !== 'EEXIST') { warn(`log lock failed: ${e.message}`); return false; }
+        // An empty or unreadable lock may be a starter mid-write: treat it as held, never delete it.
+        let lock = null;
+        try { lock = JSON.parse(fs.readFileSync(lockFile, 'utf8')); } catch { /* handled below */ }
+        const pid = typeof lock === 'number' ? lock : lock?.pid;
+        if (!Number.isSafeInteger(pid)) { warn('log lock is unreadable: treated as held, read-only'); return false; }
+        const real = pid !== process.pid && isAlive(pid) ? startOf(pid) : undefined;   // undefined: not running
+        const sameProcess = real !== undefined && (real == null || lock.startMs == null || Math.abs(real - lock.startMs) <= LOCK_SLACK_MS);
+        if (sameProcess) { warn(`another monitor (pid ${pid}) owns the log: read-only`); return false; }
+        try { fs.unlinkSync(lockFile); } catch { /* raced with another starter */ }
+      }
+    }
+    return false;
+  }
+  function release() {
+    if (!owner) return;
+    owner = false;
+    try { fs.unlinkSync(webFile); } catch { /* no web */ }
+    try { fs.unlinkSync(lockFile); } catch { /* already gone */ }
+  }
+
+  const repos = () => { try { return fs.readdirSync(dir, { withFileTypes: true }).filter(e => e.isDirectory()).map(e => e.name); } catch { return []; } };
+
+  // Removes day files and ended summaries older than 30 days.
+  function cleanup(now) {
+    const cutoff = now - KEEP_DAYS * DAY_MS;
+    let removed = 0;
+    const drop = file => { try { fs.unlinkSync(file); removed++; } catch (e) { warn(`cannot remove ${file}: ${e.message}`); } };
+    // Half-written temp files of a crashed writer (an hour old, so a live writer is never raced).
+    for (const d of [dir, ...repos().flatMap(r => [path.join(dir, r), path.join(dir, r, 'sessions')])]) {
+      let names = [];
+      try { names = fs.readdirSync(d); } catch { continue; }
+      for (const n of names.filter(x => x.endsWith('.tmp'))) {
+        try { if (fs.statSync(path.join(d, n)).mtimeMs < now - STALE_TMP_MS) drop(path.join(d, n)); } catch { /* gone */ }
+      }
+    }
+    for (const repo of repos()) {
+      let names = [];
+      try { names = fs.readdirSync(path.join(dir, repo)); } catch { /* unreadable folder */ }
+      for (const n of names) {
+        const d = fileDay(n);
+        if (d && Date.parse(`${d}T23:59:59Z`) < cutoff) drop(path.join(dir, repo, n));
+      }
+      const sdir = path.join(dir, repo, 'sessions');
+      try { names = fs.readdirSync(sdir); } catch { continue; }
+      for (const n of names.filter(x => x.endsWith('.json'))) {
+        const s = readSummary(path.join(sdir, n));
+        if (s && s.state === 'ended' && s.lastActivityAt < cutoff) drop(path.join(sdir, n));
+      }
+    }
+    return removed;
+  }
+
+  function readSummary(file) {
+    try {
+      const s = JSON.parse(fs.readFileSync(file, 'utf8'));
+      if (typeof s?.provider !== 'string' || typeof s.id !== 'string' || !Number.isFinite(s.startedAt) || !Number.isFinite(s.lastActivityAt)) throw new Error('missing fields');
+      return s;
+    } catch (e) { warn(`skipped ${file}: ${e.message}`); return null; }
+  }
+
+  // Every summary on disk, newest activity first; remembered so later writes can tell what changed.
+  function load() {
+    const all = [];
+    for (const repo of repos()) {
+      const sdir = path.join(dir, repo, 'sessions');
+      let names = [];
+      try { names = fs.readdirSync(sdir); } catch { continue; }
+      for (const n of names.filter(x => x.endsWith('.json'))) {
+        const s = readSummary(path.join(sdir, n));
+        if (s) { all.push(s); known.set(`${s.provider}:${s.id}`, { summary: s, material: materialOf(s), writtenAt: 0 }); }
+      }
+    }
+    for (const q of loadQuota()) lastQuota.set(q.provider, quotaKey(q));
+    return all.sort((a, b) => b.lastActivityAt - a.lastActivityAt);
+  }
+
+  // The newest logged numbers per provider, so a restart does not log them again.
+  function loadQuota() {
+    const m = path.join(dir, '_machine');
+    let names = [];
+    try { names = fs.readdirSync(m).filter(n => n.startsWith('quota-') && fileDay(n)).sort(); } catch { return []; }
+    const latest = new Map();
+    for (const n of names.slice(-2)) {
+      let bad = 0;
+      for (const line of fs.readFileSync(path.join(m, n), 'utf8').split('\n')) {
+        if (!line.trim()) continue;
+        try { const q = JSON.parse(line); if (q?.provider) latest.set(q.provider, q); } catch { bad++; }
+      }
+      if (bad) warn(`skipped ${bad} malformed line(s) in ${n}`);
+    }
+    return [...latest.values()];
+  }
+
+  const quotaKey = q => JSON.stringify(Object.keys(q).filter(k => k !== 't' && k !== 'provider').sort().map(k => [k, q[k] ? { percent: q[k].percent, resetsAt: q[k].resetsAt } : null]));
+  function logQuota(accounts, now) {
+    if (!owner) return;
+    for (const [provider, acct] of Object.entries(accounts)) {
+      // An unknown (stale) window is not a number to log.
+      const a = { windows: Object.fromEntries(Object.keys(acct.windows).map(w => [w, acct.windows[w]?.stale ? null : acct.windows[w]])) };
+      const row = { provider };
+      for (const w of Object.keys(a.windows)) row[w] = a.windows[w] ? { percent: a.windows[w].percent, resetsAt: a.windows[w].resetsAt, readAt: a.windows[w].readAt ?? a.windows[w].at, source: a.windows[w].source } : null;
+      if (!Object.values(a.windows).some(Boolean)) continue;
+      if (lastQuota.get(provider) === quotaKey(row)) continue;
+      lastQuota.set(provider, quotaKey(row));
+      append(path.join(dir, '_machine', `quota-${day(now)}.jsonl`), { t: now, ...row });
+    }
+  }
+
+  function append(file, row) {
+    try {
+      fs.mkdirSync(path.dirname(file), { recursive: true });
+      const fd = fs.openSync(file, 'a');
+      try { fs.writeFileSync(fd, JSON.stringify(row) + '\n'); fs.fsyncSync(fd); } finally { fs.closeSync(fd); }
+    }
+    catch (e) { warn(`cannot write ${file}: ${e.message}`); }
+  }
+
+  // What identifies a change worth writing at once; tokens, context and activity wait for the tick.
+  // running <-> waiting flips are not lifecycle: only ended-or-not counts.
+  const lifeOf = s => s.state === 'ended' ? 'ended' : 'alive';
+  const materialOf = s => JSON.stringify([lifeOf(s), s.turn === 'aborted', s.parent, s.link?.kind, s.link?.label, s.resume, s.kind, s.name, s.model, s.effort, s.orphan]);
+  const summaryOf = (s, repo, now) => ({ v: 1, provider: s.provider, id: s.id, billing: s.billing ?? 'unknown', repo, cwd: s.cwd, model: s.model, effort: s.effort, name: s.name, kind: s.kind, agentType: s.agentType ?? null, state: s.state, turn: s.turn ?? null,
+    startedAt: s.startedAt, lastActivityAt: s.lastActivityAt, tokens: s.tokens, context: s.context, parent: s.parent, link: s.link, runs: s.runs, resume: s.resume,
+    orphan: s.orphan, share: s.share, writtenAt: now });
+
+  // sessions must carry .repo. Writes summaries and lifecycle events for what changed since the last call.
+  function record(sessions, now) {
+    if (!owner) return;
+    for (const s of sessions) {
+      const k = `${s.provider}:${s.id}`, prev = known.get(k), mat = materialOf(s);
+      const events = [];
+      const mark = (event, t, extra = {}) => events.push({ t, event, provider: s.provider, id: s.id, ...extra });
+      if (!prev) {
+        mark('start', s.startedAt, { kind: s.kind, cwd: s.cwd });
+        if (s.parent) mark('link', s.startedAt, { parent: s.parent, kind: s.link?.kind, label: s.link?.label });
+        if (s.state === 'ended') mark('end', s.lastActivityAt);
+        if (s.orphan) mark('orphan', now, { parent: s.parent });
+      } else {
+        if (s.orphan && !prev.summary.orphan) mark('orphan', now, { parent: s.parent });
+        const p = prev.summary;
+        if (lifeOf(p) !== lifeOf(s) && s.state === 'ended') mark('end', now);
+        if (s.resume > (p.resume ?? 0)) mark('resume', now, { run: s.resume + 1 });
+        if (p.parent !== s.parent || p.link?.kind !== s.link?.kind) mark('link', now, { parent: s.parent, kind: s.link?.kind, label: s.link?.label });
+      }
+      if (prev && prev.material === mat && now - prev.writtenAt < TICK_MS) continue;
+      const summary = summaryOf(s, s.repo, now);
+      if (prev && prev.material === mat && JSON.stringify({ ...summary, state: lifeOf(summary), writtenAt: 0 }) === JSON.stringify({ ...prev.summary, state: lifeOf(prev.summary), writtenAt: 0 })) continue;
+      const file = path.join(dir, s.repo, 'sessions', `${safe(s.provider)}-${safe(s.id)}.json`);
+      try {
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        atomicWrite(file, JSON.stringify(summary));
+        known.set(k, { summary, material: mat, writtenAt: now });
+        for (const e of events) append(path.join(dir, s.repo, `events-${day(e.t)}.jsonl`), e);
+      } catch (e) { warn(`cannot write ${file}: ${e.message}`); }
+    }
+  }
+
+  function publishWeb(url) {
+    if (owner) atomicWrite(webFile, JSON.stringify({ pid: process.pid, url }));
+  }
+  function readWeb() {
+    try {
+      const lock = JSON.parse(fs.readFileSync(lockFile, 'utf8'));
+      const web = JSON.parse(fs.readFileSync(webFile, 'utf8'));
+      return web.pid === (lock.pid ?? lock) && /^http:\/\/127\.0\.0\.1:\d+$/.test(web.url) ? web.url : null;
+    } catch { return null; }
+  }
+
+  return { acquire, release, cleanup, load, record, logQuota, publishWeb, readWeb, warnings, get owner() { return owner; } };
+}
+
+module.exports = { createLog };

package/agentmoni/lib/monitor.js

@@ -0,0 +1,58 @@
+// The refresh loop body: sessions + links + account quota + shares + log. Everything external is injectable.
+const os = require('node:os');
+const path = require('node:path');
+const { load } = require('./catalog.js');
+const { collect } = require('./collect.js');
+const { createTracker } = require('./state.js');
+const agents = require('./agents/index.js');
+const { quotaProvidersOf } = require('./present.js');
+const { createQuota } = require('./quota.js');
+const { computeShares } = require('./share.js');
+const { createLog } = require('./log.js');
+const { repoKey } = require('./repokey.js');
+
+const DAY_MS = 86400e3;
+const RETRY_LOCK_MS = 30 * 1000;
+// Logs live outside the repo: $AGENTMONI_HOME, else %LOCALAPPDATA%\agentmoni, else ~/.agentmoni.
+const defaultLogDir = () => process.env.AGENTMONI_HOME || (process.env.LOCALAPPDATA ? path.join(process.env.LOCALAPPDATA, 'agentmoni') : path.join(os.homedir(), '.agentmoni'));
+
+// days: how far back transcripts are read; it must cover the longest declared window plus a day of margin.
+function createMonitor({ registry = agents, catalog = load(), logDir = defaultLogDir(), days = 8, fetch, collectOptions = {}, isAlive, startOf, ...agentOptions } = {}) {
+  const tracker = createTracker();
+  const log = createLog({ dir: logDir, isAlive, startOf, ...agentOptions });
+  let saved = [];
+  const quota = createQuota({ ...agentOptions, logDir, fetch }, registry);
+
+  // Takes the log lock (read-only when another monitor holds it), drops files older than 30 days, and restores runs
+  // and history from the summaries so a restart keeps what the last monitor saw.
+  let triedAt = 0;
+  function start(now = Date.now()) {
+    triedAt = now;
+    if (log.acquire()) log.cleanup(now);
+    saved = log.load();
+    for (const s of saved) tracker.restore(`${s.provider}:${s.id}`, s.runs);
+  }
+  function stop() { log.release(); }
+
+  // waitQuota: wait for the usage endpoint (one-shot tools); the live loop reads the cache and lets the request finish by itself.
+  async function refresh({ now = Date.now(), waitQuota = false } = {}) {
+    // A read-only monitor takes the log over when the owner is gone.
+    if (!log.owner && now - triedAt >= RETRY_LOCK_MS) { triedAt = now; if (log.acquire()) { log.cleanup(now); saved = log.load(); } }
+    const { sessions, ambiguous } = collect({ since: now - days * DAY_MS, now, tracker, registry, ...collectOptions });
+    const quotaProviders = quotaProvidersOf({ sessions, history: saved.map(s => ({ ...s, state: 'ended' })) }, registry);
+    const asking = quota.refresh(now, quotaProviders, sessions);
+    if (waitQuota) await asking;
+    const accounts = quota.read(sessions, now);
+    const shares = computeShares({ catalog, sessions, history: saved.filter(s => !new Set(sessions.map(x => `${x.provider}:${x.id}`)).has(`${s.provider}:${s.id}`)), accounts, now });
+    for (const s of shares.sessions) s.repo = repoKey(s.cwd);
+    log.record(shares.sessions, now);
+    log.logQuota(Object.fromEntries(quotaProviders.map(p => [p, accounts[p]])), now);
+    // Sessions whose transcripts are gone (or older than `days`) are still known from their summaries.
+    const live = new Set(shares.sessions.map(s => `${s.provider}:${s.id}`));
+    const history = saved.filter(s => !live.has(`${s.provider}:${s.id}`)).map(s => ({ ...s, state: 'ended', fromLog: true }));
+    return { sessions: shares.sessions, history, accounts, outside: shares.outside, warnings: [...shares.warnings, ...log.warnings], ambiguous };
+  }
+  return { start, stop, refresh, catalog, log };
+}
+
+module.exports = { createMonitor, defaultLogDir };