@compaction/cli 0.1.0

package/dist/core/standalone-capsule-provenance.js

@@ -0,0 +1,62 @@
+import { access, readFile } from "node:fs/promises";
+async function fileExists(filePath) {
+    try {
+        await access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function hasCompleteEntry(entry) {
+    return (typeof entry.source_trace_id === "string" &&
+        entry.source_trace_id.length > 0 &&
+        typeof entry.source_message_id === "string" &&
+        entry.source_message_id.length > 0 &&
+        typeof entry.source_pointer === "string" &&
+        entry.source_pointer.length > 0 &&
+        typeof entry.source_hash === "string" &&
+        entry.source_hash.length > 0 &&
+        entry.source_hash_algorithm === "sha256" &&
+        entry.source_recoverable === true &&
+        typeof entry.source_recovery_path === "string" &&
+        entry.source_recovery_path.length > 0);
+}
+export function statusFromStateCapsule(capsule) {
+    const entries = capsule.provenance_entries ?? [];
+    const topLevelComplete = hasCompleteEntry({
+        source_trace_id: capsule.source_trace_id,
+        source_message_id: capsule.source_message_id,
+        source_pointer: capsule.source_pointer,
+        source_hash: capsule.source_hash,
+        source_hash_algorithm: capsule.source_hash_algorithm,
+        source_recoverable: capsule.source_recoverable ?? "unknown",
+        source_recovery_path: capsule.source_recovery_path,
+        original_payload_token_count: capsule.original_payload_token_count,
+        capsule_token_count: capsule.capsule_token_count
+    });
+    if (topLevelComplete && entries.length > 0 && entries.every(hasCompleteEntry)) {
+        return "complete";
+    }
+    if (topLevelComplete || entries.length > 0 || capsule.source_recoverable === true || capsule.source_recoverable === "unknown") {
+        return "partial";
+    }
+    return "missing";
+}
+export async function readStandaloneCapsuleProvenanceStatus(capsulePath) {
+    if (!capsulePath)
+        return "missing";
+    if (!(await fileExists(capsulePath)))
+        return "missing";
+    try {
+        const capsule = JSON.parse(await readFile(capsulePath, "utf8"));
+        if (typeof capsule !== "object" || capsule === null || Array.isArray(capsule)) {
+            return "unknown";
+        }
+        return statusFromStateCapsule(capsule);
+    }
+    catch {
+        return "unknown";
+    }
+}
+//# sourceMappingURL=standalone-capsule-provenance.js.map

package/dist/core/state-capsule.d.ts

@@ -0,0 +1,3 @@
+import type { AgentTrace, StateCapsule, WasteFinding } from "./types.js";
+import type { PolicyMiddlewareStateCapsule } from "./policy-types.js";
+export declare function createStateCapsule(trace: AgentTrace, findings?: WasteFinding[], policyCapsules?: PolicyMiddlewareStateCapsule[]): StateCapsule;

package/dist/core/state-capsule.js

@@ -0,0 +1,147 @@
+import { createHash } from "node:crypto";
+import { estimateTextTokens } from "./token-estimator.js";
+function firstMessageByRole(trace, role) {
+    return trace.messages.find((message) => message.role === role);
+}
+function lastMessageByRole(trace, role) {
+    return [...trace.messages].reverse().find((message) => message.role === role);
+}
+function compactSentence(content) {
+    const normalized = content.trim().replace(/\s+/g, " ");
+    return normalized.length > 220 ? `${normalized.slice(0, 217)}...` : normalized;
+}
+function sourcePreview(content) {
+    const normalized = content.trim().replace(/\s+/g, " ");
+    return normalized.length > 160 ? `${normalized.slice(0, 157)}...` : normalized;
+}
+function contentHash(content) {
+    return createHash("sha256").update(content).digest("hex");
+}
+function findVerificationMessages(trace) {
+    return trace.messages.filter((message) => {
+        if (message.role !== "tool") {
+            return false;
+        }
+        const text = message.content.toLowerCase();
+        return message.toolName === "test" || text.includes(" passed") || text.includes(" failed") || text.includes("timeout");
+    });
+}
+function sourcePointerText(traceId, messageId, messageIndex, sourceHash) {
+    return `trace=${traceId} message=${messageId} index=${messageIndex} sha256=${sourceHash}`;
+}
+function provenanceFromFinding(trace, finding) {
+    const sourceMessageId = finding.messageIds[0];
+    const sourceIndex = trace.messages.findIndex((message) => message.id === sourceMessageId);
+    const sourceMessage = sourceIndex >= 0 ? trace.messages[sourceIndex] : undefined;
+    if (!sourceMessage) {
+        return {
+            source_trace_id: trace.id,
+            source_message_id: sourceMessageId,
+            source_pointer: `trace=${trace.id} message=${sourceMessageId}`,
+            source_recoverable: "unknown",
+            original_payload_token_count: finding.estimatedTokens
+        };
+    }
+    const hash = contentHash(sourceMessage.content);
+    return {
+        source_trace_id: trace.id,
+        source_message_id: sourceMessage.id,
+        source_pointer: sourcePointerText(trace.id, sourceMessage.id, sourceIndex, hash),
+        source_hash: hash,
+        source_hash_algorithm: "sha256",
+        source_excerpt_preview: sourcePreview(sourceMessage.content),
+        source_recoverable: true,
+        source_recovery_path: `messages[${sourceIndex}]`,
+        original_payload_token_count: estimateTextTokens(sourceMessage.content),
+        compacted_message_ids: finding.messageIds.slice(1)
+    };
+}
+function provenanceFromPolicyCapsule(capsule) {
+    return {
+        source_trace_id: capsule.sourcePointer.traceId,
+        source_message_id: capsule.sourcePointer.messageId,
+        source_pointer: sourcePointerText(capsule.sourcePointer.traceId, capsule.sourcePointer.messageId, capsule.sourcePointer.messageIndex, capsule.sourcePointer.contentSha256),
+        source_hash: capsule.sourcePointer.contentSha256,
+        source_hash_algorithm: "sha256",
+        source_excerpt_preview: capsule.sourceExcerptPreview,
+        source_recoverable: true,
+        source_recovery_path: `messages[${capsule.sourcePointer.messageIndex}]`,
+        original_payload_token_count: capsule.originalPayloadTokenCount,
+        capsule_token_count: estimateTextTokens(capsule.text),
+        compacted_message_ids: capsule.compactedMessageIds,
+        replacement_mode: capsule.replacementMode
+    };
+}
+function firstDefinedProvenance(entries) {
+    const first = entries[0];
+    if (!first) {
+        return {
+            source_recoverable: "unknown",
+            unsupported_additions_check: "No source provenance was available to check for unsupported additions.",
+            provenance_limitations: ["No compacted source pointer was available; provenance is marked unknown rather than invented."]
+        };
+    }
+    return {
+        source_trace_id: first.source_trace_id,
+        source_message_id: first.source_message_id,
+        source_pointer: first.source_pointer,
+        source_hash: first.source_hash,
+        source_hash_algorithm: first.source_hash_algorithm,
+        source_excerpt_preview: first.source_excerpt_preview,
+        source_recoverable: first.source_recoverable,
+        source_recovery_path: first.source_recovery_path,
+        original_payload_token_count: first.original_payload_token_count,
+        capsule_token_count: first.capsule_token_count,
+        unsupported_additions_check: first.source_recoverable === true
+            ? "State capsule facts are limited to deterministic trace-derived facts and source-pointer metadata."
+            : "Source recoverability is unknown; unsupported additions cannot be fully checked.",
+        provenance_limitations: [
+            "Short previews are intentionally truncated and are not a substitute for reviewing the source pointer locally.",
+            "State Capsule v0 records deterministic provenance; it does not perform semantic replay."
+        ]
+    };
+}
+export function createStateCapsule(trace, findings = [], policyCapsules = []) {
+    const retainedFacts = [];
+    const openQuestions = [];
+    const safetyNotes = [];
+    const userGoal = firstMessageByRole(trace, "user");
+    if (userGoal) {
+        retainedFacts.push(`User goal: ${compactSentence(userGoal.content)}`);
+    }
+    for (const message of findVerificationMessages(trace)) {
+        retainedFacts.push(`Verification evidence from ${message.id}: ${compactSentence(message.content)}`);
+    }
+    const finalAssistantMessage = lastMessageByRole(trace, "assistant");
+    if (finalAssistantMessage) {
+        retainedFacts.push(`Latest assistant summary: ${compactSentence(finalAssistantMessage.content)}`);
+    }
+    const repeatedFindings = findings.filter((finding) => finding.category === "repeated_tool_output");
+    for (const finding of repeatedFindings) {
+        retainedFacts.push(`Repeated output preserved by pointer: ${finding.summary}`);
+    }
+    if (retainedFacts.length === 0) {
+        openQuestions.push("No durable facts were identified by the conservative state capsule heuristic.");
+    }
+    if (findings.length === 0 && policyCapsules.length === 0) {
+        safetyNotes.push("No waste findings were detected; the capsule is informational only.");
+    }
+    else {
+        safetyNotes.push("State capsule was generated from local trace content only; no model provider was called.");
+        safetyNotes.push("Review source pointers before relying on compacted context for critical decisions.");
+    }
+    const provenanceEntries = policyCapsules.length > 0 ? policyCapsules.map(provenanceFromPolicyCapsule) : repeatedFindings.map((finding) => provenanceFromFinding(trace, finding));
+    const capsuleTokens = estimateTextTokens([...retainedFacts, ...openQuestions, ...safetyNotes].join("\n"));
+    const entriesWithCapsuleCounts = provenanceEntries.map((entry) => ({ ...entry, capsule_token_count: entry.capsule_token_count ?? capsuleTokens }));
+    return {
+        traceId: trace.id,
+        ...firstDefinedProvenance(entriesWithCapsuleCounts),
+        provenance_entries: entriesWithCapsuleCounts,
+        preserved_commitments: retainedFacts,
+        omitted_or_unknown_commitments: openQuestions.length > 0 ? openQuestions : ["No additional commitments were inferred beyond the retained trace-derived facts."],
+        retainedFacts,
+        openQuestions,
+        safetyNotes
+    };
+}
+//# sourceMappingURL=state-capsule.js.map

package/dist/core/token-accounting.d.ts

@@ -0,0 +1,62 @@
+import type { PolicyMiddlewareResult } from "../engine/policy-middleware.js";
+import type { AgentTrace } from "./types.js";
+/**
+ * Token & cost accounting surface (Strong-MVP Track D).
+ *
+ * Produces ONE honestly-labeled before/after token + cost summary that a developer can read to
+ * answer: tokens used, input vs output, how much was reduced, estimated $ saved, and — critically —
+ * whether each figure was MEASURED (provider-reported) or ESTIMATED (local chars/4).
+ *
+ * Label discipline (mvp-capability-matrix.md rows 2/3/10, README evidence ladder):
+ *  - `provider-reported` is used ONLY when the trace/run carries provider usage metadata.
+ *  - otherwise every figure is `local estimate` (chars/4 trace tokens + price-table cost).
+ *  - NEVER `billing-confirmed`. Cost is a price-table estimate, not a billed figure.
+ *
+ * Output tokens BEFORE come from the trace (assistant messages). Output tokens AFTER are equal to
+ * the before value for the supported policies (compaction targets non-assistant input spans —
+ * repeated tool output / skill injections — so assistant output is unchanged); this is stated
+ * explicitly rather than implied. When provider usage data is absent, output figures are labeled
+ * local estimates like the rest.
+ */
+export type TokenFigureSource = "provider_reported" | "local_estimate";
+export interface TokenAccountingFigure {
+    value: number;
+    /** Honest source label for THIS figure. */
+    source: TokenFigureSource;
+}
+export interface TokenAccounting {
+    model: string;
+    /** Per-figure honest source label (provider_reported only when usage metadata is present). */
+    measured: boolean;
+    input_tokens_before: TokenAccountingFigure;
+    input_tokens_after: TokenAccountingFigure;
+    output_tokens_before: TokenAccountingFigure;
+    output_tokens_after: TokenAccountingFigure;
+    input_tokens_saved: number;
+    percent_input_reduction: number;
+    estimated_cost_before_usd: number;
+    estimated_cost_after_usd: number;
+    estimated_saving_per_run_usd: number;
+    /** Visible pricing assumptions for the cost figures (price-table, NOT billed). */
+    pricing_assumptions: string[];
+    /** Whether the required token/cost evidence is present (Track C gate input). */
+    evidence_present: boolean;
+    limitations: string[];
+}
+/**
+ * Build the token/cost accounting summary from an in-memory policy result.
+ *
+ * HONESTY: the numeric token figures here come from `policyResult.tokenEstimateBefore/After`,
+ * which are ALWAYS the LOCAL chars/4 estimator (`estimateTraceTokens`) over the trace messages —
+ * regardless of `trace.source`. `AgentTrace` carries no provider usage metadata (real provider
+ * usage lives in `UsageMetadata`, NOT in the trace), and a `provider_usage` capture has no messages
+ * to estimate from, so labeling its figures `provider_reported` would emit a FALSE
+ * `0 (provider-reported)` over an empty local estimate. A figure is therefore labeled
+ * `provider_reported` ONLY when it genuinely derives from provider usage metadata — which the
+ * current `AgentTrace` shape never carries — so every figure here is a `local_estimate`. When a
+ * provider-usage path is added that attaches real usage numbers, source those figures from it and
+ * flip the label per-figure; until then, never claim provider-reported over a local estimate.
+ */
+export declare function buildTokenAccounting(trace: AgentTrace, policyResult: PolicyMiddlewareResult): TokenAccounting;
+/** One-line-per-figure human rendering for stdout / markdown (each line carries its source label). */
+export declare function describeTokenAccounting(acc: TokenAccounting): string[];

package/dist/core/token-accounting.js

@@ -0,0 +1,81 @@
+import { calculateCost } from "./cost-calculator.js";
+function pct(before, after) {
+    if (before <= 0) {
+        return 0;
+    }
+    return Number((((before - after) / before) * 100).toFixed(2));
+}
+/**
+ * Build the token/cost accounting summary from an in-memory policy result.
+ *
+ * HONESTY: the numeric token figures here come from `policyResult.tokenEstimateBefore/After`,
+ * which are ALWAYS the LOCAL chars/4 estimator (`estimateTraceTokens`) over the trace messages —
+ * regardless of `trace.source`. `AgentTrace` carries no provider usage metadata (real provider
+ * usage lives in `UsageMetadata`, NOT in the trace), and a `provider_usage` capture has no messages
+ * to estimate from, so labeling its figures `provider_reported` would emit a FALSE
+ * `0 (provider-reported)` over an empty local estimate. A figure is therefore labeled
+ * `provider_reported` ONLY when it genuinely derives from provider usage metadata — which the
+ * current `AgentTrace` shape never carries — so every figure here is a `local_estimate`. When a
+ * provider-usage path is added that attaches real usage numbers, source those figures from it and
+ * flip the label per-figure; until then, never claim provider-reported over a local estimate.
+ */
+export function buildTokenAccounting(trace, policyResult) {
+    // The figures below come from the local chars/4 estimator (`estimateTraceTokens` via
+    // `policyResult.tokenEstimateBefore/After`), NOT from provider usage metadata — which the
+    // `AgentTrace` shape does not carry. So these are local estimates even on a `provider_usage`
+    // trace (whose capture has no messages to estimate from). Fail honest: label them local_estimate.
+    const measured = false;
+    const source = "local_estimate";
+    const inputBefore = policyResult.tokenEstimateBefore.inputTokens;
+    const inputAfter = policyResult.tokenEstimateAfter.inputTokens;
+    const outputBefore = policyResult.tokenEstimateBefore.outputTokens;
+    // Supported policies do not touch assistant output spans, so output-after equals output-before.
+    const outputAfter = policyResult.tokenEstimateAfter.outputTokens;
+    const costBefore = calculateCost(trace.model, policyResult.tokenEstimateBefore).totalCostUsd;
+    const costAfter = calculateCost(trace.model, policyResult.tokenEstimateAfter).totalCostUsd;
+    const evidencePresent = Number.isFinite(inputBefore) && Number.isFinite(inputAfter) && inputBefore >= 0;
+    return {
+        model: trace.model,
+        measured,
+        input_tokens_before: { value: inputBefore, source },
+        input_tokens_after: { value: inputAfter, source },
+        output_tokens_before: { value: outputBefore, source },
+        output_tokens_after: { value: outputAfter, source },
+        input_tokens_saved: Math.max(0, inputBefore - inputAfter),
+        percent_input_reduction: pct(inputBefore, inputAfter),
+        estimated_cost_before_usd: Number(costBefore.toFixed(6)),
+        estimated_cost_after_usd: Number(costAfter.toFixed(6)),
+        estimated_saving_per_run_usd: Number(Math.max(0, costBefore - costAfter).toFixed(6)),
+        pricing_assumptions: [
+            `price-table estimate for ${trace.model} (NOT billing-confirmed, NOT a billed figure)`,
+            measured
+                ? "token counts are provider-reported; cost is a local price-table estimate over those counts"
+                : "token counts are local estimates (chars/4); cost is a local price-table estimate over those counts"
+        ],
+        evidence_present: evidencePresent,
+        limitations: [
+            measured
+                ? "Input/output token counts are provider-reported; cost remains a price-table ESTIMATE, never billing-confirmed."
+                : "Input/output token counts are LOCAL ESTIMATES (chars/4); cost is a price-table ESTIMATE, never provider-reported or billing-confirmed.",
+            "Output tokens after compaction equal output tokens before: the supported policies compact only non-assistant input spans (repeated tool output / skill injections), so assistant output is unchanged.",
+            "No realized/applied savings is claimed; these are per-run estimates only."
+        ]
+    };
+}
+/** One-line-per-figure human rendering for stdout / markdown (each line carries its source label). */
+export function describeTokenAccounting(acc) {
+    const label = (f) => `${f.value} (${f.source === "provider_reported" ? "provider-reported" : "local estimate (chars/4)"})`;
+    return [
+        `model: ${acc.model}`,
+        `input tokens before: ${label(acc.input_tokens_before)}`,
+        `input tokens after:  ${label(acc.input_tokens_after)}`,
+        `output tokens before: ${label(acc.output_tokens_before)}`,
+        `output tokens after:  ${label(acc.output_tokens_after)}`,
+        `input tokens saved: ${acc.input_tokens_saved} (${acc.percent_input_reduction}% input reduction)`,
+        `estimated cost before: $${acc.estimated_cost_before_usd.toFixed(6)} (price-table estimate, NOT billed)`,
+        `estimated cost after:  $${acc.estimated_cost_after_usd.toFixed(6)} (price-table estimate, NOT billed)`,
+        `estimated saving per run: $${acc.estimated_saving_per_run_usd.toFixed(6)} (estimate, NOT billing-confirmed, NOT realized)`,
+        ...acc.pricing_assumptions.map((a) => `pricing assumption: ${a}`)
+    ];
+}
+//# sourceMappingURL=token-accounting.js.map

package/dist/core/token-estimator.d.ts

@@ -0,0 +1,3 @@
+import type { AgentTrace, TokenEstimate } from "./types.js";
+export declare function estimateTextTokens(text: string): number;
+export declare function estimateTraceTokens(trace: AgentTrace): TokenEstimate;

package/dist/core/token-estimator.js

@@ -0,0 +1,18 @@
+const APPROX_CHARS_PER_TOKEN = 4;
+export function estimateTextTokens(text) {
+    return Math.max(1, Math.ceil(text.length / APPROX_CHARS_PER_TOKEN));
+}
+export function estimateTraceTokens(trace) {
+    const inputTokens = trace.messages
+        .filter((message) => message.role !== "assistant")
+        .reduce((sum, message) => sum + estimateTextTokens(message.content), 0);
+    const outputTokens = trace.messages
+        .filter((message) => message.role === "assistant")
+        .reduce((sum, message) => sum + estimateTextTokens(message.content), 0);
+    return {
+        inputTokens,
+        outputTokens,
+        totalTokens: inputTokens + outputTokens
+    };
+}
+//# sourceMappingURL=token-estimator.js.map

package/dist/core/trace-adapters.d.ts

@@ -0,0 +1,53 @@
+import type { AgentTrace } from "./types.js";
+export type TraceAdapterSource = "agent-trace" | "messages" | "codex-exec-jsonl" | "unknown";
+export type TraceAdapterStatus = "pass" | "warn" | "fail";
+export interface TraceAdapterOptions {
+    rawContent: string;
+    operatorExport?: boolean;
+}
+export interface TraceAdapterResult {
+    status: TraceAdapterStatus;
+    trace: AgentTrace | null;
+    warnings: string[];
+    failures: string[];
+    normalization_steps: string[];
+    skipped_fields: string[];
+    source_metadata: Record<string, unknown>;
+}
+export interface TraceAdapter {
+    id: TraceAdapterSource;
+    displayName: string;
+    description: string;
+    supportedSource: TraceAdapterSource;
+    limitations: string[];
+    canHandle(input: unknown): boolean;
+    normalize(input: unknown, options: TraceAdapterOptions): TraceAdapterResult;
+}
+export interface TraceAdapterDetectionResult {
+    status: TraceAdapterStatus;
+    requested_source: TraceAdapterSource;
+    adapter_id: TraceAdapterSource | null;
+    supported_format_detected: boolean;
+    warnings: string[];
+    failures: string[];
+    normalization_steps: string[];
+    skipped_fields: string[];
+    source_metadata: Record<string, unknown>;
+}
+export declare const agentTraceAdapter: TraceAdapter;
+export declare const messagesAdapter: TraceAdapter;
+export declare const codexExecJsonlAdapter: TraceAdapter;
+export declare const unknownAdapter: TraceAdapter;
+export declare const traceAdapters: TraceAdapter[];
+export interface TraceAdapterRawParseResult {
+    input: unknown | null;
+    failures: string[];
+    normalization_steps: string[];
+    source_metadata: Record<string, unknown>;
+}
+export declare function parseTraceAdapterRawContent(rawContent: string, source: TraceAdapterSource): TraceAdapterRawParseResult;
+export declare function listTraceAdapters(): TraceAdapter[];
+export declare function listTraceAdapterSources(): TraceAdapterSource[];
+export declare function assertTraceAdapterSource(source: string): asserts source is TraceAdapterSource;
+export declare function getTraceAdapter(source: TraceAdapterSource): TraceAdapter;
+export declare function detectTraceAdapter(input: unknown, requestedSource?: TraceAdapterSource): TraceAdapterDetectionResult;