@compaction/cli 0.1.0

package/dist/cli/commands/capture-claude-code.js

@@ -0,0 +1,198 @@
+import { writeJsonArtifact, writeTextArtifact } from "../../core/artifact-writer.js";
+import { ClaudeCodeAdapter, PRIVACY_WARNING } from "../../core/adapters/claude-code-adapter.js";
+import { discoverClaudeCodeSessions, DISCOVERY_PRIVACY_NOTE } from "../../core/adapters/claude-code-discovery.js";
+function buildOutputDir(sessionPath, out) {
+    if (out)
+        return out;
+    // Default: .compaction/runs/<session-id-prefix>/
+    const sessionFileName = sessionPath.split("/").pop() ?? "session";
+    const sessionIdPrefix = sessionFileName.replace(/\.jsonl$/, "").slice(0, 8);
+    return `.compaction/runs/${sessionIdPrefix}`;
+}
+function buildMarkdownReport(sessionPath, outDir, provenance, usage) {
+    const lines = [
+        "# Capture Report",
+        "",
+        `**Session:** ${sessionPath}`,
+        `**Captured at:** ${provenance.capturedAt}`,
+        `**Adapter:** ${provenance.captureAdapter}`,
+        `**Session ID:** ${provenance.sessionId ?? "unknown"}`,
+        "",
+        "## Usage",
+        "",
+        `- Input tokens: ${usage.input_tokens ?? "unknown"}`,
+        `- Output tokens: ${usage.output_tokens ?? "unknown"}`,
+        `- Cache read tokens: ${usage.cache_read_input_tokens ?? 0}`,
+        `- Cache creation tokens: ${usage.cache_creation_input_tokens ?? 0}`,
+        `- Total tokens: ${usage.total_tokens ?? "unknown"}`,
+        `- Token-count source: ${usage.provider_reported_tokens ? "provider-reported (Claude Code session usage fields) — NOT billing-confirmed" : usage.estimated_tokens ? "locally estimated (chars/4) — NOT provider-reported" : "missing / unknown"}`,
+        `- Provider reported: ${usage.provider_reported_tokens}`,
+        `- Cost source: ${usage.cost_source}`,
+        `- Cost confidence: ${usage.cost_confidence}`,
+        "",
+        "## Distinctness",
+        "",
+        ...(provenance.traceFingerprint
+            ? [
+                `- Trace fingerprint (${provenance.traceFingerprint.algorithm}): ${provenance.traceFingerprint.content_sha256}`,
+                `- Messages hashed: ${provenance.traceFingerprint.message_count}`,
+                "- This is a one-way SHA-256 DIGEST over the canonical normalized trace content — NOT raw",
+                "  messages/prompts/tool-output. It is a per-run distinctness proof: re-capturing the same",
+                "  session yields the same fingerprint, so re-captures are NOT counted as new sessions.",
+                "  Matching aggregate metrics alone do NOT prove two sessions are the same — only a matching",
+                "  fingerprint does."
+            ]
+            : [
+                "- Trace fingerprint: not available — distinctness is `not_verified` for this run.",
+                "  Without a fingerprint this run must NOT be counted as a distinct session."
+            ]),
+        "",
+        "## Warnings",
+        "",
+        ...provenance.warnings.map((w) => `- ${w}`),
+        "",
+        "## Limitations",
+        "",
+        ...provenance.limitations.map((l) => `- ${l}`),
+        "",
+        "## Artifacts",
+        "",
+        `- \`${outDir}/captured-trace.json\` — AgentTrace (source: real_captured)`,
+        `- \`${outDir}/capture-report.json\` — CapturedRun metadata`,
+        `- \`${outDir}/capture-report.md\` — this file`,
+        ""
+    ];
+    return lines.join("\n");
+}
+export async function captureClaudeCodeCommand(options) {
+    const maxToolResultChars = options.maxToolResultChars !== undefined
+        ? parseInt(options.maxToolResultChars, 10)
+        : 32_000;
+    const includeSubagents = options.includeSubagents === true;
+    // 1. Print privacy warning
+    console.log(PRIVACY_WARNING);
+    console.log();
+    const adapter = new ClaudeCodeAdapter();
+    // 2. Print reading session
+    console.log(`Reading session: ${options.session}`);
+    const capturedRun = await adapter.normalize({
+        sourcePath: options.session,
+        options: { maxToolResultChars, includeSubagents }
+    });
+    const { trace, usage, provenance } = capturedRun;
+    // 3. Print entry counts (from limitations field)
+    const assistantLine = provenance.limitations.find((l) => l.startsWith("Assistant entries:"));
+    const userLine = provenance.limitations.find((l) => l.startsWith("User entries:"));
+    const otherLine = provenance.limitations.find((l) => l.startsWith("Other/excluded entries:"));
+    const assistantCount = assistantLine ? assistantLine.replace("Assistant entries: ", "") : "?";
+    const userCount = userLine ? userLine.replace("User entries: ", "") : "?";
+    const otherCount = otherLine ? otherLine.replace("Other/excluded entries: ", "") : "?";
+    console.log(`Entries: ${assistantCount} assistant, ${userCount} user, ${otherCount} other`);
+    // 4. Print thinking blocks excluded
+    const thinkingLine = provenance.limitations.find((l) => l.startsWith("Thinking blocks excluded:"));
+    const thinkingCount = thinkingLine ? thinkingLine.replace("Thinking blocks excluded: ", "") : "0";
+    console.log(`Thinking blocks excluded: ${thinkingCount}`);
+    // 4b. Print subagents included (when --include-subagents was passed)
+    if (includeSubagents && provenance.subagents !== undefined) {
+        console.log(`Subagents included: ${provenance.subagents.length}`);
+    }
+    // 5. Print messages extracted
+    console.log(`Messages extracted: ${trace.messages.length}`);
+    // 6. Print token totals (cache counts from structured usage fields)
+    console.log(`Token totals: input=${usage.input_tokens ?? 0}, output=${usage.output_tokens ?? 0}, cache_creation=${usage.cache_creation_input_tokens ?? 0}, cache_read=${usage.cache_read_input_tokens ?? 0}`);
+    // 6b. Label the token-count source honestly (§13): provider-reported vs locally estimated.
+    // Claude Code session files embed provider usage, so these are typically provider-reported;
+    // never present an estimate as provider-reported.
+    const tokenSourceLabel = usage.provider_reported_tokens
+        ? "provider-reported (from the Claude Code session usage fields) — NOT billing-confirmed"
+        : usage.estimated_tokens
+            ? "locally estimated (chars/4) — NOT provider-reported, NOT billing-confirmed"
+            : "missing / unknown (not invented)";
+    console.log(`Token-count source: ${tokenSourceLabel}`);
+    // 6b-ii. Set expectations honestly for the downstream commands. The totals above are
+    // SESSION-LEVEL provider-reported figures (from the session's own API usage metadata). The
+    // per-message / policy before-after figures that `spend` and `compact` compute are deterministic
+    // LOCAL ESTIMATES (chars/4) — a different measurement — and are labeled as such there. This is the
+    // repo's standing discipline (session totals provider-reported; per-message figures chars/4
+    // estimates), not a defect: the two are not conflated, and neither is billing-confirmed.
+    if (usage.provider_reported_tokens) {
+        console.log("Note: the totals above are SESSION-LEVEL provider-reported counts. The per-message before/after");
+        console.log("      figures shown by 'spend' and 'compact' are deterministic LOCAL ESTIMATES (chars/4) — a");
+        console.log("      different measurement, labeled there as local estimates; neither figure is billing-confirmed.");
+    }
+    // 6c. Per-run distinctness fingerprint (a one-way digest over canonical normalized
+    // content — NOT raw content). Lets a re-capture of the same session be told apart
+    // from a genuinely new one; when unavailable, distinctness is `not_verified`.
+    if (provenance.traceFingerprint) {
+        console.log(`Trace fingerprint (distinctness, digest only — NOT raw content): ${provenance.traceFingerprint.content_sha256}`);
+    }
+    else {
+        console.log("Trace fingerprint: not available — distinctness not_verified (do not count as distinct).");
+    }
+    // Write artifacts
+    const outDir = buildOutputDir(options.session, options.out);
+    const capturedRunArtifact = { trace, usage, provenance };
+    const markdownReport = buildMarkdownReport(options.session, outDir, provenance, usage);
+    await writeJsonArtifact(outDir, "captured-trace.json", trace);
+    await writeJsonArtifact(outDir, "capture-report.json", capturedRunArtifact);
+    await writeTextArtifact(outDir, "capture-report.md", markdownReport);
+    // 7. Print artifacts written
+    console.log(`Artifacts written to: ${outDir}/`);
+    // 8. Print next step — chain into the verified strong-MVP Claude Code flow:
+    //    spend (where the spend goes) → compact --eval (compaction + strong apply-readiness:
+    //    deterministic recoverability + commitment-preservation + fixture task-check + token/cost).
+    //    `analyze` remains available for a quick read-only estimate, but the strong flow is `spend`
+    //    then `compact --eval`, so point the user there.
+    console.log("");
+    console.log("Next (Claude Code strong flow):");
+    console.log(`  1. compaction spend ${outDir}/captured-trace.json            # where the tokens/cost go (local estimate)`);
+    console.log(`  2. compaction compact ${outDir}/captured-trace.json --eval --out <dir>`);
+    console.log("     # compaction + strong apply-readiness: deterministic recoverability, commitment-preservation,");
+    console.log("     # fixture task-check, and token/cost accounting — nothing is applied automatically.");
+    console.log(`  (or: compaction analyze ${outDir}/captured-trace.json   for a quick read-only estimate)`);
+}
+/**
+ * Discover local Claude Code sessions (metadata only) and print, for each, the
+ * ready-to-run `capture claude-code --session <path>` command (guided capture).
+ *
+ * Local and read-only: scans the projects directory only, makes no network call
+ * and no upload, and never prints session message content — metadata only.
+ */
+export async function discoverClaudeCodeCommand(options) {
+    // 1. Privacy / scope note (one line, consistent with capture warnings).
+    console.log(DISCOVERY_PRIVACY_NOTE);
+    console.log();
+    const { projectsDir, projectsDirExists, sessions } = await discoverClaudeCodeSessions({
+        projectsDir: options.projectsDir
+    });
+    console.log(`Scanning Claude Code projects directory: ${projectsDir}`);
+    if (!projectsDirExists) {
+        console.log("No Claude Code projects directory found at that path. Nothing to discover.");
+        return;
+    }
+    if (sessions.length === 0) {
+        console.log("No Claude Code sessions discovered.");
+        return;
+    }
+    console.log(`Discovered ${sessions.length} session(s):`);
+    console.log();
+    for (const s of sessions) {
+        const timestamp = s.lastTimestamp ?? s.firstTimestamp ?? "unknown";
+        console.log(`- session: ${s.sessionId ?? "unknown"}`);
+        console.log(`  project:        ${s.projectSlug}${s.projectDir ? ` (${s.projectDir})` : ""}`);
+        console.log(`  timestamp:      ${timestamp}`);
+        console.log(`  messages:       ${s.messageCount}`);
+        console.log(`  subagents:      ${s.subagentCount}`);
+        console.log(`  provider usage: ${s.providerReportedUsagePresent ? "present" : "absent"}`);
+        console.log(`  run: compaction capture claude-code --session ${s.sessionPath}`);
+        console.log();
+    }
+    console.log("Sessions are listed newest-first. Longer sessions (more messages / subagents) are the most");
+    console.log("likely to contain avoidable repeated or stale tool output, so they tend to show the clearest");
+    console.log("before/after delta; a short session may legitimately have little or nothing to compact.");
+    console.log();
+    console.log("Pick one session above and run its 'compaction capture claude-code --session <path>' command,");
+    console.log("then run 'compaction spend' followed by 'compaction compact --eval' on the resulting");
+    console.log("captured-trace.json (the strong flow: spend, then compaction + apply-readiness eval).");
+}
+//# sourceMappingURL=capture-claude-code.js.map

package/dist/cli/commands/capture-provider-usage.d.ts

@@ -0,0 +1,35 @@
+import type { ProviderUsageClient } from "../../core/provider-usage/provider-usage-client.js";
+export interface CaptureProviderUsageOptions {
+    endpoint?: string;
+    credentialEnvVar?: string;
+    windowStart?: string;
+    windowEnd?: string;
+    label?: string;
+    out?: string;
+}
+/**
+ * Optional, additive, backward-compatible testability seam. Tests pass a MOCK
+ * provider-usage client (and may override the env reader) so the CLI-level
+ * stdout/stderr/artifact no-secret-leak + refusal paths can be exercised with a
+ * sentinel credential and NO real network. Defaults are the real client and
+ * process.env, so the production command path is unchanged.
+ */
+export interface CaptureProviderUsageDeps {
+    /** Injectable provider-usage client. Default: the real fetch-based client. */
+    client?: ProviderUsageClient;
+    /** Env reader override (tests). Default: process.env (used to read the credential for the redaction backstop). */
+    env?: Record<string, string | undefined>;
+    /** Fixed timestamp for deterministic test artifacts. Default: now (via the adapter). */
+    capturedAt?: string;
+    /** Fixed run id for deterministic test artifacts. Default: derived (via the adapter). */
+    runId?: string;
+}
+/**
+ * Read-only, aggregate-only provider usage/cost capture (Option A).
+ *
+ * Reads the credential from the named env var (default COMPACTION_PROVIDER_USAGE_TOKEN),
+ * refuses cleanly if it is absent/empty (clear message naming the env var, non-zero
+ * exit, NO artifact), performs the single read via the real fetch client, and writes
+ * a usage-only CapturedRun under .compaction/. ALL output is redacted before printing.
+ */
+export declare function captureProviderUsageCommand(options: CaptureProviderUsageOptions, deps?: CaptureProviderUsageDeps): Promise<void>;

package/dist/cli/commands/capture-provider-usage.js

@@ -0,0 +1,113 @@
+import { writeJsonArtifact, writeTextArtifact } from "../../core/artifact-writer.js";
+import { redactSecrets } from "../../core/provider-usage/credential-redaction.js";
+import { captureProviderUsage, DEFAULT_CREDENTIAL_ENV_VAR, MissingProviderCredentialError, PROVIDER_USAGE_PRIVACY_NOTE } from "../../core/provider-usage/provider-usage-adapter.js";
+function buildOutputDir(out) {
+    if (out)
+        return out;
+    return ".compaction/runs/provider-usage";
+}
+function buildMarkdownReport(outDir, provenance, usage) {
+    const lines = [
+        "# Provider Usage Capture Report",
+        "",
+        `**Source:** ${provenance.sourcePath}`,
+        `**Captured at:** ${provenance.capturedAt}`,
+        `**Adapter:** ${provenance.captureAdapter}`,
+        "",
+        "## Usage (aggregate only — no content)",
+        "",
+        `- Input tokens: ${usage.input_tokens ?? "unknown"}`,
+        `- Output tokens: ${usage.output_tokens ?? "unknown"}`,
+        `- Total tokens: ${usage.total_tokens ?? "unknown"}`,
+        `- Provider reported tokens: ${usage.provider_reported_tokens}`,
+        `- Cost source: ${usage.cost_source}`,
+        `- Cost confidence: ${usage.cost_confidence}`,
+        ...(usage.currency ? [`- Currency: ${usage.currency}`] : []),
+        "",
+        "## Warnings",
+        "",
+        ...provenance.warnings.map((w) => `- ${w}`),
+        "",
+        "## Limitations",
+        "",
+        ...provenance.limitations.map((l) => `- ${l}`),
+        "",
+        "## Artifacts",
+        "",
+        `- \`${outDir}/captured-trace.json\` — AgentTrace (source: provider_usage, no messages)`,
+        `- \`${outDir}/capture-report.json\` — CapturedRun metadata (usage/cost only)`,
+        `- \`${outDir}/capture-report.md\` — this file`,
+        ""
+    ];
+    return lines.join("\n");
+}
+/**
+ * Read-only, aggregate-only provider usage/cost capture (Option A).
+ *
+ * Reads the credential from the named env var (default COMPACTION_PROVIDER_USAGE_TOKEN),
+ * refuses cleanly if it is absent/empty (clear message naming the env var, non-zero
+ * exit, NO artifact), performs the single read via the real fetch client, and writes
+ * a usage-only CapturedRun under .compaction/. ALL output is redacted before printing.
+ */
+export async function captureProviderUsageCommand(options, deps = {}) {
+    const envVar = options.credentialEnvVar ?? DEFAULT_CREDENTIAL_ENV_VAR;
+    // Env reader: process.env by default; tests may inject an override.
+    const env = deps.env ?? process.env;
+    // Capture the configured secret (if any) ONLY to feed the redaction backstop —
+    // it is never printed and never written. Primary control is that nothing on this
+    // path puts it into output; this is the defense-in-depth value for redaction.
+    const configuredSecret = env[envVar];
+    // Redacted printer: every line written by this command passes through redaction.
+    const say = (line) => console.log(redactSecrets(line, configuredSecret));
+    const sayErr = (line) => console.error(redactSecrets(line, configuredSecret));
+    say(PROVIDER_USAGE_PRIVACY_NOTE);
+    say("");
+    if (!options.endpoint) {
+        sayErr("error: --endpoint <url> is required (the provider usage/cost reporting endpoint).");
+        process.exitCode = 1;
+        return;
+    }
+    let capturedRun;
+    try {
+        capturedRun = await captureProviderUsage({
+            endpoint: options.endpoint,
+            credentialEnvVar: envVar,
+            windowStart: options.windowStart,
+            windowEnd: options.windowEnd,
+            label: options.label,
+            // Seam: default undefined => the adapter uses the real fetch client / process.env / now.
+            client: deps.client,
+            env: deps.env,
+            capturedAt: deps.capturedAt,
+            runId: deps.runId
+        });
+    }
+    catch (error) {
+        if (error instanceof MissingProviderCredentialError) {
+            // Clean refusal: clear message naming the env var, non-zero exit, NO artifact.
+            sayErr(`error: ${error.message}`);
+            process.exitCode = 1;
+            return;
+        }
+        // Any other failure (auth error, network, parse): redact before printing,
+        // exit non-zero, write NO partial artifact.
+        const message = error instanceof Error ? error.message : String(error);
+        sayErr(`error: provider usage read failed: ${message}`);
+        process.exitCode = 1;
+        return;
+    }
+    const { trace, usage, provenance } = capturedRun;
+    const outDir = buildOutputDir(options.out);
+    say(`Source: ${provenance.sourcePath}`);
+    say(`Token totals (aggregate): input=${usage.input_tokens ?? 0}, output=${usage.output_tokens ?? 0}, total=${usage.total_tokens ?? 0}`);
+    say(`Cost source: ${usage.cost_source} (confidence: ${usage.cost_confidence})`);
+    say("Messages captured: 0 (aggregate usage only — no prompt/completion content)");
+    const capturedRunArtifact = { trace, usage, provenance };
+    const markdownReport = buildMarkdownReport(outDir, provenance, usage);
+    await writeJsonArtifact(outDir, "captured-trace.json", trace);
+    await writeJsonArtifact(outDir, "capture-report.json", capturedRunArtifact);
+    await writeTextArtifact(outDir, "capture-report.md", markdownReport);
+    say(`Artifacts written to: ${outDir}/`);
+    say(`Next: compaction analyze ${outDir}/captured-trace.json`);
+}
+//# sourceMappingURL=capture-provider-usage.js.map

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

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

package/dist/cli/commands/capture.js

@@ -0,0 +1,76 @@
+import chalk from "chalk";
+import { captureOpenAIAgentsCommand, captureOpenAIAgentsExport } from "../../core/openai-agents-capture.js";
+import { captureClaudeCodeCommand, discoverClaudeCodeCommand } from "./capture-claude-code.js";
+import { captureProviderUsageCommand } from "./capture-provider-usage.js";
+import { DEFAULT_CREDENTIAL_ENV_VAR } from "../../core/provider-usage/provider-usage-adapter.js";
+export function registerCaptureCommand(program) {
+    const capture = program.command("capture").description("Capture local integration traces into compaction.dev AgentTrace format.");
+    capture
+        .command("openai-agents")
+        .description("Capture OpenAI Agents SDK-style local trace events from a command wrapper or local export.")
+        .requiredOption("--out <dir>", "Output root directory for capture artifacts")
+        .option("--export <file>", "Read a local OpenAI Agents SDK-style JSONL trace/span export instead of running a command")
+        .argument("[commandParts...]", "Command and arguments to execute after --")
+        .allowUnknownOption(true)
+        .action(async (commandParts, options) => {
+        console.log(chalk.cyan("compaction capture openai-agents"));
+        console.log("Capturing local OpenAI Agents SDK-style events. No ChatGPT scraping, provider proxying, or upload is performed.");
+        const artifacts = options.export
+            ? await captureOpenAIAgentsExport(options.export, options.out)
+            : await captureOpenAIAgentsCommand(commandParts, options.out);
+        console.log(artifacts.terminalSummary);
+        console.log(chalk.green(`Wrote ${artifacts.paths.capturedTracePath}`));
+        console.log(chalk.green(`Wrote ${artifacts.paths.captureReportJsonPath}`));
+        console.log(chalk.green(`Wrote ${artifacts.paths.captureReportMarkdownPath}`));
+        if (artifacts.report.status === "fail") {
+            process.exitCode = 1;
+        }
+    });
+    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.")
+        .option("--session <path>", "Path to the Claude Code session JSONL file (e.g. ~/.claude/projects/<slug>/<session-id>.jsonl)")
+        .option("--discover", "List discoverable local Claude Code sessions (metadata only) and print the ready-to-run --session command for each. Local, read-only.")
+        .option("--projects-dir <path>", "Override the Claude Code projects root to scan with --discover (default: ~/.claude/projects). Read-only.")
+        .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")
+        .action(async (options) => {
+        if (options.discover) {
+            await discoverClaudeCodeCommand({ projectsDir: options.projectsDir });
+            return;
+        }
+        if (!options.session) {
+            console.error("error: either --session <path> or --discover is required.");
+            console.error("Run 'compaction capture claude-code --discover' to list local sessions.");
+            process.exitCode = 1;
+            return;
+        }
+        await captureClaudeCodeCommand({
+            session: options.session,
+            out: options.out,
+            maxToolResultChars: options.maxToolResultChars,
+            includeSubagents: options.includeSubagents
+        });
+    });
+    capture
+        .command("provider-usage")
+        .description("Read-only, aggregate-only provider usage/cost capture (Option A). Reads aggregate token/cost only — NO prompt/completion content. The credential is read from an environment variable (never a flag value), used only for the single read-only request, and never logged or written to any artifact. Local only — the only egress is the configured provider endpoint.")
+        .requiredOption("--endpoint <url>", "Provider usage/cost reporting endpoint to read (non-secret).")
+        .option("--credential-env-var <name>", `Name of the environment variable to read the read-only credential from (default: ${DEFAULT_CREDENTIAL_ENV_VAR}). This NAMES the env var only — it never carries the secret value.`, DEFAULT_CREDENTIAL_ENV_VAR)
+        .option("--window-start <iso>", "Reporting window start (ISO 8601).")
+        .option("--window-end <iso>", "Reporting window end (ISO 8601).")
+        .option("--label <label>", "Human-readable label for the captured run/window.")
+        .option("--out <dir>", "Output directory for captured artifacts (default: .compaction/runs/provider-usage/).")
+        .action(async (options) => {
+        await captureProviderUsageCommand({
+            endpoint: options.endpoint,
+            credentialEnvVar: options.credentialEnvVar,
+            windowStart: options.windowStart,
+            windowEnd: options.windowEnd,
+            label: options.label,
+            out: options.out
+        });
+    });
+}
+//# sourceMappingURL=capture.js.map

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

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

package/dist/cli/commands/compact.js

@@ -0,0 +1,206 @@
+import path from "node:path";
+import chalk from "chalk";
+import { Option } from "commander";
+import { writeJsonArtifact, writeTextArtifact } from "../../core/artifact-writer.js";
+import { describeTokenAccounting } from "../../core/token-accounting.js";
+import { parseTraceFile } from "../../core/trace-parser.js";
+import { buildRunLabelsFile, hasAnyLabel } from "../../core/run-labels.js";
+import { runEngineCommand } from "../engine-degrade.js";
+const VALID_REVIEWER_TYPES = ["human", "automated", "none"];
+/**
+ * Print the combined compaction→eval summary for `compact --eval`. The five signals are kept
+ * STRICTLY SEPARATE and each carries its honest label, so the strong deterministic recoverability
+ * fact is never blurred with the weak local token/cost estimate:
+ *   1. token/cost — local estimate (chars/4 + price-table), NOT billing-confirmed, NOT realized savings.
+ *   2. deterministic recoverability — passed/failed/not_computed + the recoverability check counts.
+ *   3. evidence tier — fixture / imported / real_captured, derived at the weakest honest level from
+ *      the trace source (a fixture/imported trace can never be reported as real_captured).
+ *   4. semantic_preservation — always not_evaluated (never scored).
+ *   5. commitment_preservation — always not_evaluated (never scored).
+ * `recoverability: passed` means byte/hash/source-pointer recoverability ONLY.
+ */
+function printCombinedEvalSummary(result) {
+    const checks = result.recoverability_checks;
+    const passedChecks = checks.filter((c) => c.status === "pass").length;
+    console.log("");
+    console.log(chalk.bold("Recoverability eval (--eval): deterministic, in-process — no hand-assembled bundle"));
+    // 1. token/cost estimate — local estimate ONLY.
+    console.log(chalk.bold("[1] Token/cost estimate (local estimate):"));
+    console.log("  Locally estimated (chars/4 trace tokens + price-table cost) — NOT provider-reported, " +
+        "NOT billing-confirmed, NOT realized savings. See compaction report above for the before/after figures.");
+    // 2. deterministic recoverability result + counts.
+    console.log(chalk.bold("[2] Deterministic recoverability:"));
+    console.log(`  ${result.recoverability.toUpperCase()} (byte/hash/source-pointer recoverability ONLY)`);
+    console.log(`  ${result.recoverability_reason}`);
+    console.log(`  Recoverability checks: ${passedChecks}/${checks.length} passed`);
+    for (const check of checks) {
+        console.log(`    [${check.status}] ${check.label}`);
+    }
+    // 3. evidence tier (derived from trace source; never elevated).
+    console.log(chalk.bold("[3] Evidence tier:"));
+    console.log(`  ${result.evidence_source} (from ${result.evidence_source_type}); real_captured=${result.real_captured}`);
+    // 4 + 5. preservation axes — always not_evaluated.
+    console.log(chalk.bold("[4] Semantic preservation:"));
+    console.log(`  ${result.semantic_preservation} (NOT scored by this harness)`);
+    console.log(chalk.bold("[5] Commitment preservation:"));
+    console.log(`  ${result.commitment_preservation} (NOT scored by this harness)`);
+    console.log("  A passing recoverability verdict is byte/hash/source-pointer recoverability ONLY — " +
+        "it is NOT a meaning-preservation or task-critical-commitment claim.");
+}
+/**
+ * Print the STRONG eval summary for `compact --eval` (Strong-MVP Tracks B/C/D): the deterministic
+ * commitment-preservation recoverability check, the fixture-based task-check, the token/cost
+ * accounting (each figure labeled provider-reported vs local estimate), and the composed strong
+ * apply-readiness verdict with a per-axis reason. Every label is the weakest honest level:
+ * commitment-preservation and task-check are RECOVERABILITY checks, NOT semantic/meaning guarantees,
+ * and the task-check is fixture-based, NOT real model replay.
+ */
+function printStrongEvalSummary(strong) {
+    console.log("");
+    console.log(chalk.bold("Strong apply-readiness eval (Tracks B/C/D): deterministic, in-process"));
+    // [6] commitment preservation (recoverability of extracted task-critical items — NOT semantic).
+    const c = strong.commitment_preservation;
+    console.log(chalk.bold("[6] Commitment preservation (deterministic recoverability check, NOT semantic):"));
+    console.log(`  ${c.status.toUpperCase()} — ${c.reason}`);
+    console.log(`  commitments=${c.commitment_count} (retained=${c.retained_count}, recoverable=${c.recoverable_count}, missing=${c.missing_count})`);
+    for (const detail of c.details) {
+        console.log(`    [${detail.recoverability}] ${detail.category}: ${detail.text}`);
+    }
+    // [7] fixture-based task-check (NOT real model replay).
+    const t = strong.task_check;
+    console.log(chalk.bold("[7] Task-check (fixture-based, NOT real model replay):"));
+    console.log(`  ${t.status.toUpperCase()} (workflow=${t.workflow}) — ${t.reason}`);
+    // [8] token & cost accounting (each figure labeled).
+    console.log(chalk.bold("[8] Token & cost accounting:"));
+    for (const line of describeTokenAccounting(strong.token_accounting)) {
+        console.log(`  ${line}`);
+    }
+    // [9] strong apply-readiness verdict (per-axis reasons).
+    const r = strong.readiness;
+    console.log(chalk.bold(`[9] Strong apply-readiness: ${r.readiness.toUpperCase()}`));
+    console.log(`  ${r.reason}`);
+    for (const check of r.checks) {
+        console.log(`    [${check.status}] ${check.axis}: ${check.reason}`);
+    }
+}
+function runIdFromOutputDirectory(outputDirectory) {
+    return path.basename(path.resolve(outputDirectory));
+}
+export function registerCompactCommand(program) {
+    program
+        .command("compact")
+        .argument("<trace-file>", "Path to a local agent trace JSON file")
+        .requiredOption("--out <dir>", "Directory where compaction artifacts should be written")
+        .addOption(new Option("--reviewer <type>", "Reviewer type for approval readiness signal")
+        .choices(VALID_REVIEWER_TYPES)
+        .default("none"))
+        .option("--review-summary <text>", "Review summary text (presence sets review_summary_present: true)")
+        .addOption(new Option("--approve-skill-injection-policy", "Approve and apply the byte-identical same-skill skill-injection compaction policy (default: off; nothing compacted unless provided)"))
+        .option("--eval", "After compacting, run the deterministic byte/hash/source-pointer recoverability eval on the SAME " +
+        "in-process compaction (no hand-assembled bundle) and print a combined summary. Exits non-zero if " +
+        "recoverability fails (fail-closed). Recoverability is byte/hash/source-pointer only — NOT semantic " +
+        "or commitment preservation, and NOT a savings claim.")
+        .option("--project <name>", "Local-only label: tag this run's project (for the multi-session aggregate; never uploaded)")
+        .option("--workflow <name>", "Local-only label: tag this run's workflow (for the aggregate; never uploaded)")
+        .option("--provider <name>", "Local-only label: tag this run's provider/runtime (operator-asserted, NOT provider-verified)")
+        .option("--user-label <text>", "Local-only free-form label for this run (for the aggregate; never uploaded)")
+        .option("--session <id>", "Local-only session id: group this run with others under one session in the aggregate")
+        .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");
+            const trace = await parseTraceFile(traceFile);
+            const reviewerType = options.reviewer;
+            const reviewSummaryPresent = typeof options.reviewSummary === "string" && options.reviewSummary.length > 0;
+            const approveSkillInjectionPolicy = options.approveSkillInjectionPolicy === true;
+            const runId = runIdFromOutputDirectory(options.out);
+            // Run the compaction policy ONCE, in-process, and reuse the SAME in-memory result for both the
+            // persisted artifacts and (when --eval) the recoverability eval. No disk round-trip, no
+            // 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 });
+            console.log(chalk.cyan("compaction compact"));
+            console.log(artifacts.consoleReport);
+            // Operator-visible only when the approval gesture was given; default output is unchanged.
+            if (approveSkillInjectionPolicy) {
+                const summary = artifacts.skillInjectionCompaction;
+                console.log(chalk.cyan(`Skill-injection policy (approved): compacted ${summary.compacted_count} byte-identical same-skill skill injection(s); ` +
+                    `est ${summary.estimated_tokens_removed} tokens removed (${summary.estimate_label})`));
+            }
+            // Token-count source label (honest): the compaction report's before/after token figures
+            // are locally estimated (chars/4), never provider-reported. Stating this prevents an
+            // estimate from being read as a billing-confirmed count.
+            console.log("Token-count source: locally estimated (chars/4) — NOT provider-reported, NOT billing-confirmed");
+            // Safety + recoverability linkage (safety-report.json fields), so the compaction value and
+            // its reversibility/risk evidence are visible together, not split across files.
+            const safety = artifacts.safetyReport;
+            console.log(`Risk level: ${safety.risk_level} (safety-report.json risk_level)`);
+            console.log(`Source recoverability: ${safety.source_recoverability} ` +
+                "(source pointers + content hashes + state capsules recorded; original trace retained)");
+            console.log(`Approval readiness: ${safety.approval_readiness_status}`);
+            console.log("Approval requirement: nothing is applied to your workflow automatically. " +
+                "apply-context emits an approved context ONLY with the explicit --approve-in-workflow-use gesture (no auto-apply).");
+            console.log(chalk.green(`Wrote ${artifacts.paths.reportPath}`));
+            console.log(chalk.green(`Wrote ${artifacts.paths.markdownReportPath}`));
+            console.log(chalk.green(`Wrote ${artifacts.paths.policyPath}`));
+            console.log(chalk.green(`Wrote ${artifacts.paths.capsulePath}`));
+            console.log(chalk.green(`Wrote ${artifacts.paths.compactedTracePath}`));
+            console.log(chalk.green(`Wrote ${artifacts.paths.safetyReportPath}`));
+            console.log(chalk.green(`Wrote ${artifacts.paths.safetyMarkdownReportPath}`));
+            console.log(chalk.green(`Wrote ${artifacts.paths.prCommentReportPath}`));
+            // Optional LOCAL-ONLY labels: tag this run for the multi-session aggregate. Written
+            // to run-labels.json in the run directory; never uploaded, carries no trace content.
+            const suppliedLabels = {
+                project: options.project,
+                workflow: options.workflow,
+                provider: options.provider,
+                user_label: options.userLabel,
+                session: options.session
+            };
+            if (hasAnyLabel(suppliedLabels)) {
+                const labelsPath = await writeJsonArtifact(options.out, "run-labels.json", buildRunLabelsFile(suppliedLabels));
+                console.log(chalk.green(`Wrote ${labelsPath} (local-only labels; never uploaded)`));
+            }
+            // Exact next command to continue the loop (chaining), with the trace path the user passed.
+            console.log("");
+            console.log(chalk.bold("Next: review the compaction and emit an approved context (review-only by default):"));
+            console.log(`  compaction apply-context ${traceFile} --out <dir>`);
+            console.log("  (add --approve-in-workflow-use once you have reviewed the safety report to emit the approved context)");
+            // --eval: run the deterministic recoverability eval on the SAME in-memory compaction result
+            // (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) {
+                const evalResult = evaluateCompactionResult(trace, policyResult, runId);
+                printCombinedEvalSummary(evalResult);
+                // Strong eval (Tracks B/C/D): commitment-preservation recoverability + fixture task-check +
+                // token/cost accounting + the composed strong apply-readiness gate. Fails closed: recoverability
+                // `failed` OR strong readiness `not_ready` exits non-zero.
+                // Thread the SAME --reviewer/--review-summary evidence the persisted safety-report
+                // artifacts already received (above) into the strong-eval recompute, so a real_captured
+                // trace WITH valid recoverability + commitment + task-check + reviewer + summary can
+                // legitimately reach `ready`. Fail-closed: missing/invalid review evidence still caps at
+                // `conditional` (the safety-report apply-readiness gate is unchanged).
+                const strong = evaluateStrongCompactionResult({
+                    originalTrace: trace,
+                    policyResult,
+                    runId,
+                    reviewerType,
+                    reviewSummaryPresent
+                });
+                printStrongEvalSummary(strong);
+                const strongJsonPath = await writeJsonArtifact(options.out, "strong-eval.json", strong);
+                const strongMarkdownPath = await writeTextArtifact(options.out, "strong-eval.md", formatStrongEvalMarkdownReport(strong));
+                console.log(chalk.green(`Wrote ${strongJsonPath}`));
+                console.log(chalk.green(`Wrote ${strongMarkdownPath}`));
+                if (evalResult.recoverability === "failed" || strong.readiness.readiness === "not_ready") {
+                    process.exitCode = 1;
+                }
+            }
+        });
+    });
+}
+//# sourceMappingURL=compact.js.map

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

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