@compaction/cli 0.1.4 → 0.3.0

package/dist/cli/commands/capture.js

@@ -1,8 +1,110 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
 import chalk from "chalk";
 import { captureOpenAIAgentsCommand, captureOpenAIAgentsExport } from "../../core/openai-agents-capture.js";
-import { captureClaudeCodeCommand, discoverClaudeCodeCommand } from "./capture-claude-code.js";
+import { captureCodexCommand, captureCodexExport } from "../../core/codex-capture.js";
+import { captureCursorCommand, captureCursorExport } from "../../core/cursor-capture.js";
+import { gateCursorLiveRun } from "../cursor-live-preflight.js";
+import { readCursorExportFile } from "../cursor-export-read.js";
+import { buildRunFlowTokenReport, formatRunFlowTokenReport } from "../../core/run-flow-report.js";
+import { recordCaptureContentFree, captureTokenSource } from "../../core/capture-record.js";
+import { attachOutputShapingToCommand } from "../../core/output-shaping-attach.js";
+import { OUTPUT_SHAPING_HONESTY_NOTE } from "../../core/output-shaping.js";
+import { buildCaptureUsageSidecar } from "../../core/output-shaping-ab.js";
+import { resolveApiConfig } from "../../core/api-client/index.js";
+import { hostedConfigured } from "./optimize-hosted.js";
+import { describeTokenMetadata } from "../../core/usage-metadata.js";
+import { captureClaudeCodeCommand, captureClaudeCodeFromHook, captureClaudeCodeFromPromptHook, discoverClaudeCodeCommand } from "./capture-claude-code.js";
 import { captureProviderUsageCommand } from "./capture-provider-usage.js";
+import { bridgeCodexShimActivity, bridgeCursorShimActivity } from "../../core/shim-capture-bridge.js";
 import { DEFAULT_CREDENTIAL_ENV_VAR } from "../../core/provider-usage/provider-usage-adapter.js";
+/**
+ * Shared content-free `--from-shim` handler (the PATH-shim always-on bridge — charter 2026-07-04-run-9).
+ * Reads the shim's temp copy of the tool's OWN stdout, appends ONE metrics-only activity event, writes
+ * NO trace artifact and NO content. Best-effort + fail-open: a bad/missing file is a non-fatal skip so
+ * the transparent shim can never break the wrapped command. `commandParts` (Cursor only) carries the
+ * ORIGINAL invocation so input can be locally estimated (counted, never stored).
+ */
+async function handleCaptureFromShim(tool, fromShimPath, commandParts) {
+    let rawOutput;
+    try {
+        rawOutput = await readFile(fromShimPath, "utf8");
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.log(`compaction shim: skipped (non-fatal: could not read the captured output — ${message}).`);
+        return;
+    }
+    try {
+        if (tool === "codex") {
+            const { result, tokenMetadataStatus } = await bridgeCodexShimActivity({ rawOutput, cwd: process.cwd() });
+            const label = tokenMetadataStatus === "present" ? "provider-reported" : "usage unavailable (not invented)";
+            console.log(result.appended
+                ? `compaction shim: recorded metrics-only activity (surface=codex, ${label}, id ${result.activity_event_id.slice(0, 12)}…) — see 'compaction activity'.`
+                : `compaction shim: activity not appended (${result.reason}).`);
+        }
+        else {
+            const { result, outputStatus } = await bridgeCursorShimActivity({
+                rawOutput,
+                commandParts: commandParts.length > 0 ? commandParts : undefined,
+                cwd: process.cwd()
+            });
+            const label = `local-estimate; output ${outputStatus === "present" ? "local-estimate" : "unavailable"}`;
+            console.log(result.appended
+                ? `compaction shim: recorded metrics-only activity (surface=cursor, ${label}, id ${result.activity_event_id.slice(0, 12)}…) — see 'compaction activity'.`
+                : `compaction shim: activity not appended (${result.reason}).`);
+        }
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.log(`compaction shim: skipped (non-fatal: ${message}).`);
+    }
+}
+/**
+ * Apply the opt-in output-shaping flag to a wrapped command BEFORE generation (increment 3). Returns the
+ * (possibly modified) commandParts + console lines. Surfaces NO output-savings number — a savings figure
+ * requires the private measured-A/B + short-but-sufficient eval gate. Original command is never mutated.
+ */
+function applyOutputShapingFlag(commandParts, options) {
+    if (!options.outputShaping)
+        return { commandParts, lines: [], policyNames: [] };
+    const budget = options.verbosityBudget !== undefined ? Number.parseInt(options.verbosityBudget, 10) : undefined;
+    const policies = options.outputShapingPolicies
+        ? options.outputShapingPolicies.split(",").map((s) => s.trim()).filter(Boolean)
+        : undefined;
+    const att = attachOutputShapingToCommand(commandParts, {
+        ...(budget !== undefined && Number.isFinite(budget) ? { verbosityBudgetTokens: budget } : {}),
+        ...(policies ? { policies } : {})
+    });
+    const lines = att.attached
+        ? [
+            chalk.green(`  Attached output-shaping policy to the prompt BEFORE generation: ${att.applied.map((a) => a.policy_name).join(", ")}`),
+            chalk.gray(`  ${OUTPUT_SHAPING_HONESTY_NOTE}`)
+        ]
+        : [chalk.yellow(`  Output-shaping NOT attached: ${att.reason}.`)];
+    return { commandParts: att.commandParts, lines, policyNames: att.applied.map((a) => a.policy_name) };
+}
+/**
+ * Write a content-free `capture-usage.json` sidecar next to the capture artifact (operator-side evidence).
+ * It carries provider-reported token counts + honest source + (treatment) output-shaping policy names so a
+ * later `compaction output-shaping-ab add` can link this run into an A/B arm. NO content is written.
+ */
+async function writeCaptureUsageSidecar(outDir, tool, usage, policyNames) {
+    const sidecar = buildCaptureUsageSidecar({
+        tool,
+        ...(usage.provider ? { provider: usage.provider } : {}),
+        ...(usage.model ? { model: usage.model } : {}),
+        ...(typeof usage.input_tokens === "number" ? { inputTokens: usage.input_tokens } : {}),
+        ...(typeof usage.output_tokens === "number" ? { outputTokens: usage.output_tokens } : {}),
+        providerReported: usage.provider_reported_tokens === true,
+        tokenSource: captureTokenSource(usage),
+        tokenMetadataStatus: usage.provider_reported_tokens === true ? "present" : "missing",
+        ...(policyNames.length > 0 ? { policyNames } : {})
+    });
+    const sidecarPath = path.join(outDir, "capture-usage.json");
+    await writeFile(sidecarPath, JSON.stringify(sidecar, null, 2), "utf8");
+    return sidecarPath;
+}
 export function registerCaptureCommand(program) {
     const capture = program.command("capture").description("Capture local integration traces into compaction.dev AgentTrace format.");
     capture
@@ -26,6 +128,175 @@ export function registerCaptureCommand(program) {
             process.exitCode = 1;
         }
     });
+    capture
+        .command("codex")
+        .description("Capture a LIVE `codex exec --json` run (or a saved export) into AgentTrace — no manual import. " +
+        "Provider-reported tokens from turn.completed.usage; local only, no upload, no proxying.")
+        .option("--out <dir>", "Output directory for capture artifacts")
+        .option("--export <file>", "Read a saved `codex exec --json` JSONL export instead of running a command")
+        .option("--from-shim <file>", "INTERNAL (used by the connect-once PATH shim): read a captured `codex exec --json` output copy and append ONE metrics-only, CONTENT-FREE activity event (no trace artifact, no content). Fail-open.")
+        .option("--output-shaping", "Attach the output-shaping policy to the prompt BEFORE generation (opt-in; no savings claimed)")
+        .option("--verbosity-budget <tokens>", "Soft output-token budget for the output-shaping policy")
+        .option("--output-shaping-policies <names>", "Comma-separated output-shaping policy names (default: the default-on set)")
+        .argument("[commandParts...]", 'Command and args to execute after -- (e.g. -- codex exec --json "do X")')
+        .allowUnknownOption(true)
+        .action(async (commandPartsRaw, options) => {
+        // Always-on shim bridge: content-free, writes only a metrics-only activity event. Handled first,
+        // before any artifact-writing path, and before the "provide a command" guard.
+        if (options.fromShim) {
+            await handleCaptureFromShim("codex", options.fromShim, commandPartsRaw);
+            return;
+        }
+        console.log(chalk.cyan("compaction capture codex"));
+        console.log("Capturing a local codex exec --json run. No upload, no proxying. Review the artifact before sharing (it may contain code/output).");
+        if (!options.out) {
+            console.error("error: --out <dir> is required (except with --from-shim).");
+            process.exitCode = 1;
+            return;
+        }
+        if (!options.export && commandPartsRaw.length === 0) {
+            console.error('error: provide a command after -- (e.g. -- codex exec --json "do X") or use --export <file>.');
+            process.exitCode = 1;
+            return;
+        }
+        const outDir = options.out;
+        // Opt-in: attach the output-shaping policy to the prompt BEFORE generation (no savings claimed).
+        const shaped = applyOutputShapingFlag(commandPartsRaw, options);
+        for (const line of shaped.lines)
+            console.log(line);
+        const result = options.export
+            ? captureCodexExport(await readFile(options.export, "utf8"))
+            : await captureCodexCommand(shaped.commandParts);
+        await mkdir(outDir, { recursive: true });
+        const tracePath = path.join(outDir, "captured-trace.json");
+        await writeFile(tracePath, JSON.stringify(result.trace, null, 2), "utf8");
+        // Honest token labels: provider-reported (from turn.completed.usage) or honest missing — never invented.
+        for (const line of describeTokenMetadata(result.usageMetadata))
+            console.log(`  ${line}`);
+        for (const warning of result.warnings)
+            console.log(chalk.yellow(`  ! ${warning}`));
+        console.log(chalk.green(`Wrote ${tracePath}`));
+        // Content-free A/B evidence sidecar (provider-reported counts + policy names) for output-shaping-ab.
+        const usagePath = await writeCaptureUsageSidecar(outDir, "codex", result.usageMetadata, shaped.policyNames);
+        console.log(chalk.green(`Wrote ${usagePath}`));
+        // Unified flow: content-free record (input/output separate + honest source) when hosted-configured.
+        // No default network call — only when the user has set COMPACTION_API_URL + COMPACTION_API_KEY.
+        if (hostedConfigured()) {
+            const rec = await recordCaptureContentFree(resolveApiConfig(), { usage: result.usageMetadata, tool: "codex", reference: tracePath });
+            console.log(rec.recorded ? chalk.green(`  Recorded content-free usage (tool=codex, source=${rec.source}).`) : chalk.yellow(`  Not recorded: ${rec.reason}.`));
+        }
+        else {
+            console.log("  Not recorded (set COMPACTION_API_URL + COMPACTION_API_KEY to record content-free usage).");
+        }
+        console.log(`  Next: compaction compact ${tracePath} --eval --out <dir>`);
+        const exitCode = result.commandRun?.exitCode;
+        if (typeof exitCode === "number" && exitCode !== 0)
+            process.exitCode = exitCode;
+    });
+    capture
+        .command("cursor")
+        .description("Capture a LIVE Cursor headless CLI run (or saved output) into AgentTrace — no manual import. " +
+        "LOCAL-ESTIMATE tokens only (Cursor emits no usage); output counted from the result field where " +
+        "separable (use --output-format json), else marked unavailable. Local only, no upload, no SQLite.")
+        .option("--out <dir>", "Output directory for capture artifacts")
+        .option("--export <file>", "Read saved Cursor headless output (json / stream-json) instead of running a command")
+        .option("--from-shim <file>", "INTERNAL (used by the connect-once PATH shim): read a captured Cursor headless output copy and append ONE metrics-only, CONTENT-FREE activity event (local-estimate only, no trace artifact, no content). Fail-open.")
+        .option("--output-shaping", "Attach the output-shaping policy to the prompt BEFORE generation (opt-in; Cursor output is local-estimate, no savings)")
+        .option("--verbosity-budget <tokens>", "Soft output-token budget for the output-shaping policy")
+        .option("--output-shaping-policies <names>", "Comma-separated output-shaping policy names (default: the default-on set)")
+        .argument("[commandParts...]", 'Command and args after -- (e.g. -- cursor agent -p "do X" --output-format json)')
+        .allowUnknownOption(true)
+        .action(async (commandPartsRaw, options) => {
+        // Always-on shim bridge: content-free, writes only a metrics-only activity event (local-estimate).
+        // Handled first; the ORIGINAL invocation after -- lets input be locally estimated (counted, not stored).
+        if (options.fromShim) {
+            await handleCaptureFromShim("cursor", options.fromShim, commandPartsRaw);
+            return;
+        }
+        console.log(chalk.cyan("compaction capture cursor"));
+        console.log("Capturing a local Cursor headless run. LOCAL-ESTIMATE tokens only (Cursor emits no provider usage). No upload, no SQLite. Review the artifact before sharing.");
+        if (!options.out) {
+            console.error("error: --out <dir> is required (except with --from-shim).");
+            process.exitCode = 1;
+            return;
+        }
+        if (!options.export && commandPartsRaw.length === 0) {
+            console.error('error: provide a command after -- (e.g. -- cursor agent -p "do X" --output-format json) or use --export <file>.');
+            process.exitCode = 1;
+            return;
+        }
+        // LIVE path (no --export): run the SAFE preflight FIRST (CLI-presence + capability only; never a
+        // real prompt, never `cursor agent login`, never a CURSOR_API_KEY read). If the CLI is missing or
+        // not capable, print exact guidance and STOP before spawning — no opaque failure, no crash.
+        if (!options.export) {
+            const ready = await gateCursorLiveRun();
+            if (!ready) {
+                process.exitCode = 1;
+                return;
+            }
+        }
+        // Opt-in: attach the output-shaping policy to the prompt BEFORE generation. Cursor output stays
+        // local-estimate (no provider usage) → shaping never yields a savings number for Cursor.
+        const shaped = applyOutputShapingFlag(commandPartsRaw, options);
+        for (const line of shaped.lines)
+            console.log(line);
+        // Export path: read the saved output HONESTLY (a missing/unreadable file is an actionable error,
+        // never a raw errno, never a fabricated capture). Pass the RAW declared command (if the operator
+        // provided one after --) so the LOCAL-ESTIMATE input count matches `run cursor --export` exactly;
+        // shaped parts are NOT used here — nothing was executed, so no shaping was actually attached.
+        let result;
+        if (options.export) {
+            const exportRead = await readCursorExportFile(options.export);
+            if (!exportRead.ok) {
+                for (const line of exportRead.errorLines)
+                    console.error(line);
+                process.exitCode = 1;
+                return;
+            }
+            result = captureCursorExport(exportRead.rawOutput, commandPartsRaw.length > 0 ? commandPartsRaw : undefined);
+        }
+        else {
+            result = await captureCursorCommand(shaped.commandParts);
+        }
+        const outDir = options.out;
+        await mkdir(outDir, { recursive: true });
+        const tracePath = path.join(outDir, "captured-trace.json");
+        await writeFile(tracePath, JSON.stringify(result.trace, null, 2), "utf8");
+        // Print the SAME honest per-field token block `run cursor` prints (input/output SEPARATE, source
+        // explicit, an unavailable axis carries its TRUE per-run reason) — never a bare
+        // "input tokens: unknown" with no reason, never a fabricated count, never provider-reported.
+        const cursorTokenReport = buildRunFlowTokenReport({
+            tool: "cursor",
+            usage: result.usageMetadata,
+            outputStatus: result.outputStatus
+        });
+        const cursorReasons = { input: result.inputUnavailableReason, output: result.outputUnavailableReason };
+        // `capture` does not compact — no input-reduction figures follow, so that line is omitted.
+        const cursorTokenLines = formatRunFlowTokenReport(cursorTokenReport, {
+            reasons: cursorReasons,
+            inputReductionFollows: false
+        });
+        for (const line of cursorTokenLines)
+            console.log(`  ${line}`);
+        for (const warning of result.warnings)
+            console.log(chalk.yellow(`  ! ${warning}`));
+        console.log(chalk.green(`Wrote ${tracePath}`));
+        // Content-free sidecar. Cursor is local-estimate (providerReported=false) → A/B treats it as
+        // unavailable for a provider-reported savings number; it can never produce a confirmed claim.
+        const usagePath = await writeCaptureUsageSidecar(outDir, "cursor", result.usageMetadata, shaped.policyNames);
+        console.log(chalk.green(`Wrote ${usagePath}`));
+        if (hostedConfigured()) {
+            const rec = await recordCaptureContentFree(resolveApiConfig(), { usage: result.usageMetadata, tool: "cursor", reference: tracePath });
+            console.log(rec.recorded ? chalk.green(`  Recorded content-free usage (tool=cursor, source=${rec.source}).`) : chalk.yellow(`  Not recorded: ${rec.reason}.`));
+        }
+        else {
+            console.log("  Not recorded (set COMPACTION_API_URL + COMPACTION_API_KEY to record content-free usage).");
+        }
+        console.log(`  Next: compaction compact ${tracePath} --eval --out <dir>`);
+        const exitCode = result.commandRun?.exitCode;
+        if (typeof exitCode === "number" && exitCode !== 0)
+            process.exitCode = exitCode;
+    });
     capture
         .command("claude-code")
         .description("Capture a Claude Code session JSONL file into compaction.dev AgentTrace format (source: real_captured). Local only — no network calls, no upload.")
@@ -35,7 +306,18 @@ export function registerCaptureCommand(program) {
         .option("--out <dir>", "Output directory for captured artifacts (default: .compaction/runs/<session-id-prefix>/)")
         .option("--max-tool-result-chars <N>", "Maximum characters to extract from each tool result before truncation (default: 32000)")
         .option("--include-subagents", "Include subagent JSONL files from <session-id>/subagents/ directory, merging their messages and usage into the captured trace")
+        .option("--from-hook", "Read a Claude Code Stop payload from stdin and record CONTENT-FREE usage via its transcript_path (used by `compaction hooks install`). Fail-open, idempotent.")
+        .option("--from-prompt-hook", "BEFORE-CALL (run-13): read a Claude Code UserPromptSubmit payload from stdin and record a CONTENT-FREE before-call RECOMMENDATION (used by the UserPromptSubmit hook). Recommendation-only (apply is a proven blocker on this surface); the prompt runs unchanged. Fail-open, silent (no stdout).")
+        .option("--dry-run", "With --from-hook: print what would be recorded without writing anything.")
         .action(async (options) => {
+        if (options.fromPromptHook) {
+            await captureClaudeCodeFromPromptHook();
+            return;
+        }
+        if (options.fromHook) {
+            await captureClaudeCodeFromHook({ dryRun: options.dryRun });
+            return;
+        }
         if (options.discover) {
             await discoverClaudeCodeCommand({ projectsDir: options.projectsDir });
             return;

package/dist/cli/commands/compact.js

@@ -2,7 +2,7 @@ import path from "node:path";
 import chalk from "chalk";
 import { Option } from "commander";
 import { writeJsonArtifact, writeTextArtifact } from "../../core/artifact-writer.js";
-import { withTraceFingerprint } from "../../core/report-generator.js";
+import { formatCompactionMarkdownReport, withSavingsEvidence, withTraceFingerprint } from "../../core/report-generator.js";
 import { describeTokenAccounting } from "../../core/token-accounting.js";
 import { parseTraceFile } from "../../core/trace-parser.js";
 import { buildRunLabelsFile, hasAnyLabel } from "../../core/run-labels.js";
@@ -109,11 +109,12 @@ export function registerCompactCommand(program) {
         .description("Compact a trace and write local artifacts.")
         .action(async (traceFile, options) => {
         await runEngineCommand(async () => {
-            // Lazy-load the proprietary engine: present in-repo/API, excluded from the public package.
-            // When absent, runEngineCommand prints the boundary message and exits cleanly (no stack trace).
-            const { writeCompactionArtifacts } = await import("../../engine/compaction-artifacts.js");
-            const { applyCompactionPolicy } = await import("../../engine/policy-middleware.js");
-            const { evaluateCompactionResult, evaluateStrongCompactionResult, formatStrongEvalMarkdownReport } = await import("../../engine/eval-harness.js");
+            // Basic deterministic compaction is PUBLIC (src/core): the transform + policy application +
+            // artifact writing ship in the npm package, so `compact` works with no private engine build.
+            // Only `--eval` (deterministic recoverability/strong eval) lazy-loads the private engine below;
+            // when the engine is absent, runEngineCommand prints the boundary message and exits cleanly.
+            const { writeCompactionArtifacts } = await import("../../core/compaction-artifacts.js");
+            const { applyCompactionPolicy } = await import("../../core/policy-middleware.js");
             const trace = await parseTraceFile(traceFile);
             const reviewerType = options.reviewer;
             const reviewSummaryPresent = typeof options.reviewSummary === "string" && options.reviewSummary.length > 0;
@@ -124,11 +125,20 @@ export function registerCompactCommand(program) {
             // hand-assembled bundle — the eval consumes the identical PolicyMiddlewareResult.
             const policyResult = applyCompactionPolicy({ trace, compactSkillInjections: approveSkillInjectionPolicy });
             const artifacts = await writeCompactionArtifacts(trace, options.out, runId, policyResult, undefined, { reviewerType, reviewSummaryPresent, approveSkillInjectionPolicy });
-            // Attribution/integrity (V0.2 savings-evidence): re-persist report.json with the
-            // content-addressed trace fingerprint so `aggregate`/`summary` can attribute each saving to a
-            // verifiable run and de-duplicate the same captured run if it is rolled up twice. Additive,
-            // backward-compatible; does not change any existing report field/label.
-            await writeJsonArtifact(options.out, "report.json", withTraceFingerprint(artifacts.report, trace));
+            // Attribution/integrity + per-run evidence label (V0.2 savings-evidence): re-persist
+            // report.json with (1) the content-addressed trace fingerprint so `aggregate`/`summary` can
+            // attribute each saving to a verifiable run and de-duplicate a run rolled up twice, and
+            // (2) the composed `savings_evidence` record stating the per-run label explicitly. The
+            // compact path's figures are local estimates (chars/4) — `local_estimate` rung 1; never
+            // billing-confirmed, never semantic. Additive, backward-compatible; changes no existing field.
+            const evidenceReport = withSavingsEvidence(withTraceFingerprint(artifacts.report, trace), {
+                costSource: "local_estimate"
+            });
+            await writeJsonArtifact(options.out, "report.json", evidenceReport);
+            // Re-render report.md from the ENRICHED report so the per-run savings_evidence record
+            // appears in the human-readable artifact too (the engine rendered report.md from the base
+            // report before the CLI added the public-layer fingerprint/evidence enrichment).
+            await writeTextArtifact(options.out, "report.md", formatCompactionMarkdownReport(evidenceReport, artifacts.policy));
             console.log(chalk.cyan("compaction compact"));
             console.log(artifacts.consoleReport);
             // Operator-visible only when the approval gesture was given; default output is unchanged.
@@ -180,6 +190,9 @@ export function registerCompactCommand(program) {
             // (no disk round-trip, no hand-assembled bundle) and print the combined summary. Fail closed:
             // a failing recoverability verdict exits non-zero, identical to standalone `compaction eval`.
             if (options.eval === true) {
+                // The recoverability/strong eval stays PRIVATE (src/engine): lazy-loaded only when --eval is
+                // requested, so basic compaction above never needs the engine. Absent engine ⇒ clean degrade.
+                const { evaluateCompactionResult, evaluateStrongCompactionResult, formatStrongEvalMarkdownReport } = await import("../../engine/eval-harness.js");
                 const evalResult = evaluateCompactionResult(trace, policyResult, runId);
                 printCombinedEvalSummary(evalResult);
                 // Strong eval (Tracks B/C/D): commitment-preservation recoverability + fixture task-check +

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

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function registerContextCommand(program: Command): void;

package/dist/cli/commands/context.js

@@ -0,0 +1,130 @@
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import chalk from "chalk";
+import { assembleContext, contextItemsFromTrace, retrieveContextItems } from "../../core/context-store.js";
+import { appendContextItems, loadContextStore } from "../../core/context-store-fs.js";
+/**
+ * V0.4 `compaction context` — a LOCAL memory + retrieval surface over the user's own captured
+ * traces (design: docs/design/v0.4-context-command.md, accepted 2026-06-24).
+ *
+ * HARD RAILS (load-bearing): local-only — no network, no model, no embeddings, no engine. It
+ * makes NO savings/cost claim (cost lives in `spend`/`summary`) and NO quality/recall/correctness
+ * verdict on user data (the four-axis sufficiency harness stays internal — there is no ground
+ * truth for an arbitrary user query). `get` prints local retrieval DIAGNOSTICS only.
+ */
+const DEFAULT_STORE_DIR = ".compaction/context-store";
+function readTrace(path) {
+    if (!existsSync(path)) {
+        throw new Error(`File not found: ${path}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        throw new Error(`Not valid JSON: ${path}`);
+    }
+    const trace = parsed;
+    if (!trace || typeof trace.id !== "string" || !Array.isArray(trace.messages)) {
+        throw new Error("Not a normalized AgentTrace (expected { id, messages: [...] }). " +
+            "Produce one with `compaction capture` or `compaction import`.");
+    }
+    for (const message of trace.messages) {
+        const m = message;
+        if (!m || typeof m.id !== "string" || typeof m.content !== "string") {
+            throw new Error("Malformed trace: every message needs a string `id` and `content`. " +
+                "Produce a trace with `compaction capture` or `compaction import`.");
+        }
+    }
+    return parsed;
+}
+function collect(value, previous) {
+    return [...previous, value];
+}
+export function registerContextCommand(program) {
+    const context = program
+        .command("context")
+        .description("Local memory: build a durable context store from your own captured/imported traces and " +
+        "retrieve the active context for a next step (local-only; no model, no network, no savings claim).");
+    context
+        .command("add")
+        .argument("<artifact>", "Path to a local normalized AgentTrace JSON (from `compaction capture`/`import`)")
+        .option("--store-dir <dir>", "Context store directory (local, gitignored)", DEFAULT_STORE_DIR)
+        .description("Append context items derived from a local trace into the local context store (size-cap enforced).")
+        .action(async (artifact, options) => {
+        const storeDir = resolve(options.storeDir ?? DEFAULT_STORE_DIR);
+        const trace = readTrace(resolve(artifact));
+        const items = contextItemsFromTrace(trace, { created_at: new Date().toISOString() });
+        const result = await appendContextItems(storeDir, items);
+        console.log(chalk.cyan("compaction context add"));
+        console.log(`Source: ${artifact}`);
+        console.log(`Store: ${storeDir}`);
+        console.log(`Items added: ${result.appended.length}   skipped (duplicate): ${result.skipped.length}   ` +
+            `evicted (size cap): ${result.evicted.length}`);
+        console.log(`Store now holds: ${result.total} items.`);
+        console.log("Local-only: nothing was uploaded. This makes no savings claim (see `compaction spend`/`summary` for cost).");
+        console.log(chalk.bold('Next: compaction context get "<your query>"'));
+    });
+    context
+        .command("get")
+        .argument("<query>", "Free-text description of the current step")
+        .option("--store-dir <dir>", "Context store directory (local, gitignored)", DEFAULT_STORE_DIR)
+        .option("--budget <tokens>", "Token budget for the assembled context (local estimate)", "4000")
+        .option("--source <pointer>", "Required source pointer for coverage diagnostics (repeatable)", collect, [])
+        .option("--limit <n>", "Max candidate items to consider after ranking")
+        .description("Retrieve + assemble the active context for a query from the local store (deterministic, local). " +
+        "Prints the assembled context WITH source pointers + local retrieval diagnostics — not a quality score.")
+        .action(async (query, options) => {
+        const storeDir = resolve(options.storeDir ?? DEFAULT_STORE_DIR);
+        const budget = Number.parseInt(options.budget ?? "4000", 10);
+        if (Number.isNaN(budget) || budget < 0) {
+            console.error("--budget must be a non-negative integer number of tokens.");
+            process.exitCode = 1;
+            return;
+        }
+        let limit;
+        if (options.limit !== undefined) {
+            limit = Number.parseInt(options.limit, 10);
+            if (Number.isNaN(limit) || limit < 0) {
+                console.error("--limit must be a non-negative integer.");
+                process.exitCode = 1;
+                return;
+            }
+        }
+        const items = await loadContextStore(storeDir);
+        const retrievalOptions = limit !== undefined ? { limit } : {};
+        const start = performance.now();
+        const ranked = retrieveContextItems(items, { text: query, source_pointers: options.source && options.source.length > 0 ? options.source : undefined }, retrievalOptions);
+        const assembled = assembleContext(ranked, { tokenBudget: budget });
+        const latencyMs = performance.now() - start;
+        console.log(chalk.cyan("compaction context get"));
+        console.log(`Query: ${JSON.stringify(query)}`);
+        console.log(`Store: ${storeDir} (${items.length} items)`);
+        if (assembled.included.length === 0) {
+            console.log("Assembled context: (no matching context in the store for this query)");
+        }
+        else {
+            console.log(`Assembled context (~${assembled.estimated_tokens} tokens, local estimate; budget ${budget}):`);
+            for (const item of assembled.included) {
+                const pointer = item.source_pointer ?? "(no source pointer)";
+                const oneLine = item.content.replace(/\s+/g, " ");
+                console.log(`  [${pointer}] ${oneLine}`);
+            }
+        }
+        const recoverable = assembled.included.filter((i) => i.recoverability === true && i.source_pointer).length;
+        console.log("Diagnostics (local retrieval, not a quality score):");
+        console.log(`  considered: ${ranked.length}   included: ${assembled.included.length}   dropped: ${assembled.dropped.length}`);
+        console.log(`  recoverable (has source pointer): ${recoverable}/${assembled.included.length}`);
+        if (options.source && options.source.length > 0) {
+            const includedPointers = new Set(assembled.included.map((i) => i.source_pointer).filter((p) => Boolean(p)));
+            const covered = options.source.filter((s) => includedPointers.has(s)).length;
+            console.log(`  source coverage: ${covered}/${options.source.length}`);
+        }
+        else {
+            console.log("  source coverage: n/a (no --source given)");
+        }
+        console.log(`  latency: ${latencyMs.toFixed(1)} ms`);
+        console.log("No model, no network. Local memory/retrieval view — it makes no savings claim and no quality/correctness claim.");
+    });
+}
+//# sourceMappingURL=context.js.map

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

@@ -0,0 +1,17 @@
+import { Command } from "commander";
+export interface RunThroughGatewayOptions {
+    provider?: string;
+    upstream?: string;
+    listen?: string;
+}
+/**
+ * Run `command` through the local Compaction Gateway. Shared by `gateway run` (the public gateway-native
+ * form) and the hidden `dev` compatibility alias — `label` only changes the message prefix + usage hint.
+ * Calls `process.exit(code)` with the child's exit code (so it is a terminal action).
+ */
+export declare function runThroughGateway(command: string[], options: RunThroughGatewayOptions, label?: string): Promise<void>;
+/**
+ * Register the hidden `dev` compatibility alias. The PUBLIC gateway-native form is `gateway run`
+ * (registered in gateway.ts); `dev` is kept for backward compatibility and hidden from top-level help.
+ */
+export declare function registerDevCommand(program: Command): void;