@khoavu882/doflow 2.0.0-beta.4 → 2.0.0

package/src/runtime/trace/telemetry.js

@@ -0,0 +1,225 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+const nodeFs = require('node:fs');
+const path = require('node:path');
+const { resolveRunsLocation } = require('./ledger.js');
+const { identityFields } = require('../context/identity.js');
+const { REPO_ROOT } = require('../../helper/repo-root.js');
+const { loadProtocols, presetIds } = require('../review/protocols.js');
+
+/**
+ * Telemetry contract v1 (088 A.1, IC-001, IC-002): the switch and the writer for the lines that
+ * live in `telemetry/<UTC date>.jsonl`, a subdirectory of the run ledger's own directory.
+ *
+ * Why not `RunLedger`: it drops every line that has no `verb` (ledger.ts `sanitizeRunEvent`) and its
+ * readers list only the `YYYY-MM-DD.jsonl` files directly under `runs/`. These lines are keyed on
+ * `kind`, carry a field set per kind taken from `core/registry/telemetry.json`, and sit in a
+ * subdirectory those readers never see.
+ *
+ * Rules that constrain everything below.
+ *   NFR-004 — records are metadata. A field is written only when the registry names it for the kind
+ *   and its value passes that field's type; anything else is dropped by name or becomes null, and
+ *   the dropped value is never echoed.
+ *   NFR-005 / FR-002 — telemetry never changes an outcome. `write` never throws, writes one
+ *   open-and-write per call, never blocks on a non-regular target, and writes nothing at all when
+ *   `DOFLOW_TELEMETRY=off`.
+ */
+
+/** Same pattern as ledger.ts `SAFE_TOKEN` (not exported there); a test holds the two equal. */
+const SAFE_TOKEN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$/;
+/** The run and lineage rule (context/identity.ts `ID_PATTERN`). */
+const ID = /^[A-Za-z0-9][A-Za-z0-9_-]{0,55}$/;
+const HEX16 = /^[0-9a-f]{16}$/;
+const HEX32 = /^[0-9a-f]{32}$/;
+const ISO_MS = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
+const DATE = /^\d{4}-\d{2}-\d{2}$/;
+
+                                              
+                                                             
+
+/**
+ * Vocabularies another registry owns, which telemetry.json names in `enum:<name>` types but does not
+ * copy (119 C-9): a preset added to protocols.json is a valid `protocol` with no edit here. Each is
+ * read from its owner, through the owner's validator, the first time a writer needs it. An owner that
+ * cannot be read or fails its validator gives no list, so the field is written null (as any value
+ * outside its vocabulary is) and the rest of the line is still written.
+ */
+const DERIVED_VOCABULARIES                                   = Object.freeze({
+  depth: 'core/registry/protocols.json review preset depth labels, loosest first',
+  protocol: 'core/registry/protocols.json order.review, then the literal package',
+});
+
+/** The derived vocabularies read from the registries under `repoRoot`; `{}` when protocols.json is unusable. */
+function derivedVocabularies(repoRoot         = REPO_ROOT)                           {
+  const loaded = loadProtocols({ repoRoot });
+  if (!loaded.ok) return {};
+  const review           = presetIds(loaded.registry, 'review');
+  return {
+    depth: [...review].reverse().map((id) => loaded.registry.presets[id].depth),
+    // 122 IC-024: `package` stands for any preset an active package contributes, so no third-party name is written.
+    protocol: [...review, 'package'],
+  };
+}
+
+/**
+ * The one reader of the switch in Node. The bridge and the observer test the same string in shell.
+ * @param {Object} [env=process.env]
+ * @returns {boolean}
+ */
+function telemetryOff(env      = process.env)          {
+  return env.DOFLOW_TELEMETRY === 'off';
+}
+
+/** One type alternative of a field (`token`, `uint`, `enum:<vocabulary>`, ...) against one value. */
+function matches(alternative        , value         , vocabulary            )          {
+  if (alternative === 'null') return value === null;
+  if (alternative === 'uint') return typeof value === 'number' && Number.isFinite(value) && Math.trunc(value) >= 0;
+  if (alternative === 'int') return typeof value === 'number' && Number.isFinite(value);
+  if (typeof value !== 'string') return false;
+  if (alternative === 'token') return SAFE_TOKEN.test(value);
+  if (alternative === 'id') return ID.test(value);
+  if (alternative === 'hex16') return HEX16.test(value);
+  if (alternative === 'hex32') return HEX32.test(value);
+  if (alternative === 'iso8601ms') return ISO_MS.test(value);
+  if (alternative === 'date') return DATE.test(value);
+  if (alternative.startsWith('enum:')) {
+    const list = vocabulary(alternative.slice(5));
+    return Array.isArray(list) && list.includes(value);
+  }
+  return false; // an unknown type never passes, so a typo in the registry writes null, not content
+}
+
+/** The value as it is written: integers truncated, anything failing the field's type null. */
+function coerce(type        , value         , vocabulary            )          {
+  if (typeof type !== 'string' || !type.split('|').some((alternative) => matches(alternative, value, vocabulary))) return null;
+  return typeof value === 'number' ? Math.trunc(value) : value;
+}
+
+let shipped      = null;
+function shippedRegistry()      {
+  if (!shipped) shipped = JSON.parse(nodeFs.readFileSync(path.join(REPO_ROOT, 'core', 'registry', 'telemetry.json'), 'utf8'));
+  return shipped;
+}
+
+class TelemetryWriter {
+  registry     ;
+  env     ;
+  fsImpl     ;
+  now            ;
+  start                    ;
+  repoRoot        ;
+  derived                                  = null;
+
+  /**
+   * @param {Object} [options]
+   * @param {Object} [options.registry] a parsed `telemetry.json` (default: the shipped one)
+   * @param {Object} [options.env=process.env] the switch, the identity trio and `DOFLOW_CONFIG_DIR`
+   * @param {Object} [options.fsImpl=fs] test seam
+   * @param {Function} [options.now] returns the current Date; test seam
+   * @param {string} [options.start] directory to walk up from for `.doflow` (default: cwd)
+   * @param {string} [options.repoRoot=REPO_ROOT] the install root the derived vocabularies are read from
+   */
+  constructor({ registry, env = process.env, fsImpl = nodeFs, now = () => new Date(), start, repoRoot = REPO_ROOT }      = {}) {
+    this.registry = registry;
+    this.repoRoot = repoRoot;
+    this.env = env;
+    this.fsImpl = fsImpl;
+    this.now = now;
+    this.start = start;
+  }
+
+  /**
+   * Appends the records, one line each, in one open-and-write to the partition named for the UTC
+   * date of the first line. Never throws; a fault writes nothing.
+   * @param {Array<{kind: string}>} records
+   * @returns {void}
+   */
+  write(records     )       {
+    try {
+      if (telemetryOff(this.env) || !Array.isArray(records)) return;
+      const registry = this.registry || shippedRegistry();
+      const lines           = [];
+      let first = '';
+      for (const record of records) {
+        let line      = null;
+        try { line = this.line(registry, record); } catch { line = null; } // a hostile record costs only itself
+        if (!line) continue;
+        if (!first) first = line.timestamp;
+        lines.push(JSON.stringify(line));
+      }
+      if (!lines.length) return;
+      const { dir: ledgerDir } = resolveRunsLocation({ start: this.start, env: this.env, fsImpl: this.fsImpl });
+      const dir = path.join(ledgerDir, 'telemetry');
+      // Non-recursive: when the ledger directory is absent this throws ENOENT and nothing is written or invented.
+      try {
+        this.fsImpl.mkdirSync(dir, { recursive: false });
+      } catch (error     ) {
+        if (error?.code !== 'EEXIST') throw error;
+      }
+      this.append(path.join(dir, `${first.slice(0, 10)}.jsonl`), Buffer.from(`${lines.join('\n')}\n`, 'utf8'));
+    } catch {
+      // A telemetry fault changes no outcome (FR-002, NFR-005): there is nothing to report to.
+    }
+  }
+
+  /**
+   * Appends to a regular file and nothing else. A FIFO with no reader would block a plain open
+   * forever, so: lstat first and skip anything that exists and is not a regular file (FIFO,
+   * directory, socket, device, symlink); then open O_NONBLOCK|O_NOFOLLOW so a swap between the lstat
+   * and the open fails (ENXIO, ELOOP) instead of blocking or following; then fstat the descriptor.
+   */
+  append(file        , data        )       {
+    let known      = null;
+    try {
+      known = this.fsImpl.lstatSync(file);
+    } catch (error     ) {
+      if (error?.code !== 'ENOENT') return;
+    }
+    if (known && !known.isFile()) return;
+    const { O_WRONLY, O_APPEND, O_CREAT, O_NOFOLLOW = 0, O_NONBLOCK = 0 } = nodeFs.constants;
+    const fd = this.fsImpl.openSync(file, O_WRONLY | O_APPEND | O_CREAT | O_NOFOLLOW | O_NONBLOCK, 0o666);
+    try {
+      if (!this.fsImpl.fstatSync(fd).isFile()) return;
+      for (let done = 0; done < data.length;) done += this.fsImpl.writeSync(fd, data, done);
+    } finally {
+      this.fsImpl.closeSync(fd);
+    }
+  }
+
+  /** The sanitised line for one record, or null when it has no registered `kind`. */
+  line(registry     , record     )      {
+    if (!record || typeof record !== 'object' || Array.isArray(record)) return null;
+    const kind = record.kind;
+    if (typeof kind !== 'string' || !Object.hasOwn(registry.kinds, kind)) return null;
+    const vocabularies = registry.vocabularies;
+    const vocabulary             = (name) => {
+      if (Object.hasOwn(DERIVED_VOCABULARIES, name)) {
+        this.derived ??= derivedVocabularies(this.repoRoot);
+        return this.derived[name] ?? null;
+      }
+      return vocabularies && Object.hasOwn(vocabularies, name) ? vocabularies[name] : null;
+    };
+    const timestamp = typeof record.timestamp === 'string' && ISO_MS.test(record.timestamp)
+      ? record.timestamp
+      : this.now().toISOString();
+    // Identity comes from the environment only (a caller-supplied value is ignored), as for the ledger.
+    const identity = identityFields(this.env);
+    const out      = {
+      timestamp,
+      kind,
+      run: identity.run ?? null,
+      lineage: identity.lineage ?? null,
+      attempt: identity.attempt === undefined ? null : Number(identity.attempt),
+    };
+    const fields = registry.kinds[kind].fields || {};
+    for (const key of Object.keys(fields)) {
+      if (!Object.hasOwn(record, key)) continue;
+      out[key] = coerce(fields[key].type, record[key], vocabulary);
+    }
+    return out;
+  }
+}
+
+module.exports = { SAFE_TOKEN, DERIVED_VOCABULARIES, derivedVocabularies, telemetryOff, TelemetryWriter };

package/src/runtime/trace/views.js

@@ -451,6 +451,7 @@ function buildDiscover(read     , { providerHealth = null, gapMs = SESSION_GAP_M
 
 module.exports = {
   SESSION_GAP_MS,
+  percentile,
   groupSessions,
   buildTrace,
   buildStats,

package/src/runtime/transcripts/command.js

@@ -0,0 +1,98 @@
+'use strict';
+
+/**
+ * `doflow transcript` (093 V8): the read-only per-agent transcript verb. `--action read --agent <key>` prints
+ * one agent's recent events with DoFlow's own record events (IC-022, `readAgent`); `--action stats` prints the
+ * project's traffic and who works with whom (IC-023, `computeStats`). Run with `cwd` = a project. It writes
+ * nothing: no state, no config home, no harness home, no upkeep.
+ */
+
+const { finishRuntime, captureCaught } = require('../cli-result.js');
+
+const ACTION_FLAGS                              = {
+  read: new Set(['--action', '--agent', '--cursor', '--limit', '--json']),
+  stats: new Set(['--action', '--window', '--json']),
+};
+const AGENT_KEY = /^[0-9a-f]{16}$/;
+const CURSOR = /^[0-9]+:[0-9]+:[0-9]+:[0-9]+$/;
+const DIGITS = /^[0-9]+$/;
+
+const dash = (value         )         => (value === null || value === undefined ? '-' : String(value));
+
+/** The text form of `read`: a header, one line per event and a footer. Text and arguments are JSON-quoted (one line each). */
+function readLines(body     )           {
+  const lines = [
+    `agent ${body.agentKey} harness ${dash(body.harness)} reader ${dash(body.reader.id)} ${body.reader.status} transcript ${body.transcript.linked ? 'linked' : body.transcript.reason}`,
+  ];
+  for (const e of body.events) {
+    const parts = [`event ${e.seq} ${dash(e.at)} ${e.kind}`];
+    if (e.model !== null) parts.push(`model ${e.model}`);
+    if (e.tool) parts.push(`tool ${dash(e.tool.name)} status ${dash(e.tool.status)} bytes ${dash(e.tool.bytes)} ms ${dash(e.tool.durationMs)}`);
+    if (e.text !== null) parts.push(`text ${JSON.stringify(e.text)}`);
+    if (e.args !== null) parts.push(`args ${JSON.stringify(e.args)}`);
+    if (e.cut) parts.push('cut');
+    if (e.tokens) parts.push(`tokens in ${dash(e.tokens.input)} out ${dash(e.tokens.output)} cache-read ${dash(e.tokens.cacheRead)} cache-write ${dash(e.tokens.cacheWrite)} reasoning ${dash(e.tokens.reasoning)}`);
+    if (e.record) parts.push(`record ${e.record.type} task ${dash(e.record.task)} result ${dash(e.record.result)}`);
+    lines.push(parts.join(' '));
+  }
+  lines.push(`cursor ${body.cursor} reset ${body.reset} eof ${body.eof} other ${body.otherRecords} unparsable ${body.unparsable} masked ${body.masked} warnings ${body.warnings.join(',') || '-'}`);
+  return lines;
+}
+
+/** The text form of `stats`: keys, models and counts only. */
+function statsLines(body     )           {
+  return [
+    `project ${body.projectKey} window ${body.windowMin} min`,
+    ...body.agents.map((a     ) => `agent ${a.agentKey} harness ${dash(a.harness)} model ${dash(a.model)} events/min ${dash(a.eventsPerMin)} tool-calls ${dash(a.toolCalls)} tool-errors ${dash(a.toolErrors)} tool-ms ${a.toolDurationMs ? `p50 ${a.toolDurationMs.p50} max ${a.toolDurationMs.max} n ${a.toolDurationMs.n}` : '-'} tokens ${a.tokens ? `in ${dash(a.tokens.input)} out ${dash(a.tokens.output)}` : '-'} last-record ${dash(a.lastRecordAt)}`),
+    ...body.models.map((m     ) => `model ${m.model} agents ${m.agents} events/min ${dash(m.eventsPerMin)} tool-calls ${dash(m.toolCalls)}`),
+    ...body.pairs.map((p     ) => `pair ${p.a} ${p.b} ${p.basis}${p.task ? ` task ${p.task}` : ''}${p.tasks ? ` tasks ${p.tasks.join(',')}` : ''}`),
+    `not-checked ${body.notChecked}`,
+  ];
+}
+
+function handleTranscriptCommand({
+  action, agent, cursor, limit, window, json = false, flags = [], env = process.env, cwd = process.cwd(), exec, alive, now, out = (line        ) => console.log(line),
+}      = {})         {
+  const usage = (message        )         => {
+    out(json ? JSON.stringify({ ok: false, error: 'usage', message }) : `doflow transcript: ${message}`);
+    return finishRuntime(2);
+  };
+  if (action !== 'read' && action !== 'stats') return usage('action must be read or stats');
+  const extra = (flags            ).map((flag) => flag.split('=')[0]).find((flag) => !ACTION_FLAGS[action].has(flag));
+  if (extra !== undefined) return usage(`unsupported flag ${extra} for ${action}; only ${[...ACTION_FLAGS[action]].join(', ')} apply`);
+
+  let count                    ;
+  let minutes                    ;
+  if (action === 'read') {
+    if (typeof agent !== 'string' || !AGENT_KEY.test(agent)) return usage('--agent must be an agent key of 16 hex characters');
+    if (cursor !== undefined && (typeof cursor !== 'string' || !CURSOR.test(cursor))) return usage('--cursor must be the cursor of an earlier read');
+    if (limit !== undefined) {
+      if (typeof limit !== 'string' || !DIGITS.test(limit) || Number(limit) < 1) return usage('--limit must be a whole number of 1 or more (at most 500 are returned)');
+      count = Math.min(500, Number(limit));
+    }
+  } else if (window !== undefined) {
+    if (typeof window !== 'string' || !DIGITS.test(window) || Number(window) < 1 || Number(window) > 60) return usage('--window must be a whole number of minutes, 1 to 60');
+    minutes = Number(window);
+  }
+
+  try {
+    const common = { env, cwd, ...(exec ? { exec } : {}), ...(alive ? { alive } : {}), ...(now ? { now } : {}) };
+    const result = action === 'read'
+      ? require('./read.js').readAgent({ ...common, agent, cursor, limit: count })
+      : require('./stats.js').computeStats({ ...common, ...(minutes !== undefined ? { windowMin: minutes } : {}) });
+    if (!result.ok) {
+      if (json) out(JSON.stringify({ v: 1, error: result.error }));
+      else console.error(`[ERROR] transcript: ${result.error}`);
+      return finishRuntime(1);
+    }
+    if (json) out(JSON.stringify(result.body));
+    else for (const line of action === 'read' ? readLines(result.body) : statsLines(result.body)) out(line);
+    return finishRuntime(0);
+  } catch (error     ) {
+    captureCaught(error, 'transcript', 1);
+    console.error(`[ERROR] transcript: ${error?.message || String(error)}`);
+    return finishRuntime(1);
+  }
+}
+
+module.exports = { handleTranscriptCommand };

package/src/runtime/transcripts/cursor.js

@@ -0,0 +1,326 @@
+'use strict';
+
+/**
+ * 093 V.4 (IC-022): the byte cursor, the bounded window read and the driver every transcript reader shares.
+ *
+ * A reader (`readers/<id>.ts`) is a `SPEC` of three small parts: its required keys, an optional `init`, and
+ * `parse(record, ctx)`, which returns the normalised events of one record. The driver owns the rest:
+ *  - the cursor `<inode>:<byteOffset>:<recordSeq>:<recordAtMs>`; a changed inode or a shorter file resets it
+ *    to the last 64 records (`reset: true`); a read with no cursor starts the same way with `reset: false`;
+ *  - at most 256 KiB per call, whole lines only: an unfinished last line is left for the next read;
+ *  - `otherRecords` (records and blocks never read into an event: thinking, prompts, attachments, unknown types),
+ *    `unparsable` (lines that are not a JSON object), and the `format-unrecognized` warning when more than 20 %
+ *    of the processed records are unparsable or lack the reader's required keys;
+ *  - text policy: every text-bearing string is masked with `maskBody` AFTER JSON decoding, then cut after
+ *    masking (reply 4 KiB, tool arguments 512 B) with `cut: true`. Never on the raw line (R§4.8): escaped JSON
+ *    such as `\"token\":\"...\"` inside a string slips past the key rules until it is decoded.
+ * Read-only: files are opened `'r'` and nothing is created or written. Ceilings: `recordSeq` counts events
+ * from the reset point, not from the start of the file; Claude usage dedup and the model of an event only see
+ * the current window, so a message split across two reads can count its usage twice.
+ */
+
+const fs = require('node:fs');
+const { createHash } = require('node:crypto');
+const { maskBody } = require('../mask.js');
+
+const MAX_READ_BYTES = 256 * 1024;
+const TAIL_RECORDS = 64;
+const DEFAULT_LIMIT = 200;
+const MAX_LIMIT = 500;
+const TEXT_CAP = 4096;
+const ARGS_CAP = 512;
+const MASK_MARGIN = 4096; // bytes kept past the cap before masking, so a secret cut by the cap is still whole when masked
+const LEAF_MAX = 8192;
+const UNRECOGNIZED_RATIO = 0.2;
+const LABEL = /^[A-Za-z0-9 ._:/@-]{1,64}$/;
+const CURSOR = /^(\d+):(\d+):(\d+):(\d+)$/;
+
+/** IC-004's label rule: a value that is not a short plain label is withheld (null for an absent value). */
+function label(value     )                {
+  if (value === null || value === undefined) return null;
+  return typeof value === 'string' && LABEL.test(value) ? value : '(withheld)';
+}
+
+function parseCursor(text     )                                                                    {
+  const m = typeof text === 'string' ? CURSOR.exec(text) : null;
+  if (!m) return null;
+  const [offset, seq, atMs] = [Number(m[2]), Number(m[3]), Number(m[4])];
+  return [offset, seq, atMs].every(Number.isSafeInteger) ? { ino: m[1], offset, seq, atMs } : null;
+}
+
+/** Milliseconds from an ISO string or an epoch-ms number; NaN when neither. */
+function toMs(at     )         {
+  if (typeof at === 'number') return Number.isFinite(at) ? at : NaN;
+  return typeof at === 'string' ? Date.parse(at) : NaN;
+}
+
+function toIso(at     )                {
+  const ms = toMs(at);
+  return Number.isFinite(ms) ? new Date(ms).toISOString() : null;
+}
+
+function callKey(id     )                {
+  return typeof id === 'string' || typeof id === 'number' ? createHash('sha256').update(String(id)).digest('hex').slice(0, 16) : null;
+}
+
+/** Bytes of a tool result's content, never the content itself. */
+function sizeOf(value     )                {
+  if (value === null || value === undefined) return null;
+  return Buffer.byteLength(typeof value === 'string' ? value : JSON.stringify(value) ?? '', 'utf8');
+}
+
+/** A token record with a number or null per field; null when nothing is known (unknown is never zero). */
+function tokens(fields                     )      {
+  const out                                = {};
+  for (const key of ['input', 'output', 'cacheRead', 'cacheWrite', 'reasoning']) {
+    out[key] = Number.isFinite(fields[key]) ? fields[key] : null;
+  }
+  return Object.values(out).some((v) => v !== null) ? out : null;
+}
+
+function cutBytes(text        , cap        )                                 {
+  const buf = Buffer.from(text, 'utf8');
+  if (buf.length <= cap) return { text, cut: false };
+  let end = cap;
+  while (end > 0 && (buf[end] & 0xc0) === 0x80) end -= 1; // never split a character
+  return { text: buf.toString('utf8', 0, end), cut: true };
+}
+
+/** Reply text: mask (after decoding), then cut. */
+function capText(value     , cap        )                                                 {
+  const s = String(value);
+  const long = s.length > cap + MASK_MARGIN;
+  const m = maskBody(long ? s.slice(0, cap + MASK_MARGIN) : s);
+  const r = cutBytes(m.text, cap);
+  return { text: r.text, cut: r.cut || long, masked: m.masked };
+}
+
+/**
+ * Tool arguments: a JSON string is decoded, every string leaf is masked on its own decoded text (so a
+ * quoted key inside an embedded JSON string is plain again), the structure is rendered, the rendering is
+ * masked once more (a `{"password":"x"}` pair only shows its key next to its value there), then cut.
+ */
+function capArgs(value     , cap        )                                                 {
+  let masked = 0;
+  let leaves = 0;
+  let v = value;
+  if (typeof v === 'string') {
+    try { const parsed = JSON.parse(v); if (parsed !== null && typeof parsed === 'object') v = parsed; } catch { /* plain text */ }
+  }
+  const walk = (x     , depth        )      => {
+    if (typeof x === 'string') {
+      if (++leaves > 64) return '...';
+      const r = maskBody(x.length > LEAF_MAX ? x.slice(0, LEAF_MAX) : x);
+      masked += r.masked;
+      return r.text;
+    }
+    if (x === null || typeof x !== 'object') return x;
+    if (depth > 6) return '...';
+    if (Array.isArray(x)) return x.slice(0, 64).map((item) => walk(item, depth + 1));
+    const out                      = {};
+    for (const key of Object.keys(x).slice(0, 64)) out[key] = walk(x[key], depth + 1);
+    return out;
+  };
+  const walked = walk(v, 0);
+  const r = capText(typeof walked === 'string' ? walked : JSON.stringify(walked) ?? '', cap);
+  return { text: r.text, cut: r.cut, masked: masked + r.masked };
+}
+
+function readRange(fd        , from        , to        )         {
+  const buf = Buffer.alloc(Math.max(0, to - from));
+  let got = 0;
+  while (got < buf.length) {
+    const n = fs.readSync(fd, buf, got, buf.length - got, from + got);
+    if (n === 0) break;
+    got += n;
+  }
+  return got < buf.length ? buf.subarray(0, got) : buf;
+}
+
+                                                                               
+
+/**
+ * Whole lines of `buf` (absolute offset `base` for its first byte). `skipFirst` drops the leading partial
+ * line (the buffer then starts one byte before the first wanted byte). Blank lines are skipped but consumed.
+ */
+function splitLines(buf        , base        , skipFirst         )                                               {
+  const lines         = [];
+  let p = 0;
+  if (skipFirst) {
+    const i = buf.indexOf(10);
+    p = i === -1 ? buf.length : i + 1;
+  }
+  for (let nl = buf.indexOf(10, p); nl !== -1 && p < buf.length; nl = buf.indexOf(10, p)) {
+    const text = buf.toString('utf8', p, nl);
+    if (text.trim() !== '') lines.push({ text, start: base + p, end: base + nl + 1 });
+    p = nl + 1;
+  }
+  return { lines, end: base + p, rest: buf.length - p };
+}
+
+/**
+ * The window one call reads. `lines` are the records to process; `prior()` returns the raw lines before the
+ * window (Copilot differences its cumulative usage against them).
+ */
+function openWindow(file        , cursorText     , maxBytes        , tailRecords         = TAIL_RECORDS)      {
+  const fd = fs.openSync(file, 'r');
+  try {
+    const st = fs.fstatSync(fd, { bigint: true });
+    const ino = String(st.ino);
+    const size = Number(st.size);
+    const cursor = parseCursor(cursorText);
+    const reset = cursor !== null && (cursor.ino !== ino || size < cursor.offset);
+    const tail = cursor === null || reset;
+    const from = tail ? Math.max(0, size - maxBytes) : (cursor       ).offset;
+    const skipFirst = tail && from > 0;
+    const base = skipFirst ? from - 1 : from;
+    const buf = readRange(fd, base, Math.min(size, from + maxBytes));
+    const split = splitLines(buf, base, skipFirst);
+    let { lines } = split;
+    if (tail && lines.length > tailRecords) lines = lines.slice(-tailRecords);
+    const windowEnd = base + buf.length;
+    // One line longer than the whole window: consume it as a single unparsable record.
+    if (!skipFirst && lines.length === 0 && split.rest > 0 && windowEnd < size) {
+      lines = [{ text: '', start: from, end: windowEnd, oversize: true }];
+    }
+    const startOffset = lines.length ? lines[0].start : split.end;
+    return {
+      ino, size, cursor, reset, tail, lines, startOffset, completeEnd: lines.length ? lines[lines.length - 1].end : split.end,
+      reachedEnd: windowEnd >= size,
+      prior()           {
+        if (startOffset === 0) return [];
+        const pFrom = Math.max(0, startOffset - maxBytes);
+        const pBase = pFrom > 0 ? pFrom - 1 : 0;
+        const pfd = fs.openSync(file, 'r');
+        try { return splitLines(readRange(pfd, pBase, startOffset), pBase, pFrom > 0).lines.map((l) => l.text); } finally { fs.closeSync(pfd); }
+      },
+    };
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+/** The first `maxLines` JSON-object records of a file (at most 64 KiB), for a reader's `header`. */
+function headRecords(file        , maxLines         = 8, maxBytes         = 64 * 1024)        {
+  const fd = fs.openSync(file, 'r');
+  try {
+    const out        = [];
+    const { lines } = splitLines(readRange(fd, 0, maxBytes), 0, false);
+    for (const line of lines) {
+      if (out.length >= maxLines) break;
+      try { const rec = JSON.parse(line.text); if (rec && typeof rec === 'object') out.push(rec); } catch { /* torn */ }
+    }
+    return out;
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+/** A small JSON companion file (at most 256 KiB), or null when absent or unreadable. */
+function readJsonFile(file        )      {
+  try {
+    const fd = fs.openSync(file, 'r');
+    try {
+      const size = fs.fstatSync(fd).size;
+      if (size > MAX_READ_BYTES) return null;
+      const parsed = JSON.parse(readRange(fd, 0, size).toString('utf8'));
+      return parsed !== null && typeof parsed === 'object' ? parsed : null;
+    } finally { fs.closeSync(fd); }
+  } catch { return null; }
+}
+
+function makeContext(mode        , agentKey     )      {
+  const ctx      = { mode, agentKey, pending: 0, state: {}, calls: new Map                                             () };
+  ctx.tool = (name     , id     , extra      = {}) => ({
+    name: label(name), callKey: callKey(id), status: extra.status ?? null, bytes: extra.bytes ?? null, durationMs: extra.durationMs ?? null,
+  });
+  ctx.noteCall = (id     , at     , name     ) => { if (id !== undefined && id !== null) ctx.calls.set(String(id), { ms: toMs(at), name: typeof name === 'string' ? name : null }); };
+  ctx.callOf = (id     ) => (id === undefined || id === null ? undefined : ctx.calls.get(String(id)));
+  /** Milliseconds from the call's record to `at`, when both are in the window. */
+  ctx.durationOf = (id     , at     ) => {
+    const call = ctx.callOf(id);
+    const d = call ? toMs(at) - call.ms : NaN;
+    return Number.isFinite(d) && d >= 0 ? d : null;
+  };
+  ctx.event = (kind        , at     , f      = {}) => {
+    let text                = null;
+    let args                = null;
+    let cut = false;
+    if (mode === 'text') {
+      if (f.text !== undefined && f.text !== null) { const r = capText(f.text, TEXT_CAP); text = r.text; cut = r.cut; ctx.pending += r.masked; }
+      if (f.args !== undefined && f.args !== null) { const r = capArgs(f.args, ARGS_CAP); args = r.text; cut = cut || r.cut; ctx.pending += r.masked; }
+    }
+    return {
+      seq: 0, at: toIso(at), kind, agentKey: ctx.agentKey, model: label(f.model ?? ctx.state.model ?? null),
+      tool: f.tool ?? null, text, args, cut, tokens: f.tokens ?? null, record: null,
+    };
+  };
+  return ctx;
+}
+
+/**
+ * Runs one reader over one transcript file. `opts`: `file`, `mode` ('text' | 'metadata'), `cursor`, `limit`
+ * (default 200, at most 500), `agentKey`, `companion` (Kiro's `.json`), `maxBytes` (default 256 KiB), `tailRecords`
+ * (records kept by a read with no cursor, default 64; the traffic stats read the whole 256 KiB tail).
+ * Throws the fs error when the file cannot be opened; the caller maps it to `not-found`.
+ */
+function readTranscript(spec     , opts     )      {
+  const mode = opts.mode === 'metadata' ? 'metadata' : 'text';
+  const limit = Math.min(MAX_LIMIT, Math.max(1, Number.isInteger(opts.limit) ? opts.limit : DEFAULT_LIMIT));
+  const win = openWindow(opts.file, opts.cursor, opts.maxBytes ?? MAX_READ_BYTES, opts.tailRecords ?? TAIL_RECORDS);
+  const ctx = makeContext(mode, opts.agentKey ?? null);
+  if (spec.init) ctx.state = spec.init(win, opts, ctx) ?? {};
+
+  const events        = [];
+  let seq = win.tail ? 0 : win.cursor.seq;
+  let atMs = win.tail ? 0 : win.cursor.atMs;
+  let committedEnd                = null;
+  let [other, unparsable, bad, processed, masked] = [0, 0, 0, 0, 0];
+  let stopped = false;
+
+  for (const line of win.lines) {
+    let rec      = null;
+    if (!line.oversize) { try { rec = JSON.parse(line.text); } catch { /* counted below */ } }
+    ctx.pending = 0;
+    let out     ;
+    if (rec === null || typeof rec !== 'object' || Array.isArray(rec)) out = { events: [], other: 0, unparsable: 1 };
+    else if (!spec.requiredKeys.every((key        ) => rec[key] !== undefined)) out = { events: [], other: 1, bad: 1 };
+    else {
+      out = spec.parse(rec, ctx);
+      if (out.other === undefined) out.other = out.events.length ? 0 : 1;
+    }
+    if (events.length > 0 && events.length + out.events.length > limit) { stopped = true; break; }
+    for (const event of out.events) { event.seq = seq; seq += 1; events.push(event); }
+    other += out.other;
+    unparsable += out.unparsable ?? 0;
+    bad += out.bad ?? 0;
+    masked += ctx.pending;
+    processed += 1;
+    committedEnd = line.end;
+    const ms = rec ? toMs(spec.at ? spec.at(rec) : rec.timestamp) : NaN;
+    if (Number.isFinite(ms)) atMs = ms;
+  }
+
+  const offset = committedEnd ?? (win.tail ? win.startOffset : win.cursor.offset);
+  let eof = !stopped && win.reachedEnd;
+  if (spec.extra) {
+    ctx.pending = 0;
+    const more = spec.extra(ctx, win, opts, limit - events.length);
+    for (const event of more.events) { event.seq = seq; seq += 1; events.push(event); }
+    masked += ctx.pending;
+    if (Number.isFinite(more.atMs)) atMs = more.atMs;
+    if (more.more) eof = false;
+  }
+
+  const warnings           = [];
+  if (processed > 0 && (unparsable + bad) / processed > UNRECOGNIZED_RATIO) warnings.push('format-unrecognized');
+  return {
+    events, cursor: `${win.ino}:${offset}:${seq}:${Math.trunc(atMs)}`, reset: win.reset, eof,
+    otherRecords: other, unparsable, masked, warnings,
+  };
+}
+
+module.exports = {
+  MAX_READ_BYTES, TAIL_RECORDS, DEFAULT_LIMIT, MAX_LIMIT, TEXT_CAP, ARGS_CAP, UNRECOGNIZED_RATIO,
+  parseCursor, readTranscript, headRecords, readJsonFile, label, toMs, toIso, sizeOf, tokens,
+};