@compaction/cli 0.1.0

package/dist/core/billing-delta/billing-delta-record.js

@@ -0,0 +1,394 @@
+/**
+ * Billing-delta measurement record — operator-run A/B protocol (local-first).
+ *
+ * Implements Alternative 1 / §3 of docs/design/billing-delta-loop.md (the accepted
+ * methodology direction): a LOCAL, OPERATOR-RUN measurement record. The OPERATOR
+ * performs the real workflow runs themselves (control arm = original context;
+ * treatment arm = apply-context-approved compacted context), reads the billed costs
+ * from THEIR OWN provider console / billing export, and ENTERS them. This module
+ * records runs with provenance, computes per-arm statistics and the delta of means,
+ * applies the accepted methodology's honesty rubric, and emits a caveated verdict.
+ *
+ * HARD HONESTY RAILS (see the accepted doc §2.4, §1(a)-(e), Risks):
+ * - This module makes NO provider call, reads NO credential, has NO network access.
+ * - Operator-entered figures are labeled `operator_entered: true`. The tool CANNOT
+ *   verify them against the provider.
+ * - The tool NEVER emits the phrase "billing-confirmed savings" as a claim and NEVER
+ *   sets `billing_confirmed: true`. This is NOT a Tier-3 claim. `ValueProof` is
+ *   untouched (its `billing_confirmed_savings.claimed` stays false).
+ * - The strongest verdict is a "measured, caveated delta on N runs of ONE workflow
+ *   under recorded conditions" — explicitly NOT a general savings claim.
+ * - Aggregate cost figures only (LOW sensitivity). NO prompt/completion content is
+ *   stored anywhere in the record.
+ */
+import { contentHash } from "../content-hash.js";
+import { getModelPricing, isKnownModel } from "../pricing.js";
+export const BILLING_DELTA_RECORD_ROOT = ".compaction/billing-delta";
+export const BILLING_DELTA_RECORD_SCHEMA = "billing-delta.measurement-record.v1";
+export const BILLING_DELTA_REPORT_SCHEMA = "billing-delta.report.v1";
+export const BILLING_DELTA_PRIVACY_POSTURE = {
+    sensitivity: "low",
+    aggregate_cost_only: true,
+    operator_entered_figures: true,
+    local_only: true
+};
+/** The documented decision criterion. Named in every report. */
+export const BILLING_DELTA_CRITERION = "delta-of-means interval = [mean_delta - 2*SE, mean_delta + 2*SE], SE = sqrt(sd_control^2/n_control + sd_treatment^2/n_treatment); " +
+    "verdict measured_caveated_delta only when N>=3 per arm AND the interval excludes zero (conservative ~2-standard-error rule, sample SD, no distributional claim beyond it)";
+/** The standard-error multiplier used to form the conservative interval. Documented and fixed (no over-engineered statistics). */
+export const BILLING_DELTA_INTERVAL_K = 2;
+/** Verbatim-ish anecdote note required by the accepted doc (§2.4: "a single A/B run is an anecdote, not proof"). */
+export const BILLING_DELTA_ANECDOTE_NOTE = "A single A/B pair is an anecdote, not proof: N=1 per arm cannot distinguish a compaction effect from run-to-run noise.";
+/**
+ * Claim-level labels for the token-delta section. Token-level, provider-reported — never a
+ * billing claim. The label is selected by the ACTUAL sign/status of the token delta so it
+ * never calls a non-reduction a "reduction" (an overclaim by mislabel): a negative input
+ * delta means the treatment context GREW (an INCREASE), zero means NO CHANGE, and the
+ * insufficient/suppressed statuses have no computed delta at all. Every variant preserves the
+ * "NOT billing-confirmed savings" disclaimer and makes no savings claim.
+ */
+export const BILLING_DELTA_TOKEN_DELTA_LABELS = {
+    /** Genuine reduction: treatment used fewer input tokens than control (positive input delta). */
+    reduction: "provider-reported token reduction (workflow-scoped) — NOT billing-confirmed savings",
+    /** Increase: treatment used MORE input tokens than control (negative input delta). Not a saving. */
+    increase: "provider-reported token INCREASE (workflow-scoped) — NOT a saving; NOT billing-confirmed savings",
+    /** No change: the input token delta is exactly zero. */
+    no_change: "provider-reported token delta: no change (workflow-scoped) — NOT billing-confirmed savings",
+    /** Not computed: insufficient token data or deltas suppressed by a failed task. */
+    not_computed: "provider-reported token delta not computed (workflow-scoped) — NOT billing-confirmed savings"
+};
+/**
+ * Select the sign/status-accurate claim label. Reduction is used ONLY when the input delta is
+ * genuinely positive (treatment used fewer tokens); a negative delta is an increase, zero is no
+ * change, and a null delta (insufficient/suppressed status) is "not computed". This never
+ * strengthens a claim — it only makes the existing label honest for the actual sign/status.
+ */
+export function selectTokenDeltaLabel(status, inputTokenDelta) {
+    if (status !== "computed" || inputTokenDelta === null) {
+        return BILLING_DELTA_TOKEN_DELTA_LABELS.not_computed;
+    }
+    if (inputTokenDelta > 0)
+        return BILLING_DELTA_TOKEN_DELTA_LABELS.reduction;
+    if (inputTokenDelta < 0)
+        return BILLING_DELTA_TOKEN_DELTA_LABELS.increase;
+    return BILLING_DELTA_TOKEN_DELTA_LABELS.no_change;
+}
+function deriveMeasurementId(workflowId, generatedAt) {
+    const seed = `${workflowId}::${generatedAt}`;
+    return `bdm_${contentHash(seed).slice(0, 16)}`;
+}
+export function buildTreatmentApprovalLink(path, fileContent) {
+    return {
+        apply_approval_record_path: path,
+        apply_approval_record_sha256: contentHash(fileContent)
+    };
+}
+export function initMeasurementRecord(input) {
+    const measurement_id = input.measurementId ?? deriveMeasurementId(input.workflowId, input.generatedAt);
+    let apply_approval_link;
+    if (input.applyApprovalRecordPath && input.applyApprovalRecordContent !== undefined) {
+        apply_approval_link = buildTreatmentApprovalLink(input.applyApprovalRecordPath, input.applyApprovalRecordContent);
+    }
+    return {
+        schema: BILLING_DELTA_RECORD_SCHEMA,
+        measurement_id,
+        created_at: input.generatedAt,
+        workflow_id: input.workflowId,
+        workflow_description: input.workflowDescription,
+        fixed_conditions: {
+            model: input.model,
+            model_version: input.modelVersion ?? "unknown",
+            input_description: input.inputDescription,
+            window: input.window
+        },
+        ...(apply_approval_link ? { apply_approval_link } : {}),
+        runs: [],
+        privacy_posture: BILLING_DELTA_PRIVACY_POSTURE,
+        operator_entered: true,
+        billing_confirmed: false,
+        tool_makes_provider_call: false
+    };
+}
+function deriveRunId(record, input) {
+    const seed = `${record.measurement_id}::${input.arm}::${input.runTimestamp}::${record.runs.length}`;
+    return `run_${contentHash(seed).slice(0, 12)}`;
+}
+export function addRun(record, input) {
+    if (!Number.isFinite(input.billedCost) || input.billedCost < 0) {
+        throw new Error("billed cost must be a finite, non-negative number");
+    }
+    if (!input.currency || input.currency.trim() === "") {
+        throw new Error("currency is required");
+    }
+    let treatment_approval_link;
+    if (input.treatmentApprovalRecordPath && input.treatmentApprovalRecordContent !== undefined) {
+        treatment_approval_link = buildTreatmentApprovalLink(input.treatmentApprovalRecordPath, input.treatmentApprovalRecordContent);
+    }
+    const run = {
+        run_id: input.runId ?? deriveRunId(record, input),
+        arm: input.arm,
+        billed_cost: input.billedCost,
+        currency: input.currency,
+        operator_entered: true,
+        ...(input.providerReportedUsage ? { provider_reported_usage: input.providerReportedUsage } : {}),
+        run_timestamp: input.runTimestamp,
+        ...(input.notes ? { notes: input.notes } : {}),
+        ...(treatment_approval_link ? { treatment_approval_link } : {})
+    };
+    // Backfill the machine-readable privacy posture when rewriting a record created
+    // before this field existed, so absence reliably means "written pre-field" and an
+    // operator continuing an old measurement does not keep persisting a posture-less file.
+    // The posture is a structural property of the substrate (local, operator-entered,
+    // aggregate-only), not a per-record choice, so backfilling it is a restatement.
+    return {
+        ...record,
+        privacy_posture: record.privacy_posture ?? BILLING_DELTA_PRIVACY_POSTURE,
+        runs: [...record.runs, run]
+    };
+}
+function mean(values) {
+    return values.reduce((sum, v) => sum + v, 0) / values.length;
+}
+function sampleStandardDeviation(values) {
+    if (values.length < 2)
+        return null;
+    const m = mean(values);
+    const variance = values.reduce((sum, v) => sum + (v - m) ** 2, 0) / (values.length - 1);
+    return Math.sqrt(variance);
+}
+function armStatistics(arm, runs) {
+    const costs = runs.filter((r) => r.arm === arm).map((r) => r.billed_cost);
+    if (costs.length === 0) {
+        return { arm, n: 0, mean: null, min: null, max: null, sample_sd: null };
+    }
+    return {
+        arm,
+        n: costs.length,
+        mean: mean(costs),
+        min: Math.min(...costs),
+        max: Math.max(...costs),
+        sample_sd: sampleStandardDeviation(costs)
+    };
+}
+function collectConfounders(runs) {
+    return runs
+        .filter((r) => typeof r.notes === "string" && r.notes.trim() !== "")
+        .map((r) => `[${r.arm} ${r.run_id}] ${r.notes}`);
+}
+function collectTreatmentLinks(runs) {
+    return runs
+        .filter((r) => r.arm === "treatment" && r.treatment_approval_link)
+        .map((r) => r.treatment_approval_link);
+}
+const BASE_CAVEATS = (workflowId, nControl, nTreatment) => [
+    `Measured, caveated delta on N runs of ONE workflow (workflow_id=${workflowId}; ` +
+        `n_control=${nControl}, n_treatment=${nTreatment}) under the recorded fixed conditions only — ` +
+        "NOT a billing-confirmed general savings claim.",
+    "Operator-entered billing figures, not provider-verified by this tool. The tool made no provider call, " +
+        "read no credential, and has no network access.",
+    "Run-to-run nondeterminism, prompt-caching, model/version drift, pricing changes, retries, and per-run " +
+        "billing attribution are confounders; control or record them. A delta interval that includes zero is not a saving.",
+    "This is NOT 'billing-confirmed savings' (Tier 3) and does NOT flip ValueProof.billing_confirmed_savings.claimed."
+];
+/** Parse the task-quality flag from a run's notes ("task: ok" | "task: failed"); "unknown" otherwise. */
+function taskFlagFromNotes(notes) {
+    const m = /task:\s*(ok|failed)/i.exec(notes ?? "");
+    return m ? m[1].toLowerCase() : "unknown";
+}
+/** Resolve a model name against the price table, tolerating dated variants (e.g. -20251001). */
+function resolvePricedModel(model) {
+    if (isKnownModel(model))
+        return model;
+    const undated = model.replace(/-\d{8}$/, "");
+    if (undated !== model && isKnownModel(undated))
+        return undated;
+    return null;
+}
+function tokenArmStatistics(arm, runs) {
+    const withTokens = runs.filter((r) => r.arm === arm && typeof r.provider_reported_usage?.input_tokens === "number");
+    const inputs = withTokens.map((r) => r.provider_reported_usage.input_tokens);
+    const outputs = withTokens
+        .map((r) => r.provider_reported_usage?.output_tokens)
+        .filter((v) => typeof v === "number");
+    const distinct = [...new Set(inputs)].sort((a, b) => a - b);
+    return {
+        arm,
+        n_with_tokens: withTokens.length,
+        input_tokens_distinct: distinct,
+        input_deterministic: withTokens.length > 0 && distinct.length === 1,
+        mean_input_tokens: inputs.length > 0 ? inputs.reduce((a, b) => a + b, 0) / inputs.length : null,
+        mean_output_tokens: outputs.length > 0 ? outputs.reduce((a, b) => a + b, 0) / outputs.length : null,
+        output_min: outputs.length > 0 ? Math.min(...outputs) : null,
+        output_max: outputs.length > 0 ? Math.max(...outputs) : null
+    };
+}
+/**
+ * Compute the provider-reported token-delta section. Input tokens are deterministic for a
+ * fixed context+prompt, so one tokened run per arm pins the input delta exactly; the
+ * billed-cost verdict and its N>=3 criterion are unaffected by this section.
+ */
+export function computeTokenDelta(record) {
+    const control = tokenArmStatistics("control", record.runs);
+    const treatment = tokenArmStatistics("treatment", record.runs);
+    const task_quality = {
+        control: record.runs.filter((r) => r.arm === "control").map((r) => taskFlagFromNotes(r.notes)),
+        treatment: record.runs.filter((r) => r.arm === "treatment").map((r) => taskFlagFromNotes(r.notes)),
+        any_failed: record.runs.some((r) => taskFlagFromNotes(r.notes) === "failed")
+    };
+    const notes = [];
+    const base = {
+        control,
+        treatment,
+        task_quality,
+        billing_confirmed: false
+    };
+    if (task_quality.any_failed) {
+        notes.push("Token deltas SUPPRESSED: at least one run recorded 'task: failed'. A cheaper run that " +
+            "failed the task is not a saving; fix task quality before reading token deltas.");
+        return {
+            ...base,
+            claim_label: selectTokenDeltaLabel("suppressed_task_failure", null),
+            status: "suppressed_task_failure",
+            input_token_delta: null,
+            input_token_delta_pct: null,
+            output_token_delta: null,
+            estimated_cost_delta: null,
+            notes
+        };
+    }
+    if (control.n_with_tokens === 0 || treatment.n_with_tokens === 0) {
+        notes.push(`Insufficient token data: provider-reported input_tokens present on ` +
+            `${control.n_with_tokens} control and ${treatment.n_with_tokens} treatment run(s); ` +
+            "need at least one tokened run per arm (input tokens are deterministic per arm, so one pins the input delta exactly).");
+        return {
+            ...base,
+            claim_label: selectTokenDeltaLabel("insufficient_token_data", null),
+            status: "insufficient_token_data",
+            input_token_delta: null,
+            input_token_delta_pct: null,
+            output_token_delta: null,
+            estimated_cost_delta: null,
+            notes
+        };
+    }
+    const input_token_delta = control.mean_input_tokens - treatment.mean_input_tokens;
+    const input_token_delta_pct = control.mean_input_tokens > 0
+        ? input_token_delta / control.mean_input_tokens
+        : null;
+    const output_token_delta = control.mean_output_tokens !== null && treatment.mean_output_tokens !== null
+        ? control.mean_output_tokens - treatment.mean_output_tokens
+        : null;
+    if (!control.input_deterministic || !treatment.input_deterministic) {
+        notes.push("Input tokens were NOT identical across runs within an arm — fixed conditions may have drifted; " +
+            "the input delta below uses arm means and should be read with that caveat.");
+    }
+    notes.push("Output tokens vary run to run; the output delta is a mean difference — read with the per-arm min/max spread.");
+    let estimated_cost_delta = null;
+    const pricedModel = resolvePricedModel(record.fixed_conditions.model);
+    if (pricedModel !== null) {
+        const pricing = getModelPricing(pricedModel);
+        const amount = (input_token_delta * pricing.inputPerMillionUsd) / 1_000_000 +
+            ((output_token_delta ?? 0) * pricing.outputPerMillionUsd) / 1_000_000;
+        // When the output delta is unavailable but the model has material output pricing,
+        // the cost estimate prices the output component as zero. Label it input-only/incomplete
+        // so a partial figure is not read as a complete cost delta.
+        const outputUnpriced = output_token_delta === null && pricing.outputPerMillionUsd > 0;
+        estimated_cost_delta = {
+            amount_usd: amount,
+            cost_source: "price_table_estimate",
+            note: outputUnpriced
+                ? `Price-table ESTIMATE for ${pricedModel} — INPUT-ONLY/INCOMPLETE: output-token delta is ` +
+                    "unavailable (one arm lacks provider-reported output tokens), so the output cost component " +
+                    "is priced as zero. Read as a lower bound on the input side only, never a complete or " +
+                    "billing-confirmed figure."
+                : `Price-table ESTIMATE for ${pricedModel} applied to the token deltas — an estimate, ` +
+                    "never a billed or billing-confirmed figure."
+        };
+    }
+    else {
+        notes.push(`No price-table entry for model '${record.fixed_conditions.model}'; estimated cost delta omitted ` +
+            "(token deltas stand on their own).");
+    }
+    return {
+        ...base,
+        claim_label: selectTokenDeltaLabel("computed", input_token_delta),
+        status: "computed",
+        input_token_delta,
+        input_token_delta_pct,
+        output_token_delta,
+        estimated_cost_delta,
+        notes
+    };
+}
+export function computeReport(record, generatedAt) {
+    const control = armStatistics("control", record.runs);
+    const treatment = armStatistics("treatment", record.runs);
+    const currency = record.runs.length > 0 ? record.runs[0].currency : null;
+    let mean_delta = null;
+    if (control.mean !== null && treatment.mean !== null) {
+        mean_delta = control.mean - treatment.mean;
+    }
+    let delta_standard_error = null;
+    let delta_interval = null;
+    let delta_interval_excludes_zero = false;
+    if (mean_delta !== null &&
+        control.sample_sd !== null &&
+        treatment.sample_sd !== null &&
+        control.n >= 2 &&
+        treatment.n >= 2) {
+        delta_standard_error = Math.sqrt(control.sample_sd ** 2 / control.n + treatment.sample_sd ** 2 / treatment.n);
+        const margin = BILLING_DELTA_INTERVAL_K * delta_standard_error;
+        delta_interval = { lower: mean_delta - margin, upper: mean_delta + margin };
+        delta_interval_excludes_zero =
+            (delta_interval.lower > 0 && delta_interval.upper > 0) ||
+                (delta_interval.lower < 0 && delta_interval.upper < 0);
+    }
+    const verdict_notes = [];
+    let verdict;
+    if (control.n < 3 || treatment.n < 3) {
+        verdict = "insufficient_data";
+        verdict_notes.push(BILLING_DELTA_ANECDOTE_NOTE);
+        verdict_notes.push(`Need N>=3 per arm (have n_control=${control.n}, n_treatment=${treatment.n}). ` +
+            "A single pair is an anecdote, not proof; fewer than 3 runs per arm is insufficient data.");
+    }
+    else if (!delta_interval_excludes_zero) {
+        verdict = "inconclusive";
+        verdict_notes.push("The delta-of-means interval includes zero: the measured difference is not distinguishable from " +
+            "run-to-run noise at the conservative ~2-standard-error margin. Not a saving.");
+    }
+    else {
+        verdict = "measured_caveated_delta";
+        const direction = mean_delta > 0 ? "lower (a saving)" : "higher (a cost increase)";
+        verdict_notes.push(`The delta-of-means interval excludes zero: treatment is measured ${direction} than control under ` +
+            "the recorded conditions. This is a measured, caveated delta on this workflow only — not a general claim.");
+    }
+    return {
+        schema: BILLING_DELTA_REPORT_SCHEMA,
+        measurement_id: record.measurement_id,
+        workflow_id: record.workflow_id,
+        generated_at: generatedAt,
+        currency,
+        fixed_conditions: record.fixed_conditions,
+        control,
+        treatment,
+        mean_delta,
+        delta_standard_error,
+        delta_interval,
+        delta_interval_excludes_zero,
+        criterion: BILLING_DELTA_CRITERION,
+        verdict,
+        verdict_notes,
+        claim_scope: `workflow_id=${record.workflow_id} under fixed conditions ` +
+            `(model=${record.fixed_conditions.model}, model_version=${record.fixed_conditions.model_version}, ` +
+            `window=${record.fixed_conditions.window}); n_control=${control.n}, n_treatment=${treatment.n}. ` +
+            "The measured workflow and conditions ONLY.",
+        not_a_general_claim: true,
+        billing_confirmed: false,
+        operator_entered: true,
+        confounders: collectConfounders(record.runs),
+        caveats: BASE_CAVEATS(record.workflow_id, control.n, treatment.n),
+        treatment_provenance_links: collectTreatmentLinks(record.runs),
+        token_delta: computeTokenDelta(record)
+    };
+}
+//# sourceMappingURL=billing-delta-record.js.map

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

@@ -0,0 +1,74 @@
+import type { AgentTrace } from "./types.js";
+import type { UsageMetadata } from "./usage-metadata.js";
+import type { TraceFingerprint } from "./trace-fingerprint.js";
+export interface CaptureAdapter {
+    /** Stable identifier for this adapter. Used in provenance and logging. */
+    readonly id: string;
+    /**
+     * Normalize a raw input (session file path, event stream, export file, etc.)
+     * into a CapturedRun containing a normalized AgentTrace, UsageMetadata,
+     * and provenance information.
+     *
+     * The adapter is responsible for:
+     * - Setting source: "real_captured" only when the trace comes from an agent
+     *   runtime session with identifiable workflow context (see real_captured semantics).
+     * - Attaching UsageMetadata at normalization time, not re-deriving it downstream.
+     * - Setting provenance.captureAdapter to this adapter's id.
+     */
+    normalize(input: CaptureAdapterInput): Promise<CapturedRun>;
+}
+export interface CaptureAdapterInput {
+    /** Path to the source artifact (session JSONL file, export file, stdout dump). */
+    sourcePath: string;
+    /** Human-readable label for CLI output. */
+    label?: string;
+    /** Additional adapter-specific options. */
+    options?: Record<string, unknown>;
+}
+export interface CapturedRun {
+    /** The normalized agent trace. */
+    trace: AgentTrace;
+    /** Usage metadata attached at capture time. Never re-derived downstream. */
+    usage: UsageMetadata;
+    /** Provenance record for the capture. */
+    provenance: CaptureProvenance;
+}
+export interface CaptureSubagentProvenance {
+    /** Unique agent identifier from the subagent JSONL entries. */
+    agentId: string;
+    /** Total user + assistant entries processed from this subagent. */
+    entryCount: number;
+    /** Agent type from meta.json, if present. */
+    agentType?: string;
+    /** Human-readable description from meta.json, if present. */
+    description?: string;
+    /** Tool use ID linking this subagent to the parent session tool call, from meta.json if present. */
+    toolUseId?: string;
+}
+export interface CaptureProvenance {
+    /** The adapter that produced this run. */
+    captureAdapter: string;
+    /** Stable source path or identifier. */
+    sourcePath: string;
+    /** ISO 8601 timestamp of when the capture was performed. */
+    capturedAt: string;
+    /** Claude Code session ID, OpenAI Agents run ID, or equivalent. Null if unknown. */
+    sessionId: string | null;
+    /** Any warnings or limitations the adapter encountered. */
+    warnings: string[];
+    /** Any limitations that apply to the captured run. */
+    limitations: string[];
+    /** Provenance records for each included subagent, when --include-subagents is used. */
+    subagents?: CaptureSubagentProvenance[];
+    /**
+     * Non-sensitive per-run distinctness fingerprint (a one-way SHA-256 DIGEST over the
+     * canonical normalized trace content — NEVER raw messages/prompts/tool-output).
+     *
+     * Lets future dogfood records cite a verifiable per-run distinctness proof so that
+     * genuinely-different captured sessions are distinguishable from re-captures of the
+     * same session (preventing real_captured N over-counting). When an adapter cannot
+     * produce a fingerprint, this is omitted and distinctness must be reported as
+     * `not_verified` — never counted as distinct. See `src/core/trace-fingerprint.ts`.
+     */
+    traceFingerprint?: TraceFingerprint;
+}

package/dist/core/capture-adapter.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=capture-adapter.js.map

package/dist/core/command-runner.d.ts

@@ -0,0 +1,29 @@
+export interface ParsedRunCommand {
+    executable: string;
+    args: string[];
+}
+export interface LocalCommandRun {
+    runId: string;
+    command: ParsedRunCommand;
+    stdout: string;
+    stderr: string;
+    rawOutput: string;
+    exitCode: number;
+    signal: NodeJS.Signals | null;
+    pid: number | null;
+    startedAt: string;
+    endedAt: string;
+    durationMs: number;
+}
+export interface PersistedLocalCommandRun {
+    run: LocalCommandRun;
+    outputDirectory: string;
+    stdoutPath: string;
+    stderrPath: string;
+    rawOutputPath: string;
+    metadataPath: string;
+}
+export declare function parseRunCommand(commandParts: string[]): ParsedRunCommand;
+export declare function createRunId(now?: Date): string;
+export declare function executeLocalCommand(command: ParsedRunCommand, runId?: string): Promise<LocalCommandRun>;
+export declare function persistLocalCommandRun(run: LocalCommandRun, runsRoot?: string): Promise<PersistedLocalCommandRun>;

package/dist/core/command-runner.js

@@ -0,0 +1,96 @@
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+export function parseRunCommand(commandParts) {
+    const [executable, ...args] = commandParts;
+    if (!executable) {
+        throw new Error("Usage: compaction run -- <command> [args...]");
+    }
+    return { executable, args };
+}
+export function createRunId(now = new Date()) {
+    const timestamp = now.toISOString().replace(/[:.]/g, "-");
+    return `run-${timestamp}-${randomUUID().slice(0, 8)}`;
+}
+export async function executeLocalCommand(command, runId = createRunId()) {
+    const startMs = Date.now();
+    const startedAt = new Date(startMs).toISOString();
+    let stdout = "";
+    let stderr = "";
+    let rawOutput = "";
+    return new Promise((resolve) => {
+        const child = spawn(command.executable, command.args, {
+            shell: false,
+            windowsHide: true
+        });
+        const pid = child.pid ?? null;
+        let spawnError;
+        child.stdout.setEncoding("utf8");
+        child.stderr.setEncoding("utf8");
+        child.stdout.on("data", (chunk) => {
+            stdout += chunk;
+            rawOutput += chunk;
+        });
+        child.stderr.on("data", (chunk) => {
+            stderr += chunk;
+            rawOutput += chunk;
+        });
+        child.on("error", (error) => {
+            spawnError = error;
+            const errorMessage = stderr.length === 0 ? error.message : `\n${error.message}`;
+            stderr += errorMessage;
+            rawOutput += errorMessage;
+        });
+        child.on("close", (exitCode, signal) => {
+            const endMs = Date.now();
+            const resolvedExitCode = spawnError ? 127 : exitCode ?? 1;
+            resolve({
+                runId,
+                command,
+                stdout,
+                stderr,
+                rawOutput,
+                exitCode: resolvedExitCode,
+                signal,
+                pid,
+                startedAt,
+                endedAt: new Date(endMs).toISOString(),
+                durationMs: Math.max(0, endMs - startMs)
+            });
+        });
+    });
+}
+export async function persistLocalCommandRun(run, runsRoot = path.join(".compaction", "runs")) {
+    const outputDirectory = path.join(runsRoot, run.runId);
+    const stdoutPath = path.join(outputDirectory, "stdout.txt");
+    const stderrPath = path.join(outputDirectory, "stderr.txt");
+    const rawOutputPath = path.join(outputDirectory, "raw-output.txt");
+    const metadataPath = path.join(outputDirectory, "metadata.json");
+    await mkdir(outputDirectory, { recursive: true });
+    await writeFile(stdoutPath, run.stdout, "utf8");
+    await writeFile(stderrPath, run.stderr, "utf8");
+    await writeFile(rawOutputPath, run.rawOutput, "utf8");
+    await writeFile(metadataPath, `${JSON.stringify({
+        runId: run.runId,
+        command: run.command,
+        exitCode: run.exitCode,
+        signal: run.signal,
+        pid: run.pid,
+        startedAt: run.startedAt,
+        endedAt: run.endedAt,
+        durationMs: run.durationMs,
+        stdoutBytes: Buffer.byteLength(run.stdout, "utf8"),
+        stderrBytes: Buffer.byteLength(run.stderr, "utf8"),
+        rawOutputBytes: Buffer.byteLength(run.rawOutput, "utf8")
+    }, null, 2)}\n`, "utf8");
+    return {
+        run,
+        outputDirectory,
+        stdoutPath,
+        stderrPath,
+        rawOutputPath,
+        metadataPath
+    };
+}
+//# sourceMappingURL=command-runner.js.map

package/dist/core/content-hash.d.ts

@@ -0,0 +1 @@
+export declare function contentHash(content: string): string;

package/dist/core/content-hash.js

@@ -0,0 +1,5 @@
+import { createHash } from "node:crypto";
+export function contentHash(content) {
+    return createHash("sha256").update(content).digest("hex");
+}
+//# sourceMappingURL=content-hash.js.map

package/dist/core/cost-calculator.d.ts

@@ -0,0 +1,6 @@
+import type { CostEstimate, TokenEstimate } from "./types.js";
+export interface CacheTokenCounts {
+    cacheReadTokens?: number;
+    cacheCreationTokens?: number;
+}
+export declare function calculateCost(model: string, estimate: TokenEstimate, cache?: CacheTokenCounts): CostEstimate;

package/dist/core/cost-calculator.js

@@ -0,0 +1,20 @@
+import { getCacheCreationPricePerMillion, getCacheReadPricePerMillion, getModelPricing } from "./pricing.js";
+const TOKENS_PER_MILLION = 1_000_000;
+export function calculateCost(model, estimate, cache) {
+    const pricing = getModelPricing(model);
+    const inputCostUsd = (estimate.inputTokens / TOKENS_PER_MILLION) * pricing.inputPerMillionUsd;
+    const outputCostUsd = (estimate.outputTokens / TOKENS_PER_MILLION) * pricing.outputPerMillionUsd;
+    const cacheReadTokens = cache?.cacheReadTokens ?? 0;
+    const cacheCreationTokens = cache?.cacheCreationTokens ?? 0;
+    const cacheReadCostUsd = (cacheReadTokens / TOKENS_PER_MILLION) * getCacheReadPricePerMillion(model);
+    const cacheCreationCostUsd = (cacheCreationTokens / TOKENS_PER_MILLION) * getCacheCreationPricePerMillion(model);
+    return {
+        model,
+        inputCostUsd,
+        outputCostUsd,
+        cacheReadCostUsd: cacheReadTokens > 0 ? cacheReadCostUsd : undefined,
+        cacheCreationCostUsd: cacheCreationTokens > 0 ? cacheCreationCostUsd : undefined,
+        totalCostUsd: inputCostUsd + outputCostUsd + cacheReadCostUsd + cacheCreationCostUsd
+    };
+}
+//# sourceMappingURL=cost-calculator.js.map