@astudioplus/compressor 0.1.0

package/dist/cli/commands/benchmark.js

@@ -0,0 +1,203 @@
+import { exec, execFile } from 'node:child_process';
+import { stat } from 'node:fs/promises';
+import path from 'node:path';
+import process from 'node:process';
+import { promisify } from 'node:util';
+import { buildVariants } from "../../bench/ablate.js";
+import { balanceWarning } from "../../bench/results.js";
+import { runBenchmark } from "../../bench/runner.js";
+import { loadSuite, suiteFixturesDir } from "../../bench/tasks.js";
+import { resolveHookCommand } from "../../paths.js";
+const execFileAsync = promisify(execFile);
+function parsePositiveInt(value, flag) {
+    const n = Number(value);
+    if (!Number.isInteger(n) || n <= 0) {
+        throw new Error(`${flag} must be a positive integer, got '${value}'`);
+    }
+    return n;
+}
+function parsePositiveNumber(value, flag) {
+    const n = Number(value);
+    if (!Number.isFinite(n) || n <= 0) {
+        throw new Error(`${flag} must be a positive number, got '${value}'`);
+    }
+    return n;
+}
+function parseModes(value) {
+    const names = value
+        .split(',')
+        .map((name) => name.trim())
+        .filter((name) => name.length > 0);
+    if (names.length === 0) {
+        throw new Error(`--modes must name at least one of full|optimized|slim`);
+    }
+    return names.map((name) => {
+        if (name === 'full' || name === 'optimized' || name === 'slim') {
+            return name;
+        }
+        throw new Error(`unknown mode '${name}' in --modes (expected full|optimized|slim)`);
+    });
+}
+function parseIdList(value) {
+    if (value === undefined) {
+        return [];
+    }
+    return value
+        .split(',')
+        .map((id) => id.trim())
+        .filter((id) => id.length > 0);
+}
+async function isDir(dirPath) {
+    try {
+        return (await stat(dirPath)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+async function assertFixtures(fixturesDir, suite) {
+    if (!(await isDir(fixturesDir))) {
+        throw new Error(`fixtures dir missing: ${fixturesDir} (expected next to the suite as <suiteDir>/../fixtures)`);
+    }
+    for (const task of suite.tasks) {
+        const dir = path.join(fixturesDir, task.fixture);
+        if (!(await isDir(dir))) {
+            throw new Error(`task '${task.id}': fixture dir missing: ${dir}`);
+        }
+    }
+}
+/** Shell out with stdin (hook commands are shell strings with quoted paths). */
+function execWithInput(command, input, env) {
+    return new Promise((resolve, reject) => {
+        const child = exec(command, { timeout: 30_000, maxBuffer: 8 * 1024 * 1024, env }, (error, stdout) => {
+            if (error !== null) {
+                reject(new Error(errorText(error)));
+                return;
+            }
+            resolve(stdout);
+        });
+        child.stdin?.end(input);
+    });
+}
+function errorText(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/** Synthetic over-budget PostToolUse payload: distinct rows so only the
+ * truncation tier fires and its marker line carries the style. ~51k chars
+ * (~14.6k est tokens) clears every mode's touch and truncate thresholds. */
+function markerStylePreflightPayload() {
+    const rows = Array.from({ length: 900 }, (_, i) => `row ${String(i).padStart(5, '0')} lorem ipsum dolor sit amet consectetur adipiscing`).join('\n');
+    return JSON.stringify({
+        tool_name: 'Bash',
+        tool_input: { command: 'echo preflight' },
+        tool_use_id: 'toolu_preflight',
+        tool_response: { stdout: rows, stderr: '', interrupted: false, isImage: false },
+    });
+}
+/**
+ * Preflight for marker-style experiments: the hook entry parses argv
+ * fail-open, so a STALE dist/hook.js that predates --marker-style ignores
+ * the flag silently and every arm measures identical 'plain' behavior — a
+ * three-arm run of pure noise with zero errors anywhere. Verify the exact
+ * installed hook command by piping the same over-budget payload through it
+ * with two different styles and requiring the outputs to differ.
+ * COMPRESSOR_NO_LEDGER keeps the probe out of the live savings ledger.
+ */
+export async function assertHookHandlesMarkerStyle(baseHookCommand) {
+    const payload = markerStylePreflightPayload();
+    const env = { ...process.env, COMPRESSOR_NO_LEDGER: '1' };
+    const outputs = [];
+    for (const style of ['plain', 'deterrent']) {
+        let stdout;
+        try {
+            stdout = await execWithInput(`${baseHookCommand} --marker-style ${style}`, payload, env);
+        }
+        catch (error) {
+            throw new Error(`marker-style preflight: hook command failed (${baseHookCommand} --marker-style ${style}): ${errorText(error)}`);
+        }
+        if (stdout.trim() === '') {
+            throw new Error(`marker-style preflight: hook emitted nothing for an over-budget payload (${baseHookCommand} --marker-style ${style}) — the installed bundle is broken or stale; run 'npm run build' and retry`);
+        }
+        outputs.push(stdout);
+    }
+    if (outputs[0] === outputs[1]) {
+        throw new Error(`marker-style preflight: hook output is byte-identical for --marker-style plain and deterrent — the installed dist/hook.js ignores the flag (stale bundle); run 'npm run build' and retry, or the experiment arms would all measure 'plain'`);
+    }
+}
+async function assertClaudeAnswersVersion(bin) {
+    try {
+        // .mjs/.js bins (test stubs) are not directly executable: run via node
+        if (/\.(mjs|js)$/.test(bin)) {
+            await execFileAsync(process.execPath, [bin, '--version'], { timeout: 30_000 });
+        }
+        else {
+            await execFileAsync(bin, ['--version'], { timeout: 30_000 });
+        }
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new Error(`claude binary '${bin}' failed --version — install Claude Code (or point COMPRESSOR_CLAUDE_BIN at a working binary): ${detail}`);
+    }
+}
+export async function runBenchmarkCommand(opts) {
+    const trials = parsePositiveInt(opts.trials, '--trials');
+    const concurrency = parsePositiveInt(opts.concurrency, '--concurrency');
+    const maxBudgetUsd = parsePositiveNumber(opts.maxBudgetUsd, '--max-budget-usd');
+    const modes = parseModes(opts.modes);
+    const suitePath = path.resolve(opts.suite);
+    const outDir = path.resolve(opts.out);
+    // preflight: every check below runs before any workspace or results file exists
+    const suite = await loadSuite(suitePath);
+    const fixturesDir = suiteFixturesDir(suitePath);
+    await assertFixtures(fixturesDir, suite);
+    const hookArgs = opts.hookArgs?.trim();
+    const markerStyles = parseIdList(opts.markerStyles);
+    const variants = buildVariants({
+        modes,
+        ablate: parseIdList(opts.ablate),
+        ablateAdd: parseIdList(opts.ablateAdd),
+        ablateGroups: parseIdList(opts.ablateGroup),
+        hook: opts.hook,
+        ...(hookArgs !== undefined && hookArgs !== '' ? { hookArgs } : {}),
+        ...(markerStyles.length > 0 ? { markerStyles } : {}),
+    });
+    const hooked = variants.find((variant) => variant.hook);
+    if (hooked !== undefined && hooked.baseMode !== 'full') {
+        // throws 'run npm run build' when dist/hook.js is missing
+        const hookCommand = resolveHookCommand(hooked.baseMode);
+        // a bundle that EXISTS can still predate --marker-style: verify it
+        // before spending a single API dollar on indistinguishable arms
+        if (variants.some((v) => v.hook && v.hookArgs?.includes('--marker-style') === true)) {
+            await assertHookHandlesMarkerStyle(hookCommand);
+        }
+    }
+    const bin = process.env.COMPRESSOR_CLAUDE_BIN;
+    if (bin === undefined && (process.env.ANTHROPIC_API_KEY ?? '') === '') {
+        throw new Error('ANTHROPIC_API_KEY is not set: claude --bare never reads OAuth/keychain, so benchmarks need ANTHROPIC_API_KEY exported.');
+    }
+    await assertClaudeAnswersVersion(bin ?? 'claude');
+    const cellCount = suite.tasks.length * variants.length * trials;
+    console.log(`${cellCount} cells: ${suite.tasks.length} tasks × ${variants.length} variants (${variants
+        .map((variant) => variant.id)
+        .join(', ')}) × ${trials} trials`);
+    console.log(`hard ceiling: $${maxBudgetUsd} (--max-budget-usd)`);
+    const { runId, results, resultsFile } = await runBenchmark({
+        suite,
+        variants,
+        trials,
+        model: opts.model,
+        maxBudgetUsd,
+        concurrency,
+        outDir,
+        fixturesDir,
+        onProgress: (line) => console.log(line),
+    });
+    console.log('');
+    // post-run balance assertion: unbalanced variants invalidate comparisons
+    const imbalance = balanceWarning(results);
+    if (imbalance !== null) {
+        console.log(imbalance);
+    }
+    console.log(`results: ${resultsFile}`);
+    console.log(`next: compressor report --run ${runId} --out ${outDir}`);
+}

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

@@ -0,0 +1,8 @@
+export interface CompressOptions {
+    mode?: string;
+    kind?: string;
+    filePath?: string;
+    markerStyle?: string;
+}
+export declare function readStdin(): Promise<string>;
+export declare function runCompress(opts: CompressOptions): Promise<void>;

package/dist/cli/commands/compress.js

@@ -0,0 +1,45 @@
+import process from 'node:process';
+import { compress, policyFor } from "../../engine/index.js";
+import { tiktokenEstimator } from "../../tokens/estimate.js";
+export async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(typeof chunk === 'string' ? Buffer.from(chunk) : chunk);
+    }
+    return Buffer.concat(chunks).toString('utf8');
+}
+function parseMode(value) {
+    if (value === 'full' || value === 'optimized' || value === 'slim') {
+        return value;
+    }
+    throw new Error(`unknown mode '${value}' (expected full|optimized|slim)`);
+}
+function parseKind(value) {
+    if (value === 'read' || value === 'bash' || value === 'search' || value === 'other') {
+        return value;
+    }
+    throw new Error(`unknown kind '${value}' (expected read|bash|search|other)`);
+}
+function parseMarkerStyle(value) {
+    if (value === 'plain' || value === 'deterrent' || value === 'informative') {
+        return value;
+    }
+    throw new Error(`unknown marker style '${value}' (expected plain|deterrent|informative)`);
+}
+export async function runCompress(opts) {
+    const mode = parseMode(opts.mode ?? 'optimized');
+    const meta = { tool: parseKind(opts.kind ?? 'other'), mode };
+    if (opts.filePath !== undefined) {
+        meta.filePath = opts.filePath;
+    }
+    const policy = opts.markerStyle === undefined
+        ? policyFor(mode)
+        : { ...policyFor(mode), markerStyle: parseMarkerStyle(opts.markerStyle) };
+    const text = await readStdin();
+    const result = compress(text, meta, policy, tiktokenEstimator());
+    process.stdout.write(result.content);
+    const { estTokensIn, estTokensOut, kind, transforms } = result.stats;
+    const pct = estTokensIn === 0 ? 0 : Math.round(((estTokensIn - estTokensOut) / estTokensIn) * 100);
+    const ids = transforms.map((t) => t.id).join(',');
+    process.stderr.write(`kind=${kind} ~${estTokensIn} → ~${estTokensOut} est tokens (estimated; -${pct}%) transforms=${ids}\n`);
+}

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

@@ -0,0 +1,5 @@
+export interface CountOptions {
+    exact?: boolean;
+    model?: string;
+}
+export declare function runCount(files: string[], opts: CountOptions): Promise<void>;

package/dist/cli/commands/count.js

@@ -0,0 +1,25 @@
+import { readFile } from 'node:fs/promises';
+export async function runCount(files, opts) {
+    const model = opts.model ?? 'claude-sonnet-4-6';
+    let total = 0;
+    for (const file of files) {
+        const text = await readFile(file, 'utf8');
+        if (opts.exact === true) {
+            const { countTokensExact } = await import("../../tokens/exact.js");
+            const n = await countTokensExact(text, model);
+            total += n;
+            console.log(`${file}: ${n} tokens (exact, ${model})`);
+        }
+        else {
+            const { estimateTokens } = await import("../../tokens/estimate.js");
+            const n = estimateTokens(text);
+            total += n;
+            console.log(`${file}: ~${n} tokens (estimated)`);
+        }
+    }
+    if (files.length > 1) {
+        console.log(opts.exact === true
+            ? `total: ${total} tokens (exact, ${model})`
+            : `total: ~${total} tokens (estimated)`);
+    }
+}

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

@@ -0,0 +1,6 @@
+export interface HookCliOptions {
+    mode?: string;
+    markerStyle?: string;
+}
+export declare function runHookPostToolUse(opts: HookCliOptions): Promise<void>;
+export declare function runHookCopilotPostToolUse(opts: HookCliOptions): Promise<void>;

package/dist/cli/commands/hook.js

@@ -0,0 +1,30 @@
+import { handleCopilotPostToolUse } from "../../hook/copilot.js";
+import { settleThenExit } from "../../hook/exit.js";
+import { handlePostToolUse } from "../../hook/post-tool-use.js";
+import { readStdin } from "./compress.js";
+function parseMode(value) {
+    return value === 'full' || value === 'optimized' || value === 'slim' ? value : 'optimized';
+}
+/** Fail-open (hook hot path): unknown style falls back to the policy default. */
+function parseMarkerStyle(value) {
+    return value === 'plain' || value === 'deterrent' || value === 'informative'
+        ? value
+        : undefined;
+}
+// Both actions are documented protocol surfaces a user can wire into
+// .claude/settings.json or .github/hooks, so they need the SAME hot-path
+// bound as the bundles: settleThenExit writes stdout first, caps the ledger
+// settle at 250ms, and force-terminates on timeout. Without it the process
+// exits only when the event loop drains — i.e. after the fire-and-forget
+// ledger append completes, which is unbounded on a slow disk and infinite on
+// a stuck one. These functions therefore never return.
+export async function runHookPostToolUse(opts) {
+    const payload = await readStdin();
+    const result = handlePostToolUse(payload, parseMode(opts.mode ?? 'optimized'), parseMarkerStyle(opts.markerStyle));
+    await settleThenExit(result.output);
+}
+export async function runHookCopilotPostToolUse(opts) {
+    const payload = await readStdin();
+    const result = handleCopilotPostToolUse(payload, parseMode(opts.mode ?? 'optimized'), parseMarkerStyle(opts.markerStyle));
+    await settleThenExit(result.output);
+}

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

@@ -0,0 +1,16 @@
+import type { Adapter, AdapterContext } from '../../adapters/index.ts';
+import type { PackMode } from '../../packs/types.ts';
+export interface ScopeOptions {
+    global?: boolean;
+    dryRun?: boolean;
+}
+export interface InitOptions extends ScopeOptions {
+    agent: string[];
+    mode: string;
+}
+export declare function effectNote(agents: readonly Pick<Adapter, 'name'>[]): string;
+export declare function parsePackMode(value: string): PackMode;
+export declare function resolveAgents(names: string[]): Adapter[];
+export declare function buildContext(global: boolean, mode: PackMode, requireHookBundle?: boolean): AdapterContext;
+export declare function installForAgents(agents: Adapter[], mode: PackMode, opts: ScopeOptions): Promise<void>;
+export declare function runInit(opts: InitOptions): Promise<void>;

package/dist/cli/commands/init.js

@@ -0,0 +1,76 @@
+import { homedir } from 'node:os';
+import process from 'node:process';
+import { applyChanges, getAdapter, renderChanges } from "../../adapters/index.js";
+import { describeHookCommand, resolveCopilotHookCommand, resolveHookCommand, } from "../../paths.js";
+const AGENT_EFFECT_NOTES = {
+    'claude-code': 'Claude Code: takes effect on the next session (/clear or new session).',
+    copilot: 'Copilot: hook config loads when the CLI starts — restart any running copilot session.',
+    cursor: 'Cursor: rules apply to new chats.',
+    'agents-md': 'AGENTS.md: read at agent startup.',
+};
+export function effectNote(agents) {
+    return agents.map((a) => AGENT_EFFECT_NOTES[a.name]).join(' ');
+}
+export function parsePackMode(value) {
+    if (value === 'optimized' || value === 'slim') {
+        return value;
+    }
+    throw new Error(`unknown mode '${value}' (expected optimized|slim)`);
+}
+const AGENT_NAMES = ['claude-code', 'copilot', 'cursor', 'agents-md'];
+export function resolveAgents(names) {
+    return names.map((name) => {
+        const known = AGENT_NAMES.find((agent) => agent === name);
+        const adapter = known === undefined ? undefined : getAdapter(known);
+        if (adapter === undefined) {
+            throw new Error(`no adapter for agent '${name}' (known: ${AGENT_NAMES.join(', ')})`);
+        }
+        return adapter;
+    });
+}
+export function buildContext(global, mode, requireHookBundle = true) {
+    return {
+        projectDir: process.cwd(),
+        homeDir: homedir(),
+        global,
+        // status/uninstall only match against the command string — they must work
+        // even when the bundle is missing (e.g. removing a broken install)
+        hookCommand: requireHookBundle
+            ? resolveHookCommand(mode)
+            : describeHookCommand(mode),
+    };
+}
+export async function installForAgents(agents, mode, opts) {
+    // claude-code installs the PostToolUse hook (dist/hook.js) and copilot the
+    // postToolUse hook (dist/copilot-hook.js); instruction-only agents (cursor,
+    // agents-md) must not require either bundle to exist
+    const needsHookBundle = agents.some((adapter) => adapter.name === 'claude-code');
+    const ctx = buildContext(opts.global === true, mode, needsHookBundle);
+    const hasCopilot = agents.some((adapter) => adapter.name === 'copilot');
+    if (hasCopilot) {
+        // existence check only (both scopes — global installs the hook too):
+        // refuses to install a hook command that would fail on every tool call
+        // (Copilot postToolUse is fail-open = silent no-op)
+        resolveCopilotHookCommand(mode);
+    }
+    for (const adapter of agents) {
+        const changes = await adapter.install(mode, ctx);
+        const rendered = renderChanges(changes);
+        if (rendered !== '') {
+            console.log(rendered);
+        }
+        if (opts.dryRun !== true) {
+            await applyChanges(changes);
+        }
+    }
+    const names = agents.map((adapter) => adapter.name).join(', ');
+    const suffix = opts.dryRun === true ? ' (dry-run: nothing written)' : '';
+    console.log(`Mode ${mode} installed for ${names}. ${effectNote(agents)}${suffix}`);
+    if (hasCopilot && opts.global === true) {
+        const verb = opts.dryRun === true ? 'would be installed' : 'installed';
+        console.log(`Copilot --global: hook ${verb} machine-wide (Copilot CLI); instructions were NOT installed (no global mechanism) — run init --agent copilot in each repo for instruction packs.`);
+    }
+}
+export async function runInit(opts) {
+    await installForAgents(resolveAgents(opts.agent), parsePackMode(opts.mode), opts);
+}

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

@@ -0,0 +1,90 @@
+import type { VariantAggregate } from '../../bench/results.ts';
+import type { CellResult, RunMeta } from '../../bench/types.ts';
+export type ReportFormat = 'table' | 'md' | 'json';
+export interface ReportCliOptions {
+    run?: string;
+    out: string;
+    compare?: string[];
+    format: string;
+}
+/** Deltas vs a baseline variant — actual usage numbers, never estimates. */
+export interface VariantDelta {
+    variantId: string;
+    /** % change in median output tokens; null when either side has no valid cells or the baseline median is 0 */
+    outputPct: number | null;
+    /** % change in median cost; null when either side is missing or the baseline is 0 */
+    costPct: number | null;
+    /** success-rate change in percentage points; null when either side unjudged */
+    successPp: number | null;
+}
+/** Marginal per-atom deltas: <baseline>-minus/plus-<atom> vs that baseline. */
+export interface AblationDeltas {
+    baselineId: string;
+    deltas: VariantDelta[];
+}
+export interface DataQualityIssues {
+    /** tasks whose check passed BEFORE the agent ran — the cell proves nothing */
+    vacuousTasks: string[];
+    /** cells served by a model other than the requested one (silent fallback) */
+    substitutedCells: string[];
+    /** cells whose result JSON had no modelUsage — served model unverifiable */
+    unknownServedCells: string[];
+    /** cells the runner never scheduled (budget ceiling / unenforceable ceiling) */
+    skippedCells: string[];
+    /** infra failures — separate from task failures, excluded from success% */
+    errorCells: string[];
+    /** cells with permission denials — the model burned turns on retries, numbers are inflated */
+    deniedCells: string[];
+}
+/** One taskId × variantId cell of the per-task breakdown. */
+export interface TaskVariantCell {
+    taskId: string;
+    variantId: string;
+    /** all rows for this pair, including infra errors */
+    cells: number;
+    /** non-error rows — medians below are over these */
+    valid: number;
+    /** valid rows with a boolean success verdict */
+    judged: number;
+    successes: number;
+    /** successes / judged; null when nothing was judged */
+    successFraction: number | null;
+    /** median output tokens over valid rows */
+    medianOutput: number;
+    /** median input + cacheCreation + cacheRead (context volume) over valid rows */
+    medianContext: number;
+}
+/** taskIds × variantIds matrix; cells[i][j] = taskIds[i] × variantIds[j], null = no rows. */
+export interface ByTaskBreakdown {
+    /** sorted ascending */
+    taskIds: string[];
+    /** 'full' first when present, then alphabetical */
+    variantIds: string[];
+    cells: (TaskVariantCell | null)[][];
+}
+export interface RunReport {
+    runId: string;
+    meta: RunMeta | null;
+    aggregates: VariantAggregate[];
+    /** null when the run has no 'full' variant to compare against */
+    deltas: VariantDelta[] | null;
+    /** per-atom marginal deltas vs each ablation baseline; null when no ablation variants */
+    ablationDeltas: AblationDeltas[] | null;
+    byTask: ByTaskBreakdown;
+    issues: DataQualityIssues;
+}
+export declare function parseFormat(value: string): ReportFormat;
+export declare function computeDeltas(aggregates: VariantAggregate[]): VariantDelta[] | null;
+/**
+ * The ablation gate question: for each <baseline>-minus/plus-<atom> variant,
+ * the marginal output & success delta vs that baseline — not vs full.
+ */
+export declare function computeAblationDeltas(aggregates: VariantAggregate[]): AblationDeltas[] | null;
+export declare function computeByTask(results: CellResult[]): ByTaskBreakdown;
+export declare function findIssues(results: CellResult[]): DataQualityIssues;
+export declare function buildRunReport(runId: string, meta: RunMeta | null, results: CellResult[]): RunReport;
+export declare function loadRunReport(outDir: string, runId: string): Promise<RunReport>;
+export declare function latestRunId(outDir: string): Promise<string | null>;
+export declare function formatReport(report: RunReport, format: ReportFormat): string;
+export declare function formatComparison(a: RunReport, b: RunReport, format: ReportFormat): string;
+export declare function runReport(opts: ReportCliOptions): Promise<void>;