@khoavu882/doflow 2.0.0-beta.4 → 2.0.0

package/src/runtime/transcripts/registry.js

@@ -0,0 +1,161 @@
+'use strict';
+
+// 093 V.1, IC-021: loader, validator and doctor view for core/registry/transcripts.json, the data that
+// says where each harness keeps its transcripts. Like advice.json it stays outside REGISTRY_FILES: a bad
+// file turns the transcript feature off (`config-invalid`), it must not fail every install command.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { REPO_ROOT } = require('../../helper/repo-root.js');
+
+const TRANSCRIPTS_FILE = 'core/registry/transcripts.json';
+const HARNESSES_FILE = 'core/registry/harnesses.json';
+const STALE_DAYS = 90;
+const DAY_MS = 86400000;
+const STATUSES = ['supported', 'events-only', 'unknown'];
+const FORMATS = ['jsonl', 'sqlite', 'jsonl+json'];
+const APPEND_ONLY = ['yes', 'no', 'unknown'];
+const JOINS = ['session-id', 'cwd', 'none'];
+const OSES = ['darwin', 'linux', 'win32'];
+const PLACEHOLDERS = new Set(['sessionId', 'cwdEncoded']);
+const ENTRY_KEYS = ['harness', 'reader', 'status', 'locations', 'format', 'appendOnly', 'join', 'requiredKeys', 'evidence', 'verifiedOn', 'versions'];
+
+function isObject(value     )          {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function isStringArray(value     )          {
+  return Array.isArray(value) && value.every((item) => typeof item === 'string' && item.length > 0);
+}
+
+/** True for a real calendar date written YYYY-MM-DD. */
+function isDate(value     )          {
+  if (typeof value !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(value)) return false;
+  const at = new Date(`${value}T00:00:00Z`);
+  return !Number.isNaN(at.getTime()) && at.toISOString().slice(0, 10) === value;
+}
+
+function validateLocation(location     , where        , errors          )       {
+  if (!isObject(location)) { errors.push(`${where} must be an object`); return; }
+  if (!OSES.includes(location.os)) errors.push(`${where}.os must be one of ${OSES.join(', ')}`);
+  if (!(typeof location.base === 'string' && /^(home|xdg-data|env:[A-Z_][A-Z0-9_]*)$/.test(location.base))) {
+    errors.push(`${where}.base must be home, xdg-data or env:<NAME>`);
+  }
+  if (!isStringArray(location.segments)) errors.push(`${where}.segments must be an array of non-empty strings`);
+  if (typeof location.glob !== 'string' || !location.glob) {
+    errors.push(`${where}.glob must be a non-empty string`);
+  } else {
+    for (const [, name] of location.glob.matchAll(/\{([^}]*)\}/g)) {
+      if (!PLACEHOLDERS.has(name)) errors.push(`${where}.glob has an unknown placeholder {${name}}`);
+    }
+  }
+  // R28: a Windows location stays unverified until someone measures it, and only Windows may say so.
+  if (location.os === 'win32') {
+    if (location.status !== 'unknown') errors.push(`${where} is win32, so its status must be "unknown"`);
+  } else if (location.status !== undefined) {
+    errors.push(`${where}.status is only allowed on a win32 location`);
+  }
+}
+
+function validateEntry(entry     , index        , errors          )       {
+  const label = isObject(entry) && typeof entry.harness === 'string' ? entry.harness : `entries[${index}]`;
+  if (!isObject(entry)) { errors.push(`${label} must be an object`); return; }
+  for (const key of ENTRY_KEYS) {
+    if (!Object.hasOwn(entry, key)) errors.push(`${label}.${key} is missing`);
+  }
+  if (typeof entry.harness !== 'string' || !entry.harness) errors.push(`${label}.harness must be a non-empty string`);
+  if (Object.hasOwn(entry, 'reader') && entry.reader !== null && (typeof entry.reader !== 'string' || !entry.reader)) {
+    errors.push(`${label}.reader must be a module id or null`);
+  }
+  if (Object.hasOwn(entry, 'status') && !STATUSES.includes(entry.status)) errors.push(`${label}.status must be one of ${STATUSES.join(', ')}`);
+  // A reader exists exactly when the harness is supported (IC-021: OpenCode moves only with its reader).
+  if (STATUSES.includes(entry.status) && entry.reader !== undefined) {
+    if (entry.status === 'supported' && entry.reader === null) errors.push(`${label}.reader must be set when status is supported`);
+    if (entry.status !== 'supported' && entry.reader !== null) errors.push(`${label}.reader must be null unless status is supported`);
+  }
+  if (Object.hasOwn(entry, 'locations')) {
+    if (!Array.isArray(entry.locations) || entry.locations.length === 0) errors.push(`${label}.locations must be a non-empty array`);
+    else entry.locations.forEach((location     , i        ) => validateLocation(location, `${label}.locations[${i}]`, errors));
+  }
+  if (Object.hasOwn(entry, 'format') && !FORMATS.includes(entry.format)) errors.push(`${label}.format must be one of ${FORMATS.join(', ')}`);
+  if (Object.hasOwn(entry, 'appendOnly') && !APPEND_ONLY.includes(entry.appendOnly)) errors.push(`${label}.appendOnly must be one of ${APPEND_ONLY.join(', ')}`);
+  if (Object.hasOwn(entry, 'join') && !JOINS.includes(entry.join)) errors.push(`${label}.join must be one of ${JOINS.join(', ')}`);
+  if (Object.hasOwn(entry, 'requiredKeys') && !isStringArray(entry.requiredKeys)) errors.push(`${label}.requiredKeys must be an array of non-empty strings`);
+  if (Object.hasOwn(entry, 'evidence') && (!isStringArray(entry.evidence) || entry.evidence.length === 0)) errors.push(`${label}.evidence must be a non-empty array of strings`);
+  if (Object.hasOwn(entry, 'verifiedOn') && !isDate(entry.verifiedOn)) errors.push(`${label}.verifiedOn must be a YYYY-MM-DD date`);
+  if (Object.hasOwn(entry, 'versions') && entry.versions !== null && (typeof entry.versions !== 'string' || !entry.versions)) {
+    errors.push(`${label}.versions must be a version range or null`);
+  }
+}
+
+/** The registry ids of core/registry/harnesses.json, read as plain data. */
+function readHarnessIds(repoRoot        , fsImpl      = fs)           {
+  const parsed = JSON.parse(fsImpl.readFileSync(path.join(path.resolve(repoRoot), HARNESSES_FILE), 'utf8'));
+  return parsed.harnesses.map((harness     ) => harness.id);
+}
+
+/**
+ * Checks the registry's shape and the id guard: the entry ids and `harnessIds` are the same set, with no
+ * exception (row 127 retired Gemini CLI, so there is no Gemini entry and no allowance for one).
+ */
+function validateTranscriptRegistry(registry     , { harnessIds }                          )                                    {
+  const errors           = [];
+  if (!isObject(registry)) return { ok: false, errors: ['registry must be an object'] };
+  if (registry.version !== 1) errors.push('version must be 1');
+  if (!Array.isArray(registry.entries)) {
+    errors.push('entries must be an array');
+    return { ok: false, errors };
+  }
+  registry.entries.forEach((entry     , i        ) => validateEntry(entry, i, errors));
+  const seen = new Set        ();
+  for (const entry of registry.entries) {
+    if (!isObject(entry) || typeof entry.harness !== 'string') continue;
+    if (seen.has(entry.harness)) errors.push(`${entry.harness} is a duplicate entry`);
+    seen.add(entry.harness);
+    if (!harnessIds.includes(entry.harness)) errors.push(`${entry.harness} is not a harnesses.json id`);
+  }
+  for (const id of harnessIds) {
+    if (!seen.has(id)) errors.push(`${id} has no entry (every harnesses.json id needs one)`);
+  }
+  return { ok: errors.length === 0, errors };
+}
+
+function loadTranscriptRegistry({ repoRoot = REPO_ROOT, file, fsImpl = fs }      = {})                                                                    {
+  const root = path.resolve(repoRoot);
+  const target = file || path.join(root, TRANSCRIPTS_FILE);
+  let registry     ;
+  let harnessIds          ;
+  try {
+    registry = JSON.parse(fsImpl.readFileSync(target, 'utf8'));
+    harnessIds = readHarnessIds(root, fsImpl);
+  } catch (error     ) {
+    return { ok: false, reason: 'config-invalid', detail: `${target}: ${error.message}` };
+  }
+  const validation = validateTranscriptRegistry(registry, { harnessIds });
+  if (!validation.ok) return { ok: false, reason: 'config-invalid', detail: validation.errors.join('; ') };
+  return { ok: true, registry };
+}
+
+/** Entries whose `verifiedOn` is more than STALE_DAYS before `now`. */
+function staleEntries(registry     , now       = new Date())                                                                  {
+  const out                                                                  = [];
+  for (const entry of registry.entries) {
+    const ageDays = Math.floor((now.getTime() - new Date(`${entry.verifiedOn}T00:00:00Z`).getTime()) / DAY_MS);
+    if (ageDays > STALE_DAYS) out.push({ harness: entry.harness, verifiedOn: entry.verifiedOn, ageDays });
+  }
+  return out;
+}
+
+/**
+ * The doctor's `transcripts` row: `ok`, `stale` (a `verifiedOn` older than 90 days) or `drift` (the file or
+ * the id guard is invalid, so the transcript feature is off). Read-only; never a finding, so the exit code
+ * does not change. A `format-unrecognized` seen at run time joins this row when V.4's readers exist.
+ */
+function transcriptsDoctorView({ repoRoot = REPO_ROOT, file, fsImpl = fs, now = new Date() }      = {})      {
+  const loaded = loadTranscriptRegistry({ repoRoot, file, fsImpl });
+  if (!loaded.ok) return { state: 'drift', entries: 0, stale: [], errors: (loaded.detail          ).split('; ') };
+  const stale = staleEntries(loaded.registry, now);
+  return { state: stale.length ? 'stale' : 'ok', entries: loaded.registry.entries.length, stale, errors: [] };
+}
+
+module.exports = { loadTranscriptRegistry, validateTranscriptRegistry, staleEntries, transcriptsDoctorView, STALE_DAYS, TRANSCRIPTS_FILE };

package/src/runtime/transcripts/stats.js

@@ -0,0 +1,161 @@
+'use strict';
+
+/**
+ * `transcript --action stats` (093 IC-023): traffic over the last window and who works with whom, for one
+ * project. The agents are `buildTree`'s nodes (newest first, at most 32; the rest counted in `notChecked`).
+ * A linked transcript is read in metadata mode (no text, no arguments), at most its last 256 KiB, in pages.
+ * An event without a time (Kiro keeps none per record) takes the transcript's newest known time, which for
+ * Kiro is the newest turn `end_timestamp`; if there is none, the window is unknown and the counts are null.
+ * Unknown is never zero: a harness that does not record a value gives null, and an agent with no readable
+ * transcript gives null everywhere. Zero is reported only for a transcript that was read and held nothing.
+ * `pairs` says who works with whom: equal model id (`same-model`), active attempts or running worker runs on
+ * one task id (`same-task`, `task`), and a plan `overlaps` pair held by two agents (`overlap`, `tasks`).
+ * Nothing is written; no path, pid or raw session id is printed.
+ */
+
+const fs = require('node:fs');
+const { buildTree, READERS } = require('../fleet/tree.js');
+const { loadPlan } = require('../task-attempts.js');
+const { overlaps } = require('../task-graph.js');
+const { parseCursor, toMs } = require('./cursor.js');
+const { inCheckouts, checkoutRoots, registryById } = require('./read.js');
+
+const DEFAULT_WINDOW = 10;
+const MAX_AGENTS = 32;
+const MAX_PAGES = 8;
+const TAIL_RECORDS = 4096;
+const TOKEN_FIELDS = ['input', 'output', 'cacheRead', 'cacheWrite', 'reasoning'];
+
+/** Sums of the fields any event recorded; a field no event recorded stays null, and none at all is null. */
+function sumTokens(list       )      {
+  const out                                = {};
+  for (const field of TOKEN_FIELDS) {
+    const values = list.map((t) => t[field]).filter((v) => Number.isFinite(v));
+    out[field] = values.length ? values.reduce((a, b) => a + b, 0) : null;
+  }
+  return Object.values(out).some((v) => v !== null) ? out : null;
+}
+
+const round2 = (n        )         => Math.round(n * 100) / 100;
+
+/** Every event of the transcript's window, in pages, with the newest time the reader knew. */
+function readWindow(mod     , node     , internal     )                                   {
+  const events        = [];
+  let cursor                    ;
+  let clock = NaN;
+  for (let page = 0; page < MAX_PAGES; page += 1) {
+    const r = mod.read({ file: internal.file, companion: internal.companion, mode: 'metadata', cursor, limit: 500, tailRecords: TAIL_RECORDS, agentKey: node.agentKey });
+    events.push(...r.events);
+    const c = parseCursor(r.cursor);
+    clock = c && c.atMs > 0 ? c.atMs : clock;
+    cursor = r.cursor;
+    if (r.eof) break;
+  }
+  return { events, clock };
+}
+
+/** The per-agent numbers of the events at or after `startMs`. */
+function summarize(events       , clock        , startMs        , windowMin        )      {
+  if (events.length === 0) {
+    return { eventsPerMin: 0, toolCalls: 0, toolErrors: 0, toolDurationMs: null, tokens: null };
+  }
+  const timed = events.map((e) => ({ e, t: Number.isFinite(toMs(e.at)) ? toMs(e.at) : clock })).filter((x) => Number.isFinite(x.t));
+  if (timed.length === 0) return { eventsPerMin: null, toolCalls: null, toolErrors: null, toolDurationMs: null, tokens: null };
+  const inWindow = timed.filter((x) => x.t >= startMs).map((x) => x.e);
+  const results = inWindow.filter((e) => e.kind === 'tool-result');
+  const known = results.filter((e) => e.tool && e.tool.status !== null && e.tool.status !== undefined);
+  const durations = results.map((e) => e.tool && e.tool.durationMs).filter((d) => Number.isFinite(d)).sort((a, b) => a - b);
+  const usage = inWindow.filter((e) => e.kind === 'usage' && e.tokens).map((e) => e.tokens);
+  return {
+    eventsPerMin: round2(inWindow.length / windowMin),
+    toolCalls: inWindow.filter((e) => e.kind === 'tool-call').length,
+    toolErrors: results.length > 0 && known.length === 0 ? null : known.filter((e) => e.tool.status === 'error').length,
+    toolDurationMs: durations.length ? { p50: durations[Math.ceil(durations.length / 2) - 1], max: durations[durations.length - 1], n: durations.length } : null,
+    tokens: sumTokens(usage),
+  };
+}
+
+function groupModels(agents       )        {
+  const byModel = new Map               ();
+  for (const a of agents) if (a.model !== null) byModel.set(a.model, [...(byModel.get(a.model) ?? []), a]);
+  const sum = (list       , key        )                => {
+    const values = list.map((a) => a[key]).filter((v) => v !== null);
+    return values.length ? round2(values.reduce((x, y) => x + y, 0)) : null;
+  };
+  return [...byModel.entries()].sort((x, y) => (x[0] < y[0] ? -1 : 1)).map(([model, list]) => ({
+    model, agents: list.length, eventsPerMin: sum(list, 'eventsPerMin'), toolCalls: sum(list, 'toolCalls'), tokens: sumTokens(list.map((a) => a.tokens).filter(Boolean)),
+  }));
+}
+
+function pairsOf(agents       , holds                    , planOverlaps                         )        {
+  const out = new Map             ();
+  const add = (a        , b        , basis        , task               , tasks                 )       => {
+    out.set(`${a}|${b}|${basis}|${task ?? ''}|${(tasks ?? []).join(',')}`, { a, b, basis, task, tasks });
+  };
+  const sorted = [...agents].sort((x, y) => (x.agentKey < y.agentKey ? -1 : 1));
+  for (let i = 0; i < sorted.length; i += 1) {
+    for (let j = i + 1; j < sorted.length; j += 1) {
+      const [x, y] = [sorted[i], sorted[j]];
+      if (x.model !== null && x.model === y.model) add(x.agentKey, y.agentKey, 'same-model', null, null);
+      const [hx, hy] = [holds.get(x.agentKey) ?? [], holds.get(y.agentKey) ?? []];
+      for (const h of hx) {
+        if (hy.some((g) => g.slug === h.slug && g.task === h.task)) add(x.agentKey, y.agentKey, 'same-task', h.task, null);
+        for (const pair of planOverlaps(h.slug)) {
+          const other = pair.a === h.task ? pair.b : pair.b === h.task ? pair.a : null;
+          if (other !== null && hy.some((g) => g.slug === h.slug && g.task === other)) add(x.agentKey, y.agentKey, 'overlap', null, [h.task, other]);
+        }
+      }
+    }
+  }
+  return [...out.values()].sort((p, q) => (p.a < q.a ? -1 : p.a > q.a ? 1 : p.b < q.b ? -1 : p.b > q.b ? 1 : p.basis < q.basis ? -1 : p.basis > q.basis ? 1 : String(p.task ?? p.tasks).localeCompare(String(q.task ?? q.tasks))));
+}
+
+function computeStats({
+  env = process.env, cwd = process.cwd(), windowMin = DEFAULT_WINDOW, exec, alive, fsImpl = fs, platform, home, now = Date.now,
+}      = {})      {
+  const built = buildTree({ env, cwd, ...(exec ? { exec } : {}), ...(alive ? { alive } : {}), ...(fsImpl !== fs ? { fsImpl } : {}), ...(platform ? { platform } : {}), ...(home ? { home } : {}) });
+  if (!built.ok) return { ok: false, error: built.error };
+  const registry = registryById();
+  const roots = checkoutRoots({ cwd, exec, fsImpl });
+  const startMs = now() - windowMin * 60000;
+  const ranked = [...built.body.nodes].sort((a     , b     ) => (a.lastRecordAt === b.lastRecordAt ? 0 : a.lastRecordAt === null ? 1 : b.lastRecordAt === null ? -1 : a.lastRecordAt < b.lastRecordAt ? 1 : -1) || (a.agentKey < b.agentKey ? -1 : 1));
+  const chosen = ranked.slice(0, MAX_AGENTS);
+
+  const holds = new Map               ();
+  const agents = chosen.map((node     ) => {
+    const internal = built.internal.get(node.agentKey) ?? {};
+    holds.set(node.agentKey, internal.holds ?? []);
+    let numbers      = { eventsPerMin: null, toolCalls: null, toolErrors: null, toolDurationMs: null, tokens: null };
+    if (node.transcript.linked && internal.file) {
+      try {
+        const mod = READERS[registry[node.harness].reader]();
+        const header = mod.header({ file: internal.file, companion: internal.companion });
+        if (inCheckouts(header.cwd, roots, fsImpl)) {
+          const { events, clock } = readWindow(mod, node, internal);
+          numbers = summarize(events, clock, startMs, windowMin);
+        }
+      } catch { /* an unreadable transcript is unknown, not zero */ }
+    }
+    return { agentKey: node.agentKey, harness: node.harness, model: node.model, ...numbers, lastRecordAt: node.lastRecordAt };
+  });
+
+  const planCache = new Map               ();
+  const planOverlaps = (slug        )        => {
+    if (!planCache.has(slug)) {
+      let list        = [];
+      try { list = overlaps(loadPlan({ roots, slug, fsImpl }).graph); } catch { /* no readable plan: no overlap pairs */ }
+      planCache.set(slug, list);
+    }
+    return planCache.get(slug)         ;
+  };
+
+  return {
+    ok: true,
+    body: {
+      v: 1, projectKey: built.body.projectKey, windowMin, agents, models: groupModels(agents),
+      pairs: pairsOf(agents, holds, planOverlaps), notChecked: Math.max(0, ranked.length - MAX_AGENTS),
+    },
+  };
+}
+
+module.exports = { computeStats, DEFAULT_WINDOW, MAX_AGENTS };