@astudioplus/compressor 0.1.0

package/dist/cli/commands/savings.js

@@ -0,0 +1,196 @@
+import { writeFile } from 'node:fs/promises';
+import { resolveLedgerDir } from "../../ledger/write.js";
+import { readLedger } from "../../ledger/read.js";
+const fmt = (n) => Math.round(n).toLocaleString('en-US');
+export function parseSince(value) {
+    if (value === 'all') {
+        return undefined;
+    }
+    const days = /^(\d+)d$/.exec(value)?.[1];
+    if (days === undefined) {
+        throw new Error(`invalid --since '${value}' (expected e.g. 7d, 30d, or 'all')`);
+    }
+    return new Date(Date.now() - Number(days) * 86_400_000);
+}
+/**
+ * Human label for the lookback window. Totals MUST state their window:
+ * the default is 30d, and an unqualified headline (especially in the
+ * shareable HTML artifact) reads as all-time.
+ */
+export function windowLabel(since) {
+    if (since === 'all') {
+        return 'all time';
+    }
+    const days = /^(\d+)d$/.exec(since)?.[1];
+    if (days === undefined) {
+        return since;
+    }
+    return Number(days) === 1 ? 'last 1 day' : `last ${days} days`;
+}
+function labelFor(event, by) {
+    switch (by) {
+        case 'day':
+            return event.ts.slice(0, 10);
+        case 'tool':
+            return event.tool;
+        case 'mode':
+            return event.mode;
+    }
+}
+/** Group savings by dimension. Days sort ascending; tool/mode by size. */
+export function aggregateSavings(events, by) {
+    const groups = new Map();
+    for (const event of events) {
+        const label = labelFor(event, by);
+        const row = groups.get(label) ?? { label, savedChars: 0, savedTokens: 0, events: 0 };
+        row.savedChars += event.charsIn - event.charsOut;
+        row.savedTokens += event.estTokensIn - event.estTokensOut;
+        row.events += 1;
+        groups.set(label, row);
+    }
+    const rows = [...groups.values()];
+    return by === 'day'
+        ? rows.sort((a, b) => a.label.localeCompare(b.label))
+        : rows.sort((a, b) => b.savedTokens - a.savedTokens);
+}
+const BAR_WIDTH = 40;
+function bar(value, max) {
+    if (value <= 0 || max <= 0) {
+        return '';
+    }
+    return '█'.repeat(Math.max(1, Math.round((value / max) * BAR_WIDTH)));
+}
+function chartLines(rows) {
+    const max = Math.max(...rows.map((r) => r.savedTokens), 1);
+    const labelWidth = Math.max(...rows.map((r) => r.label.length), 0);
+    return rows.map((r) => `  ${r.label.padEnd(labelWidth)}  ${bar(r.savedTokens, max).padEnd(BAR_WIDTH)}  ≈ ${fmt(r.savedTokens)} tok`);
+}
+/**
+ * Empty states must distinguish "no ledger at all" (hook not installed /
+ * never fired — point at `compressor init`) from "no events INSIDE the
+ * window" (the hook works fine; suggesting a reinstall would misdirect).
+ * `eventsOutsideWindow` is the all-time count when the window filtered
+ * everything out.
+ */
+export function renderEmpty(dir, window, eventsOutsideWindow = 0) {
+    if (eventsOutsideWindow > 0) {
+        return [
+            `no ledger events in the ${window} window (looked in ${dir})`,
+            '',
+            `the ledger holds ${fmt(eventsOutsideWindow)} events outside this window — the hook is`,
+            'working; widen the window (e.g. --since all) to see them.',
+        ].join('\n');
+    }
+    return [
+        `no ledger events yet (looked in ${dir})`,
+        '',
+        'the compression hook records an event every time it shrinks tool output',
+        'during a real agent session — run `compressor init`, use claude-code or',
+        'copilot normally, then check back here.',
+        '',
+        'recording can be disabled with COMPRESSOR_NO_LEDGER=1 (kill switch).',
+    ].join('\n');
+}
+export function renderSavings(events, by, dir, window) {
+    const savedChars = events.reduce((acc, e) => acc + (e.charsIn - e.charsOut), 0);
+    const savedTokens = events.reduce((acc, e) => acc + (e.estTokensIn - e.estTokensOut), 0);
+    const lines = [
+        `saved ${fmt(savedChars)} chars (exact) ≈ ${fmt(savedTokens)} tokens (estimated — cheap estimator, not billable counts) · ${window}`,
+        `events: ${fmt(events.length)} (${window})`,
+        '',
+        `by ${by}:`,
+        ...chartLines(aggregateSavings(events, by)),
+        '',
+        'measured savings come from `compressor benchmark` — this view is the live estimated ledger',
+        `ledger: ${dir} (disable recording with COMPRESSOR_NO_LEDGER=1)`,
+    ];
+    return lines.join('\n');
+}
+function escapeHtml(text) {
+    return text
+        .replaceAll('&', '&amp;')
+        .replaceAll('<', '&lt;')
+        .replaceAll('>', '&gt;')
+        .replaceAll('"', '&quot;');
+}
+function svgBarChart(rows) {
+    if (rows.length === 0) {
+        return '<p class="empty">no events in this window</p>';
+    }
+    const rowH = 26;
+    const labelW = 120;
+    const barMax = 420;
+    const valueW = 140;
+    const width = labelW + barMax + valueW;
+    const height = rows.length * rowH + 10;
+    const max = Math.max(...rows.map((r) => r.savedTokens), 1);
+    const parts = rows.map((r, i) => {
+        const y = 5 + i * rowH;
+        const w = r.savedTokens <= 0 ? 0 : Math.max(2, Math.round((r.savedTokens / max) * barMax));
+        return [
+            `<text x="${labelW - 10}" y="${y + 17}" text-anchor="end" class="label">${escapeHtml(r.label)}</text>`,
+            `<rect x="${labelW}" y="${y + 4}" width="${w}" height="16" rx="3" class="bar"/>`,
+            `<text x="${labelW + w + 8}" y="${y + 17}" class="value">≈ ${fmt(r.savedTokens)} tok (${fmt(r.savedChars)} chars)</text>`,
+        ].join('');
+    });
+    return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${width} ${height}" width="${width}" height="${height}" role="img">${parts.join('')}</svg>`;
+}
+export function renderSavingsHtml(events, dir, window) {
+    const savedChars = events.reduce((acc, e) => acc + (e.charsIn - e.charsOut), 0);
+    const savedTokens = events.reduce((acc, e) => acc + (e.estTokensIn - e.estTokensOut), 0);
+    const sections = ['day', 'tool', 'mode']
+        .map((by) => `<h2>by ${by}</h2>\n${svgBarChart(aggregateSavings(events, by))}`)
+        .join('\n');
+    // Self-contained on purpose: inline CSS, static SVG, no JS, no requests.
+    // The window label is mandatory: this artifact is shared standalone and an
+    // unqualified headline would read as all-time.
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>compressor savings</title>
+<style>
+body { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; margin: 2rem auto; max-width: 760px; color: #1f2328; }
+h1 { font-size: 1.3rem; } h2 { font-size: 1rem; margin-top: 1.6rem; }
+.totals { font-size: 0.95rem; } .footer, .empty { color: #57606a; font-size: 0.8rem; }
+svg .label, svg .value { font-size: 12px; fill: #1f2328; }
+svg .bar { fill: #4c9aff; }
+</style>
+</head>
+<body>
+<h1>compressor savings <span class="footer">(${escapeHtml(window)})</span></h1>
+<p class="totals">saved ${fmt(savedChars)} chars (exact) ≈ ${fmt(savedTokens)} tokens (estimated — cheap estimator, not billable counts) · ${fmt(events.length)} events · ${escapeHtml(window)}</p>
+${sections}
+<p class="footer">measured savings come from <code>compressor benchmark</code> — this view is the live estimated ledger.<br>
+ledger: ${escapeHtml(dir)} · disable recording with COMPRESSOR_NO_LEDGER=1</p>
+</body>
+</html>
+`;
+}
+function parseBy(value) {
+    if (value === 'day' || value === 'tool' || value === 'mode') {
+        return value;
+    }
+    throw new Error(`invalid --by '${value}' (expected day|tool|mode)`);
+}
+export async function runSavings(opts) {
+    const sinceRaw = opts.since ?? '30d';
+    const since = parseSince(sinceRaw);
+    const window = windowLabel(sinceRaw);
+    const by = parseBy(opts.by ?? 'day');
+    const dir = opts.ledgerDir ?? resolveLedgerDir();
+    const events = await readLedger(since === undefined ? { dir } : { dir, since });
+    if (events.length === 0) {
+        // distinguish a truly empty ledger from one whose events all fall
+        // outside the window — the latter must not suggest reinstalling a hook
+        // that works fine
+        const allTime = since === undefined ? [] : await readLedger({ dir });
+        console.log(renderEmpty(dir, window, allTime.length));
+        return;
+    }
+    console.log(renderSavings(events, by, dir, window));
+    if (opts.html !== undefined) {
+        await writeFile(opts.html, renderSavingsHtml(events, dir, window), 'utf8');
+        console.log(`\nhtml report written to ${opts.html}`);
+    }
+}

package/dist/cli/commands/set-mode.d.ts

@@ -0,0 +1,5 @@
+import type { ScopeOptions } from './init.ts';
+export interface SetModeOptions extends ScopeOptions {
+    agent: string[];
+}
+export declare function runSetMode(mode: string, opts: SetModeOptions): Promise<void>;

package/dist/cli/commands/set-mode.js

@@ -0,0 +1,13 @@
+import { effectNote, installForAgents, parsePackMode, resolveAgents } from "./init.js";
+import { uninstallForAgents } from "./uninstall.js";
+export async function runSetMode(mode, opts) {
+    const agents = resolveAgents(opts.agent);
+    if (mode === 'full') {
+        await uninstallForAgents(agents, opts);
+        const names = agents.map((adapter) => adapter.name).join(', ');
+        const suffix = opts.dryRun === true ? ' (dry-run: nothing written)' : '';
+        console.log(`Mode full: compressor artifacts removed for ${names} (true baseline, no instruction pack, no hook). ${effectNote(agents)}${suffix}`);
+        return;
+    }
+    await installForAgents(agents, parsePackMode(mode), opts);
+}

package/dist/cli/commands/stats.d.ts

@@ -0,0 +1,5 @@
+export interface StatsOptions {
+    project?: string;
+    since?: string;
+}
+export declare function runStats(opts: StatsOptions): Promise<void>;

package/dist/cli/commands/stats.js

@@ -0,0 +1,51 @@
+import path from 'node:path';
+import process from 'node:process';
+import { addUsage, aggregateUsage, findTranscripts, readSessionUsage, } from "../../claude/transcripts.js";
+function parseSinceDays(value) {
+    const days = /^(\d+)d$/.exec(value)?.[1];
+    if (days === undefined) {
+        throw new Error(`invalid --since '${value}' (expected e.g. 7d, 30d)`);
+    }
+    return Number(days);
+}
+const fmt = (n) => n.toLocaleString('en-US');
+export async function runStats(opts) {
+    const days = parseSinceDays(opts.since ?? '30d');
+    const projectDir = path.resolve(opts.project ?? process.cwd());
+    const since = new Date(Date.now() - days * 86_400_000);
+    const files = await findTranscripts({ projectDir, since });
+    const sessions = [];
+    for (const file of files) {
+        sessions.push(await readSessionUsage(file));
+    }
+    const totals = aggregateUsage(sessions);
+    const turns = sessions.reduce((acc, s) => acc + s.turns, 0);
+    const byModel = {};
+    for (const session of sessions) {
+        for (const [model, usage] of Object.entries(session.byModel)) {
+            byModel[model] = addUsage(byModel[model] ?? { input: 0, output: 0, cacheCreation: 0, cacheRead: 0 }, usage);
+        }
+    }
+    const rows = [
+        ['sessions', fmt(sessions.length)],
+        ['turns', fmt(turns)],
+        ['input', fmt(totals.input)],
+        ['output', fmt(totals.output)],
+        ['cacheCreation', fmt(totals.cacheCreation)],
+        ['cacheRead', fmt(totals.cacheRead)],
+    ];
+    const width = Math.max(...rows.map(([label]) => label.length));
+    for (const [label, value] of rows) {
+        console.log(`${label.padEnd(width)}  ${value}`);
+    }
+    const models = Object.entries(byModel);
+    if (models.length > 0) {
+        console.log('');
+        console.log('by model:');
+        for (const [model, u] of models) {
+            console.log(`  ${model}: input=${fmt(u.input)} output=${fmt(u.output)} cacheCreation=${fmt(u.cacheCreation)} cacheRead=${fmt(u.cacheRead)}`);
+        }
+    }
+    console.log('');
+    console.log(`actual usage from Claude Code transcripts (last ${days}d, ${projectDir})`);
+}

package/dist/cli/commands/status.d.ts

@@ -0,0 +1 @@
+export declare function runStatus(global?: boolean): Promise<void>;

package/dist/cli/commands/status.js

@@ -0,0 +1,11 @@
+import { adapters } from "../../adapters/index.js";
+import { buildContext } from "./init.js";
+export async function runStatus(global = false) {
+    const ctx = buildContext(global, 'optimized', false);
+    for (const adapter of adapters) {
+        const status = await adapter.status(ctx);
+        const installed = status.installed ? 'installed' : 'not installed';
+        const mode = status.mode === undefined ? '' : ` (mode=${status.mode})`;
+        console.log(`${status.agent}: ${installed}${mode} — ${status.detail}`);
+    }
+}

package/dist/cli/commands/uninstall.d.ts

@@ -0,0 +1,7 @@
+import type { Adapter } from '../../adapters/index.ts';
+import type { ScopeOptions } from './init.ts';
+export interface UninstallOptions extends ScopeOptions {
+    agent: string[];
+}
+export declare function uninstallForAgents(agents: Adapter[], opts: ScopeOptions): Promise<void>;
+export declare function runUninstall(opts: UninstallOptions): Promise<void>;

package/dist/cli/commands/uninstall.js

@@ -0,0 +1,22 @@
+import { applyChanges, renderChanges } from "../../adapters/index.js";
+import { buildContext, resolveAgents } from "./init.js";
+export async function uninstallForAgents(agents, opts) {
+    const ctx = buildContext(opts.global === true, 'optimized', false);
+    for (const adapter of agents) {
+        const changes = await adapter.uninstall(ctx);
+        const rendered = renderChanges(changes);
+        if (rendered !== '') {
+            console.log(rendered);
+        }
+        if (opts.dryRun !== true) {
+            await applyChanges(changes);
+        }
+    }
+}
+export async function runUninstall(opts) {
+    const agents = resolveAgents(opts.agent);
+    await uninstallForAgents(agents, opts);
+    const names = agents.map((adapter) => adapter.name).join(', ');
+    const suffix = opts.dryRun === true ? ' (dry-run: nothing written)' : '';
+    console.log(`Compressor artifacts removed for ${names}.${suffix}`);
+}

package/dist/cli/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli/index.js

@@ -0,0 +1,146 @@
+#!/usr/bin/env node
+import process from 'node:process';
+import { Command } from 'commander';
+const program = new Command();
+program
+    .name('compressor')
+    .description('Token optimization for AI coding agents: instruction packs, tool-output compression, measured savings')
+    .version('0.1.0');
+program
+    .command('init')
+    .description('install the instruction pack + PostToolUse hook for the given agents')
+    .option('--agent <name...>', 'agent adapters to target', ['claude-code'])
+    .option('--mode <mode>', 'pack mode (optimized|slim)', 'optimized')
+    .option('--global', 'install at user level instead of project level')
+    .option('--dry-run', 'print planned changes without writing')
+    .action(async (opts) => {
+    const { runInit } = await import("./commands/init.js");
+    await runInit(opts);
+});
+program
+    .command('set-mode')
+    .description("switch mode; 'full' removes all compressor artifacts (true baseline)")
+    .argument('<mode>', 'full|optimized|slim')
+    .option('--agent <name...>', 'agent adapters to target', ['claude-code'])
+    .option('--global', 'apply at user level instead of project level')
+    .option('--dry-run', 'print planned changes without writing')
+    .action(async (mode, opts) => {
+    const { runSetMode } = await import("./commands/set-mode.js");
+    await runSetMode(mode, opts);
+});
+program
+    .command('status')
+    .description('show installation state per agent')
+    .option('--global', 'report user-level (machine-wide) state instead of project state')
+    .action(async (opts) => {
+    const { runStatus } = await import("./commands/status.js");
+    await runStatus(opts.global === true);
+});
+program
+    .command('uninstall')
+    .description('remove all compressor-owned artifacts')
+    .option('--agent <name...>', 'agent adapters to target', ['claude-code'])
+    .option('--global', 'apply at user level instead of project level')
+    .option('--dry-run', 'print planned changes without writing')
+    .action(async (opts) => {
+    const { runUninstall } = await import("./commands/uninstall.js");
+    await runUninstall(opts);
+});
+program
+    .command('compress')
+    .description('compress stdin to stdout via the engine; stats on stderr')
+    .option('--mode <mode>', 'full|optimized|slim', 'optimized')
+    .option('--kind <kind>', 'read|bash|search|other', 'other')
+    .option('--file-path <path>', 'source path hint (drives code detection)')
+    .option('--marker-style <style>', 'plain|deterrent|informative (default: policy value)')
+    .action(async (opts) => {
+    const { runCompress } = await import("./commands/compress.js");
+    await runCompress(opts);
+});
+program
+    .command('count')
+    .description('count tokens per file (estimated by default, --exact via Anthropic API)')
+    .argument('<file...>', 'files to count')
+    .option('--exact', 'use the Anthropic count_tokens endpoint (needs ANTHROPIC_API_KEY)')
+    .option('--model <model>', 'model for --exact counts', 'claude-sonnet-4-6')
+    .action(async (files, opts) => {
+    const { runCount } = await import("./commands/count.js");
+    await runCount(files, opts);
+});
+program
+    .command('stats')
+    .description('aggregate actual token usage from Claude Code transcripts')
+    .option('--project <path>', 'project directory (default: cwd)')
+    .option('--since <window>', 'lookback window, e.g. 7d or 30d', '30d')
+    .action(async (opts) => {
+    const { runStats } = await import("./commands/stats.js");
+    await runStats(opts);
+});
+program
+    .command('savings')
+    .description('show what the compression hook saved (live ledger, estimated tokens)')
+    .option('--since <window>', "lookback window: e.g. 7d, 30d, or 'all'", '30d')
+    .option('--by <dimension>', 'aggregate by day|tool|mode', 'day')
+    .option('--html <path>', 'also write a self-contained HTML report (inline SVG, no JS)')
+    .option('--ledger-dir <dir>', 'ledger directory (default: COMPRESSOR_LEDGER_DIR or ~/.compressor/ledger)')
+    .action(async (opts) => {
+    const { runSavings } = await import("./commands/savings.js");
+    await runSavings(opts);
+});
+program
+    .command('benchmark')
+    .description('run the benchmark suite: cells = task × variant × trial, results as JSONL')
+    .option('--suite <path>', 'suite JSON file', 'bench/suites/basic.json')
+    .option('--modes <modes>', 'comma-separated full|optimized|slim', 'full,optimized,slim')
+    .option('--trials <n>', 'trials per task × variant', '5')
+    .option('--model <model>', 'requested model (served model verified per cell)', 'claude-sonnet-4-6')
+    .option('--ablate <ids>', 'comma-separated atom ids: adds optimized-minus-<id> variants (slim-minus-<id> for slim-only atoms)')
+    .option('--ablate-add <ids>', 'comma-separated REJECTED atom ids: adds optimized-plus-<id> variants')
+    .option('--ablate-group <groups>', 'comma-separated atom categories (output|behavior): adds optimized-minus-<group>-atoms variants with every atom of that category removed')
+    .option('--no-hook', 'skip the compression hook in optimized/slim cells')
+    .option('--hook-args <args>', "extra args appended to the hook command in every hook-bearing variant (e.g. '--marker-style informative')")
+    .option('--marker-styles <styles>', 'comma-separated plain|deterrent|informative: each hook-bearing variant fans out into one arm per style IN THE SAME RUN (one budget ceiling, balanced task×trial groups)')
+    .option('--concurrency <n>', 'cells run in parallel', '2')
+    .option('--max-budget-usd <usd>', 'hard cost ceiling; scheduling stops when reached', '5')
+    .option('--out <dir>', 'results directory', 'bench/results')
+    .action(async (opts) => {
+    const { runBenchmarkCommand } = await import("./commands/benchmark.js");
+    await runBenchmarkCommand(opts);
+});
+program
+    .command('report')
+    .description('aggregate a benchmark run: per-variant medians+IQR, deltas vs full, per-atom ablation deltas vs their baseline')
+    .option('--run <id>', 'run id (default: latest run in --out)')
+    .option('--out <dir>', 'results directory', 'bench/results')
+    .option('--compare <runs...>', 'compare two runs side-by-side by variant')
+    .option('--format <format>', 'table|md|json', 'table')
+    .action(async (opts) => {
+    const { runReport } = await import("./commands/report.js");
+    await runReport(opts);
+});
+const hook = program.command('hook').description('hook protocol entry points (read stdin)');
+hook
+    .command('post-tool-use')
+    .description('PostToolUse protocol: payload on stdin, updated output on stdout')
+    .option('--mode <mode>', 'full|optimized|slim', 'optimized')
+    .option('--marker-style <style>', 'plain|deterrent|informative (default: policy value)')
+    .action(async (opts) => {
+    const { runHookPostToolUse } = await import("./commands/hook.js");
+    await runHookPostToolUse(opts);
+});
+hook
+    .command('copilot-post-tool-use')
+    .description('Copilot postToolUse protocol: payload on stdin, modifiedResult JSON on stdout')
+    .option('--mode <mode>', 'full|optimized|slim', 'optimized')
+    .option('--marker-style <style>', 'plain|deterrent|informative (default: policy value)')
+    .action(async (opts) => {
+    const { runHookCopilotPostToolUse } = await import("./commands/hook.js");
+    await runHookCopilotPostToolUse(opts);
+});
+try {
+    await program.parseAsync(process.argv);
+}
+catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+}

package/dist/copilot-hook-entry.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/copilot-hook-entry.js

@@ -0,0 +1,36 @@
+import process from 'node:process';
+import { handleCopilotPostToolUse } from "./hook/copilot.js";
+import { settleThenExit } from "./hook/exit.js";
+// Copilot postToolUse hook entry, bundled to dist/copilot-hook.js. Fail-open:
+// any failure means emit nothing and exit 0 so the original tool result
+// passes through (Copilot parses stdout as the hook output JSON only when
+// present; empty stdout = no-op).
+function parseMode(argv) {
+    const idx = argv.indexOf('--mode');
+    const value = idx === -1 ? undefined : argv[idx + 1];
+    return value === 'full' || value === 'optimized' || value === 'slim' ? value : 'optimized';
+}
+/** Fail-open: unknown or missing style falls back to the policy default. */
+function parseMarkerStyle(argv) {
+    const idx = argv.indexOf('--marker-style');
+    const value = idx === -1 ? undefined : argv[idx + 1];
+    return value === 'plain' || value === 'deterrent' || value === 'informative'
+        ? value
+        : undefined;
+}
+async function main() {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(typeof chunk === 'string' ? Buffer.from(chunk) : chunk);
+    }
+    const payload = Buffer.concat(chunks).toString('utf8');
+    return handleCopilotPostToolUse(payload, parseMode(process.argv), parseMarkerStyle(process.argv)).output;
+}
+// Exit path shared with the claude-code entry and the CLI subcommands
+// (src/hook/exit.ts): stdout first, ledger settle capped at 250ms, SIGKILL
+// on timeout so a stuck filesystem can never hang the agent.
+main().then((output) => {
+    settleThenExit(output).catch(() => process.exit(0));
+}, () => {
+    settleThenExit(null).catch(() => process.exit(0));
+});