@compaction/cli 0.1.0

package/dist/cli/commands/integrations.js

@@ -0,0 +1,29 @@
+import chalk from "chalk";
+import { runEngineCommand } from "../engine-degrade.js";
+export function registerIntegrationsCommand(program) {
+    const integrations = program.command("integrations").description("Run real local integration capture workflows.");
+    integrations
+        .command("run")
+        .description("Run a supported integration capture and feed it through optimize/spend/review evidence generation.")
+        .argument("<integration-id>", "Integration id to run, for example openai-agents")
+        .requiredOption("--out <dir>", "Output root directory for integration artifacts")
+        .argument("[commandParts...]", "Command and arguments to execute after --")
+        .allowUnknownOption(true)
+        .action(async (integrationId, commandParts, options) => {
+        await runEngineCommand(async () => {
+            // The integration workflow drives the proprietary optimize/review engine. Lazy-load the core
+            // integrations module (which statically imports the engine); when the engine build is excluded
+            // this dynamic import fails and runEngineCommand prints the boundary message and exits cleanly.
+            const { runIntegration } = await import("../../core/integrations.js");
+            console.log(chalk.cyan(`compaction integrations run ${integrationId}`));
+            console.log("Running a local integration capture. No scraping, hosted service, auth, billing workflow, model routing, provider switching, or auto mode is used.");
+            const artifacts = await runIntegration({ integrationId, outRoot: options.out, commandParts });
+            console.log(artifacts.terminalSummary);
+            console.log(chalk.green(`Wrote ${artifacts.paths.normalizedTracePath}`));
+            console.log(chalk.green(`Wrote ${artifacts.paths.reportJsonPath}`));
+            console.log(chalk.green(`Wrote ${artifacts.paths.reportMarkdownPath}`));
+            console.log(chalk.green(`Evidence directory: ${artifacts.outputDirectory}`));
+        });
+    });
+}
+//# sourceMappingURL=integrations.js.map

package/dist/cli/commands/launch-treatment-session.d.ts

@@ -0,0 +1,14 @@
+import { Command } from "commander";
+/**
+ * `compaction launch-treatment-session --apply-dir <dir> [--out <script>] [--seed <file>] [--project-dir <dir>]`
+ *
+ * Prepares (WRITES) an executable launch script for a FRESH seeded Claude Code session — the Lane B
+ * treatment arm. It NEVER starts the session itself and NEVER spawns `claude`; YOU run the script.
+ *
+ * Reuses the EXACT approval gates of `export-session-seed` (valid `approved_for_in_workflow_use` record,
+ * approved-context present + hash-matched, retained original present + hash-matched). Refuses otherwise —
+ * no script written, exit non-zero. If `session-seed.md` is absent it is generated by REUSING
+ * `exportSessionSeed`; if present it is reused unchanged. Read-only over apply artifacts except for the
+ * new script (and the seed only when generated). No provider call, no network, no global config changes.
+ */
+export declare function registerLaunchTreatmentSessionCommand(program: Command): void;

package/dist/cli/commands/launch-treatment-session.js

@@ -0,0 +1,50 @@
+import chalk from "chalk";
+import { runEngineCommand } from "../engine-degrade.js";
+/**
+ * `compaction launch-treatment-session --apply-dir <dir> [--out <script>] [--seed <file>] [--project-dir <dir>]`
+ *
+ * Prepares (WRITES) an executable launch script for a FRESH seeded Claude Code session — the Lane B
+ * treatment arm. It NEVER starts the session itself and NEVER spawns `claude`; YOU run the script.
+ *
+ * Reuses the EXACT approval gates of `export-session-seed` (valid `approved_for_in_workflow_use` record,
+ * approved-context present + hash-matched, retained original present + hash-matched). Refuses otherwise —
+ * no script written, exit non-zero. If `session-seed.md` is absent it is generated by REUSING
+ * `exportSessionSeed`; if present it is reused unchanged. Read-only over apply artifacts except for the
+ * new script (and the seed only when generated). No provider call, no network, no global config changes.
+ */
+export function registerLaunchTreatmentSessionCommand(program) {
+    program
+        .command("launch-treatment-session")
+        .description("Prepare (WRITE, never run) an executable launch script for a FRESH seeded Claude Code session — Lane B treatment arm (TREATMENT SETUP, NOT billing-confirmed savings; operator-invoked, NOT auto-apply). Refuses unless approved + hashes match. Never spawns claude; never touches global config.")
+        .requiredOption("--apply-dir <dir>", "The apply-context artifacts directory (must contain an approval record)")
+        .option("--out <script>", "Where to write the launch script (default: <apply-dir>/launch-treatment-session.sh)")
+        .option("--seed <file>", "Path to the session seed to read/generate (default: <apply-dir>/session-seed.md)")
+        .option("--project-dir <dir>", "Project directory the launched session runs in (default: current directory)")
+        .action(async (options) => {
+        await runEngineCommand(async () => {
+            // The treatment-session launcher is internal methodology (engine). Lazy-load it; degrades
+            // honestly when the engine build is excluded from the package.
+            const { prepareTreatmentSessionLauncher } = await import("../../engine/treatment-session-launcher.js");
+            console.log(chalk.cyan("compaction launch-treatment-session (Lane B treatment setup)"));
+            console.log("Operator-invoked, NOT auto-apply. This command only WRITES a launch script; it starts no session and spawns no process. No provider call, no network.");
+            const result = await prepareTreatmentSessionLauncher({
+                applyDir: options.applyDir,
+                outScript: options.out,
+                seedFile: options.seed,
+                projectDir: options.projectDir
+            });
+            if (result.refused) {
+                console.error(chalk.red("Refused — no launch script written:"));
+                for (const reason of result.reasons) {
+                    console.error(chalk.red(`- ${reason}`));
+                }
+                process.exitCode = 1;
+                return;
+            }
+            console.log(result.consoleSummary);
+            console.log(chalk.green(`Wrote ${result.scriptPath}`));
+            console.log(chalk.yellow(`Run it yourself when ready: bash ${result.scriptPath}`));
+        });
+    });
+}
+//# sourceMappingURL=launch-treatment-session.js.map

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

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

package/dist/cli/commands/optimize.js

@@ -0,0 +1,33 @@
+import chalk from "chalk";
+import { runEngineCommand } from "../engine-degrade.js";
+export function registerOptimizeCommand(program) {
+    const optimize = program.command("optimize").description("Run local trace optimization loops for supported integrations.");
+    optimize
+        .command("openai-agents")
+        .description("Capture and optimize a local OpenAI Agents SDK trace without applying changes.")
+        .requiredOption("--out <dir>", "Output root directory for optimization artifacts")
+        .argument("[commandParts...]", "Command and arguments to execute after --")
+        .allowUnknownOption(true)
+        .action(async (commandParts, 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 { optimizeOpenAIAgents } = await import("../../engine/openai-agents-optimization.js");
+            console.log(chalk.cyan("compaction optimize openai-agents"));
+            console.log("Running a local OpenAI Agents SDK optimization loop. No auto-apply, ChatGPT scraping, production proxying, or hosted upload is performed.");
+            const artifacts = await optimizeOpenAIAgents({ outRoot: options.out, commandParts });
+            if (artifacts.usedLocalFixture) {
+                console.log("Using local fixture because provider credentials are not configured.");
+            }
+            console.log(artifacts.terminalSummary);
+            console.log(chalk.green(`Wrote ${artifacts.paths.capturedTracePath}`));
+            console.log(chalk.green(`Wrote ${artifacts.paths.optimizationSummaryJsonPath}`));
+            console.log(chalk.green(`Wrote ${artifacts.paths.optimizationSummaryMarkdownPath}`));
+            console.log(chalk.green(`Evidence directory: ${artifacts.outputDirectory}`));
+            if (artifacts.summary.status === "fail") {
+                process.exitCode = 1;
+            }
+        });
+    });
+}
+//# sourceMappingURL=optimize.js.map

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

@@ -0,0 +1,4 @@
+import { Command } from "commander";
+import type { RecommendationReport } from "../../engine/recommendation.js";
+export declare function formatRecommendationConsoleSummary(recommendation: RecommendationReport, futureModesNotice: string): string;
+export declare function registerRecommendCommand(program: Command): void;

package/dist/cli/commands/recommend.js

@@ -0,0 +1,66 @@
+import chalk from "chalk";
+import { createSafetyReport } from "../../core/safety-report.js";
+import { parseTraceFile } from "../../core/trace-parser.js";
+import { detectWaste } from "../../core/waste-detector.js";
+import { runEngineCommand } from "../engine-degrade.js";
+function formatNullable(value) {
+    return value ?? "None";
+}
+export function formatRecommendationConsoleSummary(recommendation, futureModesNotice) {
+    return [
+        `Trace id: ${recommendation.trace_id}`,
+        `Recommended mode: ${recommendation.recommended_mode}`,
+        `Policy name: ${formatNullable(recommendation.policy_name)}`,
+        `Policy-level tokens saved: ${recommendation.tokens_saved} (${recommendation.percent_reduction}% reduction), $${recommendation.saving_per_run} per run.`,
+        `Safety status: ${recommendation.safety_status}`,
+        `Risk level: ${recommendation.risk_level}`,
+        `Required next step: ${recommendation.required_next_step}`,
+        "Future modes notice:",
+        futureModesNotice
+    ].join("\n");
+}
+export function registerRecommendCommand(program) {
+    program
+        .command("recommend")
+        .argument("<trace-file>", "Path to a local agent trace JSON file")
+        .description("Recommend an advisory local compaction mode and write recommendation artifacts.")
+        .action(async (traceFile) => {
+        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 { applyCompactionPolicy } = await import("../../engine/policy-middleware.js");
+            const { createRecommendation } = await import("../../engine/recommendation.js");
+            const { formatFutureModesNotice, writeRecommendationArtifacts } = await import("../../engine/recommendation-artifacts.js");
+            const trace = await parseTraceFile(traceFile);
+            const findings = detectWaste(trace);
+            const policyResult = applyCompactionPolicy({ trace });
+            const safetyReport = createSafetyReport({
+                runId: trace.id,
+                generatedAt: trace.generatedAt,
+                originalTrace: trace,
+                compactedMessages: policyResult.compactedMessages,
+                stateCapsules: policyResult.stateCapsules,
+                compactedMessageIds: policyResult.compactedMessageIds,
+                tokensSaved: policyResult.tokensSaved,
+                policyName: policyResult.appliedPolicyName
+            });
+            const recommendation = createRecommendation({
+                trace,
+                policyResult,
+                generatedAt: trace.generatedAt,
+                safetyReport,
+                findings
+            });
+            const artifacts = await writeRecommendationArtifacts(recommendation);
+            console.log(chalk.cyan("compaction recommend"));
+            console.log(formatRecommendationConsoleSummary(recommendation, formatFutureModesNotice()));
+            console.log(chalk.green(`Wrote ${artifacts.paths.recommendationJsonPath}`));
+            console.log(chalk.green(`Wrote ${artifacts.paths.recommendationMarkdownPath}`));
+            // Exact next command to continue the loop (chaining), with the trace path the user passed.
+            console.log("");
+            console.log(chalk.bold("Next: produce the before/after delta + named policy + safety report:"));
+            console.log(`  compaction compact ${traceFile} --out <dir>`);
+        });
+    });
+}
+//# sourceMappingURL=recommend.js.map

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

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

package/dist/cli/commands/review.js

@@ -0,0 +1,60 @@
+import readline from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+import chalk from "chalk";
+import { runEngineCommand } from "../engine-degrade.js";
+async function confirmApproval() {
+    const rl = readline.createInterface({ input, output });
+    try {
+        const answer = await rl.question("Approve this optimization? Type yes to approve: ");
+        return answer.trim().toLowerCase() === "yes";
+    }
+    finally {
+        rl.close();
+    }
+}
+export function registerReviewCommand(program) {
+    program
+        .command("review")
+        .description("Run a guided local optimization review with spend, safety, recommendation, and explicit approval decision.")
+        .argument("<optimization-or-spend-path>", "Path to an optimization summary, spend summary, recommendation, or approval-ready artifact")
+        .option("--require-safety-pass", "Refuse approval unless safety status is pass")
+        .option("--approve", "Request explicit local approval from the guided review")
+        .option("--yes", "Approve without an interactive confirmation prompt when all guardrails pass")
+        .action(async (sourcePath, options) => {
+        await runEngineCommand(async () => {
+            // Lazy-load the proprietary engine BEFORE any interactive prompt: present in-repo/API, excluded
+            // from the public package. When absent, runEngineCommand prints the boundary message and exits
+            // cleanly (no stack trace) without ever prompting for approval.
+            const { createOptimizationReview } = await import("../../engine/optimization-review.js");
+            console.log(chalk.cyan("compaction review"));
+            console.log("Guided local review only. No provider APIs, live provider mutation, production proxying, auto mode, model routing, hosted dashboard, auth, database, or billing workflow is used.");
+            const approvalRequested = Boolean(options.approve);
+            const approvalConfirmed = approvalRequested && (Boolean(options.yes) || (await confirmApproval()));
+            const artifacts = await createOptimizationReview({
+                sourceArtifactPath: sourcePath,
+                requireSafetyPass: Boolean(options.requireSafetyPass),
+                approvalRequested,
+                approvalConfirmed
+            });
+            console.log(artifacts.terminalSummary);
+            if (artifacts.paths.reviewSummaryJsonPath) {
+                console.log(chalk.green(`Wrote ${artifacts.paths.reviewSummaryJsonPath}`));
+            }
+            if (artifacts.paths.reviewSummaryMarkdownPath) {
+                console.log(chalk.green(`Wrote ${artifacts.paths.reviewSummaryMarkdownPath}`));
+            }
+            if (artifacts.approvalArtifacts) {
+                console.log(chalk.green(`Wrote ${artifacts.approvalArtifacts.paths.approvalReportJsonPath}`));
+                console.log(chalk.green(`Wrote ${artifacts.approvalArtifacts.paths.approvalReportMarkdownPath}`));
+                if (artifacts.approvalArtifacts.paths.approvedTracePath) {
+                    console.log(chalk.green(`Wrote ${artifacts.approvalArtifacts.paths.approvedTracePath}`));
+                }
+            }
+            console.log(chalk.green(`Evidence directory: ${artifacts.outputDirectory}`));
+            if (approvalRequested && artifacts.summary.approval_decision !== "approved") {
+                process.exitCode = 1;
+            }
+        });
+    });
+}
+//# sourceMappingURL=review.js.map

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

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

package/dist/cli/commands/run.js

@@ -0,0 +1,49 @@
+import chalk from "chalk";
+import { parseRunCommand, executeLocalCommand, persistLocalCommandRun } from "../../core/command-runner.js";
+import { writeJsonArtifact } from "../../core/artifact-writer.js";
+import { localCommandRunToAgentTrace } from "../../core/run-trace-converter.js";
+import { runEngineCommand } from "../engine-degrade.js";
+export function registerRunCommand(program) {
+    program
+        .command("run")
+        .description("Run a local command, capture output locally, convert it to a trace, and write compaction artifacts.")
+        .argument("[commandParts...]", "Command and arguments to execute after --")
+        .allowUnknownOption(true)
+        .action(async (commandParts) => {
+        await runEngineCommand(async () => {
+            // `run`'s value IS the compaction report it produces, which needs the proprietary engine.
+            // Lazy-load it FIRST so a public install degrades immediately — before spawning the child
+            // command — rather than running the command and then failing to compact.
+            const { writeCompactionArtifacts } = await import("../../engine/compaction-artifacts.js");
+            const command = parseRunCommand(commandParts);
+            console.log(chalk.cyan("compaction run"));
+            console.log("Running local command and capturing stdout/stderr locally. Child output is not printed by compaction.");
+            const run = await executeLocalCommand(command);
+            const persistedRun = await persistLocalCommandRun(run);
+            const trace = localCommandRunToAgentTrace(run);
+            const tracePath = await writeJsonArtifact(persistedRun.outputDirectory, "trace.json", trace);
+            const artifacts = await writeCompactionArtifacts(trace, persistedRun.outputDirectory, run.runId);
+            console.log(`Exit code: ${run.exitCode ?? "none"}`);
+            console.log(`Signal: ${run.signal ?? "none"}`);
+            console.log(`Duration: ${run.durationMs} ms`);
+            console.log(chalk.green(`Wrote ${persistedRun.stdoutPath}`));
+            console.log(chalk.green(`Wrote ${persistedRun.stderrPath}`));
+            console.log(chalk.green(`Wrote ${persistedRun.rawOutputPath}`));
+            console.log(chalk.green(`Wrote ${persistedRun.metadataPath}`));
+            console.log(chalk.green(`Wrote ${tracePath}`));
+            console.log(artifacts.consoleReport);
+            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}`));
+            if (run.exitCode !== 0 && run.exitCode !== null) {
+                process.exitCode = run.exitCode;
+            }
+        });
+    });
+}
+//# sourceMappingURL=run.js.map

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

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

package/dist/cli/commands/spend.js

@@ -0,0 +1,24 @@
+import chalk from "chalk";
+import { writeSpendArtifacts, loadEngineOptimizationDeltaProvider } from "../../core/spend-attribution.js";
+export function registerSpendCommand(program) {
+    program
+        .command("spend")
+        .description("Summarize local context spend attribution and optimization delta for a trace or optimization summary.")
+        .argument("<trace-or-optimization-path>", "Path to a local agent trace JSON or optimization-summary.json")
+        .option("--out <dir>", "Output root directory for spend artifacts", ".compaction/spend")
+        .action(async (inputPath, options) => {
+        // `spend` is a FREE command: local token/cost attribution + waste/skill-injection always work
+        // WITHOUT the engine. The engine optimization-delta provider is loaded only if a private engine
+        // build is present; in a public install it resolves to null and the optimization-delta section
+        // degrades honestly (no policy candidate, no synthetic saving). The command never crashes here.
+        console.log(chalk.cyan("compaction spend"));
+        console.log("Summarizing local context spend attribution. No provider APIs, billing lookup, auto mode, model routing, or hosted dashboard is used.");
+        const optimizationDeltaProvider = (await loadEngineOptimizationDeltaProvider()) ?? undefined;
+        const artifacts = await writeSpendArtifacts(inputPath, options.out, undefined, optimizationDeltaProvider);
+        console.log(artifacts.terminalSummary);
+        console.log(chalk.green(`Wrote ${artifacts.paths.spendSummaryJsonPath}`));
+        console.log(chalk.green(`Wrote ${artifacts.paths.spendSummaryMarkdownPath}`));
+        console.log(chalk.green(`Evidence directory: ${artifacts.outputDirectory}`));
+    });
+}
+//# sourceMappingURL=spend.js.map

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

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

package/dist/cli/commands/summary.js

@@ -0,0 +1,19 @@
+import chalk from "chalk";
+import { writeJsonArtifact, writeTextArtifact } from "../../core/artifact-writer.js";
+import { createRunSummary, formatRunSummary, formatRunSummaryMarkdown } from "../../core/run-aggregator.js";
+export function registerSummaryCommand(program) {
+    program
+        .command("summary")
+        .description("Summarize local compaction run reports across .compaction/runs/*/report.json.")
+        .action(async () => {
+        const summary = await createRunSummary();
+        const consoleSummary = formatRunSummary(summary);
+        const markdownSummary = formatRunSummaryMarkdown(summary);
+        const summaryJsonPath = await writeJsonArtifact(".compaction", "summary.json", summary);
+        const summaryMarkdownPath = await writeTextArtifact(".compaction", "summary.md", markdownSummary);
+        console.log(chalk.cyan(consoleSummary));
+        console.log(chalk.green(`Wrote ${summaryJsonPath}`));
+        console.log(chalk.green(`Wrote ${summaryMarkdownPath}`));
+    });
+}
+//# sourceMappingURL=summary.js.map

package/dist/cli/engine-degrade.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Open-core public/proprietary boundary (Phase 1c/1d).
+ *
+ * The proprietary optimization/eval engine lives in `src/engine/**` and is BUILT into
+ * `dist/engine/**` for the in-repo dev/test/API build, but is EXCLUDED from the published
+ * npm tarball (see `package.json` `files`). Shipped modules must therefore never STATICALLY
+ * `import` an engine module — doing so would (a) pull engine code into the published static
+ * graph and (b) crash a public install at module-load time.
+ *
+ * Engine-backed CLI commands instead LAZY-LOAD their engine module through a dynamic `import()`
+ * (which is NOT part of the static import graph). When the engine build is present (in-repo) the
+ * command runs normally. When it is ABSENT (public install) the dynamic import throws
+ * `ERR_MODULE_NOT_FOUND`; `runEngineCommand()` catches that, prints the single sanctioned
+ * boundary message, exits non-zero, and prints NO stack trace and NO engine output. Any OTHER
+ * error (a real bug inside a present engine) is re-thrown unchanged.
+ */
+/**
+ * The EXACT, single sanctioned degrade message. Product-critic reviewed (Phase 1c/1d):
+ * it names the boundary factually and immediately reaffirms what stays free. Do not fork
+ * per-command variants of this string.
+ */
+export declare const ENGINE_DEGRADE_MESSAGE: string;
+/**
+ * True when `error` is the Node "module not found" thrown by a dynamic `import()` of an
+ * engine module that was excluded from the published package (vs. a real runtime error
+ * raised from inside an engine module that IS present).
+ */
+export declare function isEngineAbsentError(error: unknown): boolean;
+/**
+ * Run an engine-backed command body. If the engine build is absent (public install), print
+ * the sanctioned boundary message to stderr, set a non-zero exit code, and return WITHOUT a
+ * stack trace. Any other error propagates unchanged so real bugs are never masked.
+ *
+ * Usage:
+ *   await runEngineCommand(async () => {
+ *     const { optimizeOpenAIAgents } = await import("../../engine/openai-agents-optimization.js");
+ *     // ...use it...
+ *   });
+ */
+export declare function runEngineCommand(body: () => Promise<void>): Promise<void>;

package/dist/cli/engine-degrade.js

@@ -0,0 +1,59 @@
+/**
+ * Open-core public/proprietary boundary (Phase 1c/1d).
+ *
+ * The proprietary optimization/eval engine lives in `src/engine/**` and is BUILT into
+ * `dist/engine/**` for the in-repo dev/test/API build, but is EXCLUDED from the published
+ * npm tarball (see `package.json` `files`). Shipped modules must therefore never STATICALLY
+ * `import` an engine module — doing so would (a) pull engine code into the published static
+ * graph and (b) crash a public install at module-load time.
+ *
+ * Engine-backed CLI commands instead LAZY-LOAD their engine module through a dynamic `import()`
+ * (which is NOT part of the static import graph). When the engine build is present (in-repo) the
+ * command runs normally. When it is ABSENT (public install) the dynamic import throws
+ * `ERR_MODULE_NOT_FOUND`; `runEngineCommand()` catches that, prints the single sanctioned
+ * boundary message, exits non-zero, and prints NO stack trace and NO engine output. Any OTHER
+ * error (a real bug inside a present engine) is re-thrown unchanged.
+ */
+/**
+ * The EXACT, single sanctioned degrade message. Product-critic reviewed (Phase 1c/1d):
+ * it names the boundary factually and immediately reaffirms what stays free. Do not fork
+ * per-command variants of this string.
+ */
+export const ENGINE_DEGRADE_MESSAGE = "Optimization and stronger evals require Compaction API or a private engine build. " +
+    "Local capture, measurement, reports, and redacted share bundles remain available.";
+/**
+ * True when `error` is the Node "module not found" thrown by a dynamic `import()` of an
+ * engine module that was excluded from the published package (vs. a real runtime error
+ * raised from inside an engine module that IS present).
+ */
+export function isEngineAbsentError(error) {
+    if (!error || typeof error !== "object")
+        return false;
+    const code = error.code;
+    return code === "ERR_MODULE_NOT_FOUND" || code === "MODULE_NOT_FOUND";
+}
+/**
+ * Run an engine-backed command body. If the engine build is absent (public install), print
+ * the sanctioned boundary message to stderr, set a non-zero exit code, and return WITHOUT a
+ * stack trace. Any other error propagates unchanged so real bugs are never masked.
+ *
+ * Usage:
+ *   await runEngineCommand(async () => {
+ *     const { optimizeOpenAIAgents } = await import("../../engine/openai-agents-optimization.js");
+ *     // ...use it...
+ *   });
+ */
+export async function runEngineCommand(body) {
+    try {
+        await body();
+    }
+    catch (error) {
+        if (isEngineAbsentError(error)) {
+            process.stderr.write(`${ENGINE_DEGRADE_MESSAGE}\n`);
+            process.exitCode = 1;
+            return;
+        }
+        throw error;
+    }
+}
+//# sourceMappingURL=engine-degrade.js.map

package/dist/cli/index.d.ts

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

package/dist/cli/index.js

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { registerAnalyzeCommand } from "./commands/analyze.js";
+import { registerAdapterCommand } from "./commands/adapter.js";
+import { registerAggregateCommand } from "./commands/aggregate.js";
+import { registerAuditCommand } from "./commands/audit.js";
+import { registerApplyCommand } from "./commands/apply.js";
+import { registerApplyContextCommand } from "./commands/apply-context.js";
+import { registerApproveCommand } from "./commands/approve.js";
+import { registerBillingDeltaCommand } from "./commands/billing-delta.js";
+import { registerInitCommand } from "./commands/init.js";
+import { registerCaptureCommand } from "./commands/capture.js";
+import { registerCompactCommand } from "./commands/compact.js";
+import { registerEvalCommand } from "./commands/eval.js";
+import { registerExportSessionSeedCommand } from "./commands/export-session-seed.js";
+import { registerFeedbackCommand } from "./commands/feedback.js";
+import { registerImportCommand } from "./commands/import.js";
+import { registerIntegrationsCommand } from "./commands/integrations.js";
+import { registerLaunchTreatmentSessionCommand } from "./commands/launch-treatment-session.js";
+import { registerOptimizeCommand } from "./commands/optimize.js";
+import { registerRecommendCommand } from "./commands/recommend.js";
+import { registerReviewCommand } from "./commands/review.js";
+import { registerRunCommand } from "./commands/run.js";
+import { registerSpendCommand } from "./commands/spend.js";
+import { registerSummaryCommand } from "./commands/summary.js";
+const program = new Command();
+program
+    .name("compaction")
+    .description("CLI-first trace compaction tools for AI agent workflows.")
+    .version("0.1.0");
+registerAnalyzeCommand(program);
+registerAdapterCommand(program);
+registerAggregateCommand(program);
+registerAuditCommand(program);
+registerApplyCommand(program);
+registerApplyContextCommand(program);
+registerApproveCommand(program);
+registerBillingDeltaCommand(program);
+registerInitCommand(program);
+registerCaptureCommand(program);
+registerCompactCommand(program);
+registerEvalCommand(program);
+registerExportSessionSeedCommand(program);
+registerFeedbackCommand(program);
+registerImportCommand(program);
+registerIntegrationsCommand(program);
+registerLaunchTreatmentSessionCommand(program);
+registerOptimizeCommand(program);
+registerRecommendCommand(program);
+registerReviewCommand(program);
+registerRunCommand(program);
+registerSpendCommand(program);
+registerSummaryCommand(program);
+program.parseAsync(process.argv).catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(message);
+    process.exitCode = 1;
+});
+//# sourceMappingURL=index.js.map

package/dist/core/adapter-validation.d.ts

@@ -0,0 +1,32 @@
+import { type TraceAdapterSource, type TraceAdapterStatus } from "./trace-adapters.js";
+import type { AgentTrace } from "./types.js";
+export type AdapterValidationSource = TraceAdapterSource;
+export type AdapterValidationStatus = TraceAdapterStatus;
+export interface AdapterValidationReport {
+    validation_id: string;
+    generated_at: string;
+    input_path: string;
+    source: AdapterValidationSource;
+    adapter_id: AdapterValidationSource;
+    status: AdapterValidationStatus;
+    output_trace_id: string | null;
+    message_count: number;
+    supported_format_detected: boolean;
+    warnings: string[];
+    failures: string[];
+    normalization_steps: string[];
+    skipped_fields: string[];
+    limitations: string[];
+    recommended_next_command: string | null;
+}
+export interface AdapterValidationArtifacts {
+    report: AdapterValidationReport;
+    normalizedTrace: AgentTrace | null;
+    paths: {
+        outputDirectory: string;
+        normalizedTracePath: string;
+        validationReportJsonPath: string;
+        validationReportMarkdownPath: string;
+    };
+}
+export declare function validateAdapterFixtureFile(inputPath: string, source: string, outputRoot?: string): Promise<AdapterValidationArtifacts>;