@compaction/cli 0.1.0

package/dist/core/aggregate-format.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Human renderings (stdout + markdown) and the CONTENT-FREE redacted share bundle for the
+ * Track E multi-session aggregate.
+ *
+ * The share bundle is what a developer hands a founder/admin: the rolled-up aggregate
+ * NUMBERS + local labels + evidence tiers, and NOTHING ELSE. It is assembled by WHITELIST
+ * from the already-aggregated numeric/enum/short-label fields — there is no code path that
+ * copies raw trace text, prompts, completions, tool output, file paths, run ids, or report
+ * paths into it. Like the feedback bundle, it is a LOCAL FILE ONLY: no network, no upload.
+ */
+import type { AggregateReport, AggregateTotals, VerificationCounts } from "./session-aggregate.js";
+import { AGGREGATE_EVIDENCE_LABELS } from "./session-aggregate.js";
+import type { RunLabels } from "./run-labels.js";
+export declare const SHARE_BUNDLE_VERSION = "1.0.0";
+export declare const SHARE_NO_UPLOAD_NOTE: string;
+export declare const SHARE_CONTENT_FREE_NOTE: string;
+export declare function formatAggregateReport(report: AggregateReport): string;
+export declare function formatAggregateMarkdown(report: AggregateReport): string;
+export interface ShareBundleBreakdownEntry {
+    key: string;
+    runs: number;
+    input_tokens_saved: number;
+    estimated_savings_usd: number;
+    ready: number;
+    conditional: number;
+    not_ready: number;
+}
+export interface AggregateShareBundle {
+    share_bundle_version: string;
+    generated_at: string;
+    privacy: {
+        content_free: string;
+        upload: string;
+        includes: string[];
+        excludes: string[];
+    };
+    /** Local label filters that scoped this rollup (short strings only). */
+    applied_filters: RunLabels;
+    /** Operator provenance labels (short strings only). */
+    rollup_labels: RunLabels;
+    session_count: number;
+    totals: AggregateTotals;
+    verification: VerificationCounts;
+    /** Provider/runtime breakdown — short label keys + numbers only (no run ids). */
+    by_provider: ShareBundleBreakdownEntry[];
+    by_project: ShareBundleBreakdownEntry[];
+    by_workflow: ShareBundleBreakdownEntry[];
+    evidence_labels: AggregateReport["evidence_labels"];
+    limitations: string[];
+}
+/**
+ * Build the CONTENT-FREE aggregate share bundle from an already-aggregated report.
+ *
+ * WHITELIST construction: this copies ONLY numeric totals, enum verification counts, short
+ * label keys/filters, and the static evidence-label/limitation strings. It deliberately
+ * does NOT copy `report.sessions[].run_ids`, `skipped_run_directories` (which carry run
+ * directory paths), or any per-run identifier — so no run id, report path, or trace content
+ * can reach the shared artifact.
+ */
+export declare function buildAggregateShareBundle(report: AggregateReport, generatedAt?: string): AggregateShareBundle;
+export declare function formatShareBundleMarkdown(bundle: AggregateShareBundle): string;
+export { AGGREGATE_EVIDENCE_LABELS };

package/dist/core/aggregate-format.js

@@ -0,0 +1,349 @@
+/**
+ * Human renderings (stdout + markdown) and the CONTENT-FREE redacted share bundle for the
+ * Track E multi-session aggregate.
+ *
+ * The share bundle is what a developer hands a founder/admin: the rolled-up aggregate
+ * NUMBERS + local labels + evidence tiers, and NOTHING ELSE. It is assembled by WHITELIST
+ * from the already-aggregated numeric/enum/short-label fields — there is no code path that
+ * copies raw trace text, prompts, completions, tool output, file paths, run ids, or report
+ * paths into it. Like the feedback bundle, it is a LOCAL FILE ONLY: no network, no upload.
+ */
+import { AGGREGATE_EVIDENCE_LABELS } from "./session-aggregate.js";
+export const SHARE_BUNDLE_VERSION = "1.0.0";
+export const SHARE_NO_UPLOAD_NOTE = "This is a LOCAL share artifact only. It performs NO network call, NO upload, and NO telemetry. " +
+    "It contains aggregate numbers, local labels, and evidence tiers — NOT raw traces, prompts, " +
+    "completions, tool output, file contents, run ids, or report paths.";
+export const SHARE_CONTENT_FREE_NOTE = "Content-free by construction: assembled by whitelist from already-aggregated numeric / enum / " +
+    "short-label fields. No trace content has a field to land in.";
+function usd(value) {
+    return `$${value.toFixed(6)}`;
+}
+function totalsLines(totals) {
+    return [
+        `runs (compactions): ${totals.compactions}`,
+        `token-evidence split: provider-reported ${totals.runs_provider_reported}, local-estimate ${totals.runs_local_estimate}, unknown ${totals.runs_unknown_token_evidence}`,
+        `input tokens before: ${totals.total_input_tokens_before}`,
+        `input tokens after:  ${totals.total_input_tokens_after}`,
+        `input tokens saved:  ${totals.total_input_tokens_saved}`,
+        `output tokens before: ${totals.total_output_tokens_before} (over ${totals.runs_with_output_tokens} run(s); ${totals.runs_without_output_tokens} unknown)`,
+        `output tokens after:  ${totals.total_output_tokens_after} (over ${totals.runs_with_output_tokens} run(s); ${totals.runs_without_output_tokens} unknown)`,
+        `estimated cost before: ${usd(totals.total_estimated_cost_before_usd)} (price-table estimate, NOT billed)`,
+        `estimated cost after:  ${usd(totals.total_estimated_cost_after_usd)} (price-table estimate, NOT billed)`,
+        `estimated savings:     ${usd(totals.total_estimated_savings_usd)} (estimated, summed over ${totals.compactions} recorded run(s); NOT billing-confirmed, NOT realized, NOT extrapolated)`
+    ];
+}
+function verificationLines(v) {
+    return [
+        `readiness: ready ${v.ready}, conditional ${v.conditional}, not_ready ${v.not_ready}, not_evaluated ${v.not_evaluated}`,
+        `recoverability: pass ${v.recoverability_pass}, fail ${v.recoverability_fail}, not_evaluated ${v.recoverability_not_evaluated}`,
+        `commitment-preservation: pass ${v.commitment_pass}, fail ${v.commitment_fail}, not_evaluated ${v.commitment_not_evaluated}`,
+        `task-check: pass ${v.task_check_pass}, fail ${v.task_check_fail}, unsupported ${v.task_check_unsupported}, not_evaluated ${v.task_check_not_evaluated}`
+    ];
+}
+function filtersLine(filters) {
+    const parts = Object.entries(filters).map(([k, val]) => `${k}=${val}`);
+    return parts.length === 0 ? "none" : parts.join(", ");
+}
+export function formatAggregateReport(report) {
+    const lines = [];
+    lines.push("compaction multi-session aggregate (LOCAL — no upload, no dashboard)");
+    lines.push(`Source: ${report.source_glob}`);
+    lines.push(`Generated at: ${report.generated_at}`);
+    lines.push(`Applied label filters: ${filtersLine(report.applied_filters)}`);
+    lines.push(`Rollup labels: ${filtersLine(report.rollup_labels)}`);
+    lines.push(`Sessions: ${report.session_count}`);
+    lines.push("");
+    lines.push("Cross-session totals");
+    for (const line of totalsLines(report.totals))
+        lines.push(`- ${line}`);
+    lines.push("");
+    lines.push("Cross-session verification");
+    for (const line of verificationLines(report.verification))
+        lines.push(`- ${line}`);
+    lines.push("");
+    lines.push("Per-session summary");
+    if (report.sessions.length === 0) {
+        lines.push("- none (no recorded runs to roll up)");
+    }
+    else {
+        for (const session of report.sessions) {
+            lines.push(`- session ${session.session_id}${session.explicit_session_label ? "" : " (run-id fallback)"} — ${session.run_ids.length} run(s)`);
+            const labelBits = [];
+            if (session.labels.projects.length)
+                labelBits.push(`projects: ${session.labels.projects.join("/")}`);
+            if (session.labels.workflows.length)
+                labelBits.push(`workflows: ${session.labels.workflows.join("/")}`);
+            if (session.labels.providers.length)
+                labelBits.push(`providers: ${session.labels.providers.join("/")}`);
+            if (session.labels.user_labels.length)
+                labelBits.push(`labels: ${session.labels.user_labels.join("/")}`);
+            if (labelBits.length)
+                lines.push(`  - ${labelBits.join("; ")}`);
+            for (const line of totalsLines(session.totals))
+                lines.push(`  - ${line}`);
+            for (const line of verificationLines(session.verification))
+                lines.push(`  - ${line}`);
+        }
+    }
+    lines.push("");
+    lines.push("Provider/runtime breakdown (operator-asserted label; 'unlabeled' when absent)");
+    appendBreakdownLines(lines, report.by_provider);
+    lines.push("");
+    lines.push("Project breakdown");
+    appendBreakdownLines(lines, report.by_project);
+    lines.push("");
+    lines.push("Workflow breakdown");
+    appendBreakdownLines(lines, report.by_workflow);
+    lines.push("");
+    lines.push("Evidence labels (every figure carries its label)");
+    for (const [, label] of Object.entries(report.evidence_labels))
+        lines.push(`- ${label}`);
+    lines.push("");
+    lines.push("Skipped run directories");
+    if (report.skipped_run_directories.length === 0)
+        lines.push("- none");
+    else
+        for (const s of report.skipped_run_directories)
+            lines.push(`- ${s.run_directory}: ${s.reason}`);
+    lines.push("");
+    lines.push("Limitations");
+    for (const limitation of report.limitations)
+        lines.push(`- ${limitation}`);
+    return lines.join("\n");
+}
+function appendBreakdownLines(lines, buckets) {
+    if (buckets.length === 0) {
+        lines.push("- none");
+        return;
+    }
+    for (const bucket of buckets) {
+        lines.push(`- ${bucket.key}: ${bucket.totals.compactions} run(s), ${bucket.totals.total_input_tokens_saved} input tokens saved, ${usd(bucket.totals.total_estimated_savings_usd)} estimated savings; readiness ready ${bucket.verification.ready}/conditional ${bucket.verification.conditional}/not_ready ${bucket.verification.not_ready}`);
+    }
+}
+function breakdownRows(buckets) {
+    if (buckets.length === 0)
+        return ["| none | 0 | 0 | $0.000000 | 0 | 0 | 0 |"];
+    return buckets.map((b) => `| ${b.key} | ${b.totals.compactions} | ${b.totals.total_input_tokens_saved} | ${usd(b.totals.total_estimated_savings_usd)} | ${b.verification.ready} | ${b.verification.conditional} | ${b.verification.not_ready} |`);
+}
+export function formatAggregateMarkdown(report) {
+    const t = report.totals;
+    const v = report.verification;
+    const lines = [];
+    lines.push("# Compaction Multi-Session Aggregate");
+    lines.push("");
+    lines.push("Local, file-based rollup across recorded sessions/runs. No hosted dashboard, no upload, no telemetry.");
+    lines.push("");
+    lines.push(`- Source: ${report.source_glob}`);
+    lines.push(`- Generated at: ${report.generated_at}`);
+    lines.push(`- Applied label filters: ${filtersLine(report.applied_filters)}`);
+    lines.push(`- Rollup labels: ${filtersLine(report.rollup_labels)}`);
+    lines.push(`- Sessions: ${report.session_count}`);
+    lines.push("");
+    lines.push("## Cross-session totals");
+    lines.push("");
+    lines.push(`- Runs (compactions): ${t.compactions}`);
+    lines.push(`- Token-evidence split: provider-reported ${t.runs_provider_reported}, local-estimate ${t.runs_local_estimate}, unknown ${t.runs_unknown_token_evidence}`);
+    lines.push(`- Total input tokens before: ${t.total_input_tokens_before}`);
+    lines.push(`- Total input tokens after: ${t.total_input_tokens_after}`);
+    lines.push(`- Total input tokens saved: ${t.total_input_tokens_saved}`);
+    lines.push(`- Total output tokens before: ${t.total_output_tokens_before} (over ${t.runs_with_output_tokens} run(s); ${t.runs_without_output_tokens} unknown)`);
+    lines.push(`- Total output tokens after: ${t.total_output_tokens_after} (over ${t.runs_with_output_tokens} run(s); ${t.runs_without_output_tokens} unknown)`);
+    lines.push(`- Total estimated cost before: ${usd(t.total_estimated_cost_before_usd)} (price-table estimate, NOT billed)`);
+    lines.push(`- Total estimated cost after: ${usd(t.total_estimated_cost_after_usd)} (price-table estimate, NOT billed)`);
+    lines.push(`- Total estimated savings: ${usd(t.total_estimated_savings_usd)}`);
+    lines.push(`- Savings are estimated and summed over the ${t.compactions} recorded run(s) only; NOT billing-confirmed, NOT realized, NOT extrapolated to any time period.`);
+    lines.push("");
+    lines.push("## Cross-session verification");
+    lines.push("");
+    lines.push(`- Readiness: ready ${v.ready}, conditional ${v.conditional}, not_ready ${v.not_ready}, not_evaluated ${v.not_evaluated}`);
+    lines.push(`- Recoverability: pass ${v.recoverability_pass}, fail ${v.recoverability_fail}, not_evaluated ${v.recoverability_not_evaluated}`);
+    lines.push(`- Commitment-preservation: pass ${v.commitment_pass}, fail ${v.commitment_fail}, not_evaluated ${v.commitment_not_evaluated}`);
+    lines.push(`- Task-check: pass ${v.task_check_pass}, fail ${v.task_check_fail}, unsupported ${v.task_check_unsupported}, not_evaluated ${v.task_check_not_evaluated}`);
+    lines.push("");
+    lines.push("## Per-session summary");
+    lines.push("");
+    lines.push("| Session | Runs | Input tokens saved | Estimated savings | ready | conditional | not_ready |");
+    lines.push("| --- | ---: | ---: | ---: | ---: | ---: | ---: |");
+    if (report.sessions.length === 0) {
+        lines.push("| none | 0 | 0 | $0.000000 | 0 | 0 | 0 |");
+    }
+    else {
+        for (const s of report.sessions) {
+            lines.push(`| ${s.session_id}${s.explicit_session_label ? "" : " (run-id)"} | ${s.run_ids.length} | ${s.totals.total_input_tokens_saved} | ${usd(s.totals.total_estimated_savings_usd)} | ${s.verification.ready} | ${s.verification.conditional} | ${s.verification.not_ready} |`);
+        }
+    }
+    lines.push("");
+    lines.push("## Provider/runtime breakdown");
+    lines.push("");
+    lines.push("Provider/runtime is an operator-asserted local label (never provider-verified); 'unlabeled' when absent.");
+    lines.push("");
+    lines.push("| Provider/runtime | Runs | Input tokens saved | Estimated savings | ready | conditional | not_ready |");
+    lines.push("| --- | ---: | ---: | ---: | ---: | ---: | ---: |");
+    for (const row of breakdownRows(report.by_provider))
+        lines.push(row);
+    lines.push("");
+    lines.push("## Project breakdown");
+    lines.push("");
+    lines.push("| Project | Runs | Input tokens saved | Estimated savings | ready | conditional | not_ready |");
+    lines.push("| --- | ---: | ---: | ---: | ---: | ---: | ---: |");
+    for (const row of breakdownRows(report.by_project))
+        lines.push(row);
+    lines.push("");
+    lines.push("## Workflow breakdown");
+    lines.push("");
+    lines.push("| Workflow | Runs | Input tokens saved | Estimated savings | ready | conditional | not_ready |");
+    lines.push("| --- | ---: | ---: | ---: | ---: | ---: | ---: |");
+    for (const row of breakdownRows(report.by_workflow))
+        lines.push(row);
+    lines.push("");
+    lines.push("## Evidence labels");
+    lines.push("");
+    for (const [, label] of Object.entries(report.evidence_labels))
+        lines.push(`- ${label}`);
+    lines.push("");
+    lines.push("## Skipped run directories");
+    lines.push("");
+    if (report.skipped_run_directories.length === 0) {
+        lines.push("- none");
+    }
+    else {
+        for (const s of report.skipped_run_directories)
+            lines.push(`- ${s.run_directory}: ${s.reason}`);
+    }
+    lines.push("");
+    lines.push("## Limitations");
+    lines.push("");
+    for (const limitation of report.limitations)
+        lines.push(`- ${limitation}`);
+    return lines.join("\n");
+}
+const SHARE_INCLUDES = [
+    "aggregate token totals (input before/after/saved; output where recorded)",
+    "token-evidence split (provider-reported vs local-estimate run counts)",
+    "estimated cost + estimated savings totals (price-table estimate; NOT billing-confirmed)",
+    "compaction count + session count",
+    "verification outcome counts (readiness; recoverability / commitment / task-check pass/fail)",
+    "provider/runtime, project, and workflow breakdowns (short label keys + numbers only)",
+    "the local label filters / rollup labels (short operator strings)",
+    "the per-figure evidence labels and limitations"
+];
+const SHARE_EXCLUDES = [
+    "raw trace messages, prompts, completions, tool outputs",
+    "source code / file contents / file paths",
+    "run ids, report paths, run directories",
+    "per-session run id lists",
+    "credentials / tokens / environment variables",
+    "any free-form text from a run"
+];
+function breakdownEntries(buckets) {
+    // WHITELIST: copy ONLY the short label key + numeric aggregates. No run ids, no paths.
+    return buckets.map((b) => ({
+        key: b.key,
+        runs: b.totals.compactions,
+        input_tokens_saved: b.totals.total_input_tokens_saved,
+        estimated_savings_usd: b.totals.total_estimated_savings_usd,
+        ready: b.verification.ready,
+        conditional: b.verification.conditional,
+        not_ready: b.verification.not_ready
+    }));
+}
+/**
+ * Build the CONTENT-FREE aggregate share bundle from an already-aggregated report.
+ *
+ * WHITELIST construction: this copies ONLY numeric totals, enum verification counts, short
+ * label keys/filters, and the static evidence-label/limitation strings. It deliberately
+ * does NOT copy `report.sessions[].run_ids`, `skipped_run_directories` (which carry run
+ * directory paths), or any per-run identifier — so no run id, report path, or trace content
+ * can reach the shared artifact.
+ */
+export function buildAggregateShareBundle(report, generatedAt = new Date().toISOString()) {
+    return {
+        share_bundle_version: SHARE_BUNDLE_VERSION,
+        generated_at: generatedAt,
+        privacy: {
+            content_free: SHARE_CONTENT_FREE_NOTE,
+            upload: SHARE_NO_UPLOAD_NOTE,
+            includes: SHARE_INCLUDES,
+            excludes: SHARE_EXCLUDES
+        },
+        applied_filters: report.applied_filters,
+        rollup_labels: report.rollup_labels,
+        session_count: report.session_count,
+        totals: report.totals,
+        verification: report.verification,
+        by_provider: breakdownEntries(report.by_provider),
+        by_project: breakdownEntries(report.by_project),
+        by_workflow: breakdownEntries(report.by_workflow),
+        evidence_labels: report.evidence_labels,
+        limitations: report.limitations
+    };
+}
+export function formatShareBundleMarkdown(bundle) {
+    const t = bundle.totals;
+    const v = bundle.verification;
+    const lines = [];
+    lines.push("# Compaction Aggregate Share Summary (redacted, content-free)");
+    lines.push("");
+    lines.push("A privacy-safe AGGREGATE summary a developer can hand a founder/admin. It shows value across");
+    lines.push("sessions WITHOUT any raw trace text, prompts, completions, tool output, run ids, or paths.");
+    lines.push("");
+    lines.push(SHARE_CONTENT_FREE_NOTE);
+    lines.push("");
+    lines.push(SHARE_NO_UPLOAD_NOTE);
+    lines.push("");
+    lines.push(`- Bundle version: ${bundle.share_bundle_version}`);
+    lines.push(`- Generated at: ${bundle.generated_at}`);
+    lines.push(`- Applied label filters: ${filtersLine(bundle.applied_filters)}`);
+    lines.push(`- Rollup labels: ${filtersLine(bundle.rollup_labels)}`);
+    lines.push(`- Sessions: ${bundle.session_count}`);
+    lines.push("");
+    lines.push("## Aggregate value (estimated, summed over recorded runs)");
+    lines.push("");
+    lines.push(`- Compactions: ${t.compactions}`);
+    lines.push(`- Token-evidence split: provider-reported ${t.runs_provider_reported}, local-estimate ${t.runs_local_estimate}, unknown ${t.runs_unknown_token_evidence}`);
+    lines.push(`- Input tokens saved: ${t.total_input_tokens_saved}`);
+    lines.push(`- Output tokens before/after: ${t.total_output_tokens_before}/${t.total_output_tokens_after} (over ${t.runs_with_output_tokens} run(s); ${t.runs_without_output_tokens} unknown)`);
+    lines.push(`- Estimated cost before/after: ${usd(t.total_estimated_cost_before_usd)} / ${usd(t.total_estimated_cost_after_usd)} (price-table estimate, NOT billed)`);
+    lines.push(`- Estimated savings: ${usd(t.total_estimated_savings_usd)} (estimated, summed over ${t.compactions} recorded run(s); NOT billing-confirmed, NOT realized, NOT extrapolated)`);
+    lines.push("");
+    lines.push("## Verification outcomes");
+    lines.push("");
+    lines.push(`- Readiness: ready ${v.ready}, conditional ${v.conditional}, not_ready ${v.not_ready}, not_evaluated ${v.not_evaluated}`);
+    lines.push(`- Recoverability: pass ${v.recoverability_pass}, fail ${v.recoverability_fail}, not_evaluated ${v.recoverability_not_evaluated}`);
+    lines.push(`- Commitment-preservation: pass ${v.commitment_pass}, fail ${v.commitment_fail}, not_evaluated ${v.commitment_not_evaluated}`);
+    lines.push(`- Task-check: pass ${v.task_check_pass}, fail ${v.task_check_fail}, unsupported ${v.task_check_unsupported}, not_evaluated ${v.task_check_not_evaluated}`);
+    lines.push("");
+    lines.push("## Provider/runtime breakdown (operator-asserted label)");
+    lines.push("");
+    lines.push("| Provider/runtime | Runs | Input tokens saved | Estimated savings | ready | conditional | not_ready |");
+    lines.push("| --- | ---: | ---: | ---: | ---: | ---: | ---: |");
+    if (bundle.by_provider.length === 0)
+        lines.push("| none | 0 | 0 | $0.000000 | 0 | 0 | 0 |");
+    else
+        for (const b of bundle.by_provider) {
+            lines.push(`| ${b.key} | ${b.runs} | ${b.input_tokens_saved} | ${usd(b.estimated_savings_usd)} | ${b.ready} | ${b.conditional} | ${b.not_ready} |`);
+        }
+    lines.push("");
+    lines.push("## What this share summary INCLUDES");
+    lines.push("");
+    for (const item of bundle.privacy.includes)
+        lines.push(`- ${item}`);
+    lines.push("");
+    lines.push("## What it EXCLUDES (never written)");
+    lines.push("");
+    for (const item of bundle.privacy.excludes)
+        lines.push(`- ${item}`);
+    lines.push("");
+    lines.push("## Evidence labels");
+    lines.push("");
+    for (const [, label] of Object.entries(bundle.evidence_labels))
+        lines.push(`- ${label}`);
+    lines.push("");
+    lines.push("## Limitations");
+    lines.push("");
+    for (const limitation of bundle.limitations)
+        lines.push(`- ${limitation}`);
+    return lines.join("\n");
+}
+export { AGGREGATE_EVIDENCE_LABELS };
+//# sourceMappingURL=aggregate-format.js.map

package/dist/core/api-client/client.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Compaction API client — transport (PUBLIC CLI/SDK code).
+ *
+ * Speaks ONLY the documented HTTP contract (`docs/api/compaction-api-v0.md`). NO engine import,
+ * NO auto-upload, NO call at import time. A content-bearing send is gated TWICE: the request
+ * body must carry `consent.upload_permitted === true` AND the caller must pass an explicit
+ * `confirmed: true` — otherwise `sendRequest` throws BEFORE any network call. Timeout is
+ * bounded; content-bearing requests are NEVER auto-retried (re-sending content must be a fresh,
+ * explicitly-confirmed action). See `docs/ops/cli-api-client-design.md` §7, §9.
+ */
+import { type ApiConfig } from "./config.js";
+import type { ApiErrorBody, ApiRequestBody, StatusResponse } from "./types.js";
+export declare class ApiNotConfirmedError extends Error {
+    constructor(message: string);
+}
+export declare class ApiTransportError extends Error {
+    constructor(message: string);
+}
+export interface ApiResponse<T> {
+    ok: boolean;
+    status: number;
+    body: T | ApiErrorBody;
+}
+/**
+ * `GET /v0/status`. Content-free and idempotent → MAY retry on transient transport errors only.
+ * Never retries on a non-2xx HTTP status (a coded error is not transient).
+ */
+export declare function apiStatus(config: ApiConfig): Promise<ApiResponse<StatusResponse>>;
+export interface SendOptions {
+    /** Explicit caller confirmation. REQUIRED (in addition to body consent) for content-bearing sends. */
+    confirmed?: boolean;
+}
+/**
+ * Send a payload-bearing request to one of the engine-backed endpoints.
+ *
+ * NO AUTO-UPLOAD: when `payloadClass` is content-bearing, this throws `ApiNotConfirmedError`
+ * BEFORE any network call unless BOTH (a) `body.consent.upload_permitted === true` and
+ * (b) `options.confirmed === true`. A content-bearing request is NEVER auto-retried.
+ *
+ * Content-free requests are sent once (the boundary is preserved on the server too, which
+ * fail-closes the same way). This function never persists or logs the body or the API key.
+ */
+export declare function sendRequest<T>(config: ApiConfig, path: string, body: ApiRequestBody, options?: SendOptions): Promise<ApiResponse<T>>;

package/dist/core/api-client/client.js

@@ -0,0 +1,143 @@
+/**
+ * Compaction API client — transport (PUBLIC CLI/SDK code).
+ *
+ * Speaks ONLY the documented HTTP contract (`docs/api/compaction-api-v0.md`). NO engine import,
+ * NO auto-upload, NO call at import time. A content-bearing send is gated TWICE: the request
+ * body must carry `consent.upload_permitted === true` AND the caller must pass an explicit
+ * `confirmed: true` — otherwise `sendRequest` throws BEFORE any network call. Timeout is
+ * bounded; content-bearing requests are NEVER auto-retried (re-sending content must be a fresh,
+ * explicitly-confirmed action). See `docs/ops/cli-api-client-design.md` §7, §9.
+ */
+import { buildHeaders } from "./config.js";
+import { bodyContainsInlineContent, ConsentError, isContentBearing } from "./payload.js";
+export class ApiNotConfirmedError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ApiNotConfirmedError";
+    }
+}
+export class ApiTransportError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ApiTransportError";
+    }
+}
+const TRANSIENT_RETRIES = 2;
+const RETRY_BACKOFF_MS = 250;
+function isTransientTransportError(err) {
+    // Node fetch wraps connection failures; a timeout is an AbortError (not transient-retryable
+    // here because the caller asked for a bounded wait). We treat only connect/reset/DNS-style
+    // failures as transient.
+    const code = err?.cause?.code;
+    return (code === "ECONNREFUSED" ||
+        code === "ECONNRESET" ||
+        code === "ENOTFOUND" ||
+        code === "EAI_AGAIN");
+}
+async function fetchWithTimeout(url, init, timeoutMs) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        return await fetch(url, { ...init, signal: controller.signal });
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+async function parseBody(res) {
+    const text = await res.text();
+    if (text.trim() === "")
+        return {};
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return { error: "invalid_response", details: "non-JSON response body" };
+    }
+}
+/**
+ * `GET /v0/status`. Content-free and idempotent → MAY retry on transient transport errors only.
+ * Never retries on a non-2xx HTTP status (a coded error is not transient).
+ */
+export async function apiStatus(config) {
+    const url = `${config.url}/v0/status`;
+    let lastErr;
+    for (let attempt = 0; attempt <= TRANSIENT_RETRIES; attempt++) {
+        try {
+            const res = await fetchWithTimeout(url, { method: "GET", headers: buildHeaders(config) }, config.timeoutMs);
+            const body = await parseBody(res);
+            return { ok: res.ok, status: res.status, body };
+        }
+        catch (err) {
+            lastErr = err;
+            if (!isTransientTransportError(err) || attempt === TRANSIENT_RETRIES)
+                break;
+            await new Promise((r) => setTimeout(r, RETRY_BACKOFF_MS * (attempt + 1)));
+        }
+    }
+    throw new ApiTransportError(`could not reach the Compaction API at ${config.url} (${String(lastErr?.message ?? lastErr)})`);
+}
+/**
+ * Send a payload-bearing request to one of the engine-backed endpoints.
+ *
+ * NO AUTO-UPLOAD: when `payloadClass` is content-bearing, this throws `ApiNotConfirmedError`
+ * BEFORE any network call unless BOTH (a) `body.consent.upload_permitted === true` and
+ * (b) `options.confirmed === true`. A content-bearing request is NEVER auto-retried.
+ *
+ * Content-free requests are sent once (the boundary is preserved on the server too, which
+ * fail-closes the same way). This function never persists or logs the body or the API key.
+ */
+export async function sendRequest(config, path, body, options = {}) {
+    const payloadClass = body.payload_class;
+    const declaredContentBearing = isContentBearing(payloadClass);
+    // DEFENSE-IN-DEPTH, FAIL-CLOSED: the gate is driven by what the body ACTUALLY contains, not by
+    // its declared `payload_class`. Because the exported API accepts caller-built bodies, a body can
+    // declare a content-free class (`metrics_only`/`redacted_structure`) while still carrying inline
+    // raw content in `trace.content` / `original_trace.content` / `compacted_context.content`. We
+    // inspect the real body BEFORE any fetch.
+    const actuallyCarriesContent = bodyContainsInlineContent(body);
+    // A content-free class that ACTUALLY carries inline content is itself an error — reject (the
+    // safest option) rather than silently strip-and-send. The label lied about the body.
+    if (!declaredContentBearing && actuallyCarriesContent) {
+        throw new ConsentError(`consent_required: payload_class "${payloadClass ?? "metrics_only"}" is declared content-free ` +
+            "but the body carries inline raw content (trace.content / original_trace.content / " +
+            "compacted_context.content). A content-free class must carry zero inline content — refusing to send.");
+    }
+    // Any body that actually carries inline content (whatever its declared class) requires BOTH
+    // explicit upload consent AND an explicit confirm before it may leave the machine.
+    if (declaredContentBearing || actuallyCarriesContent) {
+        const uploadPermitted = body.consent?.upload_permitted === true;
+        if (!uploadPermitted) {
+            throw new ApiNotConfirmedError(`refusing to send: body carries inline content but consent.upload_permitted is not true`);
+        }
+        if (options.confirmed !== true) {
+            throw new ApiNotConfirmedError(`refusing to send: content-bearing payload requires an explicit confirm (preview then confirm) before upload`);
+        }
+    }
+    const contentBearing = declaredContentBearing || actuallyCarriesContent;
+    const url = `${config.url}${path}`;
+    const init = {
+        method: "POST",
+        headers: buildHeaders(config),
+        body: JSON.stringify(body)
+    };
+    // Content-bearing requests are NEVER auto-retried. Content-free requests may retry on
+    // transient transport errors only.
+    const maxAttempts = contentBearing ? 0 : TRANSIENT_RETRIES;
+    let lastErr;
+    for (let attempt = 0; attempt <= maxAttempts; attempt++) {
+        try {
+            const res = await fetchWithTimeout(url, init, config.timeoutMs);
+            const parsed = await parseBody(res);
+            return { ok: res.ok, status: res.status, body: parsed };
+        }
+        catch (err) {
+            lastErr = err;
+            if (!isTransientTransportError(err) || attempt === maxAttempts)
+                break;
+            await new Promise((r) => setTimeout(r, RETRY_BACKOFF_MS * (attempt + 1)));
+        }
+    }
+    throw new ApiTransportError(`could not reach the Compaction API at ${config.url} (${String(lastErr?.message ?? lastErr)})`);
+}
+//# sourceMappingURL=client.js.map

package/dist/core/api-client/config.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Compaction API client — configuration (PUBLIC CLI/SDK code).
+ *
+ * Reads env ONLY. Persists NOTHING. The default URL is the LOCAL-DEV server
+ * (`127.0.0.1`); there is no remote URL baked into the public package. The API key
+ * (when set) is attached as a bearer token at call time and is NEVER persisted, logged,
+ * or printed. See `docs/ops/cli-api-client-design.md` §1.
+ */
+/** Local-dev default. Deliberately NOT a remote URL — a fresh checkout talks to a LOCAL server. */
+export declare const DEFAULT_API_URL = "http://127.0.0.1:8787";
+/** Default per-request timeout. Override with `COMPACTION_API_TIMEOUT_MS`. */
+export declare const DEFAULT_TIMEOUT_MS = 30000;
+export interface ApiConfig {
+    /** Resolved base URL (no trailing slash). */
+    url: string;
+    /** Optional bearer token. `undefined` when `COMPACTION_API_KEY` is unset. */
+    apiKey?: string;
+    /** Per-request timeout in milliseconds. */
+    timeoutMs: number;
+}
+/** A minimal env shape so this is pure/testable (defaults to `process.env`). */
+export type EnvLike = Record<string, string | undefined>;
+/**
+ * Resolve API config from the environment. Pure: same env in → same config out. Never reads
+ * or writes any file and never mutates the env.
+ *
+ *  - `COMPACTION_API_URL`     → base URL (default LOCAL `127.0.0.1:8787`).
+ *  - `COMPACTION_API_KEY`     → optional bearer token (unset by default).
+ *  - `COMPACTION_API_TIMEOUT_MS` → optional positive integer timeout.
+ */
+export declare function resolveApiConfig(env?: EnvLike): ApiConfig;
+/**
+ * Build request headers. The API key (when present) is attached as a bearer token. Returns a
+ * fresh object each call; the key is never stored elsewhere.
+ */
+export declare function buildHeaders(config: ApiConfig): Record<string, string>;