@compaction/cli 0.2.0 → 0.3.0

package/dist/core/codex-capture.d.ts

@@ -0,0 +1,45 @@
+import { type UsageMetadata } from "./usage-metadata.js";
+import type { AgentTrace } from "./types.js";
+import { type LocalCommandRun } from "./command-runner.js";
+/**
+ * Placeholder used when the captured event stream carried NO model field — an honest unknown
+ * marker, never a real model id. Exported so downstream writers (e.g. the cross-surface event on
+ * the local run record) can map it to their canonical "unknown" instead of presenting a
+ * placeholder as if it were a reported model.
+ */
+export declare const CODEX_UNKNOWN_MODEL = "codex-unknown-model";
+interface ParsedEvent {
+    value: Record<string, unknown>;
+    lineNumber: number;
+}
+/** Parse a `codex exec --json` JSONL stream into event records (one object per line). */
+export declare function parseCodexEvents(rawOutput: string): ParsedEvent[];
+export interface CodexNormalizationResult {
+    trace: AgentTrace;
+    usageMetadata: UsageMetadata;
+    eventsCaptured: number;
+    messagesCaptured: number;
+    toolOutputsCaptured: number;
+    /** "present" when a turn.completed.usage block was found, else "missing" (never invented). */
+    tokenMetadataStatus: "present" | "missing";
+    warnings: string[];
+}
+/** Build an `AgentTrace` + provider-reported usage from a captured `codex exec --json` stream. */
+export declare function normalizeCodexExecEvents(params: {
+    captureId: string;
+    rawOutput: string;
+    commandRun?: LocalCommandRun;
+    generatedAt?: string;
+}): CodexNormalizationResult;
+export interface CodexCaptureResult extends CodexNormalizationResult {
+    commandRun?: LocalCommandRun;
+}
+/**
+ * Live wrapper: spawn `codex exec --json …` (no manual export), capture its stdout, normalize.
+ * The command parts are the FULL command (e.g. ["codex","exec","--json","do the thing"]). No engine,
+ * no upload. A non-zero Codex exit is preserved on the trace; capture still returns what was produced.
+ */
+export declare function captureCodexCommand(commandParts: string[], generatedAt?: string): Promise<CodexCaptureResult>;
+/** Offline/fallback: normalize a previously-saved `codex exec --json` JSONL export file's contents. */
+export declare function captureCodexExport(rawOutput: string, generatedAt?: string): CodexCaptureResult;
+export {};

package/dist/core/codex-capture.js

@@ -0,0 +1,204 @@
+/**
+ * Codex live-wrapper capture (PUBLIC CLI/SDK code — engine-free, ships in the npm package).
+ *
+ * Wraps a real `codex exec --json` run (near-live, no manual export) and normalizes its JSONL event
+ * stream to an `AgentTrace`. Design: `docs/design/codex-live-wrapper.md` (accepted 2026-06-28).
+ *
+ * Token honesty: `codex exec --json` emits a `turn.completed` event carrying a provider `usage` block
+ * ({input_tokens, cached_input_tokens, output_tokens, reasoning_output_tokens}). When present, those are
+ * recorded as **provider-reported** (NOT estimates). When absent, usage is left missing — never invented.
+ *
+ * Content-free posture: this reads the captured stdout to build the trace LOCALLY; only counts +
+ * estimate/provider labels flow into any downstream record. The captured stream may contain code/output,
+ * so the produced artifact carries the same "review before sharing" caution as other captures.
+ *
+ * Evidence tier: a wrapped command is `source: "local_command"` — the same `imported_local` tier as the
+ * import path (below `real_captured`); the hosted record attributes `tool: "codex"` / `provider: "openai"`.
+ */
+import { CURRENT_AGENT_TRACE_ARTIFACT_VERSION } from "./trace-parser.js";
+import { createUsageMetadata, missingUsageMetadata } from "./usage-metadata.js";
+import { executeLocalCommand, parseRunCommand } from "./command-runner.js";
+const CODEX_PROVIDER = "openai";
+/**
+ * Placeholder used when the captured event stream carried NO model field — an honest unknown
+ * marker, never a real model id. Exported so downstream writers (e.g. the cross-surface event on
+ * the local run record) can map it to their canonical "unknown" instead of presenting a
+ * placeholder as if it were a reported model.
+ */
+export const CODEX_UNKNOWN_MODEL = "codex-unknown-model";
+/* ---------------- small local helpers (no engine import) ---------------- */
+function toRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value) ? value : null;
+}
+function stringValue(value) {
+    return typeof value === "string" && value.trim() !== "" ? value : undefined;
+}
+function numericValue(value) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : undefined;
+}
+/** Parse a `codex exec --json` JSONL stream into event records (one object per line). */
+export function parseCodexEvents(rawOutput) {
+    return rawOutput
+        .split(/\r?\n/)
+        .map((line, index) => ({ line: line.trim(), lineNumber: index + 1 }))
+        .filter(({ line }) => line.startsWith("{") && line.endsWith("}"))
+        .flatMap(({ line, lineNumber }) => {
+        try {
+            const record = toRecord(JSON.parse(line));
+            return record ? [{ value: record, lineNumber }] : [];
+        }
+        catch {
+            return [];
+        }
+    });
+}
+function addMessage(messages, role, content, timestamp, metadata, name) {
+    messages.push({
+        id: `codex_msg_${messages.length + 1}`,
+        role,
+        content,
+        timestamp,
+        ...(name ? { toolName: name } : {}),
+        metadata
+    });
+}
+/** Build an `AgentTrace` + provider-reported usage from a captured `codex exec --json` stream. */
+export function normalizeCodexExecEvents(params) {
+    const generatedAt = params.generatedAt ?? new Date().toISOString();
+    const startedAt = params.commandRun?.startedAt ?? generatedAt;
+    const events = parseCodexEvents(params.rawOutput);
+    const warnings = [];
+    const messages = [];
+    let toolOutputsCaptured = 0;
+    let threadId;
+    let model;
+    addMessage(messages, "system", "Codex exec capture (live command wrapper).", startedAt, {
+        integration: "codex",
+        captureMode: "command wrapper"
+    });
+    // Provider-reported usage is summed across turn.completed events; never invented.
+    let inputTokens = 0;
+    let outputTokens = 0;
+    let cachedInputTokens = 0;
+    let reasoningOutputTokens = 0;
+    let sawUsage = false;
+    for (const { value, lineNumber } of events) {
+        const type = stringValue(value.type) ?? "event";
+        threadId = threadId ?? stringValue(value.thread_id);
+        model = model ?? stringValue(value.model) ?? stringValue(toRecord(value.item)?.model);
+        if (type === "item.completed" || type === "item.started") {
+            const item = toRecord(value.item);
+            if (!item)
+                continue;
+            const itemType = stringValue(item.type);
+            const ts = stringValue(value.timestamp) ?? startedAt;
+            if (itemType === "agent_message" && type === "item.completed") {
+                // Primary key is the vendor field (`text`); `content` is a fallback so the committed
+                // SYNTHETIC demo fixture (src/examples/codex-exec-demo.jsonl) is consumable too. Real
+                // `codex exec --json` exports carry `text`, so the fallback never changes their parsing.
+                const text = stringValue(item.text) ?? stringValue(item.content);
+                if (text)
+                    addMessage(messages, "assistant", text, ts, { sourceLine: lineNumber, eventType: itemType });
+            }
+            else if (itemType === "command_execution") {
+                const command = stringValue(item.command);
+                if (command && type === "item.started") {
+                    addMessage(messages, "assistant", `Tool call: ${command}`, ts, { sourceLine: lineNumber, eventType: "tool_call" });
+                }
+                // `aggregated_output` is the vendor field; `stdout` is a fixture-compat fallback (same
+                // rationale as above — never consulted when the vendor field is present).
+                const output = stringValue(item.aggregated_output) ?? stringValue(item.output) ?? stringValue(item.stdout);
+                if (output && type === "item.completed") {
+                    addMessage(messages, "tool", output, ts, { sourceLine: lineNumber, eventType: "tool_output" }, command ?? "codex.command");
+                    toolOutputsCaptured += 1;
+                }
+            }
+        }
+        else if (type === "turn.completed") {
+            const usage = toRecord(value.usage);
+            if (usage) {
+                const i = numericValue(usage.input_tokens);
+                const o = numericValue(usage.output_tokens);
+                const c = numericValue(usage.cached_input_tokens);
+                const r = numericValue(usage.reasoning_output_tokens);
+                if (i !== undefined || o !== undefined)
+                    sawUsage = true;
+                inputTokens += i ?? 0;
+                outputTokens += o ?? 0;
+                cachedInputTokens += c ?? 0;
+                reasoningOutputTokens += r ?? 0;
+            }
+        }
+    }
+    if (events.length === 0)
+        warnings.push("No codex exec --json events were found in the captured output.");
+    if (!sawUsage)
+        warnings.push("No turn.completed.usage block was found; provider token usage is missing and was not invented.");
+    const resolvedModel = model ?? CODEX_UNKNOWN_MODEL;
+    const usageMetadata = sawUsage
+        ? createUsageMetadata({
+            inputTokens,
+            outputTokens,
+            // reasoning tokens are part of the output charge; surface in total, not double-counted as output.
+            totalTokens: inputTokens + outputTokens + reasoningOutputTokens,
+            cacheReadInputTokens: cachedInputTokens,
+            providerReportedTokens: true,
+            estimatedTokens: false,
+            model: resolvedModel,
+            provider: CODEX_PROVIDER,
+            limitations: [
+                "Provider-reported token usage from codex exec --json turn.completed.usage — NOT billing-confirmed.",
+                ...(reasoningOutputTokens > 0 ? ["Reasoning output tokens are included in the total; they are part of the output charge."] : [])
+            ]
+        })
+        : missingUsageMetadata({
+            model: resolvedModel,
+            provider: CODEX_PROVIDER,
+            limitations: ["Captured codex exec events carried no usage block; token usage is missing and was not invented."]
+        });
+    const trace = {
+        id: threadId ?? `trace_codex_${params.captureId}`,
+        title: "Codex exec captured trace",
+        artifactVersion: CURRENT_AGENT_TRACE_ARTIFACT_VERSION,
+        source: "local_command",
+        createdAt: startedAt,
+        generatedAt,
+        model: resolvedModel,
+        command: params.commandRun
+            ? { command: params.commandRun.command.executable, args: params.commandRun.command.args, cwd: process.cwd() }
+            : { command: "codex-export", args: [], cwd: process.cwd() },
+        durationMs: params.commandRun?.durationMs ?? 0,
+        exitCode: params.commandRun?.exitCode ?? 0,
+        messages
+    };
+    return {
+        trace,
+        usageMetadata,
+        eventsCaptured: events.length,
+        messagesCaptured: messages.filter((m) => ["system", "user", "assistant"].includes(m.role)).length,
+        toolOutputsCaptured,
+        tokenMetadataStatus: sawUsage ? "present" : "missing",
+        warnings
+    };
+}
+/**
+ * Live wrapper: spawn `codex exec --json …` (no manual export), capture its stdout, normalize.
+ * The command parts are the FULL command (e.g. ["codex","exec","--json","do the thing"]). No engine,
+ * no upload. A non-zero Codex exit is preserved on the trace; capture still returns what was produced.
+ */
+export async function captureCodexCommand(commandParts, generatedAt) {
+    const parsed = parseRunCommand(commandParts);
+    const commandRun = await executeLocalCommand(parsed);
+    const result = normalizeCodexExecEvents({
+        captureId: `${parsed.executable}-${commandRun.startedAt}`,
+        rawOutput: commandRun.rawOutput,
+        commandRun,
+        generatedAt
+    });
+    return { ...result, commandRun };
+}
+/** Offline/fallback: normalize a previously-saved `codex exec --json` JSONL export file's contents. */
+export function captureCodexExport(rawOutput, generatedAt) {
+    return normalizeCodexExecEvents({ captureId: "codex-export", rawOutput, generatedAt });
+}
+//# sourceMappingURL=codex-capture.js.map

package/dist/core/command-runner.js

@@ -22,7 +22,11 @@ export async function executeLocalCommand(command, runId = createRunId()) {
     return new Promise((resolve) => {
         const child = spawn(command.executable, command.args, {
             shell: false,
-            windowsHide: true
+            windowsHide: true,
+            // Capture is non-interactive: give the child a closed (/dev/null) stdin so tools that probe stdin
+            // (e.g. `codex exec`, which otherwise blocks "Reading additional input from stdin...") see EOF and
+            // proceed with the prompt argument. stdout/stderr stay piped so we can read the event stream.
+            stdio: ["ignore", "pipe", "pipe"]
         });
         const pid = child.pid ?? null;
         let spawnError;

package/dist/core/compaction-artifacts.d.ts

@@ -0,0 +1,51 @@
+import { type PolicyMiddlewareResult } from "./policy-middleware.js";
+import type { AgentTrace, CompactionPolicy, CompactionReport, StateCapsule } from "./types.js";
+export declare const COMPACTION_ARTIFACT_NAMES: readonly ["report.json", "report.md", "policy.json", "state-capsule.json", "compacted-trace.json", "safety-report.json", "safety-report.md", "pr-comment.md"];
+export interface CompactionArtifactPaths {
+    reportPath: string;
+    markdownReportPath: string;
+    policyPath: string;
+    capsulePath: string;
+    compactedTracePath: string;
+    safetyReportPath: string;
+    safetyMarkdownReportPath: string;
+    prCommentReportPath: string;
+}
+/**
+ * Concise applied-result summary for the approval-gated skill-injection rung. Present on every
+ * result; `applied` is false (counts 0) unless `approveSkillInjectionPolicy` enabled the rung AND
+ * it compacted ≥1 byte-identical same-skill injection. Estimated tokens are the chars/4 heuristic
+ * (NOT billing-confirmed, NOT realized savings). Near-identical (divergent ARGUMENTS) is excluded
+ * by construction in the core policy and never counted here.
+ */
+export interface SkillInjectionCompactionSummary {
+    applied: boolean;
+    compacted_count: number;
+    estimated_tokens_removed: number;
+    estimate_label: string;
+}
+export interface CompactionArtifactResult {
+    report: CompactionReport;
+    policy: CompactionPolicy;
+    capsule: StateCapsule;
+    compactedTrace: AgentTrace;
+    consoleReport: string;
+    safetyReport: import("./safety-report.js").SafetyReport;
+    skillInjectionCompaction: SkillInjectionCompactionSummary;
+    paths: CompactionArtifactPaths;
+}
+export interface CompactionArtifactOptions {
+    reviewerType?: import("./safety-report.js").ReviewerType;
+    reviewSummaryPresent?: boolean;
+    /**
+     * APPROVAL-GATED (design §4). When true, ALSO apply the approval-required
+     * `repeated_skill_injection_to_state_capsule` policy via `applyCompactionPolicy`'s existing
+     * `compactSkillInjections` input — compacting byte-identical same-skill later role:user skill
+     * injections into state capsules pointing at the first copy. DEFAULT (undefined/false): the
+     * compaction run compacts NO skill injections; only the tool-output policy runs. Passing the
+     * `--approve-skill-injection-policy` flag on `compact` IS the explicit operator approval gesture.
+     * This is NOT threaded into any unattended/auto-apply path.
+     */
+    approveSkillInjectionPolicy?: boolean;
+}
+export declare function writeCompactionArtifacts(trace: AgentTrace, outputDirectory: string, runId: string, providedPolicyResult?: PolicyMiddlewareResult, generatedAt?: string, options?: CompactionArtifactOptions): Promise<CompactionArtifactResult>;

package/dist/core/compaction-artifacts.js

@@ -0,0 +1,242 @@
+import { writeJsonArtifact, writeTextArtifact } from "./artifact-writer.js";
+import { createCompactionPolicy } from "./compactor.js";
+import { formatCompactionMarkdownReport, formatCompactionReport, formatPrCommentReport } from "./report-generator.js";
+import { applyCompactionPolicy } from "./policy-middleware.js";
+import { createSafetyReport, formatSafetyMarkdownReport } from "./safety-report.js";
+import { createStateCapsule } from "./state-capsule.js";
+import { buildSpendSummaryFromTrace, loadEngineOptimizationDeltaProvider } from "./spend-attribution.js";
+import { detectWaste, buildSkillInjectionAdvisory } from "./waste-detector.js";
+import { calculateSavings } from "./savings.js";
+import { calculateCost } from "./cost-calculator.js";
+export const COMPACTION_ARTIFACT_NAMES = [
+    "report.json",
+    "report.md",
+    "policy.json",
+    "state-capsule.json",
+    "compacted-trace.json",
+    "safety-report.json",
+    "safety-report.md",
+    "pr-comment.md"
+];
+function primaryFinding(findings) {
+    return findings.find((finding) => finding.category === "repeated_tool_output") ?? findings[0];
+}
+function countRepeatedOccurrences(findings, primarySource) {
+    if (!primarySource)
+        return 0;
+    // Count all duplicate findings that share this source, then add 1 for the preserved original.
+    const duplicateCount = findings.filter((f) => f.category === "repeated_tool_output" && f.messageIds[0] === primarySource).length;
+    return duplicateCount > 0 ? duplicateCount + 1 : 0;
+}
+/**
+ * Build the report-only skill-injection advisory for report.json. This is ADVISORY:
+ * it sits alongside the tool-output compaction summary and nothing here is compacted.
+ * The cost figure is a price-table ESTIMATE of the addressable token volume, not a
+ * realized saving and not yet applied.
+ */
+function skillInjectionAdvisoryForReport(trace) {
+    const advisory = buildSkillInjectionAdvisory(trace);
+    const costEquivalent = Number(calculateCost(trace.model, {
+        inputTokens: advisory.total_addressable_estimated_tokens,
+        outputTokens: 0,
+        totalTokens: advisory.total_addressable_estimated_tokens
+    }).totalCostUsd.toFixed(6));
+    return {
+        report_only: true,
+        skills: advisory.skills,
+        total_redundant_byte_identical_copies: advisory.total_redundant_byte_identical_copies,
+        total_addressable_estimated_tokens: advisory.total_addressable_estimated_tokens,
+        estimated_cost_equivalent_usd: costEquivalent,
+        first_copy_count: advisory.first_copy_count,
+        estimate_label: advisory.estimate_label,
+        recommendation: advisory.recommendation
+    };
+}
+/**
+ * Classify the already-computed token/cost deltas against the four ROADMAP
+ * "MVP value path" value-proof claims (strongest last, never conflated). This
+ * adds NO new numbers and makes NO new or stronger savings claim — it only labels
+ * the existing tokens_saved / cost deltas with their honest tier and states plainly
+ * that billing-confirmed (tier 3) is NOT claimed and fixed-plan workflow-extension
+ * value (tier 4) is NOT quantified here.
+ */
+function buildValueProof(tokensSaved, percentReduction, savingPerRun) {
+    return {
+        trace_token_reduction: {
+            claim: "trace-token reduction (estimated, local heuristic)",
+            tier: 1,
+            estimated: true,
+            tokens_saved: tokensSaved,
+            percent_reduction: percentReduction
+        },
+        estimated_provider_cost_reduction: {
+            claim: "estimated provider cost reduction (price-table estimate, NOT billing-confirmed)",
+            tier: 2,
+            estimated: true,
+            billing_confirmed: false,
+            saving_per_run_usd: savingPerRun
+        },
+        billing_confirmed_savings: {
+            claim: "billing-confirmed savings (measured provider usage/billing delta)",
+            tier: 3,
+            claimed: false,
+            billing_confirmed: false,
+            note: "NOT claimed: no provider usage/billing delta is measured by this artifact."
+        },
+        fixed_plan_workflow_extension_value: {
+            claim: "fixed-plan workflow-extension value",
+            tier: 4,
+            quantified: false,
+            note: "NOT quantified here: this artifact does not measure additional work completed under a fixed-price cap."
+        }
+    };
+}
+/**
+ * Build the concise "where spend came from" summary for report.json by REUSING the
+ * spend-attribution computation (the SpendSummary already produced by buildSpendSummaryFromTrace).
+ * This selects top buckets only; it does not recompute attribution. All figures are local
+ * estimates (chars/4 trace tokens / price-table cost), NOT billing-confirmed and NOT realized savings.
+ */
+function buildSpendBySource(spend) {
+    return {
+        estimated: true,
+        billing_confirmed: false,
+        estimate_label: "ESTIMATED: chars/4 trace-token heuristic and price-table cost — NOT billing-confirmed, NOT realized savings.",
+        top_roles: spend.spend_by_role.slice(0, 3).map((bucket) => ({
+            name: bucket.name,
+            estimated_tokens: bucket.total_tokens,
+            estimated_cost_usd: bucket.estimated_cost
+        })),
+        top_tool_outputs: spend.spend_by_tool_output.slice(0, 3).map((bucket) => ({
+            tool_name: bucket.tool_name,
+            estimated_tokens: bucket.total_tokens,
+            repeated_count: bucket.repeated_count,
+            estimated_cost_usd: bucket.estimated_cost
+        })),
+        top_policy_candidate: spend.top_policy_candidate
+            ? {
+                policy_name: spend.top_policy_candidate.policy_name,
+                estimated_tokens_saved: spend.top_policy_candidate.estimated_tokens_saved,
+                estimated_saving_per_run_usd: spend.top_policy_candidate.estimated_saving_per_run
+            }
+            : null
+    };
+}
+function reportFromPolicyResult(trace, runId, generatedAt, policyResult, findings) {
+    const savings = calculateSavings({
+        scope: "policy_level",
+        beforeTokens: policyResult.tokenEstimateBefore,
+        afterTokens: policyResult.tokenEstimateAfter,
+        beforeCost: policyResult.costEstimateBefore,
+        afterCost: policyResult.costEstimateAfter
+    });
+    const finding = primaryFinding(findings);
+    const primarySource = finding?.messageIds[0] ?? policyResult.stateCapsules[0]?.sourcePointer.messageId;
+    return {
+        run_id: runId,
+        trace_title: trace.title,
+        model: trace.model,
+        original_input_tokens: savings.input_tokens_before,
+        compacted_input_tokens: savings.input_tokens_after,
+        tokens_saved: savings.tokens_saved,
+        percent_reduction: savings.percent_reduction,
+        savings_scope: savings.savings_scope,
+        cost_before_per_run: savings.estimated_cost_before,
+        cost_after_per_run: savings.estimated_cost_after,
+        saving_per_run: savings.estimated_saving_per_run,
+        policy_name: policyResult.appliedPolicyName,
+        waste_pattern: finding?.category ?? null,
+        source_message_id: primarySource ?? null,
+        repeated_count: countRepeatedOccurrences(findings, primarySource),
+        compacted_message_ids: policyResult.compactedMessageIds,
+        artifact_version: "trace-compactor-v0",
+        created_at: trace.createdAt,
+        generated_at: generatedAt,
+        // Populated from SafetyReport after it is generated; see writeCompactionArtifacts.
+        approval_readiness_status: "conditional",
+        approval_readiness_reason: "",
+        // Value-proof tier classification of the deltas above; classifies existing
+        // numbers only, no new/stronger claim. See ValueProof.
+        value_proof: buildValueProof(savings.tokens_saved, savings.percent_reduction, savings.estimated_saving_per_run),
+        // Report-only advisory; nothing here is compacted. See SkillInjectionAdvisorySummary.
+        skill_injection_advisory: skillInjectionAdvisoryForReport(trace)
+    };
+}
+/**
+ * Summarize the applied skill-injection compaction from the policy result for operator-facing
+ * surfacing. Counts the skill-injection capsules and sums their estimated original token counts
+ * (chars/4 heuristic). When the rung was not enabled there are no such capsules, so this returns
+ * a zero/not-applied summary and default output is unchanged.
+ */
+function summarizeSkillInjectionCompaction(policyResult) {
+    const capsules = policyResult.skillInjectionCapsules;
+    const estimatedTokensRemoved = capsules.reduce((total, capsule) => total + capsule.originalPayloadTokenCount, 0);
+    return {
+        applied: capsules.length > 0,
+        compacted_count: capsules.length,
+        estimated_tokens_removed: estimatedTokensRemoved,
+        estimate_label: "ESTIMATED: chars/4 trace-token heuristic — NOT billing-confirmed, NOT realized savings."
+    };
+}
+export async function writeCompactionArtifacts(trace, outputDirectory, runId, providedPolicyResult, generatedAt = new Date().toISOString(), options = {}) {
+    const findings = detectWaste(trace);
+    const policyResult = providedPolicyResult ??
+        applyCompactionPolicy({ trace, compactSkillInjections: options.approveSkillInjectionPolicy === true });
+    const report = reportFromPolicyResult(trace, runId, generatedAt, policyResult, findings);
+    // Surface "where spend came from" by reusing the spend-attribution computation.
+    // Additive and optional; estimates only (chars/4 / price-table), not billing-confirmed.
+    // The engine optimization-delta provider is loaded lazily via spend-attribution (present in the
+    // in-repo/API build, absent in the public package) — pass it so the top policy candidate is
+    // populated exactly as before, degrading cleanly when the engine provider is unavailable.
+    const spendSummary = await buildSpendSummaryFromTrace(trace, generatedAt, null, (await loadEngineOptimizationDeltaProvider()) ?? undefined);
+    report.spend_by_source = buildSpendBySource(spendSummary);
+    const policy = createCompactionPolicy(report);
+    const capsule = createStateCapsule(trace, findings, policyResult.stateCapsules);
+    const compactedTrace = policyResult.compactedTrace ?? trace;
+    const safetyReport = createSafetyReport({
+        runId,
+        generatedAt: report.generated_at,
+        originalTrace: trace,
+        compactedMessages: policyResult.compactedMessages,
+        stateCapsules: policyResult.stateCapsules,
+        compactedMessageIds: policyResult.compactedMessageIds,
+        tokensSaved: policyResult.tokensSaved,
+        policyName: policyResult.appliedPolicyName,
+        reviewerType: options.reviewerType,
+        reviewSummaryPresent: options.reviewSummaryPresent
+    });
+    // Populate approval readiness from the generated SafetyReport.
+    report.approval_readiness_status = safetyReport.approval_readiness_status;
+    report.approval_readiness_reason = safetyReport.approval_readiness_reason;
+    const safetyMarkdownReport = formatSafetyMarkdownReport(safetyReport);
+    const markdownReport = formatCompactionMarkdownReport(report, policy);
+    const prCommentReport = formatPrCommentReport(report, policy, [...COMPACTION_ARTIFACT_NAMES]);
+    const reportPath = await writeJsonArtifact(outputDirectory, "report.json", report);
+    const markdownReportPath = await writeTextArtifact(outputDirectory, "report.md", markdownReport);
+    const policyPath = await writeJsonArtifact(outputDirectory, "policy.json", policy);
+    const capsulePath = await writeJsonArtifact(outputDirectory, "state-capsule.json", capsule);
+    const compactedTracePath = await writeJsonArtifact(outputDirectory, "compacted-trace.json", compactedTrace);
+    const safetyReportPath = await writeJsonArtifact(outputDirectory, "safety-report.json", safetyReport);
+    const safetyMarkdownReportPath = await writeTextArtifact(outputDirectory, "safety-report.md", safetyMarkdownReport);
+    const prCommentReportPath = await writeTextArtifact(outputDirectory, "pr-comment.md", prCommentReport);
+    return {
+        report,
+        policy,
+        capsule,
+        compactedTrace,
+        consoleReport: formatCompactionReport(report),
+        safetyReport,
+        skillInjectionCompaction: summarizeSkillInjectionCompaction(policyResult),
+        paths: {
+            reportPath,
+            markdownReportPath,
+            policyPath,
+            capsulePath,
+            compactedTracePath,
+            safetyReportPath,
+            safetyMarkdownReportPath,
+            prCommentReportPath
+        }
+    };
+}
+//# sourceMappingURL=compaction-artifacts.js.map

package/dist/core/compactor.d.ts

@@ -0,0 +1,9 @@
+import type { AgentTrace, CompactionPolicy, CompactionReport } from "./types.js";
+interface CompactTraceOptions {
+    generatedAt?: string;
+    runId?: string;
+}
+export declare function createCompactedTrace(trace: AgentTrace): AgentTrace;
+export declare function compactTrace(trace: AgentTrace, options?: CompactTraceOptions): CompactionReport;
+export declare function createCompactionPolicy(report: CompactionReport): CompactionPolicy;
+export {};

package/dist/core/compactor.js

@@ -0,0 +1,95 @@
+import { calculateCost } from "./cost-calculator.js";
+import { estimateTraceTokens } from "./token-estimator.js";
+import { detectWaste, getCompactedMessageIds } from "./waste-detector.js";
+const ARTIFACT_VERSION = "trace-compactor-v0";
+const POLICY_NAME = "stale_tool_output_to_state_capsule";
+const POLICY_VERSION = "0.1.0";
+function roundCurrency(value) {
+    return Number(value.toFixed(6));
+}
+function roundPercent(value) {
+    return Number(value.toFixed(2));
+}
+function createCompactedTraceFromIds(trace, compactedMessageIds) {
+    return {
+        ...trace,
+        id: `${trace.id}_compacted`,
+        title: `${trace.title} (compacted)`,
+        messages: trace.messages.filter((message) => !compactedMessageIds.has(message.id))
+    };
+}
+function findPrimaryRepeatedOutputFinding(findings) {
+    // The repeated-output policy is authoritative for the headline waste_pattern when present. When
+    // only the ADDITIVE input-compaction category 1 (superseded same-source reads) fired, surface it
+    // so the report's `waste_pattern` honestly reflects what was compacted (both categories are
+    // compacted via getCompactedMessageIds).
+    return (findings.find((finding) => finding.category === "repeated_tool_output") ??
+        findings.find((finding) => finding.category === "superseded_same_source_read"));
+}
+export function createCompactedTrace(trace) {
+    const findings = detectWaste(trace);
+    return createCompactedTraceFromIds(trace, getCompactedMessageIds(findings));
+}
+function countRepeatedOccurrences(findings, primarySource) {
+    if (!primarySource)
+        return 0;
+    const duplicateCount = findings.filter((f) => f.category === "repeated_tool_output" && f.messageIds[0] === primarySource).length;
+    return duplicateCount > 0 ? duplicateCount + 1 : 0;
+}
+export function compactTrace(trace, options = {}) {
+    const findings = detectWaste(trace);
+    const compactedMessageIds = getCompactedMessageIds(findings);
+    const compactedTrace = createCompactedTraceFromIds(trace, compactedMessageIds);
+    const primaryFinding = findPrimaryRepeatedOutputFinding(findings);
+    const before = estimateTraceTokens(trace);
+    const after = estimateTraceTokens(compactedTrace);
+    const beforeCost = calculateCost(trace.model, before);
+    const afterCost = calculateCost(trace.model, after);
+    const tokensSaved = Math.max(0, before.inputTokens - after.inputTokens);
+    const savingPerRun = Math.max(0, beforeCost.totalCostUsd - afterCost.totalCostUsd);
+    return {
+        run_id: options.runId ?? trace.id,
+        trace_title: trace.title,
+        model: trace.model,
+        original_input_tokens: before.inputTokens,
+        compacted_input_tokens: after.inputTokens,
+        tokens_saved: tokensSaved,
+        percent_reduction: before.inputTokens === 0 ? 0 : roundPercent((tokensSaved / before.inputTokens) * 100),
+        savings_scope: "trace_level",
+        cost_before_per_run: roundCurrency(beforeCost.totalCostUsd),
+        cost_after_per_run: roundCurrency(afterCost.totalCostUsd),
+        saving_per_run: roundCurrency(savingPerRun),
+        policy_name: POLICY_NAME,
+        waste_pattern: primaryFinding?.category ?? null,
+        source_message_id: primaryFinding?.messageIds[0] ?? null,
+        repeated_count: countRepeatedOccurrences(findings, primaryFinding?.messageIds[0]),
+        compacted_message_ids: [...compactedMessageIds],
+        artifact_version: ARTIFACT_VERSION,
+        created_at: trace.createdAt,
+        generated_at: options.generatedAt ?? new Date().toISOString(),
+        approval_readiness_status: "not_ready",
+        approval_readiness_reason: "Approval readiness requires a SafetyReport. Run compact with writeCompactionArtifacts to generate safety evidence."
+    };
+}
+export function createCompactionPolicy(report) {
+    return {
+        policy_name: POLICY_NAME,
+        policy_version: POLICY_VERSION,
+        trigger: "Before sending a trace segment to a model, scan local tool outputs for exact repeated normalized content.",
+        condition: "A later tool message has the same tool name and normalized content as an earlier retained tool message.",
+        action: "Keep the first copy, remove later duplicate tool-output messages from the compacted trace, and preserve the retained facts in the state capsule.",
+        safety_guarantees: [
+            "Only duplicate tool outputs are removed by this v0 policy.",
+            "The earliest matching tool output remains in the compacted trace.",
+            "Assistant, user, and system messages are not removed by this policy.",
+            "A state capsule records retained facts, verification evidence, and safety notes."
+        ],
+        expected_savings: `${report.tokens_saved} input tokens per run; approximately $${report.saving_per_run.toFixed(6)} per run (estimated).`,
+        risk_notes: [
+            "Token and cost numbers are deterministic local estimates, not provider billing records.",
+            "The policy does not summarize near-duplicates or semantically similar outputs yet.",
+            "Review the compacted trace before applying the policy to higher-risk workflows."
+        ]
+    };
+}
+//# sourceMappingURL=compactor.js.map