@sawbuck/reins 0.2.0 → 0.4.0

package/README.md

@@ -21,6 +21,13 @@ $ reins
   the check guards the 7 turns you didn't steer - a miss there is the risk.
 ```
 
+## Harnesses
+
+reins reads **Claude Code** transcripts today. The parser lives in `scan.mjs`; everything
+downstream works on abstract `{ prior, user }` turn-pairs, so another harness (Codex, Cursor)
+is a parallel module that emits the same pairs plus its own session resolver, not a rewrite.
+`pairs()` is the seam.
+
 ## Backend (SAWBUCK_JUDGE)
 
 The judge model is a socket. Set `SAWBUCK_JUDGE` (default `ollama:qwen2.5:7b`):

package/bin/reins.mjs

@@ -5,13 +5,17 @@
 
 import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
 import { join, dirname } from "node:path";
-import { scan, resolveSessionPath, pairs } from "../scan.mjs";
+import * as claudeHarness from "../scan.mjs";
+import * as codexHarness from "../codex.mjs";
+import { scan } from "../scan.mjs";
 import { score, backend, harvestScore } from "../judge.mjs";
-import { harvest, resolveSessions } from "../wizard.mjs";
+import { harvest, aggregateCues } from "../wizard.mjs";
 
 const argv = process.argv.slice(2);
 const flag = (n) => { const i = argv.indexOf(n); return i > -1 ? argv[i + 1] : null; };
 const has = (n) => argv.includes(n);
+// harness adapter: whose transcripts to read. --harness codex (or SAWBUCK_HARNESS=codex); default Claude Code.
+const H = (flag("--harness") || process.env.SAWBUCK_HARNESS) === "codex" ? codexHarness : claudeHarness;
 
 // ---- `reins wizard` / `reins harvest`: read your old chats, rank the cues you keep giving ----
 if (argv[0] === "wizard" || argv[0] === "harvest") {
@@ -38,7 +42,7 @@ It reads every turn-pair with a model. On the local ollama default that is free;
   const maxPairs = parseInt(flag("--max"), 10) || 400;
   const sinceDays = parseInt(flag("--since"), 10) || 0;
   const sinceMs = sinceDays > 0 ? Date.now() - sinceDays * 86400000 : 0;
-  const sessions = resolveSessions({ limit: sessionsN, sinceMs });
+  const sessions = H.resolveSessions({ limit: sessionsN, sinceMs });
   if (!sessions.length) { process.stderr.write("reins wizard: no Claude Code sessions found under ~/.claude/projects\n"); process.exit(2); }
   const hosted = !b.startsWith("ollama:");
   if (hosted && !has("--yes")) {
@@ -46,7 +50,7 @@ It reads every turn-pair with a model. On the local ollama default that is free;
     process.exit(2);
   }
   process.stderr.write(`reins wizard: harvesting up to ${maxPairs} turn-pairs from ${sessions.length} session(s) via ${b}${hosted ? " (hosted, paid)" : " (local, free)"}...\n`);
-  const rw = await harvest(harvestScore, { sessions, maxPairs });
+  const rw = await harvest(harvestScore, { sessions, maxPairs, pairsFn: H.pairs });
   const wf = flag("--write");
   const out = wf && !wf.startsWith("--") ? wf : join(process.cwd(), ".sawbuck", "cues.json");
   if (has("--write") || !has("--json")) {
@@ -67,6 +71,56 @@ It reads every turn-pair with a model. On the local ollama default that is free;
   process.exit(0);
 }
 
+// ---- `reins cues`: real-time cue inventory. Classify THIS session's turns into the cue
+// structure and accumulate .sawbuck/cues.json. --append scores only the new turns since last
+// run (the per-turn path), and carries cues across sessions in this repo. One judge call per
+// new turn; free on local ollama. The batch cross-session cold-start is `reins wizard`. ----
+if (argv[0] === "cues") {
+  if (has("--help") || has("-h")) {
+    process.stdout.write(`reins cues: accumulate your cue inventory as you work
+
+Usage: reins cues [--append] [--session <path>] [--judge <b>] [--max N] [--json]
+
+  --append    score only the new turns since the last run, merge into .sawbuck/cues.json
+              (the per-turn path; carries cues across sessions in this repo)
+  --max N     without --append, cap the turns scored (default 400)
+  --judge <b> ollama:<model> (default, free, local) | haiku | anthropic:<model> | openai:<model>
+
+Free on the local ollama default. Seed from your whole history once with: reins wizard.
+`);
+    process.exit(0);
+  }
+  if (flag("--judge")) process.env.SAWBUCK_JUDGE = flag("--judge");
+  const b = backend();
+  const sess = H.resolveSessionPath(flag("--session"));
+  if (!sess) { process.stderr.write("reins cues: no session transcript found\n"); process.exit(2); }
+  let ctext = ""; try { ctext = readFileSync(sess, "utf8"); } catch { process.stderr.write("reins cues: cannot read " + sess + "\n"); process.exit(2); }
+  const allC = H.pairs(ctext);
+  const cout = join(process.cwd(), ".sawbuck", "cues.json");
+  let prior = { session: "", lastPairs: 0, items: [] };
+  if (has("--append")) { try { const p = JSON.parse(readFileSync(cout, "utf8")); if (p && Array.isArray(p.items)) prior = { session: p.session || "", lastPairs: p.lastPairs || 0, items: p.items }; } catch { /* fresh */ } }
+  const startIdx = has("--append") && prior.session === sess ? Math.min(prior.lastPairs, allC.length) : 0;   // same session = resume; new/changed session = score from its start
+  let fresh = allC.slice(startIdx);
+  // bounded per call: --append scores at most PER new pairs (oldest-first, so a backlog drains over
+  // turns); a full scan caps at --max newest. Keeps the per-turn background call cheap.
+  const PER = has("--append") ? 40 : (parseInt(flag("--max"), 10) || 400);
+  if (fresh.length > PER) fresh = has("--append") ? fresh.slice(0, PER) : fresh.slice(-PER);
+  const consumed = startIdx + fresh.length;
+  const items = has("--append") ? prior.items.slice() : [];
+  const sid = sess.split("/").pop();
+  for (const { prior: a, user: u } of fresh) { let r = null; try { r = await harvestScore(a, u); } catch {} items.push({ session: sid, result: r }); }
+  const capped = items.slice(-1500);
+  const agg = aggregateCues(capped);
+  const rec = { at: new Date().toISOString(), backend: b, session: sess, lastPairs: has("--append") ? consumed : allC.length, pairs: capped.length, ...agg, items: capped };
+  try { mkdirSync(dirname(cout), { recursive: true }); writeFileSync(cout, JSON.stringify(rec, null, 2) + "\n"); } catch { process.stderr.write("reins cues: could not write " + cout + "\n"); }
+  if (has("--json")) { const { items: _omit, ...pub } = rec; process.stdout.write(JSON.stringify(pub, null, 2) + "\n"); process.exit(0); }
+  const top = agg.cues.filter((c) => c.count >= 2 || c.gen > 0).slice(0, 10);
+  process.stdout.write(`\n  reins · cues   (judge: ${b})\n  ${agg.steers} steers over ${agg.scored} scored turns · ${top.length} cues\n`);
+  for (const c of top) process.stdout.write(`    ${("[" + c.axis + "]").padEnd(12)} ${(c.cue || "(unnamed)").padEnd(32)} · ${c.sessions} sess · ${c.count}x\n`);
+  process.stdout.write(`  wrote ${cout}\n\n`);
+  process.exit(0);
+}
+
 if (has("--help") || has("-h")) {
   process.stdout.write(`reins: measure how much you steer your agent this session
 
@@ -82,13 +136,16 @@ Usage: reins [--session <path.jsonl>] [--judge <backend>] [-n N] [--json] [--wri
   --label <term>     the word for the stat on the share card (default "steer rate";
                      e.g. "yank rate" for a playful channel - keep it neutral for LinkedIn)
 
+  --harness <h>      whose transcripts to read: claude (default) | codex (reads ~/.codex/sessions)
+
+Commands: 'reins wizard' (harvest history into cues), 'reins cues' (the live cue inventory). --help on each.
 Backend is SAWBUCK_JUDGE (default ollama:qwen2.5:7b). Local = free + private.
 `);
   process.exit(0);
 }
 
 if (flag("--judge")) process.env.SAWBUCK_JUDGE = flag("--judge");
-const sess = resolveSessionPath(flag("--session"));
+const sess = H.resolveSessionPath(flag("--session"));
 if (!sess) { process.stderr.write("reins: no session transcript found (pass --session <path.jsonl>)\n"); process.exit(2); }
 
 let text = "";
@@ -105,9 +162,14 @@ if (has("--append")) {
     const p = JSON.parse(readFileSync(out, "utf8"));
     if (p && p.lastPairs != null) prior = { lastPairs: p.lastPairs, scored: p.scored || 0, steering: p.steering || 0, wsum: p._wsum || 0, distribution: p.distribution || prior.distribution };
   } catch { /* no prior tally = fresh */ }
-  const all = pairs(text);
+  const all = H.pairs(text);
   let added = 0;
-  for (const { prior: a, user: u } of all.slice(prior.lastPairs)) {
+  // bounded per call (graceful): at most PER new pairs this run, so the first --append on a long
+  // session never blocks on hundreds of judge calls at once; a backlog drains over the next turns.
+  const PER = 40;
+  const start = Math.min(prior.lastPairs, all.length);
+  const consumed = Math.min(start + PER, all.length);
+  for (const { prior: a, user: u } of all.slice(start, consumed)) {
     let s = null; try { s = await score(a, u); } catch {}
     if (!s) continue;
     prior.distribution[s.pressure] = (prior.distribution[s.pressure] || 0) + 1;
@@ -115,7 +177,7 @@ if (has("--append")) {
     if (s.pressure >= 1) prior.steering++;
   }
   const rate = prior.scored ? prior.steering / prior.scored : 0;
-  const rec = { at: new Date().toISOString(), backend: backend(), lastPairs: all.length, turns: all.length, scored: prior.scored, steering: prior.steering, steeringRate: rate, meanPressure: prior.scored ? prior.wsum / prior.scored : 0, distribution: prior.distribution, _wsum: prior.wsum };
+  const rec = { at: new Date().toISOString(), backend: backend(), lastPairs: consumed, turns: all.length, scored: prior.scored, steering: prior.steering, steeringRate: rate, meanPressure: prior.scored ? prior.wsum / prior.scored : 0, distribution: prior.distribution, _wsum: prior.wsum };
   try { mkdirSync(dirname(out), { recursive: true }); writeFileSync(out, JSON.stringify(rec) + "\n"); } catch { process.stderr.write("reins: could not write " + out + "\n"); }
   if (has("--json")) process.stdout.write(JSON.stringify(rec) + "\n");
   else process.stdout.write(`reins: +${added} new turn(s), steer rate ${Math.round(rate * 100)}% over ${prior.scored} turns\n`);
@@ -123,7 +185,7 @@ if (has("--append")) {
 }
 
 const n = parseInt(flag("-n"), 10) || 0;
-const r = await scan(text, score, { limit: n });
+const r = await scan(text, score, { limit: n, pairsFn: H.pairs });
 
 // --write [path]: persist the summary so an OFFLINE reader (the sawbuck statusline)
 // can display the live steering number without ever calling a model itself.

package/codex.mjs

@@ -0,0 +1,99 @@
+// codex.mjs - the OpenAI Codex transcript adapter. The HARNESS sibling of scan.mjs: it reads
+// Codex's rollout logs and emits the SAME { prior, user } turn-pairs, so the judge (judge.mjs),
+// the cue aggregation (wizard.mjs), and the CLI work on Codex sessions unchanged. Exports the
+// same interface as scan.mjs (pairs / resolveSessionPath / resolveSessions) so the CLI swaps
+// adapters by --harness. Format verified against codex-cli 0.147.0 on disk + the openai/codex
+// source (rollout envelope { timestamp, type, payload }, serde snake_case tags).
+//
+//   sessions:  $CODEX_HOME/sessions/YYYY/MM/DD/rollout-<iso>-<thread>.jsonl  (+ legacy flat layout)
+//   turns:     prefer type=="event_msg" payload.type in {user_message, agent_message} (clean,
+//              already scaffolding-free); fall back to type=="response_item" message role
+//              user/assistant for older sessions, filtering the injected <environment_context> /
+//              AGENTS.md / permissions / collaboration_mode pseudo-user turns.
+
+import { readFileSync, readdirSync, statSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+const codexHome = () => process.env.CODEX_HOME || join(homedir(), ".codex");
+
+// role:user response_items are polluted with injected scaffolding - not real user turns.
+const SCAFFOLD = /^\s*<(environment_context|permissions|collaboration_mode|user_instructions|system|tools?)\b/i;
+const isNoise = (t) => { const s = String(t).trim(); return s.length < 3 || SCAFFOLD.test(s); };
+
+function textOf(content) {
+  if (typeof content === "string") return content;
+  if (Array.isArray(content)) return content.filter((b) => b && (b.type === "input_text" || b.type === "output_text" || b.type === "text") && b.text).map((b) => b.text).join(" ");
+  return "";
+}
+
+// Codex rollout jsonl -> ordered { role, text } turns, from whichever layer the file has.
+function turnsFromRollout(text) {
+  const objs = [];
+  for (const line of String(text).split("\n")) { const l = line.trim(); if (!l) continue; try { objs.push(JSON.parse(l)); } catch {} }
+  // newer builds carry the clean event_msg layer; if present, use it EXCLUSIVELY (the response_item
+  // layer duplicates each turn and carries scaffolding, so mixing them double-counts).
+  const hasEvent = objs.some((o) => o && o.type === "event_msg" && o.payload && (o.payload.type === "user_message" || o.payload.type === "agent_message"));
+  const turns = [];
+  for (const o of objs) {
+    if (!o || !o.payload) continue;
+    if (hasEvent) {
+      if (o.type !== "event_msg") continue;
+      if (o.payload.type === "user_message") turns.push({ role: "user", text: o.payload.message });
+      else if (o.payload.type === "agent_message") turns.push({ role: "assistant", text: o.payload.message });
+    } else {
+      if (o.type !== "response_item" || o.payload.type !== "message") continue;
+      const r = o.payload.role;
+      if (r === "user" || r === "assistant") turns.push({ role: r, text: textOf(o.payload.content) });
+    }
+  }
+  return turns;
+}
+
+// Same pairing contract as scan.mjs: every non-opener user turn that followed an agent turn.
+export function pairs(text) {
+  const out = [];
+  let prev = "", seen = false;
+  for (const { role, text: t } of turnsFromRollout(text)) {
+    const s = String(t == null ? "" : t);
+    if (role === "assistant") { if (s.trim()) prev = s.slice(0, 600); continue; }
+    if (isNoise(s)) continue;              // skip injected scaffolding / empties
+    if (!seen) { seen = true; continue; }  // opener = a request, not a steer
+    if (prev) out.push({ prior: prev, user: s.replace(/\s+/g, " ").slice(0, 800) });
+    prev = "";
+  }
+  return out;
+}
+
+// recursively list rollout-*.jsonl under $CODEX_HOME/sessions (dated tree + legacy flat)
+function listRollouts() {
+  const root = join(codexHome(), "sessions");
+  if (!existsSync(root)) return [];
+  const found = [];
+  const walk = (dir, depth) => {
+    if (depth > 5) return;
+    let ents = []; try { ents = readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of ents) {
+      const p = join(dir, e.name);
+      if (e.isDirectory()) walk(p, depth + 1);
+      else if (e.isFile() && /^rollout-.*\.jsonl$/.test(e.name)) { try { found.push({ path: p, mtime: statSync(p).mtimeMs }); } catch {} }
+    }
+  };
+  walk(root, 0);
+  return found;
+}
+
+export function resolveSessionPath(explicit) {
+  if (explicit) return existsSync(explicit) ? explicit : null;
+  const f = listRollouts();
+  if (!f.length) return null;
+  f.sort((a, b) => b.mtime - a.mtime);
+  return f[0].path;
+}
+
+export function resolveSessions({ limit = 0, sinceMs = 0 } = {}) {
+  let f = listRollouts();
+  if (sinceMs) f = f.filter((x) => x.mtime >= sinceMs);
+  f.sort((a, b) => b.mtime - a.mtime);
+  return (limit > 0 ? f.slice(0, limit) : f).map((x) => x.path);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sawbuck/reins",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Reins: measure how much you steer your AI coding agent. A per-turn steering-pressure judge over your session transcript, pluggable backend (Haiku / local ollama / any OpenAI-compatible). The LLM half of the reins steering layer; keeps sawbuck's core offline.",
   "type": "module",
   "license": "Apache-2.0",
@@ -14,6 +14,7 @@
     "bin/reins.mjs",
     "judge.mjs",
     "scan.mjs",
+    "codex.mjs",
     "wizard.mjs",
     "README.md",
     "LICENSE",

package/scan.mjs

@@ -2,6 +2,14 @@
 // reading: score each of your turns (given the agent action it followed) and
 // aggregate into a distribution + a seismograph. The scorer is injected so the
 // aggregation is testable without a live model.
+//
+// HARNESS ADAPTER SEAM. This file is the CLAUDE CODE adapter: humanText/assistantText/
+// noise parse Claude Code's .jsonl schema, and resolveSessions finds them under
+// ~/.claude/projects. Everything downstream (the judge in judge.mjs, the cue aggregation
+// in wizard.mjs, the CLI) operates ONLY on the abstract { prior, user } turn-pairs that
+// pairs() emits and knows nothing about Claude Code. So supporting another harness (Codex,
+// Cursor, ...) is a PARALLEL module that produces the same { prior, user } pairs + its own
+// session resolver, not a refactor. pairs() is the seam; keep it harness-agnostic.
 
 import { readFileSync, readdirSync, statSync, existsSync } from "node:fs";
 import { join } from "node:path";
@@ -53,8 +61,8 @@ export function pairs(text) {
 const GLYPH = { 0: ".", 1: "-", 2: "+", 3: "#" };
 
 // scan(text, scoreFn) -> aggregate. scoreFn(prior, user) -> {pressure, axis, nudge} | null.
-export async function scan(text, scoreFn, { limit = 0 } = {}) {
-  let ps = pairs(text);
+export async function scan(text, scoreFn, { limit = 0, pairsFn = pairs } = {}) {
+  let ps = pairsFn(text);
   if (limit > 0 && ps.length > limit) ps = ps.slice(-limit);   // most recent N
   const dist = { 0: 0, 1: 0, 2: 0, 3: 0 };
   let scored = 0, fails = 0, wsum = 0, spark = "";

package/wizard.mjs

@@ -39,12 +39,12 @@ export function aggregateCues(items) {
 
 // harvest(scoreFn, { sessions, maxPairs }) -> aggregateCues over the pairs in those session
 // files, newest first, capped at maxPairs (cost control). scoreFn(prior, user) -> result | null.
-export async function harvest(scoreFn, { sessions = [], maxPairs = 400 } = {}) {
+export async function harvest(scoreFn, { sessions = [], maxPairs = 400, pairsFn = pairs } = {}) {
   const items = [];
   const gathered = [];
   for (const path of sessions) {
     let text = ""; try { text = readFileSync(path, "utf8"); } catch { continue; }
-    for (const p of pairs(text)) {
+    for (const p of pairsFn(text)) {
       gathered.push({ ...p, session: path });
       if (gathered.length >= maxPairs) break;
     }