agentic-retro 0.0.0-stage → 0.1.0

package/cli/lib/pi-extension.ts

@@ -0,0 +1,30 @@
+// agentic-retro Pi extension, written by `agentic-retro install-pi`.
+// Queues each finished session for a retro and shows new proposals at session start.
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { execFile, spawn } from "node:child_process";
+
+export default function (pi: ExtensionAPI) {
+  pi.on("session_shutdown", (event, ctx) => {
+    if (event.reason !== "quit") return; // "new", "resume", and "fork" only switch sessions
+    if (process.env.AGENTIC_RETRO_RUN === "1") return; // batch agents never queue themselves
+
+    const transcript = ctx.sessionManager.getSessionFile();
+    if (!transcript) return; // nothing was said, so nothing was saved
+
+    const child = spawn("agentic-retro", [
+      "enqueue", "--harness", "pi",
+      "--session", ctx.sessionManager.getSessionId(),
+      "--transcript", transcript,
+      "--cwd", ctx.cwd,
+    ], { detached: true, stdio: "ignore" });
+    child.on("error", () => {}); // CLI not installed: never break Pi
+    child.unref();
+  });
+
+  pi.on("session_start", (_event, ctx) => {
+    execFile("agentic-retro", ["notice"], (error, stdout) => {
+      const line = stdout?.trim();
+      if (!error && line) ctx.ui.notify(line, "info");
+    });
+  });
+}

package/cli/lib/pi.js

@@ -0,0 +1,15 @@
+// Pi has no hook config, so a small extension file stands in for the hooks.
+import { mkdirSync, copyFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const TEMPLATE = join(dirname(fileURLToPath(import.meta.url)), 'pi-extension.ts');
+
+export function installPi() {
+  const dir = join(process.env.PI_HOME || join(homedir(), '.pi'), 'agent', 'extensions');
+  mkdirSync(dir, { recursive: true });
+  const file = join(dir, 'agentic-retro.ts');
+  copyFileSync(TEMPLATE, file);
+  console.log(`agentic-retro: wrote ${file}`);
+}

package/cli/lib/queue.js

@@ -0,0 +1,61 @@
+// The queue: finished sessions wait here until their group fills a batch.
+import { execFileSync } from 'node:child_process';
+import { readdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, basename } from 'node:path';
+import { readJson, writeJson } from './paths.js';
+import { loadConfig } from './config.js';
+import { startBatch } from './runner.js';
+
+function repoOf(cwd) {
+  try {
+    return execFileSync('git', ['-C', cwd, 'rev-parse', '--show-toplevel'],
+      { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+  } catch {
+    return cwd;
+  }
+}
+
+// Codex sometimes ends a session with a null transcript_path, so look for its rollout file.
+function findCodexRollout(sessionId) {
+  const sessions = join(process.env.CODEX_HOME || join(homedir(), '.codex'), 'sessions');
+  try {
+    const match = readdirSync(sessions, { recursive: true }).find((f) => f.endsWith(`-${sessionId}.jsonl`));
+    return match ? join(sessions, match) : null;
+  } catch {
+    return null;
+  }
+}
+
+// Claude Code and Codex share one hook, so the transcript path tells them apart.
+// Only Codex ends a session with no transcript path.
+function harnessOf(transcript) {
+  if (!transcript) return 'codex';
+  if (transcript.includes('/.codex/') || basename(transcript).startsWith('rollout-')) return 'codex';
+  if (transcript.includes('/.claude/')) return 'claude';
+  if (transcript.includes('/.pi/')) return 'pi';
+  return undefined;
+}
+
+export async function enqueue({ harness, sessionId, transcript, cwd }) {
+  if (process.env.AGENTIC_RETRO_RUN === '1') return; // batch agents never queue themselves
+  transcript ||= findCodexRollout(sessionId) ?? null;
+  harness ||= harnessOf(transcript);
+  if (!harness || !sessionId || !cwd) throw new Error('enqueue needs a harness, session, and cwd');
+
+  const queue = readJson('queue.json', []);
+  if (queue.some((s) => s.sessionId === sessionId)) return;
+  const entry = { harness, sessionId, transcript, cwd, repo: repoOf(cwd), endedAt: new Date().toISOString() };
+  queue.push(entry);
+
+  const { batch } = loadConfig();
+  const sameGroup = (s) => batch.group === 'global' || s.repo === entry.repo;
+  const group = queue.filter(sameGroup);
+  if (group.length < batch.size) return writeJson('queue.json', queue);
+
+  // Save first and remove after, so a failed hand-off leaves the sessions queued.
+  writeJson('queue.json', queue);
+  const sessions = group.slice(0, batch.size);
+  await startBatch(sessions);
+  writeJson('queue.json', queue.filter((s) => !sessions.includes(s)));
+}

package/cli/lib/runner.js

@@ -0,0 +1,48 @@
+// Starts a batch run: writes the batch manifest, syncs outcomes and digests, then launches the batch agent.
+import { spawn, execFileSync } from 'node:child_process';
+import { openSync, appendFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { writeJson, statePath } from './paths.js';
+import { nextBatch } from './ledger.js';
+import { loadConfig } from './config.js';
+import { syncOutcomes } from './outcomes.js';
+import { writeBatchDigests } from './digest.js';
+import { buildCommand, PANE_ID } from './commands.js';
+
+export { buildCommand };
+
+function runHerdr([create, paneRun]) {
+  let output;
+  try {
+    output = execFileSync(create.file, create.args, { cwd: create.cwd, encoding: 'utf8' });
+  } catch (error) {
+    throw new Error(`herdr could not open a workspace – is the herdr server running? (${error.message})`);
+  }
+  const paneId = JSON.parse(output).result.root_pane.pane_id;
+  const args = paneRun.args.map((arg) => (arg === PANE_ID ? paneId : arg));
+  execFileSync(paneRun.file, args, { cwd: paneRun.cwd });
+}
+
+// Detached with output in run.log, so enqueue (a session-end hook) returns at once.
+function launch({ file, args, env, cwd }) {
+  const log = join(cwd, 'run.log');
+  const out = openSync(log, 'a');
+  const child = spawn(process.env.AGENTIC_RETRO_LAUNCHER || file, args, {
+    cwd, env: { ...process.env, ...env }, detached: true, stdio: ['ignore', out, out],
+  });
+  child.on('error', (error) => appendFileSync(log, `could not start ${file}: ${error.message}\n`));
+  child.unref();
+}
+
+export async function startBatch(sessions) {
+  const n = nextBatch();
+  writeJson(`batches/${n}/batch.json`, { sessions });
+  if (process.env.AGENTIC_RETRO_DRY_RUN === '1') return n;
+
+  syncOutcomes();
+  await writeBatchDigests(n, sessions);
+  const command = buildCommand(loadConfig(), statePath('batches', String(n)), n, sessions);
+  if (Array.isArray(command)) runHerdr(command);
+  else launch(command);
+  return n;
+}

package/cli/lib/setup.js

@@ -0,0 +1,52 @@
+// Interactive setup: one question per config setting, each with presets. Enter keeps the current value.
+import { createInterface } from 'node:readline';
+import { existsSync } from 'node:fs';
+import { delimiter, join } from 'node:path';
+import { loadConfig, saveConfig, getKey, parseValue } from './config.js';
+
+const onPath = (bin) => (process.env.PATH || '').split(delimiter).some((dir) => existsSync(join(dir, bin)));
+
+function questions() {
+  const harnesses = ['claude', 'codex', 'pi', ...(onPath('herdr') ? ['herdr'] : [])];
+  return [
+    ['batch.size', 'Sessions per batch', ['5', '10']],
+    ['batch.group', 'Group sessions by', ['repo', 'global']],
+    ['runner.harness', 'Harness that runs batch agents', harnesses],
+    ['runner.model', 'Model for batch agents (opus applies to Claude; Codex/Pi use their own default unless given a model name)', ['opus', 'default']],
+    ['runner.permissions', 'Batch agent permissions', ['auto', 'scoped', 'bypass']],
+    ['categories.clarity', 'Propose code-clarity changes?', ['true', 'false']],
+    ['categories.agent-setup', 'Propose agent-setup changes (skills, hooks, instructions)?', ['true', 'false']],
+    ['categories.repo-for-agents', 'Propose changes that make repos easier for agents?', ['true', 'false']],
+    ['scope', 'Code-clarity scope', ['touched', 'neighbours', 'two-layers']],
+    ['output', 'Output', ['pr', 'report']],
+    ['autoMergeLowRisk', 'Auto-merge low-risk agent-setup PRs?', ['false', 'true']],
+    ['expireAfterBatches', 'Expire open proposals after how many batches', ['3', '5']],
+    ['editable', 'Writable paths (JSON list)', ['[]']],
+    ['targets.preset', 'Where agent-setup changes go', ['~/.claude/skills', '~/.codex/skills', '<plugin repo path>']],
+    ['targets.note', 'Note for agents about targets', []],
+    ['notes', 'Anything else batch agents should know', []],
+  ];
+}
+
+const show = (value) => (typeof value === 'string' ? value : JSON.stringify(value));
+
+export async function setup() {
+  const rl = createInterface({ input: process.stdin, output: process.stdout, terminal: false });
+  const lines = rl[Symbol.asyncIterator]();
+  const config = loadConfig();
+
+  for (const [key, label, presets] of questions()) {
+    const current = show(getKey(config, key));
+    const choices = presets.length ? ` (${presets.join(' / ')})` : '';
+    process.stdout.write(`${label}${choices} [${current}]: `);
+    const { value, done } = await lines.next();
+    const answer = done ? '' : value.trim();
+    const parts = key.split('.');
+    const last = parts.pop();
+    parts.reduce((node, part) => node[part], config)[last] = parseValue(key, answer || current);
+  }
+
+  rl.close();
+  saveConfig(config);
+  process.stdout.write('\nSaved config.json\n');
+}

package/cli/lib/stats.js

@@ -0,0 +1,57 @@
+// Stats: how often each kind of proposal lands, and how many tokens each changed line costs.
+import { existsSync, readFileSync } from 'node:fs';
+import { statePath } from './paths.js';
+import { CATEGORIES, loadLedger } from './ledger.js';
+
+function categoryStats(proposals) {
+  const counts = { accepted: 0, rejected: 0, expired: 0, open: 0 };
+  for (const p of proposals) counts[p.status] += 1;
+  // Share of settled proposals only: open ones have no verdict yet.
+  const settled = counts.accepted + counts.rejected + counts.expired;
+  return { ...counts, acceptedShare: settled ? counts.accepted / settled : null };
+}
+
+function readMetrics() {
+  const path = statePath('metrics.jsonl');
+  if (!existsSync(path)) return [];
+  return readFileSync(path, 'utf8').split('\n').filter(Boolean).map((line) => JSON.parse(line));
+}
+
+// A session counts only when it has token data and changed at least one line.
+function batchRatios(metrics) {
+  const totals = new Map();
+  for (const m of metrics) {
+    const lines = (m.linesAdded ?? 0) + (m.linesRemoved ?? 0);
+    if (m.inputTokens == null || m.outputTokens == null || !lines) continue;
+    const total = totals.get(m.batch) ?? { tokens: 0, lines: 0 };
+    total.tokens += m.inputTokens + m.outputTokens;
+    total.lines += lines;
+    totals.set(m.batch, total);
+  }
+  return [...totals]
+    .sort(([a], [b]) => a - b)
+    .map(([batch, { tokens, lines }]) => ({ batch, tokensPerLine: tokens / lines }));
+}
+
+export function collectStats() {
+  const { proposals } = loadLedger();
+  const categories = Object.fromEntries(CATEGORIES.map((c) =>
+    [c, categoryStats(proposals.filter((p) => p.category === c))]));
+  return { categories, batches: batchRatios(readMetrics()) };
+}
+
+function formatStats({ categories, batches }) {
+  const lines = Object.entries(categories).map(([name, c]) => {
+    const share = c.acceptedShare === null ? '-' : `${Math.round(c.acceptedShare * 100)}%`;
+    return `${name}: ${c.accepted} accepted, ${c.rejected} rejected, ${c.expired} expired, ${c.open} open, ${share} accepted`;
+  });
+  lines.push('tokens per line changed:');
+  if (!batches.length) lines.push('  no metrics yet');
+  for (const b of batches) lines.push(`  batch ${b.batch}: ${Math.round(b.tokensPerLine)}`);
+  return lines.join('\n');
+}
+
+export function stats({ json }) {
+  const result = collectStats();
+  console.log(json ? JSON.stringify(result, null, 2) : formatStats(result));
+}

package/cli/lib/transcripts/claude.js

@@ -0,0 +1,84 @@
+// Reads a Claude Code transcript (~/.claude/projects/<slug>/<session>.jsonl).
+import { eachLine, countLines, emptySession, stamp } from './lines.js';
+
+const SUBAGENT_TOOLS = new Set(['Task', 'Agent']);
+
+// Claude Code writes these into the transcript as user messages; the person never typed them.
+// A relayed "Another Claude session sent a message:" line is agent traffic too, not a user turn.
+const INJECTED = /^\s*(<command-name>|<command-message>|<local-command-stdout>|<task-notification>|<teammate-message|<system-reminder>|Another Claude session sent a message:)/;
+
+function target(input = {}) {
+  return input.file_path ?? input.command ?? input.pattern ?? input.url ?? input.description ?? input.path ?? '';
+}
+
+function edit(name, input = {}) {
+  const file = input.file_path;
+  if (name === 'Write') return { file, added: countLines(input.content), removed: 0 };
+  const pairs = name === 'Edit' ? [input] : name === 'MultiEdit' ? input.edits ?? [] : null;
+  if (!pairs) return null;
+  return {
+    file,
+    added: pairs.reduce((sum, e) => sum + countLines(e.new_string), 0),
+    removed: pairs.reduce((sum, e) => sum + countLines(e.old_string), 0),
+  };
+}
+
+function resultText(content) {
+  if (typeof content === 'string') return content;
+  if (Array.isArray(content)) return content.map((c) => c.text ?? '').join(' ');
+  return '';
+}
+
+// Input counts every prompt token: fresh, read from cache, and written to cache.
+function totalUsage(usages) {
+  if (!usages.length) return null;
+  const sum = (key) => usages.reduce((total, u) => total + (u[key] ?? 0), 0);
+  return {
+    input: sum('input_tokens') + sum('cache_read_input_tokens') + sum('cache_creation_input_tokens'),
+    output: sum('output_tokens'),
+  };
+}
+
+export async function readSession(path) {
+  const session = emptySession();
+  const usages = new Map(); // one assistant message streams as several lines sharing message.id; the last line's usage is final
+  const calls = new Map(); // tool_use id -> toolCall, so results can mark errors
+
+  await eachLine(path, (line) => {
+    const message = line.message;
+    if (!message || (line.type !== 'user' && line.type !== 'assistant')) return;
+    session.cwd ??= line.cwd ?? null;
+    stamp(session, line.timestamp);
+    const blocks = Array.isArray(message.content) ? message.content : [];
+
+    if (line.type === 'user') {
+      const results = blocks.filter((b) => b.type === 'tool_result');
+      for (const r of results) {
+        const call = calls.get(r.tool_use_id);
+        if (call && r.is_error) call.error = resultText(r.content) || 'error';
+      }
+      if (results.length || line.isMeta) return;
+      const text = typeof message.content === 'string' ? message.content : resultText(blocks);
+      if (INJECTED.test(text)) return;
+      session.turns.user++;
+      session.userMessages.push(text);
+      return;
+    }
+
+    const id = message.id ?? line.uuid;
+    if (!usages.has(id)) session.turns.assistant++;
+    usages.set(id, message.usage ?? usages.get(id) ?? null);
+    for (const block of blocks) {
+      if (block.type !== 'tool_use') continue;
+      const call = { tool: block.name, target: String(target(block.input)), error: null };
+      session.toolCalls.push(call);
+      calls.set(block.id, call);
+      if (SUBAGENT_TOOLS.has(block.name)) session.subagents++;
+      const change = edit(block.name, block.input);
+      if (change) session.edits.push(change);
+    }
+  });
+
+  session.usage = totalUsage([...usages.values()].filter(Boolean));
+  return session;
+}

package/cli/lib/transcripts/codex-tools.js

@@ -0,0 +1,76 @@
+// Turns Codex tool records into tool calls and edits, for both transcript formats.
+// Legacy: function_call "shell" with a command array. Current (0.162+): custom_tool_call "exec" whose input is a JS script.
+
+// Counts +/- lines per file in an apply_patch body ("*** Update File: x" headers).
+function patchEdits(patch) {
+  const edits = [];
+  let current = null;
+  for (const line of patch.split('\n')) {
+    const header = line.match(/^\*\*\* (?:Add|Update|Delete) File: (.+)$/);
+    if (header) edits.push((current = { file: header[1].trim(), added: 0, removed: 0 }));
+    else if (!current || line.startsWith('***')) continue;
+    else if (line.startsWith('+') && !line.startsWith('+++')) current.added++;
+    else if (line.startsWith('-') && !line.startsWith('---')) current.removed++;
+  }
+  return edits;
+}
+
+function parse(json) {
+  try { return JSON.parse(json); } catch { return null; }
+}
+
+function patchCall(patch) {
+  const edits = patchEdits(patch);
+  return { call: { tool: 'apply_patch', target: edits.map((e) => e.file).join(', '), error: null }, edits };
+}
+
+// Returns the patch text from ["apply_patch", patch] or ["bash", "-lc", "apply_patch <<'EOF' ... EOF"].
+function patchOf(command) {
+  if (command[0] === 'apply_patch') return command[1] ?? '';
+  const script = command.at(-1) ?? '';
+  return /^\s*apply_patch\b/.test(script) ? script : null;
+}
+
+function legacyShell(name, args) {
+  const command = Array.isArray(args.command) ? args.command : [String(args.command ?? '')];
+  const patch = patchOf(command);
+  if (patch !== null) return [patchCall(patch)];
+  const target = command.length > 2 && command[1] === '-lc' ? command[2] : command.join(' ');
+  return [{ call: { tool: name, target, error: null }, edits: [] }];
+}
+
+// A JS string literal body like `npm test` or `*** Begin Patch\n...`, unescaped.
+const STRING = '"((?:[^"\\\\]|\\\\.)*)"';
+const SCRIPT_CALLS = new RegExp(`tools\\.(?:exec_command\\(\\{\\s*cmd\\s*:\\s*${STRING}|apply_patch\\(\\s*${STRING})`, 'g');
+
+// One script can run several tools; each becomes its own call. Unknown scripts show as themselves.
+function execScript(script) {
+  const found = [...script.matchAll(SCRIPT_CALLS)].map(([, cmd, patch]) =>
+    cmd !== undefined
+      ? { call: { tool: 'exec', target: parse(`"${cmd}"`) ?? cmd, error: null }, edits: [] }
+      : patchCall(parse(`"${patch}"`) ?? ''));
+  return found.length ? found : [{ call: { tool: 'exec', target: script, error: null }, edits: [] }];
+}
+
+// Returns [{call, edits}] for a tool record, or null when the record is not a tool call.
+export function toolCalls(p) {
+  const plain = (target) => [{ call: { tool: p.name, target: String(target ?? ''), error: null }, edits: [] }];
+  if (p.type === 'custom_tool_call') return p.name === 'exec' ? execScript(String(p.input ?? '')) : plain(p.input);
+  if (p.type !== 'function_call') return null;
+  const args = parse(p.arguments) ?? {};
+  if (p.name === 'spawn_agent') return plain(args.task_name);
+  return legacyShell(p.name, args.command === undefined ? { command: p.arguments ?? '' } : args);
+}
+
+// Returns "exit N: output" for a failed command, or null.
+export function failure(p) {
+  if (p.type === 'function_call_output') {
+    const result = parse(p.output);
+    const code = result?.metadata?.exit_code;
+    return code ? `exit ${code}: ${result.output ?? ''}` : null;
+  }
+  if (p.type !== 'custom_tool_call_output') return null;
+  const texts = Array.isArray(p.output) ? p.output.map((o) => o.text ?? '') : [String(p.output ?? '')];
+  const result = texts.map((t) => parse(t)).find((r) => r && 'exit_code' in r);
+  return result?.exit_code ? `exit ${result.exit_code}: ${result.output ?? ''}` : null;
+}

package/cli/lib/transcripts/codex.js

@@ -0,0 +1,55 @@
+// Reads a Codex transcript (~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl).
+import { eachLine, emptySession, stamp } from './lines.js';
+import { toolCalls, failure } from './codex-tools.js';
+
+// Codex injects these as user messages; the person never typed them.
+const INJECTED = /^\s*(<environment_context>|<user_instructions>|<permissions instructions>|# AGENTS\.md instructions)/;
+
+function messageText(content) {
+  return Array.isArray(content) ? content.map((c) => c.text ?? '').join('\n') : String(content ?? '');
+}
+
+export async function readSession(path) {
+  const session = emptySession();
+  const calls = new Map(); // call_id -> last toolCall, so outputs can mark errors
+  // Older Codex logs turns as event_msg records and mirrors them as response_items; newer Codex only has the response_items.
+  const events = { user: [], assistant: 0 };
+  const items = { user: [], assistant: 0 };
+  let usage = null;
+
+  await eachLine(path, (line) => {
+    const p = line.payload ?? {};
+    stamp(session, line.timestamp);
+    if (line.type === 'session_meta' || line.type === 'turn_context') session.cwd ??= p.cwd ?? null;
+    if (line.type === 'event_msg') {
+      if (p.type === 'user_message') events.user.push(String(p.message ?? ''));
+      else if (p.type === 'agent_message') events.assistant++;
+      else if (p.type === 'token_count' && p.info?.total_token_usage) {
+        const total = p.info.total_token_usage;
+        usage = { input: total.input_tokens ?? 0, output: total.output_tokens ?? 0 };
+      }
+    }
+    if (line.type !== 'response_item') return;
+
+    if (p.type === 'message') {
+      const text = messageText(p.content);
+      if (p.role === 'user' && !INJECTED.test(text)) items.user.push(text);
+      else if (p.role === 'assistant') items.assistant++;
+      return;
+    }
+    const error = failure(p);
+    if (error && calls.has(p.call_id)) calls.get(p.call_id).error = error;
+    for (const { call, edits } of toolCalls(p) ?? []) {
+      session.toolCalls.push(call);
+      session.edits.push(...edits);
+      calls.set(p.call_id, call);
+      if (call.tool === 'spawn_agent') session.subagents++;
+    }
+  });
+
+  const turns = events.user.length || events.assistant ? events : items;
+  session.userMessages = turns.user;
+  session.turns = { user: turns.user.length, assistant: turns.assistant };
+  session.usage = usage;
+  return session;
+}

package/cli/lib/transcripts/lines.js

@@ -0,0 +1,33 @@
+// Shared helpers for the transcript readers: stream JSONL and count lines in edit text.
+import { createReadStream } from 'node:fs';
+import { createInterface } from 'node:readline';
+
+// Calls fn on each parsed line; skips lines that are not JSON. Streams, so 100MB+ transcripts stay cheap.
+export async function eachLine(path, fn) {
+  const lines = createInterface({ input: createReadStream(path), crlfDelay: Infinity });
+  for await (const line of lines) {
+    let entry;
+    try { entry = JSON.parse(line); } catch { continue; }
+    if (entry && typeof entry === 'object') fn(entry);
+  }
+}
+
+// "a\nb\n" is two lines; "" is none.
+export function countLines(text) {
+  if (typeof text !== 'string' || text === '') return 0;
+  return text.replace(/\n$/, '').split('\n').length;
+}
+
+export function emptySession() {
+  return {
+    cwd: null, start: null, end: null, userMessages: [], toolCalls: [], edits: [],
+    usage: null, turns: { user: 0, assistant: 0 }, subagents: 0,
+  };
+}
+
+// Keeps the first and last timestamp seen.
+export function stamp(session, timestamp) {
+  if (!timestamp) return;
+  session.start ??= timestamp;
+  session.end = timestamp;
+}

package/cli/lib/transcripts/pi.js

@@ -0,0 +1,62 @@
+// Reads a Pi transcript (~/.pi/agent/sessions/<cwd-slug>/<time>_<id>.jsonl).
+import { eachLine, countLines, emptySession, stamp } from './lines.js';
+
+const SUBAGENT_TOOLS = new Set(['subagent', 'delegate', 'task']);
+
+function target(args = {}) {
+  return args.path ?? args.command ?? args.pattern ?? args.url ?? '';
+}
+
+function edit(name, args = {}) {
+  if (name === 'write') return { file: args.path, added: countLines(args.content), removed: 0 };
+  if (name !== 'edit') return null;
+  const edits = args.edits ?? [{ oldText: args.oldText, newText: args.newText }];
+  return {
+    file: args.path,
+    added: edits.reduce((sum, e) => sum + countLines(e.newText), 0),
+    removed: edits.reduce((sum, e) => sum + countLines(e.oldText), 0),
+  };
+}
+
+const text = (content) => (Array.isArray(content) ? content.map((c) => c.text ?? '').join(' ') : String(content ?? ''));
+
+export async function readSession(path) {
+  const session = emptySession();
+  const calls = new Map(); // toolCall id -> toolCall, so results can mark errors
+  const usage = { input: 0, output: 0 };
+  let hasUsage = false;
+
+  await eachLine(path, (line) => {
+    if (line.type === 'session') session.cwd ??= line.cwd ?? null;
+    if (line.type !== 'message' || !line.message) return;
+    const message = line.message;
+    stamp(session, line.timestamp);
+
+    if (message.role === 'user') {
+      session.turns.user++;
+      session.userMessages.push(text(message.content));
+    } else if (message.role === 'toolResult') {
+      const call = calls.get(message.toolCallId);
+      if (call && message.isError) call.error = text(message.content) || 'error';
+    } else if (message.role === 'assistant') {
+      session.turns.assistant++;
+      if (message.usage) {
+        hasUsage = true;
+        usage.input += message.usage.input ?? 0;
+        usage.output += message.usage.output ?? 0;
+      }
+      for (const item of message.content ?? []) {
+        if (item.type !== 'toolCall') continue;
+        const call = { tool: item.name, target: String(target(item.arguments)), error: null };
+        session.toolCalls.push(call);
+        calls.set(item.id, call);
+        if (SUBAGENT_TOOLS.has(item.name)) session.subagents++;
+        const change = edit(item.name, item.arguments);
+        if (change) session.edits.push(change);
+      }
+    }
+  });
+
+  session.usage = hasUsage ? usage : null;
+  return session;
+}

package/package.json

@@ -1,6 +1,12 @@
 {
   "name": "agentic-retro",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "agentic-retrospective: reviews finished agent coding sessions and proposes improvements",
+  "type": "module",
+  "bin": { "agentic-retro": "cli/agentic-retro.js" },
+  "files": ["cli/", "skills/"],
+  "engines": { "node": ">=20" },
+  "scripts": { "test": "node --test test/*.test.js" },
+  "license": "MIT",
+  "repository": "github:ac8318740/agentic-retro"
+}

package/skills/retro/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: retro
+description: Thin wrapper that runs `agentic-retro stats` and explains the result in plain words. Invoke when the user asks for a retrospective, or wants to see how their agentic-retro proposals are landing.
+---
+
+# Retro
+
+Run `agentic-retro stats` and explain the result in plain words.
+
+## Run it
+
+```
+agentic-retro stats
+```
+
+This reads the ledger (every proposal's outcome: accepted, rejected, or expired) and the metrics stored per session.
+
+## Explain the result
+
+Cover two things, both from `agentic-retro stats`:
+
+- **Accepted share per category** – of every proposal in `clarity`, `agent-setup`, and `repo-for-agents`, the share the user accepted
+    - A low share in one category means the user keeps rejecting that kind of change
+- **Tokens per line of code over time** – how many tokens each batch spends per line changed, tracked across batches
+    - A rising trend means sessions are costing more for the same amount of code
+
+Keep the explanation short.
+
+- Lead with the number or trend that matters most
+    - Example: "Agent-setup proposals: 80% accepted. Clarity proposals: 20% accepted"
+- Say what it suggests
+    - Example: "Agents keep proposing clarity changes you reject - consider turning that category off"
+- Skip any category with no proposals yet
+
+## Why this matters
+
+Batch agents read the accepted share before proposing changes. They propose less of what the user keeps rejecting. This skill shows the user the same numbers.