@compaction/cli 0.1.0

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

@@ -0,0 +1,79 @@
+import type { AgentTrace } from "./types.js";
+/** Algorithm identifier surfaced alongside the digest so the signal is self-describing. */
+export declare const TRACE_FINGERPRINT_ALGORITHM = "sha256-canonical-content-v1";
+/**
+ * A non-sensitive per-run distinctness fingerprint for a captured trace.
+ *
+ * Every field here is non-sensitive: a hex digest plus structural counts. There is
+ * NO message/prompt/tool-output text in this object.
+ */
+export interface TraceFingerprint {
+    /** Algorithm + canonicalization version (so the digest is interpretable later). */
+    algorithm: string;
+    /**
+     * Hex SHA-256 digest over the canonical normalized trace content. One-way digest
+     * ONLY — never raw content. Same session → same value; different session → different.
+     */
+    content_sha256: string;
+    /** Non-sensitive structural count: number of messages hashed. */
+    message_count: number;
+}
+/**
+ * Compute the per-run distinctness fingerprint for a captured trace.
+ *
+ * Returns a digest-only object. The raw `canonicalContent` is consumed by the hash
+ * and discarded; it is never returned or stored. This is the smallest safe
+ * distinctness signal: it distinguishes a genuinely different session from a
+ * re-capture of the same session without exposing any session content.
+ */
+export declare function computeTraceFingerprint(trace: AgentTrace): TraceFingerprint;
+/**
+ * Minimal per-run record the distinctness classifier needs. Carries ONLY a
+ * non-sensitive fingerprint digest (optional) — no content, no aggregate metrics
+ * masquerading as proof. A record whose fingerprint is absent/unverifiable is
+ * counted as `not_verified`, NEVER as distinct.
+ */
+export interface DistinctnessRecord {
+    /** Stable per-run identifier for reporting (e.g. session id or run dir). Non-sensitive. */
+    runId: string;
+    /**
+     * The verifiable distinctness digest, when available. When undefined/empty, the
+     * run's distinctness is NOT verified and it does not contribute to the distinct
+     * count.
+     */
+    content_sha256?: string | null;
+}
+export interface DistinctnessResult {
+    /**
+     * Number of DISTINCT verified sessions: the count of unique non-empty
+     * `content_sha256` values. Re-captures (same digest) collapse to one.
+     */
+    distinct_verified_count: number;
+    /** The unique verified fingerprints (sorted), for citation. */
+    distinct_fingerprints: string[];
+    /**
+     * Run ids whose distinctness could NOT be verified (missing/empty fingerprint).
+     * These are reported as `not_verified` and are NOT added to the distinct count.
+     */
+    not_verified_run_ids: string[];
+    /**
+     * Total runs considered (verified-distinct contributions + duplicates +
+     * not_verified). Provided so a report can never silently drop runs.
+     */
+    total_runs: number;
+}
+/**
+ * Classify a set of per-run records into a de-duplicated distinct count plus an
+ * explicit `not_verified` bucket.
+ *
+ * Rules (the anti-overcount contract):
+ * - same fingerprint  → counted once (de-dup).
+ * - different fingerprint → counted as distinct.
+ * - missing/empty fingerprint → `not_verified`; does NOT inflate the distinct count.
+ *
+ * Aggregate metrics are intentionally NOT an input here: matching aggregates alone
+ * never makes two runs "the same", and unverifiable distinctness is never upgraded
+ * to distinct. The fingerprint is the only signal that moves a run into the
+ * verified-distinct set.
+ */
+export declare function classifyDistinctness(records: readonly DistinctnessRecord[]): DistinctnessResult;

package/dist/core/trace-fingerprint.js

@@ -0,0 +1,102 @@
+import { contentHash } from "./content-hash.js";
+/**
+ * Per-run trace distinctness fingerprint.
+ *
+ * PURPOSE (evidence integrity): give each captured run a verifiable, non-sensitive
+ * distinctness signal so that genuinely-different sessions are distinguishable from
+ * re-captures of the SAME session. This prevents over-counting `real_captured` N
+ * (the prior failure mode: re-running capture over the same 3 static sessions and
+ * reporting them as new because distinctness was asserted by size/date, not verified).
+ *
+ * PRIVACY (load-bearing): the emitted value is a one-way SHA-256 DIGEST ONLY. Raw
+ * message content, prompts, completions, tool output, file contents, and secrets are
+ * fed INTO the hash (one-way) and are NEVER emitted. `computeTraceFingerprint`
+ * returns only the hex digest + non-sensitive structural counts; it returns no
+ * message text. Asserting non-content is also covered by a dedicated test
+ * (`tests/core/trace-fingerprint.test.ts`).
+ *
+ * WHAT IS HASHED (the canonical normalized trace content): the ordered message
+ * stream as `role | toolName | content`, joined with control-character separators,
+ * prefixed with the model. Capture-time-varying fields (capturedAt / generatedAt
+ * timestamps, absolute source path, the fingerprint field itself, durationMs) are
+ * deliberately EXCLUDED so the same session captured twice yields the SAME
+ * fingerprint, while a genuinely different session yields a different one.
+ *
+ * HONESTY: this is a distinctness signal, NOT a "byte-identical sessions" claim and
+ * NOT a semantic/billing/commitment claim. If only aggregate metrics match but no
+ * fingerprint is available, distinctness is reported as `not_verified` — never
+ * inflated into a distinct count. See `classifyDistinctness`.
+ */
+/**
+ * Field/record separators inside the canonical content string. ASCII control
+ * characters (Unit Separator U+001F / Record Separator U+001E) are used so message
+ * text cannot accidentally forge a record boundary (collision-resistance of the
+ * canonicalization). Built via String.fromCharCode so no raw control chars sit in source.
+ */
+const FIELD_SEP = String.fromCharCode(0x1f);
+const RECORD_SEP = String.fromCharCode(0x1e);
+/**
+ * Build the canonical content string that the fingerprint digests.
+ *
+ * INTERNAL ONLY — this string contains raw message content and MUST NOT be emitted
+ * anywhere. It exists solely as input to the one-way hash. Callers receive only the
+ * resulting digest from `computeTraceFingerprint`.
+ */
+function canonicalContent(trace) {
+    const head = `model${FIELD_SEP}${trace.model}`;
+    const body = trace.messages
+        .map((m) => [m.role, m.toolName ?? "", m.content].join(FIELD_SEP))
+        .join(RECORD_SEP);
+    return head + RECORD_SEP + body;
+}
+/** Algorithm identifier surfaced alongside the digest so the signal is self-describing. */
+export const TRACE_FINGERPRINT_ALGORITHM = "sha256-canonical-content-v1";
+/**
+ * Compute the per-run distinctness fingerprint for a captured trace.
+ *
+ * Returns a digest-only object. The raw `canonicalContent` is consumed by the hash
+ * and discarded; it is never returned or stored. This is the smallest safe
+ * distinctness signal: it distinguishes a genuinely different session from a
+ * re-capture of the same session without exposing any session content.
+ */
+export function computeTraceFingerprint(trace) {
+    return {
+        algorithm: TRACE_FINGERPRINT_ALGORITHM,
+        content_sha256: contentHash(canonicalContent(trace)),
+        message_count: trace.messages.length
+    };
+}
+/**
+ * Classify a set of per-run records into a de-duplicated distinct count plus an
+ * explicit `not_verified` bucket.
+ *
+ * Rules (the anti-overcount contract):
+ * - same fingerprint  → counted once (de-dup).
+ * - different fingerprint → counted as distinct.
+ * - missing/empty fingerprint → `not_verified`; does NOT inflate the distinct count.
+ *
+ * Aggregate metrics are intentionally NOT an input here: matching aggregates alone
+ * never makes two runs "the same", and unverifiable distinctness is never upgraded
+ * to distinct. The fingerprint is the only signal that moves a run into the
+ * verified-distinct set.
+ */
+export function classifyDistinctness(records) {
+    const verified = new Set();
+    const notVerified = [];
+    for (const r of records) {
+        const fp = r.content_sha256;
+        if (typeof fp === "string" && fp.length > 0) {
+            verified.add(fp);
+        }
+        else {
+            notVerified.push(r.runId);
+        }
+    }
+    return {
+        distinct_verified_count: verified.size,
+        distinct_fingerprints: [...verified].sort(),
+        not_verified_run_ids: notVerified,
+        total_runs: records.length
+    };
+}
+//# sourceMappingURL=trace-fingerprint.js.map

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

@@ -0,0 +1,41 @@
+import { type TraceAdapterSource, type TraceAdapterStatus } from "./trace-adapters.js";
+import type { AgentTrace } from "./types.js";
+export type TraceIntakeSource = TraceAdapterSource;
+export type TraceIntakeStatus = TraceAdapterStatus;
+/**
+ * Filename for the normalized AgentTrace written by `import`. This deliberately matches the
+ * `captured-trace.json` produced by every `capture` command so the documented follow-up chain
+ * (`compaction analyze ./my-trace/captured-trace.json`, etc., printed by `compaction init`)
+ * resolves identically whether the trace came from capture or import. Keeping the import output
+ * name distinct from the capture output name previously broke the copy-pasteable init chain.
+ */
+export declare const IMPORTED_TRACE_FILENAME = "captured-trace.json";
+export interface TraceIntakeReport {
+    input_path: string;
+    source: TraceIntakeSource;
+    adapter_id: TraceIntakeSource;
+    status: TraceIntakeStatus;
+    generated_at: string;
+    output_trace_id: string | null;
+    message_count: number;
+    supported_format_detected: boolean;
+    warnings: string[];
+    failures: string[];
+    normalization_steps: string[];
+    skipped_fields: string[];
+    source_metadata: Record<string, unknown>;
+    recommended_next_command: string | null;
+}
+export interface TraceIntakeArtifacts {
+    report: TraceIntakeReport;
+    normalizedTrace: AgentTrace | null;
+    paths: {
+        normalizedTracePath: string;
+        intakeReportJsonPath: string;
+        intakeReportMarkdownPath: string;
+    };
+}
+export interface ImportTraceOptions {
+    operatorExport?: boolean;
+}
+export declare function importTraceFile(inputPath: string, source: string, outputDirectory: string, options?: ImportTraceOptions): Promise<TraceIntakeArtifacts>;

package/dist/core/trace-intake.js

@@ -0,0 +1,164 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { assertTraceAdapterSource, getTraceAdapter, parseTraceAdapterRawContent } from "./trace-adapters.js";
+/**
+ * Filename for the normalized AgentTrace written by `import`. This deliberately matches the
+ * `captured-trace.json` produced by every `capture` command so the documented follow-up chain
+ * (`compaction analyze ./my-trace/captured-trace.json`, etc., printed by `compaction init`)
+ * resolves identically whether the trace came from capture or import. Keeping the import output
+ * name distinct from the capture output name previously broke the copy-pasteable init chain.
+ */
+export const IMPORTED_TRACE_FILENAME = "captured-trace.json";
+function markdownList(values, emptyText) {
+    if (values.length === 0) {
+        return `- ${emptyText}`;
+    }
+    return values.map((value) => `- ${value}`).join("\n");
+}
+function formatMetadata(metadata) {
+    const entries = Object.entries(metadata);
+    if (entries.length === 0) {
+        return "- No source metadata.";
+    }
+    return entries.map(([key, value]) => `- ${key}: ${String(value)}`).join("\n");
+}
+function formatIntakeReportMarkdown(report) {
+    return [
+        "# Trace Intake Report",
+        "",
+        "## Summary",
+        "",
+        `- Status: ${report.status}`,
+        `- Supported format detected: ${report.supported_format_detected ? "yes" : "no"}`,
+        `- Output trace ID: ${report.output_trace_id ?? "none"}`,
+        `- Message count: ${report.message_count}`,
+        `- Generated at: ${report.generated_at}`,
+        "",
+        "## Source",
+        "",
+        `- Input path: ${report.input_path}`,
+        `- Requested source: ${report.source}`,
+        `- Adapter: ${report.adapter_id}`,
+        "",
+        "## Source Metadata",
+        "",
+        formatMetadata(report.source_metadata),
+        "",
+        "## Normalization",
+        "",
+        markdownList(report.normalization_steps, "No normalization steps were applied."),
+        "",
+        "## Warnings",
+        "",
+        markdownList(report.warnings, "No warnings."),
+        "",
+        "## Failures",
+        "",
+        markdownList(report.failures, "No failures."),
+        "",
+        "## Recommended Next Command",
+        "",
+        report.recommended_next_command ? `\`${report.recommended_next_command}\`` : "No next command is recommended until intake succeeds.",
+        "",
+        "## Limitations",
+        "",
+        "- External Trace Intake v0 is local and file-based only.",
+        "- Trace adapters are local file normalizers, not live runtime/provider integrations.",
+        "- It does not upload data or call model/provider APIs.",
+        "- Live provider/runtime integrations are future work; source-backed adapters read only local export files.",
+        "- Codex exec JSONL support is limited to local files and does not launch Codex or call provider APIs.",
+        "- Unsupported fields are preserved only when they fit the internal AgentTrace message metadata shape.",
+        ""
+    ].join("\n");
+}
+function buildReport(params) {
+    return {
+        input_path: params.inputPath,
+        source: params.source,
+        adapter_id: params.adapterId,
+        status: params.status,
+        generated_at: params.generatedAt,
+        output_trace_id: params.outputTraceId,
+        message_count: params.messageCount,
+        supported_format_detected: params.supportedFormatDetected,
+        warnings: params.warnings,
+        failures: params.failures,
+        normalization_steps: params.normalizationSteps,
+        skipped_fields: params.skippedFields,
+        source_metadata: params.sourceMetadata,
+        recommended_next_command: params.status === "fail" ? null : `compaction analyze ${params.normalizedTracePath}`
+    };
+}
+async function writeIntakeArtifacts(outputDirectory, report, normalizedTrace) {
+    await mkdir(outputDirectory, { recursive: true });
+    const normalizedTracePath = path.join(outputDirectory, IMPORTED_TRACE_FILENAME);
+    const intakeReportJsonPath = path.join(outputDirectory, "intake-report.json");
+    const intakeReportMarkdownPath = path.join(outputDirectory, "intake-report.md");
+    if (normalizedTrace) {
+        await writeFile(normalizedTracePath, `${JSON.stringify(normalizedTrace, null, 2)}\n`, "utf8");
+    }
+    await writeFile(intakeReportJsonPath, `${JSON.stringify(report, null, 2)}\n`, "utf8");
+    await writeFile(intakeReportMarkdownPath, formatIntakeReportMarkdown(report), "utf8");
+    return {
+        report,
+        normalizedTrace,
+        paths: {
+            normalizedTracePath,
+            intakeReportJsonPath,
+            intakeReportMarkdownPath
+        }
+    };
+}
+export async function importTraceFile(inputPath, source, outputDirectory, options = {}) {
+    assertTraceAdapterSource(source);
+    const rawContent = await readFile(inputPath, "utf8");
+    const generatedAt = new Date().toISOString();
+    const normalizedTracePath = path.join(outputDirectory, IMPORTED_TRACE_FILENAME);
+    const adapter = getTraceAdapter(source);
+    const parsedInput = parseTraceAdapterRawContent(rawContent, source);
+    if (parsedInput.failures.length > 0 || parsedInput.input === null) {
+        const report = buildReport({
+            inputPath,
+            source,
+            adapterId: adapter.id,
+            status: "fail",
+            generatedAt,
+            outputTraceId: null,
+            messageCount: 0,
+            supportedFormatDetected: false,
+            warnings: [],
+            failures: parsedInput.failures,
+            normalizationSteps: parsedInput.normalization_steps,
+            skippedFields: [],
+            sourceMetadata: {
+                adapter_id: adapter.id,
+                supported_source: adapter.supportedSource,
+                local_file_normalizer: true,
+                live_provider_integration: false,
+                ...parsedInput.source_metadata
+            },
+            normalizedTracePath
+        });
+        return writeIntakeArtifacts(outputDirectory, report, null);
+    }
+    const result = adapter.normalize(parsedInput.input, { rawContent, operatorExport: options.operatorExport === true });
+    const normalizedTrace = result.trace;
+    const report = buildReport({
+        inputPath,
+        source,
+        adapterId: adapter.id,
+        status: result.status,
+        generatedAt,
+        outputTraceId: normalizedTrace?.id ?? null,
+        messageCount: normalizedTrace?.messages.length ?? 0,
+        supportedFormatDetected: normalizedTrace !== null,
+        warnings: result.warnings,
+        failures: result.failures,
+        normalizationSteps: [...parsedInput.normalization_steps, ...result.normalization_steps],
+        skippedFields: result.skipped_fields,
+        sourceMetadata: { ...parsedInput.source_metadata, ...result.source_metadata },
+        normalizedTracePath
+    });
+    return writeIntakeArtifacts(outputDirectory, report, result.status === "fail" ? null : normalizedTrace);
+}
+//# sourceMappingURL=trace-intake.js.map

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

@@ -0,0 +1,203 @@
+import { z } from "zod";
+import type { AgentTrace } from "./types.js";
+export declare const CURRENT_AGENT_TRACE_ARTIFACT_VERSION = "agent-trace-v1";
+export declare const agentTraceSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    artifactVersion: z.ZodOptional<z.ZodString>;
+    artifact_version: z.ZodOptional<z.ZodString>;
+    source: z.ZodOptional<z.ZodEnum<["manual", "cli_wrapper", "local_command", "demo", "real_captured", "provider_usage", "codex_import"]>>;
+    createdAt: z.ZodOptional<z.ZodString>;
+    created_at: z.ZodOptional<z.ZodString>;
+    generatedAt: z.ZodOptional<z.ZodString>;
+    generated_at: z.ZodOptional<z.ZodString>;
+    model: z.ZodString;
+    command: z.ZodOptional<z.ZodObject<{
+        command: z.ZodString;
+        args: z.ZodArray<z.ZodString, "many">;
+        cwd: z.ZodOptional<z.ZodString>;
+        shell: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        command: string;
+        args: string[];
+        cwd?: string | undefined;
+        shell?: string | undefined;
+    }, {
+        command: string;
+        args: string[];
+        cwd?: string | undefined;
+        shell?: string | undefined;
+    }>>;
+    durationMs: z.ZodOptional<z.ZodNumber>;
+    duration_ms: z.ZodOptional<z.ZodNumber>;
+    exitCode: z.ZodOptional<z.ZodNumber>;
+    exit_code: z.ZodOptional<z.ZodNumber>;
+    messages: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        role: z.ZodEnum<["system", "user", "assistant", "tool", "stdout", "stderr"]>;
+        content: z.ZodString;
+        timestamp: z.ZodString;
+        toolName: z.ZodOptional<z.ZodString>;
+        metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        role: "system" | "user" | "assistant" | "tool" | "stdout" | "stderr";
+        content: string;
+        timestamp: string;
+        toolName?: string | undefined;
+        metadata?: Record<string, unknown> | undefined;
+    }, {
+        id: string;
+        role: "system" | "user" | "assistant" | "tool" | "stdout" | "stderr";
+        content: string;
+        timestamp: string;
+        toolName?: string | undefined;
+        metadata?: Record<string, unknown> | undefined;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    model: string;
+    id: string;
+    title: string;
+    messages: {
+        id: string;
+        role: "system" | "user" | "assistant" | "tool" | "stdout" | "stderr";
+        content: string;
+        timestamp: string;
+        toolName?: string | undefined;
+        metadata?: Record<string, unknown> | undefined;
+    }[];
+    command?: {
+        command: string;
+        args: string[];
+        cwd?: string | undefined;
+        shell?: string | undefined;
+    } | undefined;
+    artifactVersion?: string | undefined;
+    artifact_version?: string | undefined;
+    source?: "manual" | "cli_wrapper" | "local_command" | "demo" | "real_captured" | "provider_usage" | "codex_import" | undefined;
+    createdAt?: string | undefined;
+    created_at?: string | undefined;
+    generatedAt?: string | undefined;
+    generated_at?: string | undefined;
+    durationMs?: number | undefined;
+    duration_ms?: number | undefined;
+    exitCode?: number | undefined;
+    exit_code?: number | undefined;
+}, {
+    model: string;
+    id: string;
+    title: string;
+    messages: {
+        id: string;
+        role: "system" | "user" | "assistant" | "tool" | "stdout" | "stderr";
+        content: string;
+        timestamp: string;
+        toolName?: string | undefined;
+        metadata?: Record<string, unknown> | undefined;
+    }[];
+    command?: {
+        command: string;
+        args: string[];
+        cwd?: string | undefined;
+        shell?: string | undefined;
+    } | undefined;
+    artifactVersion?: string | undefined;
+    artifact_version?: string | undefined;
+    source?: "manual" | "cli_wrapper" | "local_command" | "demo" | "real_captured" | "provider_usage" | "codex_import" | undefined;
+    createdAt?: string | undefined;
+    created_at?: string | undefined;
+    generatedAt?: string | undefined;
+    generated_at?: string | undefined;
+    durationMs?: number | undefined;
+    duration_ms?: number | undefined;
+    exitCode?: number | undefined;
+    exit_code?: number | undefined;
+}>, {
+    model: string;
+    id: string;
+    title: string;
+    messages: {
+        id: string;
+        role: "system" | "user" | "assistant" | "tool" | "stdout" | "stderr";
+        content: string;
+        timestamp: string;
+        toolName?: string | undefined;
+        metadata?: Record<string, unknown> | undefined;
+    }[];
+    command?: {
+        command: string;
+        args: string[];
+        cwd?: string | undefined;
+        shell?: string | undefined;
+    } | undefined;
+    artifactVersion?: string | undefined;
+    artifact_version?: string | undefined;
+    source?: "manual" | "cli_wrapper" | "local_command" | "demo" | "real_captured" | "provider_usage" | "codex_import" | undefined;
+    createdAt?: string | undefined;
+    created_at?: string | undefined;
+    generatedAt?: string | undefined;
+    generated_at?: string | undefined;
+    durationMs?: number | undefined;
+    duration_ms?: number | undefined;
+    exitCode?: number | undefined;
+    exit_code?: number | undefined;
+}, {
+    model: string;
+    id: string;
+    title: string;
+    messages: {
+        id: string;
+        role: "system" | "user" | "assistant" | "tool" | "stdout" | "stderr";
+        content: string;
+        timestamp: string;
+        toolName?: string | undefined;
+        metadata?: Record<string, unknown> | undefined;
+    }[];
+    command?: {
+        command: string;
+        args: string[];
+        cwd?: string | undefined;
+        shell?: string | undefined;
+    } | undefined;
+    artifactVersion?: string | undefined;
+    artifact_version?: string | undefined;
+    source?: "manual" | "cli_wrapper" | "local_command" | "demo" | "real_captured" | "provider_usage" | "codex_import" | undefined;
+    createdAt?: string | undefined;
+    created_at?: string | undefined;
+    generatedAt?: string | undefined;
+    generated_at?: string | undefined;
+    durationMs?: number | undefined;
+    duration_ms?: number | undefined;
+    exitCode?: number | undefined;
+    exit_code?: number | undefined;
+}>, AgentTrace, {
+    model: string;
+    id: string;
+    title: string;
+    messages: {
+        id: string;
+        role: "system" | "user" | "assistant" | "tool" | "stdout" | "stderr";
+        content: string;
+        timestamp: string;
+        toolName?: string | undefined;
+        metadata?: Record<string, unknown> | undefined;
+    }[];
+    command?: {
+        command: string;
+        args: string[];
+        cwd?: string | undefined;
+        shell?: string | undefined;
+    } | undefined;
+    artifactVersion?: string | undefined;
+    artifact_version?: string | undefined;
+    source?: "manual" | "cli_wrapper" | "local_command" | "demo" | "real_captured" | "provider_usage" | "codex_import" | undefined;
+    createdAt?: string | undefined;
+    created_at?: string | undefined;
+    generatedAt?: string | undefined;
+    generated_at?: string | undefined;
+    durationMs?: number | undefined;
+    duration_ms?: number | undefined;
+    exitCode?: number | undefined;
+    exit_code?: number | undefined;
+}>;
+export declare function parseTraceFile(traceFile: string): Promise<AgentTrace>;