iteration-cli 0.7.3 → 0.8.1

package/README.md

@@ -7,11 +7,15 @@ npm install --global iteration-cli
 iteration connect
 ```
 
-The collectors run on macOS or Linux with Node.js 22 or later. Linux needs systemd. The CLI automatically enables background collection after logout and installs a user service that starts at boot and restarts on failure. If server policy does not let the user enable this, an administrator must allow background services for the account. The setting applies to the whole Linux account and remains enabled after `iteration disconnect`; the CLI does not turn off other user services. `iteration connect` finds supported agents with local session directories, asks once before uploading their saved sessions and future activity, and connects them to one workspace. A connected collector checks for newly detected supported agents and connects them under that approval. Each source has its own background process, local checkpoint, and upload queue. Run `iteration` to see connected sources, `iteration status codex` or `iteration status claude` for details, and `iteration help` for other commands. `iteration connect codex` and `iteration connect claude` remain available for advanced source-specific setups.
+The collectors run on macOS or Linux with Node.js 22 or later. Cursor's local Agents window collector is tested on macOS. Linux needs systemd. The CLI automatically enables background collection after logout and installs a user service that starts at boot and restarts on failure. If server policy does not let the user enable this, an administrator must allow background services for the account. The setting applies to the whole Linux account and remains enabled after `iteration disconnect`; the CLI does not turn off other user services. `iteration connect` finds supported agents with local session directories, asks once before uploading their saved sessions and future activity, and connects them to one workspace. A connected collector checks for newly detected supported agents and connects them under that approval. Each source has its own background process, local checkpoint, and upload queue. Run `iteration` to see connected sources, `iteration status cursor` for Cursor details, and `iteration help` for other commands. Source-specific connect commands remain available for advanced setups.
+
+Cursor's **This Mac** Agents sessions are read from `~/.cursor/projects/*/agent-transcripts/<conversation>/<conversation>.jsonl`. Connecting Cursor also installs user-level hooks in `~/.cursor/hooks.json` automatically. They capture tool output, thought blocks, model and usage fields, subagent transcripts, and other lifecycle records that the main transcript omits; the collector queues those records locally before upload. Existing hooks are preserved, and `iteration disconnect cursor` removes only Iteration's entries. No Cursor approval or settings step is needed. A custom Cursor directory can be selected with `iteration connect cursor --cursor-home DIR`. Local history predating connection has transcript messages and tool calls, but tool results that Cursor never wrote to its transcript cannot be recovered. Cloud Agents are outside this local collector.
+
+The collector replaces detected secrets with `[REDACTED]` before writing trace events to the upload outbox. It also redacts pending events left by an older collector before uploading them. This applies to Codex, Claude Code, and Cursor, including Cursor subagent transcript bytes stored as base64. Detection is best effort; original local agent files and previously uploaded traces are unchanged.
 
 Claude Code sessions are read from `~/.claude/projects`, including session subagents. If Claude uses `CLAUDE_CONFIG_DIR`, the collector follows that setting during connection; `iteration connect claude --claude-home DIR` selects another directory explicitly. The collector reads only saved local JSONL records. Claude Code may remove old transcripts under its own retention settings, so connect before local history is removed. The records can contain prompts, reasoning, tool input and output, and context snapshots; workspace members can read what uploads. Unknown record shapes are reported as capture gaps in the collector log. Remote Claude sessions are outside this local collector.
 
-Connecting also adds a Stop hook to the coding agent. After an agent turn in a git repository where you had friction episodes this week, it shows one line such as `◆ Iteration · 3 friction episodes in this repo this week · 1 new since yesterday`. The hook reads local files only and adds a few milliseconds to a turn. Codex asks you to approve it once with `/hooks`. `iteration disconnect` removes it.
+Connecting Codex or Claude Code also adds a Stop hook to the coding agent. After an agent turn in a git repository where you had friction episodes this week, it shows one line such as `◆ Iteration · 3 friction episodes in this repo this week · 1 new since yesterday`. The hook reads local files only and adds a few milliseconds to a turn. Codex asks you to approve it once with `/hooks`. `iteration disconnect` removes it.
 
 To rescan older local sessions, preview with `iteration import-history claude`, then confirm with `iteration import-history claude --yes`. Use `iteration start claude` to restart collection and `iteration disconnect claude` to stop its background process without deleting local pending data.
 

package/dist/auto-connect.d.ts

@@ -10,6 +10,7 @@ export type MachineConsent = Readonly<{
     sourceHomes: Readonly<{
         codex: string;
         claude: string;
+        cursor: string;
     }>;
 }>;
 export declare function sourceHome(source: CollectorSource): string;

package/dist/auto-connect.js

@@ -7,6 +7,7 @@ import { COLLECTOR_SOURCES, parseCollectorEnrollmentResponse, } from "iteration-
 import { installBackgroundService } from "./background-service.js";
 import { collectorFetch } from "./collector-fetch.js";
 import { installTurnSummary } from "./turn-summary.js";
+import { installCursorHooks } from "./cursor-hooks.js";
 import { assertFreshCollectorDirectory, collectorPaths, defaultCollectorDirectory, ensurePrivateDirectory, loadConfig, prepareSourceInitialState, saveConfig, saveState, validateCollectorEndpoint, } from "./storage.js";
 const consentSchema = z
     .object({
@@ -15,7 +16,13 @@ const consentSchema = z
     organizationId: z.uuid(),
     anchorSource: z.enum(COLLECTOR_SOURCES),
     anchorDataDirectory: z.string(),
-    sourceHomes: z.object({ codex: z.string(), claude: z.string() }).strict(),
+    sourceHomes: z
+        .object({
+        codex: z.string(),
+        claude: z.string(),
+        cursor: z.string().default(path.join(os.homedir(), ".cursor")),
+    })
+        .strict(),
 })
     .strict();
 function consentPath() {
@@ -24,7 +31,9 @@ function consentPath() {
 export function sourceHome(source) {
     return path.resolve(source === "codex"
         ? (process.env.CODEX_HOME ?? path.join(os.homedir(), ".codex"))
-        : (process.env.CLAUDE_CONFIG_DIR ?? path.join(os.homedir(), ".claude")));
+        : source === "claude"
+            ? (process.env.CLAUDE_CONFIG_DIR ?? path.join(os.homedir(), ".claude"))
+            : path.join(os.homedir(), ".cursor"));
 }
 export async function detectedSources(sourceHomes) {
     const detected = [];
@@ -156,10 +165,14 @@ export async function activateSource(source, home, endpoint, enrollment, state)
     };
     const config = source === "codex"
         ? { ...common, codexHome: home }
-        : { ...common, source: "claude", claudeHome: home };
+        : source === "claude"
+            ? { ...common, source: "claude", claudeHome: home }
+            : { ...common, source: "cursor", cursorHome: home };
     await saveConfig(config, paths);
     try {
         await saveState(state, paths);
+        if (source === "cursor")
+            await installCursorHooks(home, directory);
         await installBackgroundService(directory, source);
     }
     catch (error) {
@@ -192,7 +205,8 @@ export async function connectNewDetectedSources(anchor, consent) {
         const config = await activateSource(source, consent.sourceHomes[source], consent.endpoint, enrollment, state);
         connected.push(source);
         try {
-            await installTurnSummary(config);
+            if (source !== "cursor")
+                await installTurnSummary(config);
         }
         catch (error) {
             console.error(JSON.stringify({

package/dist/clerk-device-auth.js

@@ -188,7 +188,7 @@ async function clerkDeviceSignIn(configuration) {
 }
 async function enrollDevice(endpoint, accessToken, deviceName, organizationId, source) {
     const body = { deviceName };
-    if (source === "claude")
+    if (source !== "codex")
         body.source = source;
     if (organizationId !== null)
         body.organizationId = organizationId;

package/dist/cli.js

@@ -9,6 +9,7 @@ import { COLLECTOR_SOURCES, collectorSourceLabel, } from "iteration-trace-contra
 import { authenticateAndEnrollCollector } from "./clerk-device-auth.js";
 import { activateSource, connectedConfig, detectedSources, expandSource, loadMachineConsent, readCollectorScope, saveMachineConsent, sourceHome, } from "./auto-connect.js";
 import { importSourceHistory } from "./history-import.js";
+import { cursorHookFailureAtMs, installCursorHooks, uninstallCursorHooks, } from "./cursor-hooks.js";
 import { runCollector } from "./service.js";
 import { renderDetailedStatus, renderHome, safeWorkspaceName, } from "./status-view.js";
 import { installTurnSummary, codexTurnSummaryApproval, uninstallTurnSummary, } from "./turn-summary.js";
@@ -27,6 +28,7 @@ function argumentsForCli() {
             "organization-id": { type: "string" },
             "codex-home": { type: "string" },
             "claude-home": { type: "string" },
+            "cursor-home": { type: "string" },
             "data-directory": { type: "string" },
             "include-history": { type: "boolean" },
             yes: { type: "boolean" },
@@ -58,6 +60,7 @@ function usage(command) {
             "  iteration connect         Connect all detected agents on this computer",
             "  iteration connect codex",
             "  iteration connect claude",
+            "  iteration connect cursor",
             "",
             "Existing local sessions and new activity are collected automatically.",
             "",
@@ -66,6 +69,7 @@ function usage(command) {
             "  --organization-id UUID  Select a workspace without a prompt",
             "  --codex-home DIR        Use a different Codex data directory",
             "  --claude-home DIR       Use a different Claude data directory",
+            "  --cursor-home DIR       Use a different Cursor data directory",
             "  --yes                  Approve uploads without a terminal prompt",
             "  --data-directory DIR   Use a different state directory with a source-specific command",
             "  --endpoint URL         Use a different Iteration server",
@@ -81,8 +85,8 @@ function usage(command) {
         "Commands:",
         "  iteration                 See connection status",
         "  iteration status          See scan, upload, and error details",
-        "  iteration connect codex|claude  Connect one source (advanced)",
-        "  iteration disconnect codex|claude  Stop a source",
+        "  iteration connect codex|claude|cursor  Connect one source (advanced)",
+        "  iteration disconnect codex|claude|cursor  Stop a source",
         "",
         "Run iteration connect --help for advanced setup options.",
     ].join("\n") + "\n");
@@ -102,21 +106,20 @@ async function fileExists(filename) {
     }
 }
 async function defaultCommand() {
-    const [codex, claude] = await Promise.all([
-        statusSnapshot("codex", {}),
-        statusSnapshot("claude", {}),
-    ]);
-    const connected = [
-        { source: "codex", snapshot: codex },
-        { source: "claude", snapshot: claude },
-    ].filter(({ snapshot }) => snapshot.kind !== "not_connected");
+    const snapshots = await Promise.all(COLLECTOR_SOURCES.map(async (source) => ({
+        source,
+        snapshot: await statusSnapshot(source, {}),
+    })));
+    const connected = snapshots.filter(({ snapshot }) => snapshot.kind !== "not_connected");
     if (connected.length > 0) {
         process.stdout.write(`${connected.map(({ source, snapshot }) => renderHome(snapshot, Date.now(), source)).join("\n\n")}\n`);
         const discovered = await detectedSources({
             codex: sourceHome("codex"),
             claude: sourceHome("claude"),
+            cursor: sourceHome("cursor"),
         });
-        const missing = discovered.filter((source) => (source === "codex" ? codex : claude).kind === "not_connected");
+        const missing = discovered.filter((source) => snapshots.find((item) => item.source === source)?.snapshot.kind ===
+            "not_connected");
         if (missing.length > 0) {
             process.stdout.write(`\n${missing.map(collectorSourceLabel).join(" and ")} found on this computer but not connected. Run iteration connect to include ${missing.length === 1 ? "it" : "them"}.\n`);
         }
@@ -133,6 +136,8 @@ function dataDirectory(source, values) {
         defaultCollectorDirectory(source));
 }
 async function turnSummaryNotice(config) {
+    if ("cursorHome" in config)
+        return " Cursor hooks capture tool results and usage automatically.";
     try {
         await installTurnSummary(config);
         if ((await codexTurnSummaryApproval(config)) === "needs_approval") {
@@ -152,15 +157,18 @@ async function initialize(source, values) {
     const organizationId = optionalString(values, "organization-id");
     const directory = dataDirectory(source, values);
     const paths = collectorPaths(directory);
-    const sourceHome = path.resolve(source === "codex"
+    const selectedHome = path.resolve(source === "codex"
         ? (optionalString(values, "codex-home") ??
             process.env.CODEX_HOME ??
             path.join(os.homedir(), ".codex"))
-        : (optionalString(values, "claude-home") ??
-            process.env.CLAUDE_CONFIG_DIR ??
-            path.join(os.homedir(), ".claude")));
+        : source === "claude"
+            ? (optionalString(values, "claude-home") ??
+                process.env.CLAUDE_CONFIG_DIR ??
+                path.join(os.homedir(), ".claude"))
+            : (optionalString(values, "cursor-home") ??
+                path.join(os.homedir(), ".cursor")));
     await assertFreshCollectorDirectory(paths, source);
-    const preparedState = await prepareSourceInitialState(source, sourceHome, true);
+    const preparedState = await prepareSourceInitialState(source, selectedHome, true);
     await prepareBackgroundPersistence();
     const enrollment = await authenticateAndEnrollCollector(endpointUrl, deviceName, organizationId, source);
     const connection = {
@@ -171,11 +179,15 @@ async function initialize(source, values) {
         organizationName: enrollment.organizationName,
     };
     const config = source === "codex"
-        ? { ...connection, codexHome: sourceHome }
-        : { ...connection, source: "claude", claudeHome: sourceHome };
+        ? { ...connection, codexHome: selectedHome }
+        : source === "claude"
+            ? { ...connection, source: "claude", claudeHome: selectedHome }
+            : { ...connection, source: "cursor", cursorHome: selectedHome };
     await saveConfig(config, paths);
     try {
         await saveState(preparedState, paths);
+        if (source === "cursor")
+            await installCursorHooks(selectedHome, directory);
     }
     catch (error) {
         throw new Error(`Collector access was approved, but local setup did not finish. Run iteration start ${source} to repair it.`, { cause: error });
@@ -230,11 +242,15 @@ async function connectAll(values) {
             (configs[1] && "claudeHome" in configs[1]
                 ? configs[1].claudeHome
                 : sourceHome("claude"))),
+        cursor: path.resolve(optionalString(values, "cursor-home") ??
+            (configs[2] && "cursorHome" in configs[2]
+                ? configs[2].cursorHome
+                : sourceHome("cursor"))),
     };
     const detected = await detectedSources(sourceHomes);
     const existing = COLLECTOR_SOURCES.flatMap((source, index) => configs[index] ? [{ source, config: configs[index] }] : []);
     if (detected.length === 0 && existing.length === 0) {
-        process.stdout.write("No supported local coding agents found yet. Run iteration connect after using Codex or Claude Code on this computer.\n");
+        process.stdout.write("No supported local coding agents found yet. Run iteration connect after using Codex, Claude Code, or Cursor on this computer.\n");
         return;
     }
     const anchorSource = existing[0]?.source ?? detected[0];
@@ -269,7 +285,8 @@ async function connectAll(values) {
         previousConsent.organizationId !==
             existingScopes[0]?.scope.organizationId ||
         previousConsent.sourceHomes.codex !== sourceHomes.codex ||
-        previousConsent.sourceHomes.claude !== sourceHomes.claude) {
+        previousConsent.sourceHomes.claude !== sourceHomes.claude ||
+        previousConsent.sourceHomes.cursor !== sourceHomes.cursor) {
         await approveAllSources(detected, existingScopes[0]?.scope.organizationName ?? null, values.yes === true);
     }
     await prepareBackgroundPersistence();
@@ -308,6 +325,8 @@ async function connectAll(values) {
     });
     for (const item of existing) {
         await ensureStartableState(item.config, collectorPaths(item.config.dataDirectory));
+        if ("cursorHome" in item.config)
+            await installCursorHooks(item.config.cursorHome, item.config.dataDirectory);
         await installBackgroundService(item.config.dataDirectory, item.source);
         const notice = await turnSummaryNotice(item.config);
         process.stdout.write(`${collectorSourceLabel(item.source)} is still connected.${notice}\n`);
@@ -338,6 +357,8 @@ async function start(source, values) {
     if (collectorSource(config) !== source)
         throw new Error(`This collector directory belongs to ${collectorSource(config)}.`);
     const repairedState = await ensureStartableState(config, paths);
+    if ("cursorHome" in config)
+        await installCursorHooks(config.cursorHome, config.dataDirectory);
     await installBackgroundService(directory, source);
     const notice = await turnSummaryNotice(config);
     process.stdout.write(`${collectorSourceLabel(source)} is collecting again. Run iteration to check progress.${repairedState ? " Incomplete setup was repaired." : ""}${notice}\n`);
@@ -357,13 +378,16 @@ async function statusSnapshot(source, values) {
     const config = await loadConfig(paths);
     if (collectorSource(config) !== source)
         throw new Error(`This collector directory belongs to ${collectorSource(config)}.`);
-    const [running, size, ids, scan, localHealth, approval] = await Promise.all([
+    const [running, size, ids, scan, localHealth, approval, hookFailureAtMs] = await Promise.all([
         backgroundServiceStatus(source),
         outboxSize(paths),
         pendingEventIds(paths),
         historyScanProgress(collectorSourceDirectory(config), paths, source),
         healthSnapshot(paths),
         codexTurnSummaryApproval(config),
+        source === "cursor"
+            ? cursorHookFailureAtMs(config.dataDirectory)
+            : Promise.resolve(null),
     ]);
     const pendingEvents = size === 0 ? 0 : ids.size;
     const pendingBytes = ids.size === 0 ? 0 : size;
@@ -377,6 +401,7 @@ async function statusSnapshot(source, values) {
         health: localHealth.health,
         healthAvailable: localHealth.kind === "available",
         turnSummaryNeedsApproval: approval === "needs_approval",
+        hookFailureAtMs,
         tracesUrl: new URL("/app/sessions", config.endpoint).toString(),
         logPath: collectorLogPath(source),
     };
@@ -387,15 +412,17 @@ async function status(source, values) {
         process.stdout.write(`${renderDetailedStatus(snapshot, Date.now(), source)}\n`);
         return;
     }
-    const [codex, claude] = await Promise.all([
-        statusSnapshot("codex", values),
-        statusSnapshot("claude", values),
-    ]);
-    process.stdout.write(`${renderDetailedStatus(codex, Date.now(), "codex")}\n\n${renderDetailedStatus(claude, Date.now(), "claude")}\n`);
+    const snapshots = await Promise.all(COLLECTOR_SOURCES.map(async (item) => ({
+        source: item,
+        snapshot: await statusSnapshot(item, values),
+    })));
+    process.stdout.write(`${snapshots.map(({ source: item, snapshot }) => renderDetailedStatus(snapshot, Date.now(), item)).join("\n\n")}\n`);
 }
 async function main() {
     const { command, source, values } = argumentsForCli();
-    const selectedSource = source === "codex" || source === "claude" ? source : null;
+    const selectedSource = source === "codex" || source === "claude" || source === "cursor"
+        ? source
+        : null;
     if (values.help === true || command === "help") {
         return usage(command === "help" ? source : command);
     }
@@ -413,10 +440,9 @@ async function main() {
         return defaultCommand();
     }
     if (selectedSource !== null) {
-        if (selectedSource === "codex" && values["claude-home"] !== undefined)
-            throw new Error("--claude-home requires the Claude source.");
-        if (selectedSource === "claude" && values["codex-home"] !== undefined)
-            throw new Error("--codex-home requires the Codex source.");
+        for (const name of ["codex", "claude", "cursor"])
+            if (selectedSource !== name && values[`${name}-home`] !== undefined)
+                throw new Error(`--${name}-home requires the ${collectorSourceLabel(name)} source.`);
     }
     if (command === "connect" && selectedSource !== null) {
         await initialize(selectedSource, values);
@@ -424,7 +450,7 @@ async function main() {
     }
     if (command === "run") {
         if (source !== undefined && selectedSource === null)
-            throw new Error("The run source must be codex or claude.");
+            throw new Error("The run source must be codex, claude, or cursor.");
         return runCollector(optionalString(values, "data-directory") ?? undefined, selectedSource ?? undefined);
     }
     if (command === "status" &&
@@ -441,7 +467,11 @@ async function main() {
         await uninstallBackgroundService(selectedSource);
         const paths = collectorPaths(dataDirectory(selectedSource, values));
         if (await fileExists(paths.config)) {
-            await uninstallTurnSummary(await loadConfig(paths));
+            const config = await loadConfig(paths);
+            if ("cursorHome" in config)
+                await uninstallCursorHooks(config.cursorHome, config.dataDirectory);
+            else
+                await uninstallTurnSummary(config);
         }
         process.stdout.write("Collector startup removed. Local pending data was retained.\n");
         return;

package/dist/collector.js

@@ -3,8 +3,11 @@ import path from "node:path";
 import { parseTraceEventAcknowledgement, } from "iteration-trace-contracts";
 import { collectorFetch } from "./collector-fetch.js";
 import { parseClaudeLine } from "./claude-transcript.js";
+import { cursorHookFiles } from "./cursor-hooks.js";
+import { parseCursorHookLine, parseCursorTranscriptLine, } from "./cursor-transcript.js";
+import { redactTraceEvent } from "./redact-trace.js";
 import { parseRolloutLine } from "./rollout.js";
-import { acknowledgeEvents, appendEvents, collectorSource, collectorSourceDirectory, loadState, nextBatch, outboxSize, pendingEventIds, sourceFiles, saveState, } from "./storage.js";
+import { acknowledgeEvents, appendEvents, collectorSource, collectorSourceDirectory, loadState, nextBatch, outboxSize, pendingEventIds, redactPendingOutbox, sourceFiles, saveState, } from "./storage.js";
 const MAX_SCAN_BYTES_PER_FILE = 16 * 1024 * 1024;
 const MAX_SCAN_BYTES_PER_TICK = 16 * 1024 * 1024;
 const MAX_RECORD_BYTES = 3 * 1024 * 1024;
@@ -41,6 +44,10 @@ function logGap(filename, offset, reason) {
 function parseSourceRecord(source, line, filename, byteOffset) {
     if (source === "claude")
         return parseClaudeLine(line, filename, byteOffset);
+    if (source === "cursor")
+        return filename.includes(`${path.sep}cursor-hooks${path.sep}`)
+            ? parseCursorHookLine(line, filename)
+            : parseCursorTranscriptLine(line, filename, byteOffset);
     if (source === "codex") {
         const parsed = parseRolloutLine(line, filename, byteOffset);
         return parsed.kind === "event"
@@ -62,13 +69,21 @@ export async function scanSourceOnce(config, paths, signal) {
     }
     const cursors = { ...state.cursors };
     const skipping = new Set(state.skipping);
-    const files = await sourceFiles(source, sourceDirectory);
+    const files = [
+        ...(await sourceFiles(source, sourceDirectory)),
+        ...(source === "cursor" ? await cursorHookFiles(config.dataDirectory) : []),
+    ];
+    const completedHooks = [];
     const queuedIds = await pendingEventIds(paths);
     const events = [];
     let remainingBudget = MAX_SCAN_BYTES_PER_TICK;
     let caughtUp = true;
     for (const filename of files) {
         signal?.throwIfAborted();
+        const recordLimit = source === "cursor" &&
+            filename.includes(`${path.sep}cursor-hooks${path.sep}`)
+            ? 12 * 1024 * 1024
+            : MAX_RECORD_BYTES;
         if (remainingBudget === 0) {
             caughtUp = false;
             break;
@@ -118,7 +133,7 @@ export async function scanSourceOnce(config, paths, signal) {
             if (lineBytes.at(-1) === 13)
                 lineBytes = lineBytes.subarray(0, -1);
             const byteOffset = offset + lineStart;
-            if (lineBytes.length > MAX_RECORD_BYTES) {
+            if (lineBytes.length > recordLimit) {
                 logGap(filename, byteOffset, "rollout_record_exceeds_scan_limit");
                 lineStart = index + 1;
                 continue;
@@ -138,25 +153,34 @@ export async function scanSourceOnce(config, paths, signal) {
             for (const parsedEvent of parsed.events) {
                 if (queuedIds.has(parsedEvent.eventId))
                     continue;
-                const eventBytes = Buffer.byteLength(JSON.stringify(parsedEvent), "utf8");
+                const event = await redactTraceEvent(parsedEvent);
+                const eventBytes = Buffer.byteLength(JSON.stringify(event), "utf8");
                 if (eventBytes > MAX_EVENT_BYTES) {
                     logGap(filename, byteOffset, "normalized_event_exceeds_upload_limit");
                 }
                 else {
-                    events.push(parsedEvent);
-                    queuedIds.add(parsedEvent.eventId);
+                    events.push(event);
+                    queuedIds.add(event.eventId);
                 }
             }
             lineStart = index + 1;
         }
-        if (buffer.length - lineStart > MAX_RECORD_BYTES) {
+        if (buffer.length - lineStart > recordLimit) {
             logGap(filename, offset + lineStart, "incomplete_rollout_record_exceeds_scan_limit");
             skipping.add(filename);
             lineStart = buffer.length;
         }
         cursors[filename] = offset + lineStart;
+        if (source === "cursor" &&
+            filename.includes(`${path.sep}cursor-hooks${path.sep}`) &&
+            cursors[filename] === stats.size)
+            completedHooks.push(filename);
     }
     await appendEvents(events, paths);
+    for (const filename of completedHooks) {
+        await fs.rm(filename);
+        delete cursors[filename];
+    }
     await saveState({
         cursors,
         skipping: [...skipping],
@@ -217,6 +241,7 @@ async function uploadPendingOnce(config, paths, fetcher = collectorFetch, signal
     return uploaded;
 }
 export async function collectorTick(config, paths, fetcher = collectorFetch, signal, onAcknowledged) {
+    await redactPendingOutbox(paths);
     let uploaded = await uploadPendingOnce(config, paths, fetcher, signal, onAcknowledged);
     const scan = (await outboxSize(paths)) >= SCAN_PAUSE_OUTBOX_BYTES
         ? { discovered: 0, caughtUp: false }

package/dist/cursor-hook-entry.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cursor-hook-entry.js

@@ -0,0 +1,157 @@
+import { randomUUID } from "node:crypto";
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { StringDecoder } from "node:string_decoder";
+import * as z from "zod";
+import { CURSOR_HOOKS, cursorHookDirectory, cursorHookFailurePath, } from "./cursor-hooks.js";
+const MAX_INPUT_BYTES = 16 * 1024 * 1024;
+const MAX_QUEUE_BYTES = 256 * 1024 * 1024;
+const MAX_QUEUE_FILES = 2000;
+const MAX_SUBAGENT_BYTES = 64 * 1024 * 1024;
+const SUBAGENT_CHUNK_BYTES = 200_000;
+const hookInputSchema = z
+    .object({
+    conversation_id: z.string().optional(),
+    parent_conversation_id: z.string().optional(),
+    subagent_id: z.string().optional(),
+    transcript_path: z.string().nullable().optional(),
+    agent_transcript_path: z.string().nullable().optional(),
+})
+    .loose();
+async function assertQueueCapacity(directory, incomingBytes) {
+    const names = (await fs.readdir(directory)).filter((name) => name.endsWith(".jsonl") || name.endsWith(".tmp"));
+    if (names.length >= MAX_QUEUE_FILES)
+        throw new Error("Cursor hook queue is full.");
+    let total = incomingBytes;
+    for (let start = 0; start < names.length; start += 64) {
+        const sizes = await Promise.all(names.slice(start, start + 64).map(async (name) => {
+            try {
+                return (await fs.stat(path.join(directory, name))).size;
+            }
+            catch (error) {
+                if (error instanceof Error &&
+                    "code" in error &&
+                    error.code === "ENOENT")
+                    return 0;
+                throw error;
+            }
+        }));
+        total += sizes.reduce((sum, size) => sum + size, 0);
+        if (total > MAX_QUEUE_BYTES)
+            throw new Error("Cursor hook queue is full.");
+    }
+}
+async function writeRecord(directory, value) {
+    const serialized = `${JSON.stringify(value)}\n`;
+    const recordBytes = Buffer.byteLength(serialized, "utf8");
+    if (recordBytes > 12 * 1024 * 1024)
+        throw new Error("Cursor hook record exceeds the capture limit.");
+    await assertQueueCapacity(directory, recordBytes);
+    const id = randomUUID();
+    const temporary = path.join(directory, `${id}.tmp`);
+    const filename = path.join(directory, `${id}.jsonl`);
+    const handle = await fs.open(temporary, "wx", 0o600);
+    try {
+        await handle.writeFile(serialized, "utf8");
+        await handle.sync();
+    }
+    catch (error) {
+        await fs.rm(temporary, { force: true });
+        throw error;
+    }
+    finally {
+        await handle.close();
+    }
+    await fs.rename(temporary, filename);
+}
+async function captureSubagentTranscript(directory, input, capturedAt, transcriptBytes) {
+    const filename = input.agent_transcript_path;
+    if (filename === null || filename === undefined || !path.isAbsolute(filename))
+        return;
+    const stats = await fs.stat(filename);
+    if (!stats.isFile() || stats.size > MAX_SUBAGENT_BYTES)
+        throw new Error("Cursor subagent transcript exceeds the capture limit.");
+    const contents = await fs.readFile(filename);
+    const parts = Math.max(1, Math.ceil(contents.length / SUBAGENT_CHUNK_BYTES));
+    const decoder = new StringDecoder("utf8");
+    for (let index = 0; index < parts; index += 1) {
+        const bytes = contents.subarray(index * SUBAGENT_CHUNK_BYTES, (index + 1) * SUBAGENT_CHUNK_BYTES);
+        const text = decoder.write(bytes) + (index === parts - 1 ? decoder.end() : "");
+        await writeRecord(directory, {
+            kind: "subagent_transcript_chunk",
+            capturedAt,
+            transcriptBytes,
+            input: {
+                conversation_id: input.conversation_id,
+                parent_conversation_id: input.parent_conversation_id,
+                subagent_id: input.subagent_id,
+            },
+            subagent: {
+                path: filename,
+                part: index + 1,
+                totalParts: parts,
+                text,
+                base64: bytes.toString("base64"),
+            },
+        });
+    }
+}
+async function main() {
+    const hook = process.argv[2];
+    const dataDirectory = process.argv[3];
+    if (!hook ||
+        !CURSOR_HOOKS.includes(hook) ||
+        !dataDirectory)
+        throw new Error("Invalid Cursor hook command.");
+    const chunks = [];
+    let bytes = 0;
+    for await (const chunk of process.stdin) {
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        bytes += buffer.length;
+        if (bytes > MAX_INPUT_BYTES)
+            throw new Error("Cursor hook input exceeds the capture limit.");
+        chunks.push(buffer);
+    }
+    const input = hookInputSchema.parse(JSON.parse(Buffer.concat(chunks).toString("utf8")));
+    const transcriptPath = input.transcript_path ?? null;
+    let transcriptBytes = null;
+    if (transcriptPath !== null) {
+        try {
+            transcriptBytes = (await fs.stat(transcriptPath)).size;
+        }
+        catch (error) {
+            if (!(error instanceof Error && "code" in error && error.code === "ENOENT"))
+                throw error;
+        }
+    }
+    const directory = cursorHookDirectory(dataDirectory);
+    await fs.mkdir(directory, { recursive: true, mode: 0o700 });
+    const capturedAt = new Date().toISOString();
+    await writeRecord(directory, { hook, capturedAt, transcriptBytes, input });
+    if (hook === "subagentStop")
+        await captureSubagentTranscript(directory, input, capturedAt, transcriptBytes);
+}
+main()
+    .catch(async (error) => {
+    process.stderr.write(`Iteration Cursor capture failed: ${error instanceof Error ? error.message : "unknown error"}\n`);
+    const dataDirectory = process.argv[3];
+    if (dataDirectory) {
+        try {
+            await fs.mkdir(dataDirectory, { recursive: true, mode: 0o700 });
+            const temporary = `${cursorHookFailurePath(dataDirectory)}.${randomUUID()}.tmp`;
+            await fs.writeFile(temporary, `${JSON.stringify({ atMs: Date.now() })}\n`, { mode: 0o600 });
+            await fs.rename(temporary, cursorHookFailurePath(dataDirectory));
+        }
+        catch (statusError) {
+            process.stderr.write(`Iteration could not save the Cursor capture failure: ${statusError instanceof Error ? statusError.message : "unknown error"}\n`);
+        }
+    }
+    process.exitCode = 1;
+})
+    .finally(() => {
+    process.stdout.write(process.argv[2] === "preToolUse" || process.argv[2] === "subagentStart"
+        ? '{"permission":"allow"}\n'
+        : process.argv[2] === "beforeSubmitPrompt"
+            ? '{"continue":true}\n'
+            : "{}\n");
+});

package/dist/cursor-hooks.d.ts

@@ -0,0 +1,7 @@
+export declare const CURSOR_HOOKS: readonly ["sessionStart", "beforeSubmitPrompt", "preToolUse", "postToolUse", "postToolUseFailure", "afterAgentThought", "afterAgentResponse", "preCompact", "stop", "subagentStart", "subagentStop", "sessionEnd"];
+export declare function cursorHookDirectory(dataDirectory: string): string;
+export declare function cursorHookFailurePath(dataDirectory: string): string;
+export declare function cursorHookFailureAtMs(dataDirectory: string): Promise<number | null>;
+export declare function installCursorHooks(cursorHome: string, dataDirectory: string): Promise<void>;
+export declare function uninstallCursorHooks(cursorHome: string, dataDirectory: string): Promise<void>;
+export declare function cursorHookFiles(dataDirectory: string): Promise<string[]>;