@compaction/cli 0.2.0 → 0.3.1

package/dist/core/tool-shim.js

@@ -0,0 +1,447 @@
+/**
+ * Transparent capturing PATH-shim infrastructure (PUBLIC CLI/SDK code — engine-free, ships in the
+ * npm package). This is the TRUE always-on mechanism for Codex and Cursor (charter 2026-07-04-run-9),
+ * mirroring the run-8 Claude Code connect→install→RE-READ→VERIFY pattern
+ * (`src/core/claude-code-connect.ts`): a "connected/active" claim may rest ONLY on a resolve-check —
+ * never on the mere act of writing a file.
+ *
+ * Mechanism (charter order: native hook → shell alias → PATH shim → else stop): a Compaction-owned
+ * shim directory (`~/.compaction/shims/`, overridable via `COMPACTION_SHIM_DIR` / `COMPACTION_HOME`
+ * for tests) holds a small bash shim named exactly like the tool (`codex`, `cursor-agent`). When that
+ * directory is on `PATH` AHEAD of the real binary, running the tool normally routes through the shim,
+ * which TRANSPARENTLY execs the REAL binary (its absolute path resolved BEFORE install and baked in so
+ * the shim can never recurse into itself) with ALL args, inherited stdio, and the preserved exit code.
+ * For the MEASURABLE batch form ONLY (`codex exec --json` / `cursor-agent … --output-format json`) it
+ * tees stdout to a temp copy and, after the real binary exits, invokes the CONTENT-FREE
+ * `compaction capture <tool> --from-shim` bridge (usage token fields only; no prompt/response/message
+ * text is ever read into the event). Interactive / other invocations PASS THROUGH untouched and are
+ * honestly NOT measured (never faked).
+ *
+ * Safety rails (charter §HARD RAILS):
+ * - NEVER overwrites or replaces the real `codex`/`cursor-agent` binaries.
+ * - NEVER edits the user's shell rc without an explicit `--write-shell-config` gesture AND a reversible
+ *   `.bak` backup (see `writeShellConfigPathLine` / `removeShellConfigPathLine`).
+ * - NEVER claims active without a resolve-verification (`verifyShimActive`).
+ * - Local file I/O only — no network, no new dependency.
+ */
+import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync, copyFileSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+export const SHIM_TOOLS = {
+    codex: { shimName: "codex", captureTool: "codex", forwardArgs: false },
+    cursor: { shimName: "cursor-agent", captureTool: "cursor", forwardArgs: true }
+};
+/** Marker line embedded in every generated shim: how verify + uninstall confirm the file is OURS. */
+export const SHIM_MARKER = "COMPACTION_SHIM";
+/** The Compaction home directory: `COMPACTION_HOME` or `<home>/.compaction`. */
+export function resolveCompactionHome(env = process.env) {
+    if (env.COMPACTION_HOME && env.COMPACTION_HOME.trim() !== "")
+        return env.COMPACTION_HOME;
+    const home = env.HOME && env.HOME.trim() !== "" ? env.HOME : homedir();
+    return path.join(home, ".compaction");
+}
+/** The Compaction-owned shim directory: `COMPACTION_SHIM_DIR`, else `<compaction-home>/shims`. */
+export function resolveShimDir(env = process.env) {
+    if (env.COMPACTION_SHIM_DIR && env.COMPACTION_SHIM_DIR.trim() !== "")
+        return env.COMPACTION_SHIM_DIR;
+    return path.join(resolveCompactionHome(env), "shims");
+}
+export function shimPathFor(tool, env = process.env) {
+    return path.join(resolveShimDir(env), SHIM_TOOLS[tool].shimName);
+}
+/* ------------------------------------------------------------------------------------------------
+ * Resolve the REAL binary on the current PATH, EXCLUDING our shim dir (so the shim never records or
+ * execs itself). This is `which <name>` minus the shim directory.
+ * ---------------------------------------------------------------------------------------------- */
+function isExecutableFile(file) {
+    try {
+        const st = statSync(file);
+        return st.isFile() && (st.mode & 0o111) !== 0;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * First executable named `name` on `PATH`, skipping any directory in `excludeDirs` (the shim dir).
+ * Returns the absolute path or `undefined`. Used at INSTALL time to record the real binary before the
+ * shim can shadow it, and to detect "tool not installed" (never shim a command that does not exist).
+ */
+export function resolveExecutableOnPath(name, env = process.env, excludeDirs = []) {
+    const pathValue = env.PATH ?? "";
+    const excluded = new Set(excludeDirs.map((d) => path.resolve(d)));
+    for (const dir of pathValue.split(path.delimiter)) {
+        if (dir.trim() === "")
+            continue;
+        if (excluded.has(path.resolve(dir)))
+            continue;
+        const candidate = path.join(dir, name);
+        if (isExecutableFile(candidate))
+            return path.resolve(candidate);
+    }
+    return undefined;
+}
+/* ------------------------------------------------------------------------------------------------
+ * Shim script generation.
+ * ---------------------------------------------------------------------------------------------- */
+/** Single-quote a value for safe embedding in the generated bash (no interpolation, no injection). */
+function bashSingleQuote(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+/** The measurable-form detector snippet per tool (sets `__measurable=1` only for the batch form). */
+function detectorSnippet(tool) {
+    if (tool === "codex") {
+        return [
+            "# Codex measurable batch form: `codex exec ... --json` (an interactive `codex` is NOT measured).",
+            "__has_exec=0; __has_json=0",
+            'for __a in "$@"; do',
+            '  case "$__a" in',
+            "    exec) __has_exec=1 ;;",
+            "    --json) __has_json=1 ;;",
+            "  esac",
+            "done",
+            'if [ "$__has_exec" = "1" ] && [ "$__has_json" = "1" ]; then __measurable=1; fi'
+        ].join("\n");
+    }
+    // cursor
+    return [
+        "# Cursor measurable batch form: `--output-format json` (or =json / stream-json). Interactive is NOT measured.",
+        '__prev=""',
+        'for __a in "$@"; do',
+        '  case "$__a" in',
+        "    --output-format=json|--output-format=stream-json) __measurable=1 ;;",
+        '    json|stream-json) if [ "$__prev" = "--output-format" ]; then __measurable=1; fi ;;',
+        "  esac",
+        '  __prev="$__a"',
+        "done"
+    ].join("\n");
+}
+/**
+ * STDIN-BOUNDARY apply block (charter 2026-07-04-run-12 — the FIRST real before-call mutation surface).
+ * ONLY Codex has a documented stdin prompt boundary (`codex exec` reads instructions from stdin when no
+ * positional prompt is given), so this block is emitted ONLY for the codex shim; the cursor shim stays
+ * byte-for-byte unchanged (recommendation-only). When stdin is PIPED, the shim buffers it, lets
+ * `precall` decide (safe boundary + avoidable context + explicit `/dev/tty` approval → compacted stdin
+ * written to a file; anything else → nothing written), and feeds the chosen stream to the real binary.
+ * Every failure feeds the ORIGINAL buffered stdin unchanged (fail-open); the exit code is preserved via
+ * PIPESTATUS. Interactive runs (stdin is a tty) skip this and use the recommendation-only path.
+ */
+function stdinApplyBlock(tool) {
+    if (tool !== "codex")
+        return ""; // Cursor: no documented stdin prompt boundary → no mediation.
+    const cfg = SHIM_TOOLS[tool];
+    return `  # STDIN-BOUNDARY apply (Codex, run-12) — mutate the model's input ONLY here, ONLY after approval.
+  # Engage ONLY when stdin is PIPED (not a tty) AND an ARGV-ONLY probe confirms stdin is the whole prompt
+  # (no positional prompt). The probe reads NO stdin, so we never buffer (never risk blocking) unless
+  # stdin genuinely IS the prompt. Anything else falls through to the recommendation-only path below.
+  if [ ! -t 0 ] && "$COMPACTION_BIN" precall ${cfg.captureTool} --stdin-boundary-check -- "$@" </dev/null >/dev/null 2>&1; then
+    __ttyavail=0; if [ -t 1 ]; then __ttyavail=1; fi
+    __sfile="$(mktemp "\${TMPDIR:-/tmp}/compaction-${cfg.shimName}-stdin-XXXXXX" 2>/dev/null)"
+    __cfile="$(mktemp "\${TMPDIR:-/tmp}/compaction-${cfg.shimName}-cpct-XXXXXX" 2>/dev/null)"
+    if [ -n "$__sfile" ] && [ -n "$__cfile" ]; then
+      cat > "$__sfile"
+      # precall writes the compacted stdin to __cfile ONLY on explicit approval; its own stdin is
+      # /dev/null and its stdout is discarded (the [y/n/v] prompt goes to /dev/tty). '|| true' → the
+      # step can never break the tool. An empty __cfile means "feed the ORIGINAL" (the fail-closed default).
+      "$COMPACTION_BIN" precall ${cfg.captureTool} --interactive "$__ttyavail" --stdin-file "$__sfile" --compacted-out "$__cfile" -- "$@" </dev/null >/dev/null 2>&1 || true
+      __infile="$__sfile"
+      if [ -s "$__cfile" ]; then __infile="$__cfile"; fi
+      __tmp="$(mktemp "\${TMPDIR:-/tmp}/compaction-${cfg.shimName}-XXXXXX" 2>/dev/null)" || { "$REAL_BIN" "$@" < "$__infile"; __c=$?; rm -f "$__sfile" "$__cfile" >/dev/null 2>&1 || true; exit "$__c"; }
+      "$REAL_BIN" "$@" < "$__infile" | tee "$__tmp"
+      __code=\${PIPESTATUS[0]}
+      ${captureSnippet(tool)}
+      rm -f "$__tmp" "$__sfile" "$__cfile" >/dev/null 2>&1 || true
+      exit "$__code"
+    fi
+    rm -f "$__sfile" "$__cfile" >/dev/null 2>&1 || true
+  fi
+`;
+}
+/** The content-free capture call the shim runs AFTER the real binary exits (best-effort, silenced). */
+function captureSnippet(tool) {
+    const cfg = SHIM_TOOLS[tool];
+    if (cfg.forwardArgs) {
+        // Cursor: forward the original invocation so the bridge can LOCAL-ESTIMATE the input count
+        // (content-free — only the token COUNT rides on the event; the prompt text is never stored).
+        return `"$COMPACTION_BIN" capture ${cfg.captureTool} --from-shim "$__tmp" -- ${cfg.shimName} "$@" >/dev/null 2>&1 || true`;
+    }
+    return `"$COMPACTION_BIN" capture ${cfg.captureTool} --from-shim "$__tmp" >/dev/null 2>&1 || true`;
+}
+/**
+ * Generate the transparent capturing shim script for `tool`, baking in the resolved absolute
+ * `realBin` path. The script: (1) execs the real binary with all args + inherited stdio + preserved
+ * exit code; (2) for the measurable batch form ONLY, runs a FAIL-OPEN, CONTENT-FREE before-call
+ * recommendation step (`compaction precall`; recommendation-only — it never mutates the input), then
+ * tees stdout to a temp copy and calls the content-free capture bridge, then deletes the temp;
+ * (3) passes everything else through untouched.
+ */
+export function generateShimScript(tool, realBin) {
+    const cfg = SHIM_TOOLS[tool];
+    return `#!/usr/bin/env bash
+# ${SHIM_MARKER}: ${tool}
+# Compaction transparent capturing shim for "${cfg.shimName}" — installed by \`compaction init --connect\`.
+#
+# It TRANSPARENTLY execs the REAL binary below with ALL args, inherited stdio, and the preserved exit
+# code. For the MEASURABLE batch form ONLY it captures provider usage token fields as a CONTENT-FREE
+# side effect (no prompt/response/message text is ever stored). Interactive / other invocations pass
+# through untouched and are NOT measured (never faked).
+#
+# The real binary path was resolved on your PATH BEFORE this shim was installed, so the shim can never
+# recurse into itself. This file NEVER replaces the real binary.
+# Uninstall (reversible): compaction init --disconnect ${tool}
+set -u
+
+REAL_BIN=${bashSingleQuote(realBin)}
+COMPACTION_BIN="\${COMPACTION_BIN:-compaction}"
+
+if [ ! -x "$REAL_BIN" ]; then
+  echo "compaction shim: the recorded ${cfg.shimName} binary was not found at $REAL_BIN — re-run 'compaction init --connect' to re-resolve it." 1>&2
+  exit 127
+fi
+
+__measurable=0
+${detectorSnippet(tool)}
+
+if [ "$__measurable" = "1" ]; then
+${stdinApplyBlock(tool)}  # BEFORE-CALL recommendation (charter 2026-07-04-run-10) — RECOMMENDATION-ONLY, FAIL-OPEN, CONTENT-FREE.
+  # 'compaction precall' is invoked purely for its side effects: when the input carries avoidable
+  # duplicated context it surfaces a recommendation on /dev/tty (interactive terminals only) and records
+  # ONE content-free activity event. It NEVER mutates the input — the real binary below always runs on
+  # the ORIGINAL "$@". precall's stdin is /dev/null (so it can never steal the tool's stdin) and its
+  # stdout/stderr are discarded (so it can never alter the tool's output); the human recommendation goes
+  # to /dev/tty directly. '|| true' makes any precall failure a no-op, so this step can never break or
+  # block the tool. NO-TTY / piped runs (__itty=0) get NO prompt and NO mutation.
+  __itty=0
+  if [ -t 0 ] && [ -t 1 ]; then __itty=1; fi
+  "$COMPACTION_BIN" precall ${cfg.captureTool} --interactive "$__itty" -- "$@" </dev/null >/dev/null 2>&1 || true
+
+  __tmp="$(mktemp "\${TMPDIR:-/tmp}/compaction-${cfg.shimName}-XXXXXX" 2>/dev/null)" || exec "$REAL_BIN" "$@"
+  # Transparent: the user sees identical stdout via tee; stderr passes straight through; the real
+  # binary's exit code is preserved via PIPESTATUS (never tee's or the capture call's).
+  "$REAL_BIN" "$@" | tee "$__tmp"
+  __code=\${PIPESTATUS[0]}
+  # Content-free capture side effect — never touches the user's stdout/stderr or exit code.
+  ${captureSnippet(tool)}
+  rm -f "$__tmp" >/dev/null 2>&1 || true
+  exit "$__code"
+else
+  exec "$REAL_BIN" "$@"
+fi
+`;
+}
+/** Does the file at `shimPath` look like a Compaction shim (marker present)? Content-free identity. */
+export function fileIsCompactionShim(shimPath) {
+    try {
+        return readFileSync(shimPath, "utf8").includes(`${SHIM_MARKER}:`);
+    }
+    catch {
+        return false;
+    }
+}
+/** The exact PATH line the user adds (or `--write-shell-config` appends) to activate the shim dir. */
+export function shimExportLine(env = process.env) {
+    const dir = resolveShimDir(env);
+    // Prefer a $HOME-relative form for the default location (matches what the user will recognize).
+    const home = env.HOME && env.HOME.trim() !== "" ? env.HOME : homedir();
+    const defaultDir = path.join(home, ".compaction", "shims");
+    const shown = path.resolve(dir) === path.resolve(defaultDir) ? '$HOME/.compaction/shims' : dir;
+    return `export PATH="${shown}:$PATH"`;
+}
+/**
+ * Resolve-verify whether the shim for `tool` is ACTIVE: the shim file exists AND the tool name
+ * resolves to that shim on the current PATH (the shim dir is on PATH ahead of the real binary).
+ */
+export function verifyShimActive(tool, env = process.env) {
+    const shimDir = resolveShimDir(env);
+    const shimPath = shimPathFor(tool, env);
+    const installed = existsSync(shimPath) && fileIsCompactionShim(shimPath);
+    // Resolve the shim NAME on the FULL PATH (do NOT exclude the shim dir — we want to know whether it
+    // wins). onPath is true only when that first match IS our shim file.
+    const resolvedPath = resolveExecutableOnPath(SHIM_TOOLS[tool].shimName, env);
+    const onPath = installed && resolvedPath !== undefined && path.resolve(resolvedPath) === path.resolve(shimPath);
+    return {
+        tool,
+        shimPath,
+        installed,
+        ...(resolvedPath !== undefined ? { resolvedPath } : {}),
+        onPath,
+        active: installed && onPath,
+        exportLine: shimExportLine(env),
+        shimDir
+    };
+}
+const RECORD_FILENAME = ".shim-record.json";
+function recordPath(env) {
+    return path.join(resolveShimDir(env), RECORD_FILENAME);
+}
+function readRecord(env) {
+    try {
+        const parsed = JSON.parse(readFileSync(recordPath(env), "utf8"));
+        if (parsed && typeof parsed === "object" && parsed.shims)
+            return parsed;
+    }
+    catch {
+        /* fall through to empty */
+    }
+    return { version: 1, shims: {} };
+}
+function writeRecord(env, record) {
+    writeFileSync(recordPath(env), `${JSON.stringify(record, null, 2)}\n`, "utf8");
+}
+/**
+ * Install the shim for `tool`: resolve the real binary (excluding our shim dir so it can never point
+ * at itself), write the shim script + a real-path record, then RE-READ the shim file to confirm it
+ * landed with the marker and the recorded real path, and finally resolve-verify PATH activation. The
+ * caller may only present "connected" for `installed-active` / `already-active` — never for
+ * `installed-not-on-path` (print the export line) or `verify-failed` (nothing is claimed).
+ */
+export function installToolShim(tool, env = process.env, options = {}) {
+    const now = options.now ?? (() => new Date().toISOString());
+    const shimDir = resolveShimDir(env);
+    const shimPath = shimPathFor(tool, env);
+    const shimName = SHIM_TOOLS[tool].shimName;
+    const exportLine = shimExportLine(env);
+    // Idempotent: already installed + active → report without rewriting.
+    const before = verifyShimActive(tool, env);
+    if (before.active) {
+        const record = readRecord(env);
+        return {
+            tool,
+            status: "already-active",
+            shimName,
+            shimDir,
+            shimPath,
+            ...(record.shims[tool]?.realBin ? { realBin: record.shims[tool].realBin } : {}),
+            verification: before,
+            exportLine
+        };
+    }
+    // Resolve the REAL binary BEFORE (re)writing the shim, excluding the shim dir (never itself).
+    const realBin = resolveExecutableOnPath(shimName, env, [shimDir]);
+    if (realBin === undefined) {
+        return {
+            tool,
+            status: "no-real-binary",
+            shimName,
+            shimDir,
+            shimPath,
+            verification: before,
+            exportLine
+        };
+    }
+    mkdirSync(shimDir, { recursive: true });
+    writeFileSync(shimPath, generateShimScript(tool, realBin), "utf8");
+    chmodSync(shimPath, 0o755);
+    const record = readRecord(env);
+    record.shims[tool] = { shimName, realBin, installedAt: now() };
+    writeRecord(env, record);
+    // RE-READ to verify the write landed (marker present + recorded real path baked in + executable).
+    let reReadOk = false;
+    try {
+        const contents = readFileSync(shimPath, "utf8");
+        const st = statSync(shimPath);
+        reReadOk = contents.includes(`${SHIM_MARKER}: ${tool}`) && contents.includes(realBin) && (st.mode & 0o111) !== 0;
+    }
+    catch {
+        reReadOk = false;
+    }
+    if (!reReadOk) {
+        return { tool, status: "verify-failed", shimName, shimDir, shimPath, realBin, verification: verifyShimActive(tool, env), exportLine };
+    }
+    const verification = verifyShimActive(tool, env);
+    return {
+        tool,
+        status: verification.active ? "installed-active" : "installed-not-on-path",
+        shimName,
+        shimDir,
+        shimPath,
+        realBin,
+        verification,
+        exportLine
+    };
+}
+/** Remove the shim file + its record entry (reversible: the real binary was never touched). */
+export function uninstallToolShim(tool, env = process.env) {
+    const shimPath = shimPathFor(tool, env);
+    const existed = existsSync(shimPath);
+    if (existed)
+        rmSync(shimPath, { force: true });
+    const record = readRecord(env);
+    if (record.shims[tool]) {
+        delete record.shims[tool];
+        try {
+            writeRecord(env, record);
+        }
+        catch {
+            /* record dir may already be gone; not fatal */
+        }
+    }
+    return { tool, status: existed ? "removed" : "not-installed", shimPath };
+}
+/* ------------------------------------------------------------------------------------------------
+ * OPT-IN, reversible shell-rc editing (only with an explicit --write-shell-config gesture).
+ * ---------------------------------------------------------------------------------------------- */
+const RC_BLOCK_START = "# >>> compaction shim PATH (added by `compaction init --connect --write-shell-config`) >>>";
+const RC_BLOCK_END = "# <<< compaction shim PATH <<<";
+/** Pick the user's shell rc file from $SHELL (zsh → ~/.zshrc, else ~/.bashrc). Content-free. */
+export function resolveShellRcPath(env = process.env) {
+    const home = env.HOME && env.HOME.trim() !== "" ? env.HOME : homedir();
+    const shell = env.SHELL ?? "";
+    if (shell.includes("zsh"))
+        return path.join(home, ".zshrc");
+    return path.join(home, ".bashrc");
+}
+/**
+ * Append the shim PATH line to the user's shell rc — ONLY when the caller passes an explicit
+ * `--write-shell-config` gesture. A `.compaction.bak` backup is written FIRST (reversible), the block
+ * is clearly marked, and the append is idempotent (already-present → no change). Never overwrites.
+ */
+export function writeShellConfigPathLine(env = process.env) {
+    const rcPath = resolveShellRcPath(env);
+    const exportLine = shimExportLine(env);
+    const existing = existsSync(rcPath) ? readFileSync(rcPath, "utf8") : "";
+    if (existing.includes(RC_BLOCK_START) || existing.includes(exportLine)) {
+        return { status: "already-present", rcPath, exportLine };
+    }
+    const backupPath = `${rcPath}.compaction.bak`;
+    let createdBackup;
+    if (existsSync(rcPath)) {
+        copyFileSync(rcPath, backupPath);
+        createdBackup = backupPath;
+    }
+    const block = `\n${RC_BLOCK_START}\n${exportLine}\n${RC_BLOCK_END}\n`;
+    writeFileSync(rcPath, existing + block, "utf8");
+    return {
+        status: existing === "" ? "no-rc-file-created" : "appended",
+        rcPath,
+        ...(createdBackup ? { backupPath: createdBackup } : {}),
+        exportLine
+    };
+}
+/**
+ * Reverse `writeShellConfigPathLine`: strip the marked block from the rc file. If a
+ * `.compaction.bak` backup exists it is restored verbatim (the fully reversible path); otherwise the
+ * marked block is removed in place.
+ */
+export function removeShellConfigPathLine(env = process.env) {
+    const rcPath = resolveShellRcPath(env);
+    if (!existsSync(rcPath))
+        return { status: "no-rc-file", rcPath };
+    const backupPath = `${rcPath}.compaction.bak`;
+    const contents = readFileSync(rcPath, "utf8");
+    if (!contents.includes(RC_BLOCK_START))
+        return { status: "not-present", rcPath };
+    if (existsSync(backupPath)) {
+        copyFileSync(backupPath, rcPath);
+        rmSync(backupPath, { force: true });
+        return { status: "removed", rcPath, backupRestored: backupPath };
+    }
+    // No backup (block appended to a then-nonexistent file): remove the marked block only.
+    const stripped = contents.replace(new RegExp(`\\n?${escapeRegExp(RC_BLOCK_START)}[\\s\\S]*?${escapeRegExp(RC_BLOCK_END)}\\n?`, "g"), "\n");
+    writeFileSync(rcPath, stripped, "utf8");
+    return { status: "removed", rcPath };
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+//# sourceMappingURL=tool-shim.js.map

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

@@ -6,7 +6,7 @@ export declare const agentTraceSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
     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"]>>;
+    source: z.ZodOptional<z.ZodEnum<["manual", "cli_wrapper", "local_command", "demo", "real_captured", "provider_usage", "codex_import", "cursor_import"]>>;
     createdAt: z.ZodOptional<z.ZodString>;
     created_at: z.ZodOptional<z.ZodString>;
     generatedAt: z.ZodOptional<z.ZodString>;
@@ -20,13 +20,13 @@ export declare const agentTraceSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
     }, "strip", z.ZodTypeAny, {
         command: string;
         args: string[];
-        cwd?: string | undefined;
         shell?: string | undefined;
+        cwd?: string | undefined;
     }, {
         command: string;
         args: string[];
-        cwd?: string | undefined;
         shell?: string | undefined;
+        cwd?: string | undefined;
     }>>;
     durationMs: z.ZodOptional<z.ZodNumber>;
     duration_ms: z.ZodOptional<z.ZodNumber>;
@@ -69,12 +69,12 @@ export declare const agentTraceSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
     command?: {
         command: string;
         args: string[];
-        cwd?: string | undefined;
         shell?: string | undefined;
+        cwd?: string | undefined;
     } | undefined;
     artifactVersion?: string | undefined;
     artifact_version?: string | undefined;
-    source?: "manual" | "cli_wrapper" | "local_command" | "demo" | "real_captured" | "provider_usage" | "codex_import" | undefined;
+    source?: "manual" | "cli_wrapper" | "local_command" | "demo" | "real_captured" | "provider_usage" | "codex_import" | "cursor_import" | undefined;
     createdAt?: string | undefined;
     created_at?: string | undefined;
     generatedAt?: string | undefined;
@@ -98,12 +98,12 @@ export declare const agentTraceSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
     command?: {
         command: string;
         args: string[];
-        cwd?: string | undefined;
         shell?: string | undefined;
+        cwd?: string | undefined;
     } | undefined;
     artifactVersion?: string | undefined;
     artifact_version?: string | undefined;
-    source?: "manual" | "cli_wrapper" | "local_command" | "demo" | "real_captured" | "provider_usage" | "codex_import" | undefined;
+    source?: "manual" | "cli_wrapper" | "local_command" | "demo" | "real_captured" | "provider_usage" | "codex_import" | "cursor_import" | undefined;
     createdAt?: string | undefined;
     created_at?: string | undefined;
     generatedAt?: string | undefined;
@@ -127,12 +127,12 @@ export declare const agentTraceSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
     command?: {
         command: string;
         args: string[];
-        cwd?: string | undefined;
         shell?: string | undefined;
+        cwd?: string | undefined;
     } | undefined;
     artifactVersion?: string | undefined;
     artifact_version?: string | undefined;
-    source?: "manual" | "cli_wrapper" | "local_command" | "demo" | "real_captured" | "provider_usage" | "codex_import" | undefined;
+    source?: "manual" | "cli_wrapper" | "local_command" | "demo" | "real_captured" | "provider_usage" | "codex_import" | "cursor_import" | undefined;
     createdAt?: string | undefined;
     created_at?: string | undefined;
     generatedAt?: string | undefined;
@@ -156,12 +156,12 @@ export declare const agentTraceSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
     command?: {
         command: string;
         args: string[];
-        cwd?: string | undefined;
         shell?: string | undefined;
+        cwd?: string | undefined;
     } | undefined;
     artifactVersion?: string | undefined;
     artifact_version?: string | undefined;
-    source?: "manual" | "cli_wrapper" | "local_command" | "demo" | "real_captured" | "provider_usage" | "codex_import" | undefined;
+    source?: "manual" | "cli_wrapper" | "local_command" | "demo" | "real_captured" | "provider_usage" | "codex_import" | "cursor_import" | undefined;
     createdAt?: string | undefined;
     created_at?: string | undefined;
     generatedAt?: string | undefined;
@@ -185,12 +185,12 @@ export declare const agentTraceSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
     command?: {
         command: string;
         args: string[];
-        cwd?: string | undefined;
         shell?: string | undefined;
+        cwd?: string | undefined;
     } | undefined;
     artifactVersion?: string | undefined;
     artifact_version?: string | undefined;
-    source?: "manual" | "cli_wrapper" | "local_command" | "demo" | "real_captured" | "provider_usage" | "codex_import" | undefined;
+    source?: "manual" | "cli_wrapper" | "local_command" | "demo" | "real_captured" | "provider_usage" | "codex_import" | "cursor_import" | undefined;
     createdAt?: string | undefined;
     created_at?: string | undefined;
     generatedAt?: string | undefined;

package/dist/core/trace-parser.js

@@ -16,11 +16,11 @@ const commandMetadataSchema = z.object({
     cwd: z.string().min(1).optional(),
     shell: z.string().min(1).optional()
 });
-// `codex_import` is deliberately NOT a command trace: an imported `codex exec --json`
-// JSONL export carries no command/exitCode/durationMs provenance, so it must not be
-// subjected to command-trace validation (that is why the Codex import path could not
-// reuse `cli_wrapper`/`local_command`). Keep this exclusion in lockstep with the
-// `imported_local` evidence mapping in safety-report.ts.
+// `codex_import` (and `cursor_import`) are deliberately NOT command traces: an imported
+// `codex exec --json` JSONL / Cursor session export carries no command/exitCode/durationMs
+// provenance, so they must not be subjected to command-trace validation (that is why the
+// import paths could not reuse `cli_wrapper`/`local_command`). Keep this exclusion in
+// lockstep with the `imported_local` evidence mapping in safety-report.ts.
 function isCommandTrace(source) {
     return source === "cli_wrapper" || source === "local_command";
 }
@@ -30,7 +30,7 @@ const rawAgentTraceSchema = z
     title: z.string().min(1),
     artifactVersion: z.string().min(1).optional(),
     artifact_version: z.string().min(1).optional(),
-    source: z.enum(["manual", "cli_wrapper", "local_command", "demo", "real_captured", "provider_usage", "codex_import"]).optional(),
+    source: z.enum(["manual", "cli_wrapper", "local_command", "demo", "real_captured", "provider_usage", "codex_import", "cursor_import"]).optional(),
     createdAt: isoTimestampSchema.optional(),
     created_at: isoTimestampSchema.optional(),
     generatedAt: isoTimestampSchema.optional(),

package/dist/core/types.d.ts

@@ -1,5 +1,5 @@
 export type TraceRole = "system" | "user" | "assistant" | "tool" | "stdout" | "stderr";
-export type TraceSource = "manual" | "cli_wrapper" | "local_command" | "demo" | "real_captured" | "provider_usage" | "codex_import";
+export type TraceSource = "manual" | "cli_wrapper" | "local_command" | "demo" | "real_captured" | "provider_usage" | "codex_import" | "cursor_import";
 export interface TraceCommandMetadata {
     command: string;
     args: string[];
@@ -43,7 +43,17 @@ export interface CostEstimate {
     totalCostUsd: number;
 }
 export interface WasteFinding {
-    category: "repeated_tool_output" | "stale_context" | "verbose_observation" | "repeated_skill_injection";
+    /**
+     * `superseded_same_source_read` (input-compaction category 1, accepted design
+     * docs/design/input-compaction-policy-reach.md D2): the SAME source was read multiple times and
+     * a LATER read is authoritative; an EARLIER full copy whose content GENUINELY DIFFERS (whitespace-
+     * normalized) from the latest can be replaced by a recoverable pointer to the retained original.
+     * ADDITIVE to `repeated_tool_output` (which handles identical-up-to-whitespace repeats) and never
+     * weakens it: an identical earlier copy is LEFT to `repeated_tool_output`, never category-1-compacted.
+     * Convention for this category's `messageIds`: `[0]` = the KEPT latest authoritative read (verbatim),
+     * `[1..]` = the earlier superseded reads to compact (each recoverable from the retained original).
+     */
+    category: "repeated_tool_output" | "stale_context" | "verbose_observation" | "repeated_skill_injection" | "superseded_same_source_read";
     messageIds: string[];
     summary: string;
     estimatedTokens: number;

package/dist/core/waste-detector.d.ts

@@ -5,4 +5,24 @@ export interface WasteDetectionThresholds {
     minDuplicateCharacters?: number;
 }
 export declare function detectWaste(trace: AgentTrace, thresholds?: WasteDetectionThresholds): WasteFinding[];
+/**
+ * Input-compaction category 1: detect SUPERSEDED same-source reads.
+ *
+ * When the SAME source (provable source identity) is read ≥2 times, the LATEST read is authoritative
+ * (preserved verbatim). Each EARLIER read whose whitespace-normalized content GENUINELY DIFFERS from
+ * the latest's is a superseded candidate that can be replaced by a recoverable pointer to the
+ * retained original. Conservative & additive:
+ *  - Outputs with NO provable source identity are skipped (not eligible).
+ *  - An earlier output that is identical-up-to-whitespace to the latest is LEFT to the existing
+ *    `repeated_tool_output` policy (NOT category-1-compacted) — no overlap, no double-compaction.
+ *  - Each compacted (earlier) output must meet the SAME thresholds detectWaste uses
+ *    (minDuplicateTokens / minDuplicateCharacters).
+ *
+ * Finding convention: `messageIds[0]` = KEPT latest authoritative read; `messageIds[1..]` = earlier
+ * superseded reads to compact (estimatedTokens = sum of the compacted earlier reads' estimates).
+ *
+ * NO scoring formula, weight, relevance, or learned logic — only deterministic source-identity
+ * equality + whitespace-normalized content difference + the existing min-tokens/chars thresholds.
+ */
+export declare function detectSupersededSameSourceReads(trace: AgentTrace, thresholds?: WasteDetectionThresholds): WasteFinding[];
 export declare function getCompactedMessageIds(findings: WasteFinding[]): Set<string>;