attesso 0.4.1 → 0.6.0

package/src/usage.mjs

@@ -0,0 +1,96 @@
+// Usage is reported by the agent or the recorder, never inferred from a tool
+// proposal. The page may show exact call counts without usage; it must not
+// convert task totals into a per-call saving.
+const numeric = (value, field) => {
+  const number = Number(value);
+  if (!Number.isFinite(number) || number < 0) throw new Error(`usage.${field} must be a non-negative number`);
+  return number;
+};
+
+export function normalizeUsage(entry) {
+  const meta = entry.meta ?? {};
+  const source = meta.usage && typeof meta.usage === 'object' ? meta.usage : meta;
+  const hasUsage = entry.action === 'llm.session'
+    || source.tokens !== undefined
+    || source.input_tokens !== undefined
+    || source.output_tokens !== undefined
+    || source.cached_tokens !== undefined
+    || source.cost_usd !== undefined;
+  if (!hasUsage) return null;
+  const input = source.input_tokens === undefined ? 0 : numeric(source.input_tokens, 'input_tokens');
+  const output = source.output_tokens === undefined ? 0 : numeric(source.output_tokens, 'output_tokens');
+  const total = source.tokens === undefined ? input + output : numeric(source.tokens, 'tokens');
+  return {
+    task: entry.task ?? '(unscoped)',
+    seq: entry.action === 'llm.session' ? null : entry.seq,
+    tokens: total,
+    cached_tokens: source.cached_tokens === undefined ? 0 : numeric(source.cached_tokens, 'cached_tokens'),
+    cost_usd: source.cost_usd === undefined ? 0 : numeric(source.cost_usd, 'cost_usd'),
+    api_calls: source.api_calls === undefined ? 0 : numeric(source.api_calls, 'api_calls'),
+    source: entry.action === 'llm.session' ? 'session' : 'call',
+  };
+}
+
+export function usageForDay(catalog, { day, timeZone }) {
+  const tasks = new Map();
+  let invalid = 0;
+  catalog.scanDay(day, timeZone, (entry) => {
+    const task = entry.task ?? '(unscoped)';
+    const item = tasks.get(task) ?? {
+      task, calls: 0, blocked: 0, tokens: 0, cached_tokens: 0,
+      cost_usd: 0, api_calls: 0, measured: false, invalid: 0,
+    };
+    if (entry.action === 'llm.session') {
+      try {
+        const usage = normalizeUsage(entry);
+        if (usage) {
+          item.tokens += usage.tokens;
+          item.cached_tokens += usage.cached_tokens;
+          item.cost_usd += usage.cost_usd;
+          item.api_calls += usage.api_calls;
+          item.measured = true;
+        }
+      } catch {
+        item.invalid += 1;
+        invalid += 1;
+      }
+      tasks.set(task, item);
+      return;
+    }
+    item.calls += 1;
+    if (entry.decision === 'DENY') item.blocked += 1;
+    try {
+      const usage = normalizeUsage(entry);
+      if (usage) {
+        item.tokens += usage.tokens;
+        item.cached_tokens += usage.cached_tokens;
+        item.cost_usd += usage.cost_usd;
+        item.api_calls += usage.api_calls;
+        item.measured = true;
+      }
+    } catch {
+      item.invalid += 1;
+      invalid += 1;
+    }
+    tasks.set(task, item);
+  });
+  const list = [...tasks.values()].map((item) => ({ ...item, cost_usd: Number(item.cost_usd.toFixed(6)) }));
+  const totals = list.reduce((sum, item) => ({
+    calls: sum.calls + item.calls,
+    blocked: sum.blocked + item.blocked,
+    measured_calls: sum.measured_calls + (item.measured ? item.calls : 0),
+    tokens: sum.tokens + item.tokens,
+    cached_tokens: sum.cached_tokens + item.cached_tokens,
+    cost_usd: Number((sum.cost_usd + item.cost_usd).toFixed(6)),
+    api_calls: sum.api_calls + item.api_calls,
+  }), { calls: 0, blocked: 0, measured_calls: 0, tokens: 0, cached_tokens: 0, cost_usd: 0, api_calls: 0 });
+  return {
+    day,
+    tasks: list,
+    totals,
+    coverage: totals.calls ? totals.measured_calls / totals.calls : 0,
+    invalid,
+    generated_at: new Date().toISOString(),
+  };
+}
+

package/src/watch.mjs

@@ -0,0 +1,78 @@
+// A live reader over the ledger. It keeps a byte offset and a partial-line
+// buffer, so watching a large ledger does not reread it on every tick.
+import { closeSync, openSync, readSync, statSync } from 'node:fs';
+import { StringDecoder } from 'node:string_decoder';
+import { parseLine } from './jsonl.mjs';
+import { paths } from './store.mjs';
+
+const CHUNK = 64 * 1024;
+
+function readRange(file, start, end) {
+  const handle = openSync(file, 'r');
+  const buffer = Buffer.alloc(end - start);
+  let offset = 0;
+  try {
+    while (offset < buffer.length) {
+      const bytes = readSync(handle, buffer, offset, buffer.length - offset, start + offset);
+      if (bytes === 0) break;
+      offset += bytes;
+    }
+  } finally {
+    closeSync(handle);
+  }
+  return buffer.subarray(0, offset);
+}
+
+const wait = (ms, signal) =>
+  new Promise((resolve) => {
+    const done = () => {
+      clearTimeout(timer);
+      signal?.removeEventListener('abort', done);
+      resolve();
+    };
+    const timer = setTimeout(done, ms);
+    signal?.addEventListener('abort', done, { once: true });
+  });
+
+export async function* watchEntries(
+  dir,
+  { fromSeq = Number.MAX_SAFE_INTEGER, task, interval = 250, signal } = {},
+) {
+  const file = paths(dir).ledger;
+  const decoder = new StringDecoder('utf8');
+  let buffer = '';
+  let offset = 0;
+  let index = 0;
+
+  const parse = () => {
+    const entries = [];
+    let newline;
+    while ((newline = buffer.indexOf('\n')) !== -1) {
+      const line = buffer.slice(0, newline);
+      buffer = buffer.slice(newline + 1);
+      index += 1;
+      const entry = parseLine(line, index);
+      if ((task === undefined || entry.task === task) && entry.seq > fromSeq) entries.push(entry);
+    }
+    return entries;
+  };
+
+  let size = statSync(file).size;
+  while (offset < size) {
+    const end = Math.min(offset + CHUNK, size);
+    buffer += decoder.write(readRange(file, offset, end));
+    offset = end;
+    for (const entry of parse()) yield entry;
+  }
+
+  while (!signal?.aborted) {
+    await wait(interval, signal);
+    if (signal?.aborted) return;
+    size = statSync(file).size;
+    if (size < offset) throw new Error('the ledger shrank while watch was reading it');
+    if (size === offset) continue;
+    buffer += decoder.write(readRange(file, offset, size));
+    offset = size;
+    for (const entry of parse()) yield entry;
+  }
+}