@compaction/cli 0.1.0

package/README.md

@@ -0,0 +1,319 @@
+# @compaction/cli
+
+**The free, local-first CLI for capturing and measuring AI agent traces.** It
+captures supported agent sessions on your own machine, shows input/output tokens
+and estimated spend with honest labels, and writes local reports and redacted
+share bundles — and, **when you opt in**, prepares those traces for optimization
+and verification via the **Compaction API**.
+
+> **The local CLI captures, measures, and prepares.** Optimization, advanced
+> verification, apply guidance, and team reporting are **not** in the free CLI —
+> they require the **Compaction API** (opt-in).
+
+## What the free CLI does (local, no account, no upload by default)
+
+`@compaction/cli` is a local-first command-line tool. Everything below runs on your
+machine and writes local files only:
+
+- **Capture supported agent sessions.** **Claude Code is the primary supported
+  workflow** (`capture claude-code`, Integration Readiness **Level 2**
+  command-wrapper). Also supported: **OpenAI Agents SDK** (`capture openai-agents`,
+  Level 2 command-wrapper) and **Codex** local-file/trace **import** (`import`,
+  Level 1). These are local capture/import integrations — **not** native/Level 3
+  SDK instrumentation.
+- **Show input/output tokens and estimated spend.** `analyze` and the local report
+  show input/output token counts and a per-run **estimated** cost. Token counts are
+  **provider-reported** only when the captured run carries provider usage metadata;
+  otherwise they are a **local estimate (chars/4)**. Cost is a **price-table
+  estimate** labeled `local estimate` / `token-estimated cost` — **never
+  billing-confirmed**.
+- **Create local reports.** `analyze` / `compact` write local JSON + Markdown
+  reports under an operator-chosen output directory. Local files only.
+- **Create redacted, content-free share bundles.** `feedback --redact` writes a
+  redacted, privacy-safe bundle as a **local file only — never uploaded**, and only
+  with an explicit write gesture (`--yes`).
+- **No upload by default.** There is **no telemetry**. The **only** network call in
+  the free CLI is the explicitly operator-invoked, read-only `capture
+  provider-usage` (credential supplied via an environment variable only; aggregate
+  usage/cost figures only, no prompt/completion content).
+
+The free CLI deliberately answers the first-value question — *"where is my context
+being wasted, and roughly what does it cost?"* — entirely locally, with honest
+labels.
+
+## What requires the Compaction API (opt-in — not in the free CLI)
+
+The following are **not** part of the free local CLI. They are the **opt-in
+Compaction API**:
+
+- **Optimization** — producing a compacted context from a captured trace.
+- **Advanced verification** — stronger checks on what a compacted context retains.
+- **Apply guidance** — a readiness verdict and a review/approval path before any
+  context is applied.
+- **Team reporting** — cross-run / cross-session reporting when enabled.
+
+> **The Compaction API is not broadly hosted yet.** There is **no live hosted
+> service today**. The API path is **designed to** optimize and verify **when you
+> opt in** — this README does **not** claim those run as a live service. Until the
+> API is available, these capabilities are **on the roadmap / opt-in**, not present
+> in the free CLI.
+
+When the API is available, the honesty rails carry over unchanged: cost stays an
+**estimate** unless billing-confirmed (no figure carries that label today);
+verification is **deterministic recoverability, NOT semantic/meaning preservation**;
+integration stays **Level 1/2**; and there is **no auto-apply** — every application
+is an explicit operator gesture.
+
+## The free local loop (recommended first run: your OWN workflow)
+
+**capture → analyze / measure → (local report) → redact / share**
+
+The recommended first run is on **your own** captured/imported workflow — **not a
+demo**. Synthetic/demo traces exist only as illustration; they are never the
+recommended first value.
+
+1. **Capture** a real workflow trace. **Claude Code is the primary supported
+   workflow** (`capture claude-code --session <path>`, Level 2 command-wrapper).
+   Also supported: OpenAI Agents SDK (`capture openai-agents`, Level 2) and Codex
+   local-file import (`import`, Level 1).
+2. **Analyze / measure** input/output tokens and estimated spend, and see where the
+   spend came from (`analyze`).
+3. **Local report** — read the local JSON / Markdown report written under your
+   chosen output directory.
+4. **Redact / share** — `feedback --redact` writes a redacted, content-free bundle
+   you can hand a teammate or founder. Local file only, never uploaded.
+
+> **Optimization, advanced verification, apply guidance, and team reporting** are
+> the **opt-in Compaction API**, not steps of the free local CLI (see the section
+> above).
+
+## Evidence levels and claims
+
+Every figure this tool produces carries one of these labels — and nothing stronger:
+
+| Label | Meaning |
+|---|---|
+| **local estimate** | chars/4 token heuristics and price-table cost approximations computed locally |
+| **provider-reported token delta** | token counts read from the provider's own API response/usage metadata (operator-entered or captured); input tokens are deterministic for a fixed context+prompt |
+| **token-estimated cost** | a price-table estimate applied to provider-reported token counts (`price_table_estimate`) — an estimate, never a billed figure |
+| **operator-entered billing record** | billed costs the operator read from their own provider console; recorded, not provider-verified by this tool |
+| **billing-confirmed** | only with real provider billing/invoice evidence **AND** the accepted measurement criterion met on those billed runs (N ≥ 3 runs per arm AND the delta-of-means ±2·SE interval excludes zero) — the statistical criterion alone is a bar on operator-entered figures, not proof of billing, so it is never sufficient by itself — **no figure in this repository currently carries this label** |
+
+**What is NOT claimed:** no billing-confirmed savings claim; no invoice savings claim; no general savings claim (all results are workflow-scoped and caveated); no auto-apply (every application is an explicit operator gesture); no hosted service or control plane (the free CLI is local-first, file-based); no universal "no context is lost" claim; no semantic/meaning preservation claim (it stays `not_evaluated`); no native/production/Level 3 integration claim.
+
+## Install
+
+This is a local-first CLI. It makes no network calls by default; the only
+command that reaches the network is the explicitly operator-invoked
+`capture provider-usage`, and only when the operator supplies a credential via
+an environment variable. There is no telemetry.
+
+### curl + npm / npx — AVAILABLE AT LAUNCH (pending publish; not live today)
+
+**The public install path is not live yet.** The package is **not yet published**
+to npm, and the installer is not yet hosted at `cli.compaction.dev`. The commands
+below are the intended public install path and will work **only at launch**, once
+the package is published **and** the script is hosted. Do not expect them to work
+today.
+
+```bash
+# AVAILABLE AT LAUNCH — not live today.
+# One-line installer (hosted at cli.compaction.dev at launch):
+curl -fsSL https://cli.compaction.dev/install | sh
+# Inspect it first (recommended): pipe to `less`, or download and read, before sh.
+curl -fsSL https://cli.compaction.dev/install | less
+
+# or with npm / npx, once published:
+npm install -g @compaction/cli   # then: compaction init
+npx @compaction/cli init         # no global install
+```
+
+The installer ([`scripts/install.sh`](scripts/install.sh)) is checked into the repo
+and readable now: it uses **no `sudo` by default** (installs into a user-writable
+prefix), makes **no network call except the npm install** (no telemetry), supports
+macOS + Linux, and **fails clearly if the package is not yet published** rather than
+faking success. Preview it without installing anything:
+
+```bash
+sh scripts/install.sh --dry-run
+```
+
+See [`docs/ops/install-readiness.md`](docs/ops/install-readiness.md) for the full
+install-readiness contract (hosting, package name, version pinning, platforms, and
+the pre-publish state).
+
+This repository is licensed under **AGPL-3.0-only** (see [`LICENSE`](LICENSE)). The
+npm **package name is `@compaction/cli`** (scoped, public; the installed binary
+stays `compaction`). It is **not yet published** — the `npm install` / `npx`
+commands above stay PENDING until the founder runs `npm publish`. Until publish,
+use the from-source path (recommended) or the local-tarball fallback below.
+
+### From source — recommended today
+
+```bash
+git clone <repo-url>
+cd compaction-dev
+npm ci
+npm run build
+# optional: expose the `compaction` binary on your PATH
+npm link
+```
+
+For reproducible local validation, use `npm ci` (not `npm install`).
+
+### Local tarball install (temporary internal/tester fallback)
+
+Until the package is on npm, an external tester can install the packed tarball
+directly. This is a **temporary fallback**, not the intended public path:
+
+```bash
+npm pack
+npm install -g ./compaction-cli-0.1.0.tgz
+```
+
+The package layout is verified by `npm run smoke:package`, which packs the
+tarball, installs it into a scratch prefix outside the repo, and runs
+`compaction --help`, `compaction init`, and a capture → compact step from the
+installed binary. The packed tarball ships the local CLI, `README.md`, and
+`LICENSE` only.
+
+### Sanity check
+
+```bash
+compaction --help
+```
+
+## CLI (free, local)
+
+The free local commands:
+
+```bash
+compaction init                                  # scaffold local config
+compaction capture claude-code --session <session.jsonl> [--include-subagents] --out <dir>
+compaction capture claude-code --discover [--projects-dir <path>]
+compaction capture openai-agents --out <dir> -- <command> [args...]
+compaction capture openai-agents --out <dir> --export <local-jsonl-export>
+compaction capture provider-usage --endpoint <url> [--credential-env-var <NAME>] [--out <dir>]
+compaction import <trace-file> --source <source> --out <dir>
+compaction import --list-sources
+compaction analyze <trace-file>
+compaction feedback --redact [--yes]
+```
+
+### `capture claude-code` (primary supported workflow)
+
+Captures a real Claude Code session JSONL (optionally including subagent
+transcripts) into the internal trace format, preserving provider-reported token
+usage from the session's own API response metadata. `--discover` scans the local
+Claude Code projects directory read-only and lists sessions with metadata (no
+network, no upload). This is **Integration Readiness Level 2** (local
+command-wrapper) — not Level 3 native SDK instrumentation. Captured traces may
+contain local file content — review before sharing.
+
+### `capture openai-agents` (Level 2 command-wrapper)
+
+Runs a local command or reads a local JSONL export containing OpenAI Agents
+SDK-style trace/span events, normalizes the supported events into the internal
+trace format, and writes capture evidence locally. It distinguishes
+provider-reported usage from local estimates: when supported events carry provider
+token fields, those values are labeled provider-reported; when absent, token
+metadata is marked `missing`/`unknown` and **never invented**. This is local
+capture only (Level 2) — it does **not** scrape the ChatGPT app, use undocumented
+APIs, upload traces, proxy provider/model calls, switch providers/models, or add a
+dashboard/auth/billing.
+
+### `capture provider-usage` (the only network call)
+
+Explicitly operator-invoked, read-only read of aggregate usage/cost from a provider
+usage API. The credential comes from an environment variable only (never a flag
+value, never logged, never written into artifacts); absence is a clean refusal. It
+captures aggregate token/cost figures only — no prompt/completion content. The
+resulting record is classified as provider-usage evidence.
+
+### `import` (Codex / local-file traces — Level 1)
+
+Reads a local trace-like JSON/JSONL file (including a `codex exec --json` export),
+validates whether it can be converted into the internal trace format, and writes
+normalized intake artifacts to an output directory. Import is local and file-based
+only: it does not mutate the source file, upload data, call provider APIs, route
+models, create a hosted service, use a database, add auth, or add billing. List
+supported sources with `compaction import --list-sources`.
+
+Codex token counts on the import path are **locally estimated (chars/4)**, not
+provider-reported. Live provider/runtime integrations (native Claude Code/Cursor
+instrumentation, live Codex launching, hosted provider APIs) remain future work; the
+Codex support here is intentionally local/export-file based only (Level 1).
+
+### `analyze`
+
+Reads a trace file and prints trace metadata, estimated input/output/total tokens,
+an estimated local cost, conservative waste findings, and suggested
+duplicate-output compaction opportunities (advisory only — the free CLI does **not**
+apply them; optimization is the opt-in Compaction API).
+
+### `feedback --redact`
+
+Builds a **redacted, privacy-safe feedback bundle** as a **local file only — never
+uploaded**. Redaction is best-effort and the bundle's own README states what is
+included/excluded; writing the bundle requires an explicit write gesture
+(`--yes`/`--confirm`). There is no upload path.
+
+## Known limitations
+
+- **The free CLI captures and measures; it does not optimize or verify.**
+  Optimization, advanced verification, apply guidance, and team reporting are the
+  **opt-in Compaction API** — not the free local CLI. The API is **not broadly
+  hosted yet**.
+- **Cost figures are estimates or operator-entered records, not billing-confirmed.**
+  Locally computed cost figures are price-table estimates; provider-usage records
+  carry operator-entered/captured console figures (not provider-verified by this
+  tool). **No figure anywhere in this repository is billing-confirmed**; the accepted
+  criterion that could one day support such a label (N ≥ 3 per arm, ±2·SE interval
+  excluding zero, on real billed runs) has not been met.
+- **Token counts are local estimates unless provider-reported usage is captured.**
+  The default is a chars/4 estimate, labeled as such; counts are provider-reported
+  only when the captured run carries provider usage metadata. Unknown stays unknown —
+  output tokens, provider, or cost the data does not carry are never inferred.
+- **Integrations are Level 1/2, not native/production.** Claude Code and OpenAI
+  Agents capture are **Level 2** local command-wrappers; Codex/local-file import is
+  **Level 1**. There is **no** native/Level 3 SDK instrumentation, no production
+  proxy, no model routing, and no ChatGPT/Claude consumer-app support.
+- **Advanced verification (API) is deterministic recoverability, not semantic
+  preservation.** Where the opt-in API verifies a compacted context, it checks
+  deterministic recoverability for a **supported** workflow; it does **not** evaluate
+  meaning or task equivalence, and it does **not** re-run your agent through a model.
+  SEMANTIC / meaning preservation remains **not evaluated**, and true model replay is
+  **future work**.
+- **No universal "no context is lost" guarantee.** Any apply-guidance verdict from
+  the opt-in API is **fail-closed and scoped** to supported developer-agent
+  workflows — never a universal guarantee, and never a semantic/meaning claim.
+
+## Product constraints
+
+- CLI-first, not web-app-first. No web framework, no database, no auth or billing, no
+  streaming.
+- No provider integrations in the free CLI except the explicitly operator-invoked,
+  read-only `capture provider-usage` (env-only credential; aggregate usage/cost only).
+  No proxying, no model routing, no live-call interception.
+- No hosted service or control plane in the free CLI; no full observability dashboard.
+
+**On the roadmap / opt-in API (NOT in the free CLI; reads as future/opt-in anywhere
+public):** the Compaction API's optimization and advanced verification, apply
+guidance, and team reporting; a hosted dashboard / control plane; native (Level 3)
+SDK instrumentation; model routing / provider switching / live-call interception; an
+IDE plugin; true model replay; semantic / meaning preservation (today not
+evaluated); and billing-confirmed savings (no figure in this repository carries that
+label). **The Compaction API is not broadly hosted yet** — never imply a live hosted
+service exists.
+
+## Contributing / internal docs
+
+Repository development, the marketing/docs website (`apps/web`), and contributor
+workflows live in the repo's internal documentation, **not** in this npm-facing
+README:
+
+- `AGENTS.md` — the agent operating contract.
+- `ROADMAP.md` — canonical strategy and the long-term path.
+- `docs/product/product-index.md` — the product-docs entry point (`mvp-plan.md`,
+  `decisions.md`).
+- `docs/ops/install-readiness.md` — the install/publish readiness contract.

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

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

package/dist/cli/commands/adapter.js

@@ -0,0 +1,49 @@
+import chalk from "chalk";
+import { validateAdapterFixtureFile } from "../../core/adapter-validation.js";
+import { listTraceAdapters } from "../../core/trace-adapters.js";
+function printSupportedAdapters() {
+    console.log(chalk.cyan("compaction adapter sources"));
+    for (const adapter of listTraceAdapters()) {
+        console.log(`- ${adapter.id}: ${adapter.displayName}`);
+        console.log(`  ${adapter.description}`);
+    }
+    console.log("Adapter Fixture Harness v0 is local and file-based only; live provider/runtime integrations are future work.");
+}
+export function registerAdapterCommand(program) {
+    const adapter = program.command("adapter").description("Validate local adapter fixtures without live provider integrations.");
+    adapter.command("list").description("List local trace adapters available to the fixture harness.").action(() => {
+        printSupportedAdapters();
+    });
+    adapter
+        .command("validate")
+        .argument("<fixture-file>", "Path to a local adapter fixture JSON or JSONL file")
+        .requiredOption("--source <source>", "Input source from the local adapter registry")
+        .description("Validate a local fixture through adapter canHandle and normalize.")
+        .action(async (fixtureFile, options) => {
+        if (!options.source) {
+            throw new Error("Missing required option --source <source>.");
+        }
+        const artifacts = await validateAdapterFixtureFile(fixtureFile, options.source);
+        console.log(chalk.cyan("compaction adapter validate"));
+        console.log(`Status: ${artifacts.report.status}`);
+        console.log(`Validation ID: ${artifacts.report.validation_id}`);
+        console.log(`Source: ${artifacts.report.source}`);
+        console.log(`Adapter: ${artifacts.report.adapter_id}`);
+        console.log(`Supported format detected: ${artifacts.report.supported_format_detected ? "yes" : "no"}`);
+        console.log(`Messages: ${artifacts.report.message_count}`);
+        console.log(chalk.green(`Wrote ${artifacts.paths.validationReportJsonPath}`));
+        console.log(chalk.green(`Wrote ${artifacts.paths.validationReportMarkdownPath}`));
+        if (artifacts.normalizedTrace) {
+            console.log(chalk.green(`Wrote ${artifacts.paths.normalizedTracePath}`));
+            console.log(`Recommended next command: ${artifacts.report.recommended_next_command}`);
+        }
+        else {
+            console.log(chalk.red("No normalized trace was generated."));
+            for (const failure of artifacts.report.failures) {
+                console.log(chalk.red(`Failure: ${failure}`));
+            }
+            process.exitCode = 1;
+        }
+    });
+}
+//# sourceMappingURL=adapter.js.map

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

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

package/dist/cli/commands/aggregate.js

@@ -0,0 +1,60 @@
+import chalk from "chalk";
+import { writeJsonArtifact, writeTextArtifact } from "../../core/artifact-writer.js";
+import { createAggregateReport, AGGREGATE_ARTIFACT_DIRECTORY } from "../../core/session-aggregate.js";
+import { buildAggregateShareBundle, formatAggregateMarkdown, formatAggregateReport, formatShareBundleMarkdown } from "../../core/aggregate-format.js";
+import { normalizeRunLabels } from "../../core/run-labels.js";
+/** Collect ONLY the label fields that were actually supplied, so absent ≡ no filter. */
+function suppliedLabels(options) {
+    return normalizeRunLabels({
+        project: options.project,
+        workflow: options.workflow,
+        provider: options.provider,
+        user_label: options.userLabel,
+        session: options.session
+    });
+}
+export function registerAggregateCommand(program) {
+    program
+        .command("aggregate")
+        .description("Roll up local compaction runs into per-session + cross-session token / cost / estimated-savings " +
+        "and verification-outcome aggregates. LOCAL ONLY — reads .compaction/runs/*, makes NO network call, " +
+        "writes only local files. No hosted dashboard.")
+        .option("--runs <dir>", "Runs directory to aggregate", ".compaction/runs")
+        .option("--out <dir>", "Directory for the aggregate artifacts", AGGREGATE_ARTIFACT_DIRECTORY)
+        .option("--share", "Also write a redacted, content-free AGGREGATE share bundle (aggregate numbers + labels + evidence " +
+        "tiers, NOT raw traces) a developer can hand a founder/admin. Local file only — never uploaded.")
+        .option("--project <name>", "Local-only: roll up ONLY runs tagged with this project label")
+        .option("--workflow <name>", "Local-only: roll up ONLY runs tagged with this workflow label")
+        .option("--provider <name>", "Local-only: roll up ONLY runs tagged with this provider/runtime label (operator-asserted)")
+        .option("--user-label <text>", "Local-only: roll up ONLY runs tagged with this free-form user label")
+        .option("--session <id>", "Local-only: roll up ONLY runs tagged with this session id")
+        .action(async (options) => {
+        const filters = suppliedLabels(options);
+        const runsDir = options.runs ?? ".compaction/runs";
+        const outDir = options.out ?? AGGREGATE_ARTIFACT_DIRECTORY;
+        const report = await createAggregateReport(runsDir, {
+            filters,
+            rollupLabels: filters
+        });
+        const consoleReport = formatAggregateReport(report);
+        const markdown = formatAggregateMarkdown(report);
+        const aggregateDir = `${outDir}/${report.aggregate_id}`;
+        const jsonPath = await writeJsonArtifact(aggregateDir, "aggregate-report.json", report);
+        const markdownPath = await writeTextArtifact(aggregateDir, "aggregate-report.md", markdown);
+        console.log(chalk.cyan(consoleReport));
+        console.log("");
+        console.log(chalk.green(`Wrote ${jsonPath}`));
+        console.log(chalk.green(`Wrote ${markdownPath}`));
+        if (options.share === true) {
+            const shareBundle = buildAggregateShareBundle(report);
+            const shareJsonPath = await writeJsonArtifact(aggregateDir, "aggregate-share.json", shareBundle);
+            const shareMarkdownPath = await writeTextArtifact(aggregateDir, "aggregate-share.md", formatShareBundleMarkdown(shareBundle));
+            console.log("");
+            console.log(chalk.bold("Redacted aggregate share bundle (content-free): aggregate numbers + labels + evidence tiers only — " +
+                "NO raw traces, run ids, or paths. Local file only; never uploaded."));
+            console.log(chalk.green(`Wrote ${shareJsonPath}`));
+            console.log(chalk.green(`Wrote ${shareMarkdownPath}`));
+        }
+    });
+}
+//# sourceMappingURL=aggregate.js.map

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

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

package/dist/cli/commands/analyze.js

@@ -0,0 +1,55 @@
+import chalk from "chalk";
+import { readFile } from "node:fs/promises";
+import { join, dirname } from "node:path";
+import { calculateCost } from "../../core/cost-calculator.js";
+import { formatAnalyzeReport } from "../../core/report-generator.js";
+import { estimateTraceTokens } from "../../core/token-estimator.js";
+import { detectWaste, buildSkillInjectionAdvisory } from "../../core/waste-detector.js";
+import { parseTraceFile } from "../../core/trace-parser.js";
+/**
+ * Try to load sibling capture-report.json from the same directory as the trace file.
+ * Returns the usage metadata if found and valid, otherwise undefined.
+ * Never throws — missing or malformed capture-report.json is silently ignored.
+ */
+async function tryLoadCaptureUsage(traceFile) {
+    try {
+        const dir = dirname(traceFile);
+        const captureReportPath = join(dir, "capture-report.json");
+        const raw = await readFile(captureReportPath, "utf8");
+        const parsed = JSON.parse(raw);
+        if (parsed.usage && typeof parsed.usage === "object") {
+            return parsed.usage;
+        }
+    }
+    catch {
+        // No capture-report.json, or unreadable/malformed — silently ignore.
+    }
+    return undefined;
+}
+export function registerAnalyzeCommand(program) {
+    program
+        .command("analyze")
+        .argument("<trace-file>", "Path to a local agent trace JSON file")
+        .description("Analyze a trace and print token, cost, and waste estimates.")
+        .action(async (traceFile) => {
+        const trace = await parseTraceFile(traceFile);
+        const tokens = estimateTraceTokens(trace);
+        const findings = detectWaste(trace);
+        // Report-only skill-injection advisory. Built from a SEPARATE detector; nothing is
+        // compacted and it never affects `findings` / the tool-output compaction path.
+        const skillInjectionAdvisory = buildSkillInjectionAdvisory(trace);
+        // Load usage from sibling capture-report.json if available (provides cache token counts).
+        const captureUsage = await tryLoadCaptureUsage(traceFile);
+        const cost = calculateCost(trace.model, tokens, captureUsage
+            ? { cacheReadTokens: captureUsage.cache_read_input_tokens, cacheCreationTokens: captureUsage.cache_creation_input_tokens }
+            : undefined);
+        console.log(chalk.cyan("compaction analyze"));
+        console.log(formatAnalyzeReport(trace, tokens, cost, findings, captureUsage, skillInjectionAdvisory));
+        // Exact next command to continue the loop (chaining), with the trace path the user passed.
+        console.log("");
+        console.log(chalk.bold("Next: see the recommended policy and estimated delta:"));
+        console.log(`  compaction recommend ${traceFile}`);
+        console.log(`  compaction compact ${traceFile} --out <dir>   # before/after delta + named policy + safety report`);
+    });
+}
+//# sourceMappingURL=analyze.js.map

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

@@ -0,0 +1,12 @@
+import { Command } from "commander";
+/**
+ * `compaction apply-context <trace-file> --out <dir>` — LEVEL-5 IN-WORKFLOW APPLY, Form A.
+ *
+ * Operator-invoked, local-first. compaction.dev runs the existing compaction, the pre-apply safety
+ * checks, ALWAYS retains the un-compacted original, and produces the original-vs-compacted review.
+ * It emits the approved compacted context ONLY on the explicit per-application approval gesture
+ * `--approve-in-workflow-use`. It makes NO live provider call, holds NO credential, runs no proxy /
+ * hosted component, and performs no auto-apply. The unattended `apply` path is untouched and not
+ * reachable from here.
+ */
+export declare function registerApplyContextCommand(program: Command): void;

package/dist/cli/commands/apply-context.js

@@ -0,0 +1,80 @@
+import path from "node:path";
+import chalk from "chalk";
+import { Option } from "commander";
+import { parseTraceFile } from "../../core/trace-parser.js";
+import { runEngineCommand } from "../engine-degrade.js";
+function defaultOutputDir(artifactRoot, traceId) {
+    return path.join(artifactRoot, traceId);
+}
+/**
+ * `compaction apply-context <trace-file> --out <dir>` — LEVEL-5 IN-WORKFLOW APPLY, Form A.
+ *
+ * Operator-invoked, local-first. compaction.dev runs the existing compaction, the pre-apply safety
+ * checks, ALWAYS retains the un-compacted original, and produces the original-vs-compacted review.
+ * It emits the approved compacted context ONLY on the explicit per-application approval gesture
+ * `--approve-in-workflow-use`. It makes NO live provider call, holds NO credential, runs no proxy /
+ * hosted component, and performs no auto-apply. The unattended `apply` path is untouched and not
+ * reachable from here.
+ */
+export function registerApplyContextCommand(program) {
+    program
+        .command("apply-context")
+        .description("Form A in-workflow apply: review original-vs-compacted, run pre-apply safety checks, and (only with explicit per-application approval) emit an approved compacted context for YOUR OWN next provider call. compaction.dev makes no live call and holds no credential.")
+        .argument("<trace-file>", "Path to a local agent trace JSON file")
+        .option("--out <dir>", "Directory where in-workflow-apply artifacts should be written")
+        .addOption(new Option("--approve-in-workflow-use", "EXPLICIT per-application approval gesture. Without it: review artifacts are produced and NO approved context is emitted. This records 'approved for in-workflow use' (NOT 'applied')."))
+        .addOption(new Option("--approve-skill-injection-policy", "EXPLICITLY also authorize the approval-required repeated_skill_injection_to_state_capsule policy. Default off; no auto-apply."))
+        .addOption(new Option("--attest-used", "OPTIONAL operator attestation: AFTER an approval, the operator records that they used the approved context in a live call. Stored as operator-ATTESTED provenance (the operator's own claim), never observed by compaction.dev."))
+        .option("--attest-note <text>", "Optional free-text note recorded with the operator attestation")
+        .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 { IN_WORKFLOW_APPLY_ARTIFACT_ROOT, recordOperatorAttestation, runInWorkflowApply } = await import("../../engine/in-workflow-apply.js");
+            const trace = await parseTraceFile(traceFile);
+            const outputDirectory = options.out ?? defaultOutputDir(IN_WORKFLOW_APPLY_ARTIFACT_ROOT, trace.id);
+            console.log(chalk.cyan("compaction apply-context (Form A)"));
+            console.log("Operator-invoked, local-first. compaction.dev makes NO live provider call and holds NO provider credential. No proxy, no hosted component, no auto-apply.");
+            const result = await runInWorkflowApply({
+                trace,
+                outputDirectory,
+                approveInWorkflowUse: options.approveInWorkflowUse === true,
+                approveSkillInjectionPolicy: options.approveSkillInjectionPolicy === true,
+                generatedAt: trace.generatedAt
+            });
+            console.log(result.consoleSummary);
+            console.log(chalk.green(`Wrote ${result.paths.preApplyReviewJsonPath}`));
+            console.log(chalk.green(`Wrote ${result.paths.preApplyReviewMarkdownPath}`));
+            console.log(chalk.green(`Wrote ${result.paths.retainedOriginalPath}`));
+            if (result.paths.approvedContextPath) {
+                console.log(chalk.green(`Wrote ${result.paths.approvedContextPath}`));
+            }
+            if (result.paths.applyApprovalRecordPath) {
+                console.log(chalk.green(`Wrote ${result.paths.applyApprovalRecordPath}`));
+            }
+            // Optional operator attestation (only meaningful once an approval record exists).
+            if (options.attestUsed === true) {
+                if (result.approvalRecord && result.paths.applyApprovalRecordPath) {
+                    const { record, path: attestationPath } = await recordOperatorAttestation({
+                        outputDirectory,
+                        applyApprovalRecord: result.approvalRecord,
+                        applyApprovalRecordPath: result.paths.applyApprovalRecordPath,
+                        generatedAt: trace.generatedAt,
+                        operatorNote: options.attestNote
+                    });
+                    console.log(chalk.yellow(`Operator attestation recorded (operator-attested, NOT observed): ${record.provenance_label}`));
+                    console.log(chalk.green(`Wrote ${attestationPath}`));
+                }
+                else {
+                    console.log(chalk.yellow("--attest-used ignored: there is no approval record to attest against (approve in-workflow use first)."));
+                }
+            }
+            console.log(chalk.green(`Output directory: ${result.outputDirectory}`));
+            // Exit non-zero when no approved context was emitted (refusal / review-only), mirroring apply/approve.
+            if (!result.approvedContextEmitted) {
+                process.exitCode = 1;
+            }
+        });
+    });
+}
+//# sourceMappingURL=apply-context.js.map

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

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