@xhulz/nina 0.32.0 → 0.34.0

package/src/commands/export.mjs

@@ -25,7 +25,7 @@ import { spawn } from 'node:child_process';
 import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { readRun, runFile } from '../agentrun.mjs';
-import { BATCH, SETTLE_MINUTES, postScore, postScores, postSpans, scoreOf, settled, spanOf, spansOf } from '../langfuse.mjs';
+import { BATCH, SETTLE_MINUTES, contextMode, postScore, postScores, postSpans, scoreOf, settled, spanOf, spansOf } from '../langfuse.mjs';
 import { runOf, transcriptsOf } from '../transcripts.mjs';
 import { exportsDir, snapshotsDir } from '../paths.mjs';
 import { readConfig, statusPath, targetOf } from './langfuse.mjs';
@@ -214,7 +214,7 @@ export async function exportCommand(argv, ctx = {}) {
     const release = await lock(only);
     if (!release) return 0;
     try {
-      const result = await exportProject({ slug: only, name: projectName(only), file: join(snapshotsDir(), `${only}.jsonl`), target, now: ctx.now, since: setting.since, quiet: true, content: setting.content });
+      const result = await exportProject({ slug: only, name: projectName(only), file: join(snapshotsDir(), `${only}.jsonl`), target, now: ctx.now, since: setting.since, quiet: true, content: contextMode(setting) });
       if (result.spans > 0 || result.scores > 0 || result.error) {
         // The same failure again is not news: it was reported once, and repeating it every turn it is
         // retried would be the noise the detectors exist to remove.
@@ -251,7 +251,7 @@ export async function exportCommand(argv, ctx = {}) {
       continue;
     }
     try {
-      const content = Boolean(config.projects[slug]?.content);
+      const content = contextMode(config.projects[slug]);
       if ((await exportProject({ slug, name, file: join(dir, `${slug}.jsonl`), target, dry, now: ctx.now, content })).error) failed = true;
     } finally {
       await release();
@@ -265,7 +265,7 @@ export async function exportCommand(argv, ctx = {}) {
  *
  * @returns {Promise<{spans: number, scores: number, error: string|null}>} What went, and why the rest did not.
  */
-async function exportProject({ slug, name, file, target, dry, now, since = '', quiet = false, content = false }) {
+async function exportProject({ slug, name, file, target, dry, now, since = '', quiet = false, content = null }) {
   const say = quiet ? () => {} : (line) => console.log(line);
   const records = await recordsOf(file);
   const sent = await sentOf(slug);
@@ -282,7 +282,8 @@ async function exportProject({ slug, name, file, target, dry, now, since = '', q
   const tail = () => (notes.length ? ` — ${notes.join('; ')}` : '');
 
   if (dry) {
-    say(`  ${name}: would send ${todo.spans.length} trace(s)${content ? " with each stage's context" : ''} and ${todo.scores.length} score(s) to ${target.host}${tail()}`);
+    const what = content === 'prompts' ? " with each stage's prompt and report" : content ? " with each stage's context" : '';
+    say(`  ${name}: would send ${todo.spans.length} trace(s)${what} and ${todo.scores.length} score(s) to ${target.host}${tail()}`);
     if (todo.spans[0]) say(`    e.g. ${JSON.stringify(spanOf(todo.spans[0], name))}`);
     return { spans: 0, scores: 0, error: null };
   }
@@ -319,11 +320,12 @@ async function exportProject({ slug, name, file, target, dry, now, since = '', q
     if (error) break;
     const run = content ? await readRun(runFile(transcriptsOf(slug), record), record.round ?? 1) : null;
     if (content && !run) bare += 1;
-    let built = spansOf(record, name, run);
+    const sending = { prompts: content === 'prompts' };
+    let built = spansOf(record, name, run, {}, sending);
     let size = JSON.stringify(built).length;
     for (const limits of SMALLER) {
       if (size <= MAX_BODY) break;
-      built = spansOf(record, name, run, limits);
+      built = spansOf(record, name, run, limits, sending);
       size = JSON.stringify(built).length;
     }
     // Cutting its texts bounds each one, not how many calls a stage made. One that still does not fit

package/src/commands/langfuse.mjs

@@ -2,14 +2,15 @@
  * `nina langfuse` — the keys, set once, and which projects send their runs to Langfuse on their own.
  *
  *   nina langfuse login [--host <url>]            ask for the keys, check them against Langfuse, keep them
- *   nina langfuse on [--project <dir>] [--content]   send this project's runs after every turn
+ *   nina langfuse on [--project <dir>] [--content | --prompts]   send this project's runs after every turn
  *   nina langfuse off [--project <dir>]
  *   nina langfuse status
  *
  * Once a project is on, nobody runs an export: the `lessons` detector every composed project runs
  * already snapshots the project each turn, and it starts the export in the background whenever a run
  * is ready to go. What it sends is metadata unless the project is turned on with `--content`, which adds
- * each stage's own context — see `src/langfuse.mjs`.
+ * each stage's own context, or with `--prompts`, which adds only what passed between the agents: the
+ * prompt each stage was given and the report it handed back — see `src/langfuse.mjs`.
  *
  * The keys live in `~/.nina/exports/langfuse.json`, readable by the owner only, beside the record of what
  * was sent; `LANGFUSE_PUBLIC_KEY`, `LANGFUSE_SECRET_KEY` and `LANGFUSE_HOST` override them. They are asked
@@ -21,20 +22,26 @@
 import { chmod, mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
 import { join, resolve } from 'node:path';
 import { createInterface } from 'node:readline';
-import { DEFAULT_HOST, projectOf } from '../langfuse.mjs';
+import { DEFAULT_HOST, contextMode, projectOf } from '../langfuse.mjs';
 import { exportsDir, slugFor } from '../paths.mjs';
 import { projectName } from './stats.mjs';
 
 /** Where the keys and the switches live. */
 export const configPath = () => join(exportsDir(), 'langfuse.json');
 
+/** What a project sends, in words, by `contextMode`. */
+const LABELS = { full: "with each stage's own context", prompts: "with each stage's prompt and report", none: 'as metadata only' };
+
+/** The same, as `status` lists it. */
+const SHORT = { full: 'with context', prompts: 'with prompts and reports', none: 'metadata only' };
+
 /** Where the background export leaves what it last did, per project. */
 export const statusPath = (slug) => join(exportsDir(), 'langfuse', `${slug}.status.json`);
 
 /**
  * The configuration on disk: keys, host, and the projects that are on.
  *
- * @returns {Promise<{publicKey?: string, secretKey?: string, host?: string, projects: Record<string, {content: boolean, since: string}>}>}
+ * @returns {Promise<{publicKey?: string, secretKey?: string, host?: string, projects: Record<string, {content: boolean|'prompts', since: string}>}>}
  */
 export async function readConfig() {
   try {
@@ -113,7 +120,7 @@ export async function langfuse(argv, ctx = {}) {
     }
     await writeConfig({ ...config, host, publicKey, secretKey });
     console.log(`  ✓ the keys open "${opened.project}" at ${host}; kept in ${configPath()}, readable by you only`);
-    console.log('    next, in each project that should send: `nina langfuse on` (add `--content` for each stage\'s own context)\n');
+    console.log('    next, in each project that should send: `nina langfuse on` (add `--prompts` for what passed between the agents, or `--content` for each stage\'s whole context)\n');
     return 0;
   }
 
@@ -123,13 +130,21 @@ export async function langfuse(argv, ctx = {}) {
       console.error('  no keys yet — `nina langfuse login` first\n');
       return 2;
     }
-    const content = argv.includes('--content');
+    if (argv.includes('--content') && argv.includes('--prompts')) {
+      console.error('  --content already sends the prompts; pass one of the two\n');
+      return 2;
+    }
+    const content = argv.includes('--content') ? true : argv.includes('--prompts') ? 'prompts' : false;
     await writeConfig({ ...config, projects: { ...config.projects, [slug]: { content, since: new Date().toISOString() } } });
-    console.log(`  ✓ ${project} sends its runs to ${target.host} from now on, after every turn, ${content ? "with each stage's own context" : 'as metadata only'}`);
-    if (content) {
+    console.log(`  ✓ ${project} sends its runs to ${target.host} from now on, after every turn, ${LABELS[contextMode({ content }) ?? 'none']}`);
+    if (content === true) {
       console.log("    each stage's prompt, messages, tool calls and report go with it — code and whatever the stages read included;");
       console.log('    obvious secrets are masked, and nothing more is: turn it on only where that code may leave this machine');
     }
+    if (content === 'prompts') {
+      console.log("    each stage's prompt and report go with it, and nothing it read, wrote or called between them;");
+      console.log('    a prompt carries whatever the orchestrator put in it, diffs and code included, and only obvious secrets are masked');
+    }
     console.log(`    the runs from before now stay here; \`nina export --langfuse --project ${slug}\` sends them, once`);
     console.log('    it runs from the `lessons` detector in this project\'s hooks — `nina check` says whether they are wired\n');
     return 0;
@@ -150,12 +165,12 @@ export async function langfuse(argv, ctx = {}) {
     for (const [name, setting] of on) {
       const last = JSON.parse(await readFile(statusPath(name), 'utf8').catch(() => 'null'));
       const said = !last ? 'nothing sent yet' : last.error ? `✗ ${last.at}: ${last.error}` : `last sent ${last.at}: ${last.spans} trace(s), ${last.scores} score(s)`;
-      console.log(`  ${projectName(name)}: ${setting.content ? 'with context' : 'metadata only'}, since ${setting.since.slice(0, 10)} — ${said}`);
+      console.log(`  ${projectName(name)}: ${SHORT[contextMode(setting) ?? 'none']}, since ${setting.since.slice(0, 10)} — ${said}`);
     }
     console.log('');
     return 0;
   }
 
-  console.error('  usage: nina langfuse login [--host <url>] | on [--project <dir>] [--content] | off [--project <dir>] | status\n');
+  console.error('  usage: nina langfuse login [--host <url>] | on [--project <dir>] [--content | --prompts] | off [--project <dir>] | status\n');
   return 2;
 }

package/src/commands/runs.mjs

@@ -32,7 +32,7 @@ const ENDS = {
  * stages first ran.
  *
  * @param {{runs: object[], end: string}} cycle
- * @returns {{start: string, end: string, minutes: number|null, cost: number, unpriced: number, name: string, how: string, stages: {role: string, runs: number, rounds: number, back: number}[], files: number|null}}
+ * @returns {{start: string, end: string, minutes: number|null, cost: number, unpriced: number, name: string, how: string, stages: {role: string, runs: number, rounds: number, back: number}[], files: number|null, peak: number|null}}
  */
 export function summarize(cycle) {
   const rounds = cycle.runs;
@@ -56,6 +56,7 @@ export function summarize(cycle) {
     stages.set(r.role, s);
   }
   const files = rounds.filter((r) => typeof r.files_touched === 'number').map((r) => r.files_touched);
+  const peaks = rounds.filter((r) => typeof r.context_peak === 'number').map((r) => r.context_peak);
   return {
     start,
     end,
@@ -66,6 +67,7 @@ export function summarize(cycle) {
     how: ENDS[cycle.end](rounds.at(-1)),
     stages: [...stages.values()].map((s) => ({ ...s, runs: s.runs.size })),
     files: files.length ? Math.max(...files) : null,
+    peak: peaks.length ? Math.max(...peaks) : null,
   };
 }
 
@@ -111,7 +113,10 @@ export async function runs(argv) {
       const count = s.rounds > s.runs ? `${s.rounds} rounds` : `${s.rounds}`;
       return `${pink(s.role)} ${count}${s.back ? amber(`, ${s.back} sent back`) : ''}`;
     });
-    console.log(`    ${chain.join(dim(' · '))}${c.files === null ? '' : dim(` · largest write ${c.files} file(s)`)}`);
+    console.log(
+      `    ${chain.join(dim(' · '))}${c.files === null ? '' : dim(` · largest write ${c.files} file(s)`)}` +
+        (c.peak === null ? '' : dim(` · context up to ${Math.round(c.peak / 1000)}k`)),
+    );
   }
   const total = shown.reduce((a, c) => a + c.cost, 0);
   const costliest = shown.reduce((a, c) => (c.cost > a.cost ? c : a), shown[0]);

package/src/commands/stats.mjs

@@ -223,6 +223,42 @@ function costReport(records) {
   console.log(bold(`    ${'all stages'.padEnd(20)}${String([...byRole.values()].flat().length).padStart(6)}${''.padStart(10)}${money(total).padStart(10)}`));
 }
 
+/**
+ * How each stage's rounds spent their context: turns, tool calls sent per turn, the context a turn
+ * re-read when the round began and at its largest, and how long the prompt that opened the round was. Every turn is billed the whole context again, so the
+ * cost of a round is its turns times its context, and a round that starts where a long one ended pays for
+ * all of it on every turn. The first rounds of a run are set beside the later ones, which are resumes.
+ *
+ * @param {object[]} records - The rounds in the window.
+ */
+function contextReport(records) {
+  const shaped = records.filter((r) => typeof r.turns === 'number' && r.turns > 0);
+  if (shaped.length === 0) return;
+  const median = (xs) => [...xs].sort((a, b) => a - b)[Math.floor(xs.length / 2)];
+  const k = (n) => (typeof n === 'number' ? `${Math.round(n / 1000)}k` : '—');
+  const chars = (xs) => (xs.length ? median(xs).toLocaleString('en-US') : '—');
+  console.log(heading('context', 'every turn re-reads the whole context: a round costs its turns times its size, and a resumed one starts where it ended; the prompt it was handed is in characters'));
+  console.log(dim(`    ${'stage'.padEnd(20)}${'rounds'.padEnd(8)}${'n'.padStart(4)}${'turns'.padStart(7)}${'calls/turn'.padStart(12)}${'starts at'.padStart(11)}${'peak'.padStart(8)}${'prompt'.padStart(9)}`));
+  const byRole = new Map();
+  for (const r of shaped) byRole.set(r.role, [...(byRole.get(r.role) ?? []), r]);
+  for (const [role, rounds] of [...byRole].sort((a, b) => b[1].reduce((x, r) => x + r.turns, 0) - a[1].reduce((x, r) => x + r.turns, 0))) {
+    [
+      ['first', rounds.filter((r) => (r.round ?? 1) === 1)],
+      ['resumed', rounds.filter((r) => (r.round ?? 1) > 1)],
+    ].forEach(([label, group], i) => {
+      if (group.length === 0) return;
+      const turns = group.reduce((a, r) => a + r.turns, 0);
+      const calls = group.reduce((a, r) => a + (r.tool_calls ?? 0), 0);
+      const name = i === 0 || !rounds.some((r) => (r.round ?? 1) === 1) ? pink(role) + ' '.repeat(Math.max(20 - role.length, 1)) : ' '.repeat(20);
+      console.log(
+        `    ${name}${dim(label.padEnd(8))}${String(group.length).padStart(4)}${String(median(group.map((r) => r.turns))).padStart(7)}` +
+          `${(calls / turns).toFixed(2).padStart(12)}${k(median(group.map((r) => r.context_start ?? 0))).padStart(11)}${k(median(group.map((r) => r.context_peak ?? 0))).padStart(8)}` +
+          `${chars(group.map((r) => r.prompt_chars).filter((n) => typeof n === 'number')).padStart(9)}`,
+      );
+    });
+  }
+}
+
 /**
  * Whether a model a run used is the one a spec declares: an alias (`opus`) names a family — a whole
  * segment of the id, wherever it sits, so `claude-3-sonnet` is a sonnet — anything else names a model
@@ -722,6 +758,7 @@ export async function stats(argv, ctx) {
   }
 
   costReport(records.filter((r) => r.status !== 'denied'));
+  contextReport(records.filter((r) => r.status !== 'denied'));
   modelReport(records.filter((r) => r.status !== 'denied'));
   proportionReport(records.filter((r) => r.status !== 'denied'), stepLimitOf(ctx));
 

package/src/commands/upgrade.mjs

@@ -37,7 +37,8 @@ const BANNER = /^[\s█╗╔╝║═╚▄▀]*$|harness orchestration ·/;
  * fault — everything else it finds still rolls the move back.
  *
  * @param {string} target - The project.
- * @param {string[]} newSlots - Project slots this move introduces, as `<file> <slot id>`.
+ * @param {string[]} newSlots - Project slots this move introduces, as `<file> <slot id>`, and the
+ *   vocabulary names it introduces, as `{{NAME}}`.
  * @returns {{label: string, args: string[]}[]}
  */
 function validationsFor(target, newSlots = []) {
@@ -242,6 +243,10 @@ export async function upgrade(argv, ctx) {
   // A slot the new release fills itself is not asked of the project: it composes as the release wrote it.
   const defaultedAfter = await defaultedSlots(onto.dir);
   const newSlots = [...slotsAfter].filter((s) => !slotsBefore.has(s) && !filled.has(s) && !defaultedAfter.has(s)).sort();
+  // A name only the new release uses is owed the way a new slot is: it cannot be filled with meaning
+  // before the core that asks for it is pinned, and rolling back for it left no order the move completes in.
+  const newVocab = needed.filter((v) => !vocabBefore.has(v));
+  const awaited = [...newSlots, ...newVocab.map((v) => `{{${v}}}`)];
   const stranded = [...filled].filter((s) => !slotsAfter.has(s)).sort();
 
   console.log(`  ${profile.core} → ${to}\n`);
@@ -357,7 +362,7 @@ export async function upgrade(argv, ctx) {
   // What was already failing is not this upgrade's doing, and rolling back for it would blame
   // the move for a problem the project brought with it. Measured before anything is written,
   // so the only rollback is for something that WAS passing and now is not.
-  const VALIDATIONS = validationsFor(target, newSlots);
+  const VALIDATIONS = validationsFor(target, awaited);
   const DETECTORS = "running the project's own detectors";
   const hasDetectors = await declares(target, 'harness:check');
 
@@ -416,7 +421,7 @@ export async function upgrade(argv, ctx) {
   // `harness:check` — an npm script whose detector list this command does not own and cannot
   // pass an argument to. The environment is what crosses that boundary, and setting it once
   // means a reporter added to the chain later is told without anyone remembering to tell it.
-  if (newSlots.length > 0) process.env[EXPECT_ENV] = newSlots.join(',');
+  if (awaited.length > 0) process.env[EXPECT_ENV] = awaited.join(',');
 
   // Compose writes and never deletes. So the files the new version stops composing are removed right
   // after it composes — before anything is verified, so what is verified is what stays — unless they
@@ -516,6 +521,10 @@ export async function upgrade(argv, ctx) {
       console.log(`\n  ${newSlots.length} project slot(s) still to fill — only this project can write them:`);
       for (const s of newSlots) console.log(`      ${s}`);
     }
+    if (newVocab.length > 0) {
+      console.log(`\n  ${newVocab.length} vocabulary name(s) ${to} asks for and this profile does not answer — fill each, or defer it with why:`);
+      console.log(`      ${newVocab.join(', ')}`);
+    }
     console.log('');
     return 0;
   }

package/src/expected.mjs

@@ -1,8 +1,9 @@
 /**
- * The project slots a caller has declared it already knows are open.
+ * The project slots, and vocabulary names, a caller has declared it already knows are open.
  *
  * `nina upgrade --apply` creates slots: a new core can introduce one, and it cannot be filled
- * before the core that introduces it is pinned. Every reporter that fails on an unfilled slot
+ * before the core that introduces it is pinned. A name only the new core uses is the same case,
+ * named as `{{NAME}}`: `check` rolled a move back for one the preview had just listed as needed. Every reporter that fails on an unfilled slot
  * therefore has to be told, or the move deadlocks — there is no order in which it completes.
  *
  * Two reporters say this same thing, and the first fix taught only one: `check` counts a slot
@@ -21,7 +22,7 @@ export const EXPECT_ENV = 'NINA_EXPECT_UNFILLED';
 /**
  * @param {string[]} argv - The command's arguments; `--expect-unfilled <a,b>` names slots.
  * @param {NodeJS.ProcessEnv} [env] - Where to read `NINA_EXPECT_UNFILLED` from.
- * @returns {Set<string>} Slot ids as `<relative path> <slot id>`.
+ * @returns {Set<string>} Slot ids as `<relative path> <slot id>`, names as `{{NAME}}`.
  */
 export function expectedUnfilled(argv = [], env = process.env) {
   const fromArgv = argv.includes('--expect-unfilled') ? argv[argv.indexOf('--expect-unfilled') + 1] ?? '' : '';

package/src/langfuse.mjs

@@ -100,31 +100,47 @@ function usageAttributes(tokens, model, priced) {
   return out;
 }
 
+/**
+ * How much of a stage's context a project sends, from its switch in the Langfuse configuration: all of it
+ * (`--content`), only what passed between the agents (`--prompts`), or none.
+ *
+ * @param {{content?: boolean|string}|undefined} setting - The project's entry, if it is on.
+ * @returns {'full'|'prompts'|null}
+ */
+export function contextMode(setting) {
+  return setting?.content === 'prompts' ? 'prompts' : setting?.content ? 'full' : null;
+}
+
+/** A round's shape, as metadata on its root: how many turns and calls it took, and how large its context and prompt were. */
+const SHAPE = ['turns', 'tool_calls', 'context_start', 'context_peak', 'prompt_chars'];
+
 /**
  * The OTLP span at the root of a dispatch's trace. Without its context, a run that spent tokens is a
  * generation carrying the run's whole usage and estimated cost, and one that did not is a span. With it,
  * the root is the agent — its prompt in, its report out — and the usage is on the messages beneath it,
- * so no sum counts a token twice. Its verdict is the score beside it rather than an attribute on it: a
- * run whose verdict is read only later can still be given one, since that is a first score and not a
- * second span.
+ * so no sum counts a token twice. With the prompt and report alone, nothing is beneath it, so the root is
+ * a generation again, carrying the usage beside them. Its verdict is the score beside it rather than an
+ * attribute on it: a run whose verdict is read only later can still be given one, since that is a first
+ * score and not a second span.
  *
  * @param {object} record - A snapshot record.
  * @param {string} project - The name the project goes by in Langfuse.
  * @param {{prompt: string, report: string}} [context] - What the stage was given and handed back.
+ * @param {{usage?: boolean}} [options] - `usage`: the root carries the usage even with its context.
  * @returns {object|null} Null for a record with no time to place it at.
  */
-export function spanOf(record, project, context = null) {
+export function spanOf(record, project, context = null, { usage = false } = {}) {
   const start = nanos(record.ts);
   if (!start) return null;
   const end = nanos(record.result_ts) ?? start;
-  const tokens = !context && record.tokens && typeof record.tokens === 'object' ? record.tokens : null;
+  const tokens = (!context || usage) && record.tokens && typeof record.tokens === 'object' ? record.tokens : null;
   const attributes = [
     attribute('langfuse.session.id', record.session ?? 'no-session'),
     attribute('langfuse.trace.name', record.role),
     attribute('langfuse.trace.tags', ['nina', project]),
     attribute('langfuse.trace.metadata.project', project),
     attribute('langfuse.trace.metadata.role', record.role),
-    attribute('langfuse.observation.type', context ? 'agent' : tokens ? 'generation' : 'span'),
+    attribute('langfuse.observation.type', tokens ? 'generation' : context ? 'agent' : 'span'),
     attribute('langfuse.observation.metadata.role', record.role),
   ];
   if (typeof record.issues === 'number') attributes.push(attribute('langfuse.observation.metadata.issues', record.issues));
@@ -133,6 +149,7 @@ export function spanOf(record, project, context = null) {
   if (record.effort) attributes.push(attribute('langfuse.observation.metadata.effort', record.effort));
   // A round after the first is the same agent resumed after it reported; the trace says which.
   if (typeof record.round === 'number') attributes.push(attribute('langfuse.observation.metadata.round', record.round));
+  for (const key of SHAPE) if (typeof record[key] === 'number') attributes.push(attribute(`langfuse.observation.metadata.${key}`, record[key]));
   if (tokens) attributes.push(...usageAttributes(tokens, record.usage_model, record.usage_model));
   if (context) {
     attributes.push(attribute('langfuse.observation.input', context.prompt ?? ''));
@@ -144,23 +161,26 @@ export function spanOf(record, project, context = null) {
 /**
  * Everything a dispatch sends: the root, and — when its context goes too — a generation per message it
  * wrote, with that message's own tokens and cost, and an observation per tool it called, with what went
- * in and what came back. Every text is masked (`redact`), cut to a length, and has the owner's home
- * directory written as `~`.
+ * in and what came back. With `prompts`, only what passed between the agents goes: the root, with the
+ * prompt the stage was given and the report it handed back, and none of what it read, wrote or called in
+ * between. Every text is masked (`redact`), cut to a length, and has the owner's home directory written
+ * as `~`.
  *
  * @param {object} record - A snapshot record.
  * @param {string} project - The name the project goes by in Langfuse.
  * @param {object|null} run - From `readRun`, or null to send the record alone.
  * @param {{text?: number, tool?: number}} [limits] - How much of each text goes.
+ * @param {{prompts?: boolean}} [options] - `prompts`: the prompt and the report, and nothing beneath them.
  * @returns {object[]} Spans; empty for a record with no time to place it at.
  */
-export function spansOf(record, project, run, limits = {}) {
+export function spansOf(record, project, run, limits = {}, { prompts = false } = {}) {
   const textChars = limits.text ?? TEXT_CHARS;
   const toolChars = limits.tool ?? TOOL_CHARS;
   const home = homedir();
   const clean = (text, chars) => clip(redact(String(text ?? '')).replaceAll(home, '~'), chars);
-  const root = spanOf(record, project, run ? { prompt: clean(run.prompt, textChars), report: clean(run.report, textChars) } : null);
+  const root = spanOf(record, project, run ? { prompt: clean(run.prompt, textChars), report: clean(run.report, textChars) } : null, { usage: prompts });
   if (!root) return [];
-  if (!run) return [root];
+  if (!run || prompts) return [root];
   const child = (id, name, start, end, attributes) => ({
     traceId: root.traceId,
     spanId: hexId(`${record.dispatch_id}|${id}`, 16),

package/src/transcripts.mjs

@@ -626,9 +626,13 @@ async function attachAgentDetail(projectDir, dispatches) {
       // 744 of one project's 826 in full on every turn, two seconds before the person saw an answer.
       const size = (await stat(join(dir, file)).catch(() => null))?.size ?? null;
       const settled = (r) => r.handed_back === false || String(r.verdict_source ?? '').startsWith('handback');
+      // `resumes` is written only by a reader from before rounds, which bills the whole run to its first
+      // record. A store both versions wrote to — one project on the old pin, a hook elsewhere on the new —
+      // had its runs marked read by the old one and skipped here, their first round billed twice.
       if (
         run.agent_read_bytes === size &&
-        [...records, ...later].every((r) => settled(r) && 'round' in r && 'lessons_read' in r && 'tokens' in r && 'files_touched' in r && 'effort' in r)
+        !('resumes' in run) &&
+        [...records, ...later].every((r) => settled(r) && 'round' in r && 'lessons_read' in r && 'tokens' in r && 'files_touched' in r && 'effort' in r && 'turns' in r && 'prompt_chars' in r)
       ) {
         continue;
       }
@@ -656,6 +660,10 @@ async function attachAgentDetail(projectDir, dispatches) {
         usage: new Map(),
         /** The files the round wrote through the edit tools. Only their number is kept. */
         written: new Set(),
+        /** The tool calls the round made, by id: over its turns, how many calls each turn sent at once. */
+        calls: new Set(),
+        /** How long the prompt that opened the round was, in characters; never the prompt. */
+        promptChars: null,
       });
       const rounds = [fresh()];
       const roundOf = roundsOf();
@@ -675,8 +683,17 @@ async function attachAgentDetail(projectDir, dispatches) {
           }
         }
         const round = rounds[n - 1];
+        if (round.promptChars === null && line.includes('"type":"user"')) {
+          try {
+            const said = promptOf(JSON.parse(line), n);
+            if (said !== null) round.promptChars = said.length;
+          } catch {
+            // A torn line is not the prompt.
+          }
+        }
         const hasSkill = line.includes('"Skill"');
         const hasHandback = line.includes('SubagentHandback');
+        for (const m of line.matchAll(/"type":"tool_use","id":"([^"]+)"/g)) round.calls.add(m[1]);
         if (/"name":"(Edit|Write|MultiEdit|NotebookEdit)"/.test(line)) {
           try {
             for (const block of JSON.parse(line)?.message?.content ?? []) {
@@ -755,9 +772,15 @@ async function attachAgentDetail(projectDir, dispatches) {
           targets = [dispatches.get(id)];
         }
         const spent = tokensOf(round.usage);
+        const shape = contextOf(round.usage);
         targets.forEach((record, j) => {
           // One transcript, one bill: were two records ever to share an agent, the second would count it again.
           record.tokens = j === 0 ? spent.tokens : null;
+          record.turns = shape.turns;
+          record.tool_calls = round.calls.size;
+          record.context_start = shape.start;
+          record.context_peak = shape.peak;
+          record.prompt_chars = round.promptChars;
           record.usage_model = spent.model;
           record.effort = spent.effort;
           record.files_touched = round.written.size;
@@ -790,6 +813,35 @@ async function attachAgentDetail(projectDir, dispatches) {
   }
 }
 
+/**
+ * What a round was told, from one transcript row, or null when the row is not it. The dispatch's prompt
+ * opens the first round; a later round opens with the message that resumed the run, which Claude Code
+ * marks as meta, while a meta row in the first round is a reminder. The snapshot measures it and the
+ * Langfuse export sends it, so both read it here.
+ *
+ * @param {object} row - A parsed transcript row.
+ * @param {number} round - The round the row is in, from 1.
+ * @returns {string|null}
+ */
+export function promptOf(row, round) {
+  const content = row?.message?.content;
+  return row?.type === 'user' && (round > 1 || !row.isMeta) && typeof content === 'string' ? content : null;
+}
+
+/**
+ * How a round spent its context: how many turns it took, and how large the context each turn re-read was
+ * when the round began and at its largest. Every turn is billed the whole context again, so a round that
+ * begins where a long one ended — a run resumed for a fix — pays for everything before it on each turn.
+ *
+ * @param {Map<string, {usage: object}>} usage - Message id → its final usage, in the order the round sent them.
+ * @returns {{turns: number, start: number|null, peak: number|null}} Context sizes in tokens.
+ */
+export function contextOf(usage) {
+  const n = (v) => (typeof v === 'number' ? v : 0);
+  const sizes = [...usage.values()].map(({ usage: u }) => n(u.input_tokens) + n(u.cache_read_input_tokens) + n(u.cache_creation_input_tokens));
+  return { turns: sizes.length, start: sizes[0] ?? null, peak: sizes.length > 0 ? Math.max(...sizes) : null };
+}
+
 /**
  * What a run spent, from each of its messages' final usage: tokens by kind, and the model and effort
  * level that most of its messages ran at. Metadata — counts, a model id and a level, never a message.