heeded 0.0.0-stage → 0.1.1

package/dist/claude-code.js

@@ -0,0 +1,250 @@
+import { lstat, open, readdir, realpath } from 'node:fs/promises';
+import { join } from 'node:path';
+/** A folder's entries by name; none when it doesn't exist. */
+async function entries(dir) {
+    try {
+        return (await readdir(dir, { withFileTypes: true })).sort((a, b) => (a.name < b.name ? -1 : 1));
+    }
+    catch {
+        return [];
+    }
+}
+/** A file's lines as its bytes arrive, never the whole file in memory. */
+async function* lines(file) {
+    const decoder = new TextDecoder();
+    let rest = '';
+    for await (const chunk of file.createReadStream()) {
+        const text = decoder.decode(chunk, { stream: true });
+        let start = 0;
+        for (let end = text.indexOf('\n'); end >= 0; end = text.indexOf('\n', start)) {
+            yield rest + text.slice(start, end);
+            rest = '';
+            start = end + 1;
+        }
+        rest += text.slice(start);
+    }
+    rest += decoder.decode();
+    if (rest)
+        yield rest;
+}
+const isFile = (f) => typeof f === 'object' && f !== null
+    && typeof f.path === 'string' && typeof f.type === 'string'
+    && typeof f.content === 'string';
+/** The tools whose result is what the user answered: a choice among options, a plan approved or not. */
+const ASKING = new Set(['AskUserQuestion', 'ExitPlanMode']);
+function flush(state, emit) {
+    if (state.reply)
+        emit(state.reply);
+    state.reply = null;
+}
+const isObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+const tokens = (v) => (typeof v === 'number' ? v : 0);
+/** A message's text: a string, or its text blocks joined (images and the rest left out). */
+const textOf = (c) => (typeof c === 'string' ? c
+    : Array.isArray(c) ? c.filter((b) => b?.type === 'text' && typeof b.text === 'string').map((b) => b.text).join('\n') : '');
+/** A launcher that appends the user's own instructions to the system prompt marks them with this tag, opened on a line
+ * of its own (the tag named in a sentence is not a block); the rest of the system prompt is Claude Code's, or the
+ * launcher's. */
+const INSTRUCTIONS = /(?:^|\n)<user-instructions>([\s\S]*?)<\/user-instructions>/g;
+/** The events of one line; false when it should have parsed and didn't. Only the lines heeded needs are parsed, found
+ * by a substring first: a tool result, the bulk of a transcript, only when it answers one of the agent's questions; the
+ * system prompt only when it holds the user's instructions. */
+function onLine(line, state, out) {
+    const user = line.includes('"type":"user"');
+    const result = user ? /"tool_use_id":"([^"]*)"/.exec(line) : null;
+    if (!line.includes('"type":"assistant"') && !line.includes('"type":"instructions"')
+        && !line.includes('"type":"nested_memory"') && !line.includes('"compact_boundary"') && !line.includes('"queued_command"')
+        && !(line.includes('"prompt_snapshot"') && line.includes('<user-instructions>'))
+        && !(user && (!result || state.asked.has(result[1]))))
+        return true;
+    let o;
+    try {
+        o = JSON.parse(line);
+    }
+    catch {
+        return false;
+    }
+    // A message's reply goes out before an event that changes the rules or the compactions; its own calls don't.
+    const emit = (e) => {
+        flush(state, out);
+        out(e);
+    };
+    const a = o.attachment;
+    const meta = o.compactMetadata;
+    const m = o.message;
+    if (o.type === 'assistant' && isObject(m) && Array.isArray(m.content) && typeof o.timestamp === 'string'
+        && !Number.isNaN(Date.parse(o.timestamp))) {
+        // The context the request was sent with: every line of a message carries the same usage.
+        const u = m.usage;
+        if (isObject(u))
+            state.depth = tokens(u.input_tokens) + tokens(u.cache_creation_input_tokens) + tokens(u.cache_read_input_tokens);
+        for (const b of m.content) {
+            // Replies are what the user reads: a subagent's text goes to the agent that called it.
+            if (b?.type === 'text' && typeof b.text === 'string' && typeof m.id === 'string' && state.replies) {
+                if (state.reply && state.of === m.id) {
+                    state.reply.text += `\n${b.text}`;
+                }
+                else {
+                    flush(state, out);
+                    if (state.of !== m.id)
+                        [state.of, state.parts] = [m.id, 0];
+                    // A message's text after one of its calls is a reply of its own.
+                    const id = state.parts ? `${m.id}/${state.parts}` : m.id;
+                    state.reply = { kind: 'reply', id, text: b.text, at: o.timestamp, depth: state.depth, compactions: state.compactions };
+                }
+            }
+            else if (b?.type === 'tool_use' && typeof b.id === 'string' && typeof b.name === 'string' && isObject(b.input)) {
+                if (ASKING.has(b.name))
+                    state.asked.add(b.id);
+                // What the agent said goes out before the call it said it before.
+                if (state.reply) {
+                    flush(state, out);
+                    if (state.of === m.id)
+                        state.parts++;
+                }
+                const own = typeof b.input.file_path === 'string' && b.input.file_path.startsWith(state.own);
+                out({ kind: 'call', id: b.id, tool: b.name, input: b.input, at: o.timestamp, depth: state.depth, compactions: state.compactions,
+                    ...(own ? { own } : {}) });
+            }
+        }
+    }
+    else if (o.type === 'user' && isObject(m) && !o.isMeta && !o.isCompactSummary && typeof o.timestamp === 'string'
+        && !Number.isNaN(Date.parse(o.timestamp))) {
+        const results = Array.isArray(m.content) ? m.content.filter((b) => b?.type === 'tool_result') : [];
+        for (const b of results) {
+            const text = state.asked.has(b.tool_use_id) ? textOf(b.content) : '';
+            if (text.trim())
+                emit({ kind: 'prompt', text, at: o.timestamp, by: 'user', starts: false });
+        }
+        const text = results.length ? '' : textOf(m.content);
+        const start = text.trimStart();
+        const command = /^<command-(?:name|message)>/.test(start) && /<command-name>([^<]*)<\/command-name>/.exec(start);
+        if (command) {
+            const args = /<command-args>([\s\S]*?)<\/command-args>/.exec(start)?.[1] ?? '';
+            emit({ kind: 'prompt', text: `${command[1]} ${args}`.trim(), at: o.timestamp, by: 'user', starts: false });
+        }
+        else if (start && start[0] !== '<' && !start.startsWith('[Request interrupted')) {
+            // Other lines starting with a tag are Claude Code's own (a command's output, a notification), as is an
+            // interruption's note.
+            emit({ kind: 'prompt', text, at: o.timestamp, by: state.replies ? 'user' : 'agent', starts: true });
+        }
+    }
+    else if (o.type === 'attachment' && a?.type === 'queued_command' && a.commandMode === 'prompt' && a.origin?.kind === 'human'
+        && typeof o.timestamp === 'string' && !Number.isNaN(Date.parse(o.timestamp))) {
+        // What the user typed while the agent worked reaches it mid-turn, recorded only here.
+        const text = textOf(a.prompt);
+        if (text.trim())
+            emit({ kind: 'prompt', text, at: o.timestamp, by: 'user', starts: false });
+    }
+    else if (o.type === 'attachment' && a?.type === 'prompt_snapshot' && Array.isArray(a.systemPrompt)
+        && typeof o.timestamp === 'string' && !Number.isNaN(Date.parse(o.timestamp))) {
+        const parts = a.systemPrompt.filter((p) => typeof p === 'string');
+        const text = parts.flatMap((p) => [...p.matchAll(INSTRUCTIONS)].map((m) => m[1].trim())).filter(Boolean).join('\n');
+        if (text)
+            emit({ kind: 'prompt', text, at: o.timestamp, by: 'user', starts: false, session: true });
+    }
+    else if (o.type === 'attachment' && a?.type === 'instructions' && Array.isArray(a.files)) {
+        // After a compaction Claude Code records every file in effect again: they replace the ones before.
+        emit({ kind: 'instructions', files: a.files.filter(isFile), replace: state.replace });
+        state.replace = false;
+    }
+    else if (o.type === 'attachment' && a?.type === 'nested_memory' && isFile(a.content)) {
+        const { path, type, content } = a.content;
+        emit({ kind: 'instructions', files: [{ path, type, content }], replace: false });
+    }
+    else if (o.type === 'system' && o.subtype === 'compact_boundary' && typeof meta?.trigger === 'string'
+        && typeof meta.preTokens === 'number') {
+        emit({ kind: 'compaction', trigger: meta.trigger, preTokens: meta.preTokens });
+        state.compactions++;
+        state.replace = true;
+    }
+    return true;
+}
+/**
+ * Streams one transcript into events, after its `transcript` event. A main transcript (`inside` given) is read only
+ * when it ran in the folder: decided by the first line that records a `cwd`, the only line parsed for it; a file that
+ * never records one stays in scope, since its project folder's name already matched. Events of the lines before that
+ * one wait for the decision.
+ *
+ * A file read whole is unrecognized when, from 20 lines on, more than half don't parse (a line that isn't `{…}`, or one
+ * heeded parses and can't) or none is an assistant or user line: Claude Code may have changed its format, and an empty
+ * result would hide it.
+ */
+async function readFile(path, session, agent, inside, own, emit, unrecognized) {
+    const file = await open(path).catch(() => null);
+    if (!file)
+        return false; // deleted since it was listed, or not readable: skipped
+    let decided = inside === null;
+    const held = [];
+    if (decided)
+        emit({ kind: 'transcript', session, agent });
+    const out = (e) => (decided ? emit(e) : held.push(e));
+    const state = { compactions: 0, replace: false, depth: 0, replies: agent === null, reply: null, of: '', parts: 0,
+        asked: new Set(), own };
+    let total = 0;
+    let bad = 0;
+    let messages = false;
+    for await (const line of lines(file)) {
+        if (!line)
+            continue;
+        total++;
+        if (!decided && line.includes('"cwd":"')) {
+            let cwd;
+            try {
+                cwd = JSON.parse(line).cwd;
+            }
+            catch { }
+            if (typeof cwd === 'string') {
+                if (!inside(cwd))
+                    return false;
+                decided = true;
+                emit({ kind: 'transcript', session, agent });
+                held.forEach(emit);
+            }
+        }
+        if (line.includes('"type":"assistant"') || line.includes('"type":"user"'))
+            messages = true;
+        if (line[0] !== '{' || !line.endsWith('}') || !onLine(line, state, out))
+            bad++;
+    }
+    flush(state, out);
+    if (total >= 20 && (bad * 2 > total || !messages))
+        unrecognized.push(path);
+    if (!decided && total > 0) {
+        emit({ kind: 'transcript', session, agent });
+        held.forEach(emit);
+    }
+    return true;
+}
+/** Claude Code names a project's folder after its path, every character but a letter or a digit turned into `-`. */
+const encode = (path) => path.replace(/[^a-zA-Z0-9]/g, '-');
+export async function read(configDir, folder, emit) {
+    const unrecognized = [];
+    // Claude Code records the path it was started from, which may be the folder's real path or a symlink to it.
+    const folders = [...new Set([folder, await realpath(folder).catch(() => folder)])];
+    const names = folders.map(encode);
+    const inside = (cwd) => folders.some((f) => cwd === f || cwd.startsWith(`${f}/`));
+    const projects = join(configDir, 'projects');
+    for (const dir of await entries(projects)) {
+        if (!dir.isDirectory() || !names.some((n) => dir.name === n || dir.name.startsWith(`${n}-`)))
+            continue;
+        const project = join(projects, dir.name);
+        for (const file of await entries(project)) {
+            if (!file.isFile() || !file.name.endsWith('.jsonl'))
+                continue;
+            const session = file.name.slice(0, -'.jsonl'.length);
+            if (!(await readFile(join(project, file.name), session, null, inside, `${projects}/`, emit, unrecognized)))
+                continue;
+            const subagents = join(project, session, 'subagents');
+            const real = async (dir) => (await lstat(dir).catch(() => null))?.isDirectory();
+            if (!(await real(join(project, session))) || !(await real(subagents)))
+                continue;
+            for (const sub of await entries(subagents)) {
+                if (!sub.isFile() || !sub.name.startsWith('agent-') || !sub.name.endsWith('.jsonl'))
+                    continue;
+                await readFile(join(subagents, sub.name), session, sub.name.slice('agent-'.length, -'.jsonl'.length), null, `${projects}/`, emit, unrecognized);
+            }
+        }
+    }
+    return { unrecognized };
+}

package/dist/cli.js

@@ -0,0 +1,258 @@
+#!/usr/bin/env node
+// The heeded command: arguments, the two commands, the question before spending, exit codes.
+import { readFileSync, realpathSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { createInterface } from 'node:readline/promises';
+import { parseArgs } from 'node:util';
+import { counter } from './check.js';
+import { read } from './claude-code.js';
+import { BUDGET, estimate as judgingEstimate, JUDGE_MODEL, judge, select, verdicts } from './judge.js';
+import { approx, json, rules, text } from './report.js';
+import { redact } from './redact.js';
+import { estimate, extract, lineOf, MODEL, remember, rulesOf } from './rules.js';
+const HELP = `heeded — did your coding agent follow its instructions?
+
+usage
+  heeded            report on the claude code sessions run in this folder
+  heeded rules      the rules found, and how each one is checked
+
+options
+  --all             judge every case waiting, not one run's 150k tokens
+  --json            the report as json
+  --help, --version
+
+reads CLAUDE_CONFIG_DIR, else ~/.claude. caches rules and verdicts in XDG_CACHE_HOME, else ~/.cache.
+`;
+/** One pass over the folder's transcripts with the rules and verdicts cached so far: the report, the sections to read,
+ * the cases waiting for the judge, and what the most the rules may still take would cost. */
+async function scan(configDir, folder, cacheDir, home) {
+    const count = counter(rulesOf(cacheDir), verdicts(cacheDir));
+    const { unrecognized } = await read(configDir, folder, count.on);
+    for (const v of count.readVersions())
+        remember(cacheDir, v.identity, v.section.hash, v.at);
+    const data = count.result();
+    // Where each rule is written now, what the user opens to rewrite or remove it.
+    // Claude Code reads the user's own file from ~/.claude whatever the config dir.
+    const content = onDisk(folder, [configDir, join(home, '.claude')]);
+    for (const rule of data.rules) {
+        for (const file of rule.files) {
+            const line = lineOf(content(file), rule.quote, rule.heading);
+            if (line)
+                rule.lines[file] = line;
+        }
+    }
+    const waiting = count.waiting();
+    // A tool rule lists 40 of its candidates: the others cost what those listed cost on average.
+    const listed = [...waiting.tool, ...waiting.judgment].flat();
+    const each = listed.length ? judgingEstimate(listed).tokens / listed.length : 0;
+    return { report: { folder, configDir, unrecognized, ...data, toJudgeTokens: Math.round(each * data.toJudge) },
+        pending: count.pending(), waiting, mostTokens: Math.round(each * data.atMost) };
+}
+/** Instruction files as they are on disk now, secrets redacted as in what their rules were read from (a redaction
+ * keeps every line); empty for a file gone. Read only in the folder, the folders above it and the agent's own: where
+ * the user already gave access, so no privacy prompt for another folder. And only a regular file under 1 MB: a path
+ * from a transcript may name a pipe, which would never end. */
+function onDisk(folder, own) {
+    const read = new Map();
+    const allowed = (file) => [folder, ...own].some((dir) => file.startsWith(`${dir}/`))
+        || `${folder}/`.startsWith(dirname(file).replace(/\/?$/, '/'));
+    return (file) => {
+        if (!read.has(file)) {
+            let text = '';
+            try {
+                const stat = allowed(file) ? statSync(file) : null;
+                if (stat?.isFile() && stat.size < 1_000_000)
+                    text = redact(readFileSync(file, 'utf8'));
+            }
+            catch {
+                // gone, or not readable: no line
+            }
+            read.set(file, text);
+        }
+        return read.get(file);
+    };
+}
+const thousands = (n) => n.toLocaleString('en-US');
+const plural = (n, word) => `${thousands(n)} ${word}${n === 1 ? '' : 's'}`;
+const clock = (ms) => `${Math.floor(ms / 60_000)}:${String(Math.floor(ms / 1000) % 60).padStart(2, '0')}`;
+/** Runs a step that calls claude, with a status line meanwhile: what it does, the calls done when it makes several, the
+ * time so far, shown again every second. A call takes up to a minute or two: without it the run looks stuck. */
+async function step(io, doing, work) {
+    const start = Date.now();
+    let calls = '';
+    const show = () => io.status(`${doing}${calls} · ${clock(Date.now() - start)}`);
+    const timer = setInterval(show, 1000);
+    try {
+        return await work((done, of) => {
+            calls = of > 1 ? ` · ${done} of ${of} calls done` : '';
+            show();
+        });
+    }
+    finally {
+        clearInterval(timer);
+        io.status('');
+    }
+}
+/** Runs heeded; resolves to the exit code: 0 done (violations included), 1 an error, 2 wrong usage. */
+export async function main(argv, io) {
+    const usage = (what) => {
+        io.err(`heeded: ${what}. see heeded --help.\n`);
+        return 2;
+    };
+    let args;
+    try {
+        args = parseArgs({ args: argv, allowPositionals: true,
+            options: { all: { type: 'boolean' }, json: { type: 'boolean' }, help: { type: 'boolean' },
+                version: { type: 'boolean' } } });
+    }
+    catch (e) {
+        return usage(`unknown option ${/'([^']*)'/.exec(e.message)?.[1] ?? ''}`.trim());
+    }
+    const [command, ...rest] = args.positionals;
+    if (command !== undefined && command !== 'rules')
+        return usage(`unknown command ${command}`);
+    if (rest.length)
+        return usage(`unexpected ${rest.join(' ')}`);
+    if (command === 'rules' && args.values.all)
+        return usage('--all judges cases, and heeded rules never judges');
+    if (args.values.help) {
+        io.out(HELP);
+        return 0;
+    }
+    if (args.values.version) {
+        io.out(`${JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version}\n`);
+        return 0;
+    }
+    try {
+        return await run(command, args.values.json === true, args.values.all === true, io);
+    }
+    catch (e) {
+        io.err(`heeded: ${String(e.message).split('\n')[0]}\n`);
+        return 1;
+    }
+}
+/** The report, after reading new sections and judging cases if the user says so: within one run's budget, or, with
+ * `all`, round after round until no case waits. */
+async function run(command, asJson, all, io) {
+    const home = io.env.HOME || homedir();
+    const configDir = io.env.CLAUDE_CONFIG_DIR || join(home, '.claude');
+    const cacheDir = io.env.XDG_CACHE_HOME || join(home, '.cache');
+    let { report, pending, waiting, mostTokens } = await scan(configDir, io.cwd, cacheDir, home);
+    let code = 0;
+    const failed = (errors) => {
+        for (const e of errors)
+            io.err(`heeded: ${e}\n`);
+        if (errors.length)
+            code = 1;
+    };
+    // ctrl-c or ctrl-d at the question is a no.
+    const yes = async () => /^y(es)?$/i.test((await io.ask('go ahead? [y/N] ').catch(() => '')).trim());
+    const distinct = [...new Map(pending.map((p) => [p.section.hash, p.section])).values()];
+    /** Reads the new sections, then counts again: the rules just read have cases of their own. False when none was
+     * read. */
+    const readSections = async () => {
+        const found = await step(io, `reading ${plural(distinct.length, 'rule section')}`, (progress) => extract(pending, io.env, cacheDir, progress));
+        if (found.read)
+            io.err(`read ${plural(found.read, 'section')} · ${thousands(found.tokens)} tokens\n`);
+        failed(found.errors);
+        if (found.read)
+            ({ report, waiting, mostTokens } = await scan(configDir, io.cwd, cacheDir, home));
+        return found.read > 0;
+    };
+    /** Asks about the new sections alone, and reads them on yes. */
+    const askToRead = async (then) => {
+        io.err(`${plural(distinct.length, 'rule section')} to read${then} · claude ${MODEL}`
+            + ` · ${approx(estimate(distinct).tokens)} tokens\n`);
+        return await yes() && await readSections();
+    };
+    /** Judges the cases a round picks, then counts again; with `all`, again while cases wait and the last round judged
+     * some. One line for every round. */
+    const judgeCases = async () => {
+        let judged = 0;
+        let tokens = 0;
+        const errors = [];
+        for (;;) {
+            const picked = select(waiting.tool, waiting.judgment, all ? Infinity : BUDGET);
+            if (!picked.length)
+                break;
+            const done = await step(io, `judging ${plural(picked.length, 'case')}`, (progress) => judge(picked, io.env, cacheDir, progress));
+            judged += done.judged;
+            tokens += done.tokens;
+            errors.push(...done.errors);
+            if (done.judged)
+                ({ report, waiting, mostTokens } = await scan(configDir, io.cwd, cacheDir, home));
+            if (!all || !done.judged)
+                break;
+        }
+        if (judged)
+            io.err(`judged ${plural(judged, 'case')} · ${thousands(tokens)} tokens\n`);
+        failed(errors);
+    };
+    // Reading sections and judging cases spend the user's quota: only when asked on a terminal, after what the run may
+    // spend. Every call costs ~4k tokens: an estimate is never under a thousand.
+    if (io.terminal && command === 'rules') {
+        // The rules and how each is checked: no verdict changes them, only new sections do.
+        if (distinct.length)
+            await askToRead('');
+    }
+    else if (io.terminal && (distinct.length || report.toJudge > 0)) {
+        if (!all) {
+            // One question. The cases of the rules about to be read aren't known yet: with sections to read, it shows the
+            // ceiling.
+            if (distinct.length) {
+                const models = [...new Set([MODEL, JUDGE_MODEL])].join(' and ');
+                io.err(`${plural(distinct.length, 'rule section')} to read, then cases to judge · claude ${models}`
+                    + ` · up to ${approx(estimate(distinct).tokens + BUDGET)} tokens\n`);
+            }
+            else {
+                const picked = select(waiting.tool, waiting.judgment, BUDGET);
+                const some = picked.length < report.toJudge;
+                const cases = some ? `${thousands(picked.length)} of ${plural(report.toJudge, 'case')}`
+                    : plural(picked.length, 'case');
+                io.err(`${cases} to judge · claude ${JUDGE_MODEL} · ${approx(judgingEstimate(picked).tokens)} tokens`
+                    + `${some ? ` · all of them ${approx(report.toJudgeTokens)}: heeded --all` : ''}\n`);
+            }
+            if (await yes() && (!distinct.length || await readSections()))
+                await judgeCases();
+        }
+        else {
+            // Every case: what judging them costs is known once the new sections are read, so the reading is asked first.
+            const reading = !distinct.length || await askToRead(' first');
+            if (reading && report.toJudge > 0) {
+                const more = report.atMost > report.toJudge;
+                io.err(`${plural(report.toJudge, 'case')} to judge${more ? ', more if their rules apply' : ''}`
+                    + ` · claude ${JUDGE_MODEL} · ${approx(report.toJudgeTokens)} tokens`
+                    + `${more ? `, at most ${approx(mostTokens)}` : ''}\n`);
+                if (await yes())
+                    await judgeCases();
+            }
+        }
+    }
+    const color = io.columns !== undefined && !io.env.NO_COLOR;
+    if (asJson)
+        io.out(json(report));
+    else if (command === 'rules' && report.sessions && report.files.length)
+        io.out(rules(report, { color, home }));
+    else
+        io.out(text(report, { columns: io.columns ?? 80, color, now: new Date(), home }));
+    return code;
+}
+// Run as the `heeded` bin (npm links it, so its real path is compared), not when imported.
+if (process.argv[1] && realpathSync(process.argv[1]) === import.meta.filename) {
+    const ask = async (question) => {
+        const rl = createInterface({ input: process.stdin, output: process.stderr });
+        try {
+            return await rl.question(question);
+        }
+        finally {
+            rl.close();
+        }
+    };
+    process.exitCode = await main(process.argv.slice(2), {
+        env: process.env, cwd: process.cwd(), terminal: Boolean(process.stdin.isTTY && process.stderr.isTTY),
+        columns: process.stdout.isTTY ? process.stdout.columns : undefined, ask,
+        out: (s) => process.stdout.write(s), err: (s) => process.stderr.write(s),
+        status: (line) => process.stderr.write(`\r\x1b[K${line}`),
+    });
+}