@compaction/cli 0.1.4 → 0.3.0

package/dist/core/cross-surface-event.js

@@ -0,0 +1,330 @@
+/** Contract §2: which Compaction surface produced the event (exact values, verbatim). */
+export const CROSS_SURFACE_SURFACES = [
+    "cli",
+    "claude_code",
+    "codex",
+    "cursor",
+    "browser_extension",
+    "api_metered"
+];
+/** Contract §2: whose model/service was used — distinct from `surface`. */
+export const CROSS_SURFACE_PROVIDERS = ["anthropic", "openai", "cursor", "chatgpt", "other"];
+/** Contract §2: per-axis token source. Input and output are INDEPENDENT axes. */
+export const CROSS_SURFACE_TOKEN_SOURCES = ["provider-reported", "local-estimate", "unavailable"];
+/** Contract §2: how the cost figure (if any) is known. `operator-entered` is the billing-delta operator path. */
+export const CROSS_SURFACE_COST_SOURCES = [
+    "provider-reported",
+    "operator-entered",
+    "local-estimate",
+    "unavailable"
+];
+/**
+ * Contract §2 honesty rule: what a figure may be scoped to — this run / this workflow / these
+ * conditions. A GENERALIZED claim is intentionally NOT representable (D6: "Generalized
+ * billing-confirmed = future only. Public generalized 'saves X%' is forbidden.").
+ * `billing-confirmed-workflow-scoped` exists only on the `BillingConfirmedCrossSurfaceEvent` arm.
+ */
+export const CROSS_SURFACE_CLAIM_SCOPES = [
+    "run-scoped",
+    "workflow-scoped",
+    "conditions-scoped",
+    "billing-confirmed-workflow-scoped"
+];
+/* ------------------------------------------------------------------------------------------------
+ * Surfaces ↔ existing wire ToolName mapping (additive helper; changes neither enum).
+ * ---------------------------------------------------------------------------------------------- */
+/**
+ * Map the EXISTING wire `ToolName` to the contract `surface` value, honestly:
+ * - `claude-code` → `claude_code`, `codex` → `codex`, `cursor` → `cursor`;
+ * - `other` (the bare `compaction run -- <cmd>` wrapper) → `cli` per the tier table ("bare
+ *   run/trace analysis without provider usage");
+ * - `openai-agents` → `undefined`: the contract names no surface for it, and unknown stays
+ *   unknown — this helper never guesses (named residual, like the control-plane enum alignment).
+ */
+export function surfaceForToolName(tool) {
+    switch (tool) {
+        case "claude-code":
+            return "claude_code";
+        case "codex":
+            return "codex";
+        case "cursor":
+            return "cursor";
+        case "other":
+            return "cli";
+        case "openai-agents":
+            return undefined;
+    }
+}
+/* ------------------------------------------------------------------------------------------------
+ * REPORT-ONLY validator. Returns problems; never throws. It exists for the states TypeScript
+ * cannot police (parsed JSON, widened objects, wire data) and encodes the contract's honesty
+ * rules as label-correctness checks.
+ * ---------------------------------------------------------------------------------------------- */
+/**
+ * Contract tier table (§3, D3/D4): surfaces whose token tier can NEVER be provider-reported —
+ * Cursor emits no usage (vendor gap; "never provider-reported"), and the browser's visible
+ * surface exposes no provider usage ("may NOT claim provider-reported web tokens").
+ */
+export const NEVER_PROVIDER_REPORTED_SURFACES = ["cursor", "browser_extension"];
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isOneOf(value, allowed) {
+    return typeof value === "string" && allowed.includes(value);
+}
+function isNonEmptyString(value) {
+    return typeof value === "string" && value.trim() !== "";
+}
+/** A count field may be absent, `null` (explicitly not counted), or a finite number ≥ 0. */
+function countProblem(field, value) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value === "number" && Number.isFinite(value) && value >= 0)
+        return undefined;
+    return `${field}: must be a finite number >= 0, null, or absent`;
+}
+const INPUT_COUNT_FIELDS = ["input_before", "input_after"];
+const OUTPUT_COUNT_FIELDS = ["output_before", "output_after", "output_estimate"];
+function validateAxis(axisName, axis, event, problems) {
+    const countFields = axisName === "input" ? INPUT_COUNT_FIELDS : OUTPUT_COUNT_FIELDS;
+    if (!isPlainObject(axis)) {
+        problems.push(`token_source.${axisName}: must be an object with a per-axis source`);
+        return;
+    }
+    if (!isOneOf(axis.source, CROSS_SURFACE_TOKEN_SOURCES)) {
+        problems.push(`token_source.${axisName}.source: must be one of ${CROSS_SURFACE_TOKEN_SOURCES.join(" | ")} (exact)`);
+        return;
+    }
+    if (axis.source === "unavailable") {
+        // Contract §2: field-level unavailable WITH the exact reason — required per axis.
+        if (!isNonEmptyString(axis.unavailable_reason)) {
+            problems.push(`token_source.${axisName}.unavailable_reason: required when the ${axisName} axis is unavailable (the exact honest reason)`);
+        }
+        // Contract §2: never a silent zero — an unavailable axis never carries a numeric count
+        // (a 0 here would dress a missing count as a real one).
+        for (const field of countFields) {
+            if (typeof event[field] === "number") {
+                problems.push(`${field}: no silent zero — the ${axisName} axis is unavailable, so a numeric count (including 0) must not be present`);
+            }
+        }
+    }
+}
+/**
+ * Validate one parsed/unknown cross-surface event against the contract. REPORT-ONLY: returns the
+ * list of problems (empty = contract-honest) and NEVER throws — mirroring the repo's
+ * skipped-with-reason validator style. Rules enforced here are exactly the ones the type system
+ * cannot enforce on unknown data:
+ *
+ * 1. exact enums for surface / provider / token sources / cost source / claim scope;
+ * 2. D5 hard guardrail: a fixed-plan or plan-efficiency event is NEVER billing-confirmed;
+ * 3. D6: billing-confirmed requires surface api_metered + provider-reported|operator-entered cost;
+ * 4. tier table (D3/D4): cursor and browser_extension events never carry provider-reported tokens;
+ * 5. no silent zero: an unavailable axis never carries a numeric count;
+ * 6. per-axis unavailable_reason required when an axis is unavailable;
+ * 7. a numeric count requires its axis to be labeled (a count without a token_source is unlabeled).
+ */
+export function validateCrossSurfaceEvent(value) {
+    const problems = [];
+    if (!isPlainObject(value)) {
+        return { problems: ["event: must be a JSON object"] };
+    }
+    const event = value;
+    // Rule 1 — exact enums.
+    if (!isOneOf(event.surface, CROSS_SURFACE_SURFACES)) {
+        problems.push(`surface: must be one of ${CROSS_SURFACE_SURFACES.join(" | ")} (exact)`);
+    }
+    if (event.provider !== undefined && !isOneOf(event.provider, CROSS_SURFACE_PROVIDERS)) {
+        problems.push(`provider: must be one of ${CROSS_SURFACE_PROVIDERS.join(" | ")} (exact)`);
+    }
+    if (event.cost_source !== undefined && !isOneOf(event.cost_source, CROSS_SURFACE_COST_SOURCES)) {
+        problems.push(`cost_source: must be one of ${CROSS_SURFACE_COST_SOURCES.join(" | ")} (exact)`);
+    }
+    if (event.claim_scope !== undefined && !isOneOf(event.claim_scope, CROSS_SURFACE_CLAIM_SCOPES)) {
+        problems.push(`claim_scope: must be one of ${CROSS_SURFACE_CLAIM_SCOPES.join(" | ")} (exact; generalized claims are not representable)`);
+    }
+    if (event.cost_source === "unavailable" && !isNonEmptyString(event.cost_unavailable_reason)) {
+        problems.push("cost_unavailable_reason: required when cost_source is unavailable (the exact honest reason)");
+    }
+    // Count fields are well-formed (absent | null | finite >= 0).
+    for (const field of [...INPUT_COUNT_FIELDS, ...OUTPUT_COUNT_FIELDS]) {
+        const problem = countProblem(field, event[field]);
+        if (problem !== undefined)
+            problems.push(problem);
+    }
+    // Rules 5–6 — per-axis honesty; rule 7 — counts require a labeled axis.
+    const tokenSource = event.token_source;
+    if (tokenSource !== undefined) {
+        if (!isPlainObject(tokenSource)) {
+            problems.push("token_source: must be an object with input and output axes");
+        }
+        else {
+            validateAxis("input", tokenSource.input, event, problems);
+            validateAxis("output", tokenSource.output, event, problems);
+        }
+    }
+    else {
+        for (const field of [...INPUT_COUNT_FIELDS, ...OUTPUT_COUNT_FIELDS]) {
+            if (typeof event[field] === "number") {
+                problems.push(`${field}: a numeric count requires token_source for its axis — an unlabeled count is not honest`);
+            }
+        }
+    }
+    // Rule 4 — tier ceilings (D3/D4): cursor + browser events never carry provider-reported tokens.
+    if (isOneOf(event.surface, NEVER_PROVIDER_REPORTED_SURFACES) &&
+        isPlainObject(tokenSource)) {
+        for (const axisName of ["input", "output"]) {
+            const axis = tokenSource[axisName];
+            if (isPlainObject(axis) && axis.source === "provider-reported") {
+                problems.push(`token_source.${axisName}.source: surface "${String(event.surface)}" can never be provider-reported (contract tier table — vendor exposes no usage)`);
+            }
+        }
+    }
+    // Rules 2–3 — the D5/D6 guardrail on unknown data.
+    const planEfficiency = event.plan_efficiency;
+    if (planEfficiency !== undefined) {
+        if (!isPlainObject(planEfficiency)) {
+            problems.push("plan_efficiency: must be an object");
+        }
+        else {
+            if (planEfficiency.evidence_type !== "plan-efficiency") {
+                problems.push('plan_efficiency.evidence_type: must be the literal "plan-efficiency"');
+            }
+            if (planEfficiency.billing_confirmed !== false) {
+                problems.push("plan_efficiency.billing_confirmed: must be the literal false — a fixed-plan figure can NEVER be billing-confirmed (contract §4, D5)");
+            }
+        }
+    }
+    const claimsBillingConfirmed = event.claim_scope === "billing-confirmed-workflow-scoped";
+    const isFixedPlanEvent = event.billing_model === "fixed-plan" ||
+        planEfficiency !== undefined ||
+        isOneOf(event.surface, NEVER_PROVIDER_REPORTED_SURFACES);
+    if (claimsBillingConfirmed) {
+        if (event.surface !== "api_metered") {
+            problems.push(`claim_scope: billing-confirmed is only possible on surface "api_metered" (contract §5, D6) — surface "${String(event.surface)}" can never be billing-confirmed`);
+        }
+        if (event.cost_source !== "provider-reported" && event.cost_source !== "operator-entered") {
+            problems.push("cost_source: a billing-confirmed claim requires provider-reported or operator-entered cost (contract §5, D6) — never a price-table/local estimate relabeled");
+        }
+        if (event.billing_model === "fixed-plan" || planEfficiency !== undefined) {
+            problems.push("claim_scope: a fixed-plan / plan-efficiency event can NEVER be billing-confirmed (contract §4, D5 — hard guardrail, no exceptions)");
+        }
+    }
+    // Defensive label rule: an evidence label that SAYS billing-confirmed on a fixed-plan event is
+    // the exact overclaim D5 forbids, whatever the claim_scope field says.
+    if (typeof event.evidence_level === "string" &&
+        event.evidence_level.toLowerCase().includes("billing-confirmed") &&
+        isFixedPlanEvent) {
+        problems.push("evidence_level: mentions billing-confirmed on a fixed-plan / plan-efficiency / never-provider-reported event — labels must make this impossible (contract §4, D5)");
+    }
+    return { problems };
+}
+/* ------------------------------------------------------------------------------------------------
+ * Run-record event builders — the writers of the additive `cross_surface_event` field on `run`
+ * local run records. Cursor shipped first (D3 alignment, charter 2026-07-03-run-5, #583); the
+ * codex + cli writers complete the `run` surfaces (#582 residual #5, same charter). Every writer
+ * populates the event from the SAME `RunFlowTokenReport` the record already embeds, so the two can
+ * never diverge — and per-axis sources are copied VERBATIM (the builder never launders labels).
+ * ---------------------------------------------------------------------------------------------- */
+/** Generic honest fallback when an unavailable axis arrives without its TRUE per-run reason. */
+const AXIS_UNAVAILABLE_FALLBACK = "not safely separable / not reported";
+/** One axis derived from the token report. NEVER relabels: if an upstream source ever wrongly said
+ *  provider-reported for a never-provider-reported surface (e.g. Cursor), this passes it through
+ *  and `validateCrossSurfaceEvent` flags it (rule 4) — the builder does not launder labels. */
+function axisFromReport(source, reason) {
+    if (source === "unavailable") {
+        return { source, unavailable_reason: reason ?? AXIS_UNAVAILABLE_FALLBACK };
+    }
+    return { source };
+}
+/**
+ * Per-surface constraints for the `run` local-run-record writers (contract tier table §3):
+ * - `codex` — `run codex`: provider `openai`; token axes are provider-reported where a
+ *   `turn.completed.usage` block existed (the report says which). Codex reports token usage but
+ *   never a cost/billing figure, so cost is UNAVAILABLE with that exact reason.
+ * - `cursor` — `run cursor`: provider `cursor`; LOCAL-ESTIMATE/unavailable only (D3 ceiling —
+ *   Cursor emits no usage), and no cost data exists at all.
+ * - `cli` — bare `run -- <cmd>`: an arbitrary wrapped command, provider `other` (no provider is
+ *   involved that Compaction can observe); input is a local chars/4 estimate, output is
+ *   unavailable with the command-surface reason, and no billing surface exists.
+ * - `claude_code` — the `capture claude-code --from-hook` always-on path (charter 2026-07-04-run-8):
+ *   provider `anthropic`; token axes are PROVIDER-REPORTED where the Claude Code session usage
+ *   fields carried them (the report says which — a missing axis stays unavailable-with-reason,
+ *   never a silent zero). Claude Code reports tokens but no cost/billing figure, so cost is
+ *   UNAVAILABLE with that exact reason. This is NOT invented evidence: the Stop-hook capture reads
+ *   the session's OWN provider usage metadata — the same provider-reported tokens `capture
+ *   claude-code` already surfaces — it simply also records a metrics-only activity event so a
+ *   subsequent session appears in `compaction activity` with no manual import.
+ */
+export const RUN_RECORD_EVENT_SURFACES = {
+    codex: {
+        surface: "codex",
+        provider: "openai",
+        cost_unavailable_reason: "codex exec --json reports token usage (turn.completed.usage) but no cost or billing figure; no cost data exists on this path"
+    },
+    claude_code: {
+        surface: "claude_code",
+        provider: "anthropic",
+        cost_unavailable_reason: "Claude Code session usage reports provider tokens (input/output) but no cost or billing figure; no cost data exists on this path"
+    },
+    cursor: {
+        surface: "cursor",
+        provider: "cursor",
+        cost_unavailable_reason: "Cursor emits no usage or cost data; no cost figure exists for this run"
+    },
+    cli: {
+        surface: "cli",
+        provider: "other",
+        cost_unavailable_reason: "a bare wrapped command has no provider usage or billing surface; no cost figure exists for this run"
+    }
+};
+/**
+ * Build the honest cross-surface event for one `run` local run record (any of the three `run`
+ * surfaces above):
+ * - `surface`/`provider` fixed per surface; `model_label` only as honestly known, else `"unknown"`;
+ * - per-axis `token_source` copied VERBATIM from the token report (input and output INDEPENDENT),
+ *   with the capture's TRUE per-run reason on any unavailable axis (never a bare "unavailable");
+ * - counts only on available axes, under the count field that matches the axis tier:
+ *   `input_before` for the counted/estimated input; a provider-reported output is a COUNT
+ *   (`output_before`), a local-estimate output is an ESTIMATE and says so (`output_estimate`) —
+ *   an unavailable axis carries NO count (never a silent zero);
+ * - `cost_source: "unavailable"` with the exact per-surface reason (no `run` path has billing data);
+ * - `claim_scope: "run-scoped"` (never generalized); caveats = the report's honest notes.
+ *
+ * The tier ceilings stay intact: this builder never SETS provider-reported (it only copies the
+ * report's label), and if a never-provider-reported surface (Cursor) is handed one it passes it
+ * through unchanged so the report-only validator rejects it (rule 4) instead of hiding it.
+ */
+export function buildRunCrossSurfaceEvent(surfaceKey, params) {
+    const spec = RUN_RECORD_EVENT_SURFACES[surfaceKey];
+    const report = params.tokenReport;
+    const input = axisFromReport(report.input_token_source, params.reasons?.input);
+    const output = axisFromReport(report.output_token_source, params.reasons?.output);
+    return {
+        surface: spec.surface,
+        provider: spec.provider,
+        model_label: params.modelLabel ?? "unknown",
+        run_id: params.runId,
+        token_source: { input, output },
+        // Counts ride ONLY on an available axis (never a silent zero on an unavailable one).
+        ...(input.source !== "unavailable" && report.input_tokens !== undefined ? { input_before: report.input_tokens } : {}),
+        ...(output.source === "provider-reported" && report.output_tokens !== undefined
+            ? { output_before: report.output_tokens }
+            : {}),
+        ...(output.source === "local-estimate" && report.output_tokens !== undefined
+            ? { output_estimate: report.output_tokens }
+            : {}),
+        cost_source: "unavailable",
+        cost_unavailable_reason: spec.cost_unavailable_reason,
+        claim_scope: "run-scoped",
+        caveats: [...report.notes]
+    };
+}
+/**
+ * The Cursor writer (D3 alignment, #583) — kept as the named entry point its call/test sites use;
+ * now a thin delegate to the generalized builder with the `cursor` constraints (`surface:
+ * "cursor"`, `provider: "cursor"`, `model_label: "unknown"` — never inferred, D3 ceiling intact).
+ */
+export function buildCursorRunCrossSurfaceEvent(params) {
+    return buildRunCrossSurfaceEvent("cursor", params);
+}
+//# sourceMappingURL=cross-surface-event.js.map

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

@@ -0,0 +1,54 @@
+import { type UsageMetadata } from "./usage-metadata.js";
+import type { AgentTrace } from "./types.js";
+import { type LocalCommandRun } from "./command-runner.js";
+/**
+ * Extract the assistant `result` text + session id from Cursor headless output. Supports the single
+ * JSON object (`--output-format json`) and a stream-json stream (scans lines for a `result` object).
+ * Returns `outputSeparable: false` when no `result` field can be safely isolated.
+ */
+export declare function parseCursorAgentOutput(rawOutput: string): {
+    resultText?: string;
+    sessionId?: string;
+    outputSeparable: boolean;
+};
+/**
+ * Best-effort prompt extraction from the wrapped Cursor invocation: the non-flag positional args,
+ * excluding the executable + known subcommand keywords. Used ONLY for a local-estimate of input tokens
+ * (content-free count of text WE passed). Returns undefined when no prompt can be identified.
+ */
+export declare function extractCursorPrompt(commandParts: string[]): string | undefined;
+export interface CursorNormalizationResult {
+    trace: AgentTrace;
+    usageMetadata: UsageMetadata;
+    /** "present" when a prompt was identified (input locally estimated from it), else "unavailable". */
+    inputStatus: "present" | "unavailable";
+    /**
+     * The TRUE reason input is unavailable (set iff `inputStatus === "unavailable"`). Export-only runs
+     * (no invocation declared) get a DIFFERENT reason from declared-but-unidentifiable invocations, so the
+     * operator is never told "no prompt in the wrapped invocation" when there was no wrapped invocation.
+     */
+    inputUnavailableReason?: string;
+    /** "present" when the result field was separable (output estimated), else "unavailable". */
+    outputStatus: "present" | "unavailable";
+    /**
+     * The TRUE reason output is unavailable (set iff `outputStatus === "unavailable"`), so callers print
+     * the honest reason (e.g. "the captured output is empty") — never a hardcoded, possibly-wrong one.
+     */
+    outputUnavailableReason?: string;
+    warnings: string[];
+}
+/** Build an `AgentTrace` + LOCAL-ESTIMATE usage from captured Cursor headless output. */
+export declare function normalizeCursorAgentOutput(params: {
+    captureId: string;
+    rawOutput: string;
+    commandParts?: string[];
+    commandRun?: LocalCommandRun;
+    generatedAt?: string;
+}): CursorNormalizationResult;
+export interface CursorCaptureResult extends CursorNormalizationResult {
+    commandRun?: LocalCommandRun;
+}
+/** Live wrapper: spawn the Cursor headless CLI (no manual export), capture stdout, normalize. */
+export declare function captureCursorCommand(commandParts: string[], generatedAt?: string): Promise<CursorCaptureResult>;
+/** Offline/fallback: normalize a saved Cursor headless output (json / stream-json) string. */
+export declare function captureCursorExport(rawOutput: string, commandParts?: string[], generatedAt?: string): CursorCaptureResult;

package/dist/core/cursor-capture.js

@@ -0,0 +1,215 @@
+/**
+ * Cursor live-wrapper capture (PUBLIC CLI/SDK code — engine-free, ships in the npm package).
+ *
+ * Wraps a real Cursor **headless CLI agent** run (e.g. `cursor agent -p "<prompt>" --output-format
+ * json`) and normalizes its output to an `AgentTrace`. Design: `docs/design/cursor-live-wrapper.md`
+ * (accepted 2026-06-28) + the amended honesty matrix in `docs/design/unified-run-flow.md` (founder D2).
+ *
+ * HONESTY (the defining rails of this module):
+ * - **NO provider-reported tokens.** Cursor's CLI emits no usage; tokens here are **LOCAL-ESTIMATE
+ *   only** (chars/4), never provider-reported, never billing-confirmed.
+ * - **Input** is locally estimated from the prompt extracted from the wrapped invocation (where
+ *   available). **Output** is locally estimated from the headless **`result`** field when the output
+ *   can be safely separated (`--output-format json`); when it cannot, output is **UNAVAILABLE** (left
+ *   absent, with a stated reason) — never silently zero, never fabricated.
+ * - **NO output-token savings** (that is gated on the output-shaping policy family + eval).
+ * - **NO SQLite / private-storage reverse engineering.** Only the wrapped CLI's own stdout is read.
+ *
+ * Evidence tier: `source: "local_command"` (the same `imported_local` tier as the import path; below
+ * `real_captured`). The cross-tool record attributes `tool: "cursor"`, `token_source: local-estimate`.
+ */
+import { CURRENT_AGENT_TRACE_ARTIFACT_VERSION } from "./trace-parser.js";
+import { createUsageMetadata } from "./usage-metadata.js";
+import { estimateTextTokens } from "./token-estimator.js";
+import { executeLocalCommand, parseRunCommand } from "./command-runner.js";
+function toRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value) ? value : null;
+}
+function stringValue(value) {
+    return typeof value === "string" && value.trim() !== "" ? value : undefined;
+}
+/**
+ * Extract the assistant `result` text + session id from Cursor headless output. Supports the single
+ * JSON object (`--output-format json`) and a stream-json stream (scans lines for a `result` object).
+ * Returns `outputSeparable: false` when no `result` field can be safely isolated.
+ */
+export function parseCursorAgentOutput(rawOutput) {
+    // A saved export may carry a UTF-8 BOM (e.g. written on Windows). Strip it so a real, parseable
+    // `result` object is not silently mislabeled "unavailable" — the label must match the evidence.
+    const trimmed = rawOutput.replace(/^\uFEFF/, "").trim();
+    // Case 1: a single JSON result object.
+    const whole = (() => {
+        try {
+            return toRecord(JSON.parse(trimmed));
+        }
+        catch {
+            return null;
+        }
+    })();
+    if (whole) {
+        const resultText = stringValue(whole.result);
+        return { resultText, sessionId: stringValue(whole.session_id), outputSeparable: resultText !== undefined };
+    }
+    // Case 2: stream-json — scan lines for a `result` object (last one wins) + a session id.
+    let resultText;
+    let sessionId;
+    for (const line of trimmed.split(/\r?\n/)) {
+        const t = line.trim();
+        if (!t.startsWith("{") || !t.endsWith("}"))
+            continue;
+        let rec;
+        try {
+            rec = toRecord(JSON.parse(t));
+        }
+        catch {
+            continue;
+        }
+        if (!rec)
+            continue;
+        sessionId = sessionId ?? stringValue(rec.session_id);
+        const r = stringValue(rec.result);
+        if (r !== undefined)
+            resultText = r;
+    }
+    return { resultText, sessionId, outputSeparable: resultText !== undefined };
+}
+/**
+ * Best-effort prompt extraction from the wrapped Cursor invocation: the non-flag positional args,
+ * excluding the executable + known subcommand keywords. Used ONLY for a local-estimate of input tokens
+ * (content-free count of text WE passed). Returns undefined when no prompt can be identified.
+ */
+export function extractCursorPrompt(commandParts) {
+    const KEYWORDS = new Set(["cursor", "cursor-agent", "agent", "chat", "exec", "run"]);
+    // Boolean flags take no value, so the token after them is still a positional (e.g. the prompt).
+    // (Cursor selects machine output via `--output-format json` — a value-taking flag, handled below —
+    // so a bare `--json` boolean is intentionally NOT assumed here.)
+    const BOOLEAN_FLAGS = new Set(["-p", "--print", "--force"]);
+    const positionals = [];
+    let skipNext = false;
+    for (let i = 1; i < commandParts.length; i++) {
+        const part = commandParts[i];
+        if (skipNext) {
+            skipNext = false; // the value of a preceding value-taking flag (e.g. `--output-format json`)
+            continue;
+        }
+        if (part.startsWith("-")) {
+            if (!BOOLEAN_FLAGS.has(part) && !part.includes("="))
+                skipNext = true;
+            continue;
+        }
+        if (KEYWORDS.has(part))
+            continue;
+        positionals.push(part);
+    }
+    const prompt = positionals.join(" ").trim();
+    return prompt === "" ? undefined : prompt;
+}
+function addMessage(messages, role, content, timestamp, metadata) {
+    messages.push({ id: `cursor_msg_${messages.length + 1}`, role, content, timestamp, metadata });
+}
+const CURSOR_LOCAL_ESTIMATE_NOTE = "Cursor CLI emits no provider usage; tokens are LOCAL-ESTIMATE only (chars/4) — never provider-reported, never billing-confirmed.";
+/** Build an `AgentTrace` + LOCAL-ESTIMATE usage from captured Cursor headless output. */
+export function normalizeCursorAgentOutput(params) {
+    const generatedAt = params.generatedAt ?? new Date().toISOString();
+    const startedAt = params.commandRun?.startedAt ?? generatedAt;
+    const { resultText, sessionId, outputSeparable } = parseCursorAgentOutput(params.rawOutput);
+    const prompt = params.commandParts ? extractCursorPrompt(params.commandParts) : undefined;
+    const warnings = [];
+    const messages = [];
+    addMessage(messages, "system", "Cursor headless CLI capture (command wrapper).", startedAt, {
+        integration: "cursor",
+        captureMode: "command wrapper"
+    });
+    if (prompt)
+        addMessage(messages, "user", prompt, startedAt, { eventType: "prompt", tokenSource: "local-estimate" });
+    if (resultText)
+        addMessage(messages, "assistant", resultText, generatedAt, { eventType: "result", tokenSource: "local-estimate" });
+    // Input: local-estimate from the prompt where available. Output: local-estimate from the separable
+    // result field, else UNAVAILABLE (absent + a stated reason). Never provider-reported, never fabricated.
+    const inputTokens = prompt ? estimateTextTokens(prompt) : undefined;
+    const outputTokens = resultText ? estimateTextTokens(resultText) : undefined;
+    // The TRUE per-run unavailability reason: an EMPTY export/captured output is a different failure from
+    // present-but-not-separable output, and the guidance differs (`--output-format json` cannot fix an
+    // empty file). Stated exactly so the operator is never sent down the wrong path.
+    const outputUnavailableReason = outputSeparable
+        ? undefined
+        : params.rawOutput.trim() === ""
+            ? "the Cursor headless output is empty (no output was captured/saved — nothing to count)"
+            : "no separable `result` field in the Cursor headless output (use `--output-format json`)";
+    // The TRUE per-run reason input is unavailable. Export-only (no invocation declared at all) is a
+    // DIFFERENT situation from a declared invocation in which no prompt could be identified — the reason
+    // and the fix differ, so both are stated precisely (never a bare "unknown", never a fabricated count).
+    // The documented Cursor headless output (json / stream-json) carries result/session_id/duration —
+    // NOT the prompt — so input can never be derived from the export itself without format-guessing.
+    const inputUnavailableReason = prompt
+        ? undefined
+        : params.commandParts === undefined
+            ? "a saved Cursor export does not contain the prompt (the documented headless output carries the result, not the user input), and no invocation was declared after --"
+            : "no prompt could be identified in the wrapped invocation";
+    if (inputUnavailableReason) {
+        warnings.push(`Input tokens UNAVAILABLE: ${inputUnavailableReason}.`, params.commandParts === undefined
+            ? 'To get a LOCAL-ESTIMATE input count (chars/4 of the prompt YOU declare — never provider-reported), re-declare the original invocation after --: compaction run cursor --out <dir> --export <file> -- cursor agent -p "<your prompt>" --output-format json (same for capture cursor).'
+            : 'To get a LOCAL-ESTIMATE input count, pass the prompt in the invocation (e.g. cursor agent -p "<your prompt>" --output-format json).');
+    }
+    if (outputUnavailableReason) {
+        warnings.push(`Output tokens UNAVAILABLE: ${outputUnavailableReason}. ` +
+            "Provider-reported output is unavailable (Cursor emits no usage).");
+    }
+    const limitations = [CURSOR_LOCAL_ESTIMATE_NOTE];
+    // Both per-axis unavailability reasons ride in limitations so the SAME reason reaches every surface
+    // that renders this capture (CLI stdout notes, the local run record's notes, the summary rollup).
+    if (inputUnavailableReason)
+        limitations.push(`Input tokens are unavailable for this run (${inputUnavailableReason}).`);
+    if (outputUnavailableReason)
+        limitations.push(`Output tokens are unavailable for this run (${outputUnavailableReason}).`);
+    const usageMetadata = createUsageMetadata({
+        ...(inputTokens !== undefined ? { inputTokens } : {}),
+        ...(outputTokens !== undefined ? { outputTokens } : {}),
+        providerReportedTokens: false,
+        estimatedTokens: true,
+        provider: "cursor",
+        limitations
+    });
+    const trace = {
+        id: sessionId ?? `trace_cursor_${params.captureId}`,
+        title: "Cursor headless captured trace",
+        artifactVersion: CURRENT_AGENT_TRACE_ARTIFACT_VERSION,
+        source: "local_command",
+        createdAt: startedAt,
+        generatedAt,
+        model: "cursor-unknown-model",
+        command: params.commandRun
+            ? { command: params.commandRun.command.executable, args: params.commandRun.command.args, cwd: process.cwd() }
+            : { command: "cursor-export", args: [], cwd: process.cwd() },
+        durationMs: params.commandRun?.durationMs ?? 0,
+        exitCode: params.commandRun?.exitCode ?? 0,
+        messages
+    };
+    return {
+        trace,
+        usageMetadata,
+        inputStatus: prompt ? "present" : "unavailable",
+        ...(inputUnavailableReason !== undefined ? { inputUnavailableReason } : {}),
+        outputStatus: outputSeparable ? "present" : "unavailable",
+        ...(outputUnavailableReason !== undefined ? { outputUnavailableReason } : {}),
+        warnings
+    };
+}
+/** Live wrapper: spawn the Cursor headless CLI (no manual export), capture stdout, normalize. */
+export async function captureCursorCommand(commandParts, generatedAt) {
+    const parsed = parseRunCommand(commandParts);
+    const commandRun = await executeLocalCommand(parsed);
+    const result = normalizeCursorAgentOutput({
+        captureId: `${parsed.executable}-${commandRun.startedAt}`,
+        rawOutput: commandRun.rawOutput,
+        commandParts,
+        commandRun,
+        generatedAt
+    });
+    return { ...result, commandRun };
+}
+/** Offline/fallback: normalize a saved Cursor headless output (json / stream-json) string. */
+export function captureCursorExport(rawOutput, commandParts, generatedAt) {
+    return normalizeCursorAgentOutput({ captureId: "cursor-export", rawOutput, commandParts, generatedAt });
+}
+//# sourceMappingURL=cursor-capture.js.map

package/dist/core/cursor-preflight-probe.d.ts

@@ -0,0 +1,8 @@
+import type { CursorProbe } from "./cursor-preflight.js";
+/** True when EVERY arg is a recognized safe help/version token (no prompt, no `-p`, no `login`). */
+export declare function isSafeProbeArgs(args: string[]): boolean;
+/**
+ * Create the real SAFE probe. The returned probe spawns `<candidate> <args>` ONLY when `args` is a
+ * recognized safe help probe; otherwise it refuses (returns `resolved:false` without spawning).
+ */
+export declare function createSafeCursorProbe(timeoutMs?: number): CursorProbe;