iteration-cli 0.7.2 → 0.8.0

package/README.md

@@ -7,11 +7,13 @@ 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.
 
 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-fetch.js

@@ -2,13 +2,12 @@ import http from "node:http";
 import https from "node:https";
 const MAX_RESPONSE_BYTES = 1024 * 1024;
 const NULL_BODY_STATUSES = new Set([101, 103, 204, 205, 304]);
-// Node's fetch can negotiate HTTP/2 and, after a timed-out request breaks the
-// TLS connection, keep handing every later request the destroyed session until
-// the process restarts. The collector runs for days, so it uses HTTP/1.1
-// connections that are discarded when they fail.
+// Reused connections failed uploads in production: Node's HTTP/2 fetch kept a
+// destroyed session, and kept-alive sockets timed out on ~40 s server waits.
+// See docs/architecture/trace-ingestion.md.
 const agents = {
-    "http:": new http.Agent({ keepAlive: true, maxSockets: 2 }),
-    "https:": new https.Agent({ keepAlive: true, maxSockets: 2 }),
+    "http:": new http.Agent({ keepAlive: false }),
+    "https:": new https.Agent({ keepAlive: false }),
 };
 export const collectorFetch = (input, init = {}) => {
     const url = new URL(input);

package/dist/collector.js

@@ -3,6 +3,8 @@ 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 { parseRolloutLine } from "./rollout.js";
 import { acknowledgeEvents, appendEvents, collectorSource, collectorSourceDirectory, loadState, nextBatch, outboxSize, pendingEventIds, sourceFiles, saveState, } from "./storage.js";
 const MAX_SCAN_BYTES_PER_FILE = 16 * 1024 * 1024;
@@ -41,6 +43,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 +68,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 +132,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;
@@ -149,14 +163,22 @@ export async function scanSourceOnce(config, paths, signal) {
             }
             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],

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[]>;

package/dist/cursor-hooks.js

@@ -0,0 +1,163 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import * as z from "zod";
+import { ensurePrivateDirectory } from "./storage.js";
+export const CURSOR_HOOKS = [
+    "sessionStart",
+    "beforeSubmitPrompt",
+    "preToolUse",
+    "postToolUse",
+    "postToolUseFailure",
+    "afterAgentThought",
+    "afterAgentResponse",
+    "preCompact",
+    "stop",
+    "subagentStart",
+    "subagentStop",
+    "sessionEnd",
+];
+export function cursorHookDirectory(dataDirectory) {
+    return path.join(dataDirectory, "cursor-hooks");
+}
+export function cursorHookFailurePath(dataDirectory) {
+    return path.join(dataDirectory, "cursor-hook-failure.json");
+}
+export async function cursorHookFailureAtMs(dataDirectory) {
+    let contents;
+    try {
+        contents = await fs.readFile(cursorHookFailurePath(dataDirectory), "utf8");
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+    let decoded;
+    try {
+        decoded = JSON.parse(contents);
+    }
+    catch (error) {
+        throw new Error("Cursor hook failure status is invalid.", { cause: error });
+    }
+    const parsed = z
+        .object({ atMs: z.number().int().min(0) })
+        .strict()
+        .safeParse(decoded);
+    if (!parsed.success)
+        throw new Error("Cursor hook failure status is invalid.");
+    return parsed.data.atMs;
+}
+function shellQuote(value) {
+    return `'${value.replaceAll("'", `'\\''`)}'`;
+}
+function hookCommand(hook, dataDirectory) {
+    const entry = fileURLToPath(new URL("./cursor-hook-entry.js", import.meta.url));
+    return `${shellQuote(process.execPath)} ${shellQuote(entry)} ${shellQuote(hook)} ${shellQuote(dataDirectory)}`;
+}
+const hookEntrySchema = z.object({ command: z.string().optional() }).loose();
+const hookFileSchema = z
+    .object({
+    version: z.literal(1).optional(),
+    hooks: z.record(z.string(), z.array(hookEntrySchema)).optional(),
+})
+    .loose();
+async function readHooks(filename) {
+    let contents;
+    let mode = 0o600;
+    try {
+        contents = await fs.readFile(filename, "utf8");
+        mode = (await fs.stat(filename)).mode & 0o777;
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT")
+            return { file: {}, mode };
+        throw new Error(`Could not read Cursor hooks at ${filename}.`, {
+            cause: error,
+        });
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(contents);
+    }
+    catch (error) {
+        throw new Error(`Cursor hooks at ${filename} are not valid JSON.`, {
+            cause: error,
+        });
+    }
+    const checked = hookFileSchema.safeParse(parsed);
+    if (!checked.success)
+        throw new Error(`Cursor hooks at ${filename} have an unexpected shape.`);
+    return { file: checked.data, mode };
+}
+async function writeHooks(filename, file, mode) {
+    await ensurePrivateDirectory(path.dirname(filename));
+    const target = await fs.realpath(filename).catch((error) => {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT")
+            return filename;
+        throw error;
+    });
+    const temporary = `${target}.iteration-${process.pid}.tmp`;
+    const handle = await fs.open(temporary, "w", mode);
+    try {
+        await handle.writeFile(`${JSON.stringify(file, null, 2)}\n`, "utf8");
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+    await fs.rename(temporary, target);
+}
+function entries(value) {
+    return value ?? [];
+}
+export async function installCursorHooks(cursorHome, dataDirectory) {
+    await ensurePrivateDirectory(cursorHookDirectory(dataDirectory));
+    const filename = path.join(cursorHome, "hooks.json");
+    const { file, mode } = await readHooks(filename);
+    const hooks = { ...file.hooks };
+    for (const hook of CURSOR_HOOKS) {
+        const command = hookCommand(hook, dataDirectory);
+        const existing = entries(hooks[hook]);
+        if (!existing.some((entry) => entry.command === command))
+            hooks[hook] = [...existing, { command }];
+    }
+    await writeHooks(filename, { ...file, version: 1, hooks }, mode);
+}
+export async function uninstallCursorHooks(cursorHome, dataDirectory) {
+    const filename = path.join(cursorHome, "hooks.json");
+    const { file, mode } = await readHooks(filename);
+    const hooks = { ...file.hooks };
+    let changed = false;
+    for (const hook of CURSOR_HOOKS) {
+        const existing = entries(hooks[hook]);
+        const remaining = existing.filter((entry) => entry.command !== hookCommand(hook, dataDirectory));
+        if (remaining.length !== existing.length) {
+            changed = true;
+            if (remaining.length === 0)
+                delete hooks[hook];
+            else
+                hooks[hook] = remaining;
+        }
+    }
+    if (changed)
+        await writeHooks(filename, { ...file, hooks }, mode);
+}
+export async function cursorHookFiles(dataDirectory) {
+    const directory = cursorHookDirectory(dataDirectory);
+    let names;
+    try {
+        names = await fs.readdir(directory);
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT")
+            return [];
+        throw error;
+    }
+    if (names.length > 10_000)
+        throw new Error("Cursor hook queue exceeds the scan limit.");
+    return names
+        .filter((name) => /^[0-9a-f-]+\.jsonl$/i.test(name))
+        .sort()
+        .map((name) => path.join(directory, name));
+}

package/dist/cursor-transcript.d.ts

@@ -0,0 +1,8 @@
+import { type TraceEvent } from "iteration-trace-contracts";
+type ParseResult = Readonly<{
+    events: readonly TraceEvent[];
+    gaps: readonly string[];
+}>;
+export declare function parseCursorTranscriptLine(line: string, filename: string, byteOffset: number): ParseResult;
+export declare function parseCursorHookLine(line: string, filename: string): ParseResult;
+export {};

package/dist/cursor-transcript.js

@@ -0,0 +1,294 @@
+import { createHash } from "node:crypto";
+import path from "node:path";
+import * as z from "zod";
+import { parseTraceEventBatch, } from "iteration-trace-contracts";
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function record(value) {
+    const parsed = z.record(z.string(), z.json()).safeParse(value);
+    return parsed.success ? parsed.data : null;
+}
+function string(value) {
+    const parsed = z.string().safeParse(value);
+    return parsed.success ? parsed.data : null;
+}
+function nonnegativeInteger(value) {
+    const parsed = z
+        .number()
+        .int()
+        .min(0)
+        .max(Number.MAX_SAFE_INTEGER)
+        .safeParse(value);
+    return parsed.success ? parsed.data : null;
+}
+function event(conversationId, filename, byteOffset, index, eventType, payload, callId = null, occurredAt = null) {
+    const hash = createHash("sha256")
+        .update(`${filename}:${byteOffset}:${index}:${eventType}`)
+        .digest("hex");
+    return {
+        eventId: `${String(index).padStart(4, "0")}:${hash}`,
+        sessionId: `cursor:${conversationId}`,
+        sequence: byteOffset * 1000 + index,
+        callId,
+        projectId: null,
+        occurredAt,
+        eventType,
+        payload,
+    };
+}
+export function parseCursorTranscriptLine(line, filename, byteOffset) {
+    const conversationId = path.basename(filename, ".jsonl");
+    if (!UUID.test(conversationId) ||
+        path.basename(path.dirname(filename)) !== conversationId)
+        return { events: [], gaps: ["invalid_cursor_transcript_path"] };
+    let decoded;
+    try {
+        decoded = JSON.parse(line);
+    }
+    catch {
+        return { events: [], gaps: ["malformed_jsonl_record"] };
+    }
+    const source = record(decoded);
+    if (source === null)
+        return { events: [], gaps: ["record_is_not_an_object"] };
+    const events = [];
+    const gaps = [];
+    if (byteOffset === 0) {
+        events.push({
+            ...event(conversationId, filename, 0, 0, "session_meta", {
+                id: conversationId,
+                transcript_path: filename,
+            }),
+            run: {
+                kind: "identity",
+                id: conversationId,
+                parentId: null,
+                ownStart: true,
+                startOrdinal: null,
+            },
+        });
+    }
+    const role = string(source.role);
+    if (role === "user" || role === "assistant") {
+        const message = record(source.message);
+        if (message === null || !Array.isArray(message.content))
+            gaps.push("cursor_message_without_content");
+        else {
+            for (const [index, value] of message.content.entries()) {
+                const block = record(value);
+                if (block === null) {
+                    gaps.push("invalid_cursor_content_block");
+                    continue;
+                }
+                const type = string(block.type);
+                const eventType = type === "tool_use"
+                    ? "tool_call"
+                    : type === "thinking"
+                        ? "reasoning"
+                        : type === "text"
+                            ? role === "user"
+                                ? "user_message"
+                                : "assistant_message"
+                            : "source_record";
+                events.push(event(conversationId, filename, byteOffset, index + 1, eventType, {
+                    text: string(block.text) ?? string(block.thinking),
+                    name: string(block.name),
+                    input: block.input ?? null,
+                    sourceType: type,
+                    record: source,
+                }, string(block.id)));
+                if (type !== "text" && type !== "tool_use" && type !== "thinking")
+                    gaps.push(`unsupported_cursor_content_block:${type ?? "unknown"}`);
+            }
+        }
+    }
+    else if (source.type === "turn_ended") {
+        events.push(event(conversationId, filename, byteOffset, 1, source.status === "success" ? "turn_complete" : "turn_aborted", { record: source }));
+    }
+    else {
+        gaps.push(`unsupported_cursor_record:${string(source.type) ?? "unknown"}`);
+        events.push(event(conversationId, filename, byteOffset, 1, "source_record", {
+            sourceType: string(source.type),
+            record: source,
+        }));
+    }
+    return validated(events, gaps);
+}
+export function parseCursorHookLine(line, filename) {
+    let decoded;
+    try {
+        decoded = JSON.parse(line);
+    }
+    catch {
+        return { events: [], gaps: ["malformed_cursor_hook_record"] };
+    }
+    const wrapper = record(decoded);
+    const input = wrapper === null ? null : record(wrapper.input);
+    const conversationId = input === null ? null : string(input.conversation_id);
+    const hook = wrapper === null ? null : string(wrapper.hook);
+    const capturedAt = wrapper === null ? null : string(wrapper.capturedAt);
+    if (wrapper?.kind === "subagent_transcript_chunk") {
+        const subagent = record(wrapper.subagent);
+        const part = nonnegativeInteger(subagent?.part);
+        const totalParts = nonnegativeInteger(subagent?.totalParts);
+        if (conversationId === null ||
+            !UUID.test(conversationId) ||
+            capturedAt === null ||
+            Number.isNaN(Date.parse(capturedAt)) ||
+            subagent === null ||
+            part === null ||
+            totalParts === null ||
+            part < 1 ||
+            part > totalParts ||
+            string(subagent.base64) === null)
+            return { events: [], gaps: ["invalid_cursor_subagent_transcript_chunk"] };
+        const transcriptBytes = nonnegativeInteger(wrapper.transcriptBytes) ?? 0;
+        const candidate = event(conversationId, filename, transcriptBytes, part, "source_record", {
+            sourceType: "cursor_subagent_transcript",
+            text: string(subagent.text),
+            base64: string(subagent.base64),
+            path: string(subagent.path),
+            part,
+            totalParts,
+            parent_conversation_id: string(input?.parent_conversation_id),
+            subagent_id: string(input?.subagent_id),
+        }, null, capturedAt);
+        const hash = candidate.eventId.split(":").at(-1);
+        return validated([
+            {
+                ...candidate,
+                sequence: transcriptBytes * 1000 + 500,
+                eventId: `${String(Date.parse(capturedAt)).padStart(13, "0")}:${String(2000 + part).padStart(4, "0")}:${hash}`,
+            },
+        ], []);
+    }
+    if (input === null ||
+        conversationId === null ||
+        !UUID.test(conversationId) ||
+        hook === null ||
+        capturedAt === null ||
+        Number.isNaN(Date.parse(capturedAt)))
+        return { events: [], gaps: ["invalid_cursor_hook_record"] };
+    const transcriptBytes = wrapper?.transcriptBytes;
+    const sequence = nonnegativeInteger(transcriptBytes) ?? 0;
+    const events = [];
+    if (hook === "beforeSubmitPrompt" || hook === "sessionStart") {
+        const roots = Array.isArray(input.workspace_roots)
+            ? input.workspace_roots
+            : [];
+        events.push({
+            ...event(conversationId, filename, sequence, 0, "session_meta", {
+                id: conversationId,
+                cwd: string(roots[0]),
+                version: string(input.cursor_version),
+                model: string(input.model),
+                transcript_path: string(input.transcript_path),
+            }, null, capturedAt),
+            run: {
+                kind: "identity",
+                id: conversationId,
+                parentId: null,
+                ownStart: true,
+                startOrdinal: null,
+            },
+        });
+    }
+    const rawText = JSON.stringify(input);
+    if (Buffer.byteLength(rawText, "utf8") <= 500_000) {
+        events.push(event(conversationId, filename, sequence, 1, "source_record", {
+            sourceType: `cursor_hook:${hook}`,
+            record: input,
+        }, null, capturedAt));
+    }
+    else {
+        const chunks = splitText(rawText);
+        for (const [index, text] of chunks.entries())
+            events.push(event(conversationId, filename, sequence, index + 1, "source_record", {
+                sourceType: `cursor_hook:${hook}`,
+                text,
+                part: index + 1,
+                totalParts: chunks.length,
+            }, null, capturedAt));
+    }
+    const next = events.length + 1;
+    if (hook === "preToolUse") {
+        events.push(event(conversationId, filename, sequence, next, "tool_call", {
+            name: string(input.tool_name),
+            input: input.tool_input ?? null,
+        }, string(input.tool_use_id), capturedAt));
+    }
+    if (hook === "postToolUse" || hook === "postToolUseFailure") {
+        const output = string(input.tool_output) ??
+            string(input.error_message) ??
+            string(input.error) ??
+            (input.tool_output === undefined && input.error === undefined
+                ? null
+                : JSON.stringify(input.tool_output ?? input.error));
+        const chunks = output === null ? [null] : splitText(output);
+        for (const [index, text] of chunks.entries())
+            events.push(event(conversationId, filename, sequence, next + index, "tool_result", {
+                text,
+                name: string(input.tool_name),
+                part: index + 1,
+                totalParts: chunks.length,
+            }, string(input.tool_use_id), capturedAt));
+    }
+    else if (hook === "afterAgentThought") {
+        events.push(event(conversationId, filename, sequence, next, "reasoning", {
+            text: string(input.text) ?? string(input.thought),
+        }, null, capturedAt));
+    }
+    else if (hook === "afterAgentResponse" &&
+        (input.usage !== undefined ||
+            input.input_tokens !== undefined ||
+            input.output_tokens !== undefined)) {
+        events.push(event(conversationId, filename, sequence, next, "token_usage_record", {
+            model: string(input.model),
+            usage: input.usage ?? {
+                input_tokens: input.input_tokens ?? null,
+                output_tokens: input.output_tokens ?? null,
+                cache_read_tokens: input.cache_read_tokens ?? null,
+                cache_write_tokens: input.cache_write_tokens ?? null,
+            },
+        }, null, capturedAt));
+    }
+    const capturedAtMs = Date.parse(capturedAt);
+    const ordered = events.map((candidate, index) => {
+        const digest = candidate.eventId.split(":").at(-1);
+        const thought = candidate.eventType === "reasoning"
+            ? createHash("sha256")
+                .update(`${conversationId}:${string(input.generation_id)?.slice(0, 36) ?? ""}:${candidate.payload.text}`)
+                .digest("hex")
+            : null;
+        return {
+            ...candidate,
+            sequence: sequence * 1000 + 500,
+            eventId: thought === null
+                ? `${String(capturedAtMs).padStart(13, "0")}:${String(index).padStart(4, "0")}:${digest}`
+                : `thought:${thought}`,
+        };
+    });
+    return validated(ordered, []);
+}
+function splitText(value) {
+    if (value.length === 0)
+        return [""];
+    const chunks = [];
+    for (let start = 0; start < value.length;) {
+        let end = Math.min(start + 250_000, value.length);
+        if (end < value.length && /[\uD800-\uDBFF]/u.test(value[end - 1]))
+            end -= 1;
+        chunks.push(value.slice(start, end));
+        start = end;
+    }
+    return chunks;
+}
+function validated(events, gaps) {
+    const valid = [];
+    for (const candidate of events) {
+        if (parseTraceEventBatch({ events: [candidate] }).success)
+            valid.push(candidate);
+        else
+            gaps.push(`invalid_normalized_event:${candidate.eventType}`);
+    }
+    return { events: valid, gaps };
+}

package/dist/service.js

@@ -5,7 +5,8 @@ import { connectNewDetectedSources, loadMachineConsent, } from "./auto-connect.j
 import { collectorFetch } from "./collector-fetch.js";
 import { collectorTick, TraceUploadError } from "./collector.js";
 import { refreshTurnSummaries } from "./turn-summary.js";
-import { collectorSource, collectorPaths, ensureClaudeHistoryBackfill, ensureHistoryBackfill, ensurePrivateDirectory, healthSnapshot, loadConfig, saveHealth, } from "./storage.js";
+import { installCursorHooks } from "./cursor-hooks.js";
+import { collectorSource, collectorPaths, ensureClaudeHistoryBackfill, ensureCursorHistoryBackfill, ensureHistoryBackfill, ensurePrivateDirectory, healthSnapshot, loadConfig, saveHealth, } from "./storage.js";
 function errorCode(error) {
     if (error instanceof Error && "code" in error)
         return String(error.code);
@@ -125,7 +126,11 @@ export async function runCollector(directory, expectedSource) {
                 message: "Local collector status could not be read; collection continues.",
             }));
         }
-        if ("claudeHome" in config)
+        if ("cursorHome" in config) {
+            await ensureCursorHistoryBackfill(config.cursorHome, paths);
+            await installCursorHooks(config.cursorHome, config.dataDirectory);
+        }
+        else if ("claudeHome" in config)
             await ensureClaudeHistoryBackfill(config.claudeHome, paths);
         else
             await ensureHistoryBackfill(config.codexHome, paths);
@@ -208,7 +213,8 @@ export async function runCollector(directory, expectedSource) {
                 retryDelayMs = Math.min(retryDelayMs * 2, 60_000);
             }
             try {
-                await refreshTurnSummaries(config, summariesRefreshedAt, Date.now(), collectorFetch, controller.signal);
+                if (source !== "cursor")
+                    await refreshTurnSummaries(config, summariesRefreshedAt, Date.now(), collectorFetch, controller.signal);
             }
             catch (error) {
                 if (controller.signal.aborted)

package/dist/status-view.d.ts

@@ -23,6 +23,7 @@ export type CliStatus = Readonly<{
     health: CollectorHealth;
     healthAvailable: boolean;
     turnSummaryNeedsApproval: boolean;
+    hookFailureAtMs?: number | null;
     tracesUrl: string;
     logPath: string;
 }>;

package/dist/status-view.js

@@ -149,6 +149,10 @@ export function renderHome(status, nowMs = Date.now(), source = "codex") {
             lines.push(`${pendingDescription(status)}.`);
         lines.push(`Resume with iteration start ${source}.`);
     }
+    else if (status.hookFailureAtMs !== null &&
+        status.hookFailureAtMs !== undefined) {
+        lines.push(`${name} hook capture needs attention`, `A Cursor hook failed ${relativeTime(status.hookFailureAtMs, nowMs)}. Some data may be missing. See iteration status cursor.`);
+    }
     else if (!status.healthAvailable) {
         lines.push(`${name} is running; local status needs attention`, "Upload history could not be read. Collection continues in the background.");
         if (status.pendingEvents > 0)
@@ -242,6 +246,8 @@ export function renderDetailedStatus(status, nowMs = Date.now(), source = "codex
                     : "Local collector error";
         lines.push(`Last issue: ${label} (${relativeTime(failure.atMs, nowMs)})`, `Collector log: ${status.logPath}`);
     }
+    if (status.hookFailureAtMs !== null && status.hookFailureAtMs !== undefined)
+        lines.push(`Last Cursor hook capture failure: ${relativeTime(status.hookFailureAtMs, nowMs)}. Some data may be missing; inspect Cursor hook logs.`);
     if (status.turnSummaryNeedsApproval)
         lines.push(CODEX_APPROVAL_STEP);
     if (!status.running)

package/dist/storage.d.ts

@@ -11,6 +11,9 @@ export type CollectorConfig = (CollectorConnection & Readonly<{
 }>) | (CollectorConnection & Readonly<{
     source: "claude";
     claudeHome: string;
+}>) | (CollectorConnection & Readonly<{
+    source: "cursor";
+    cursorHome: string;
 }>);
 export declare function collectorSource(config: CollectorConfig): CollectorSource;
 export declare function collectorSourceDirectory(config: CollectorConfig): string;
@@ -67,6 +70,7 @@ export declare function prepareSourceInitialState(source: CollectorSource, home:
 export declare function ensureStartableState(config: CollectorConfig, paths: CollectorPaths): Promise<boolean>;
 export declare function ensureHistoryBackfill(codexHome: string, paths: CollectorPaths): Promise<boolean>;
 export declare function ensureClaudeHistoryBackfill(claudeHome: string, paths: CollectorPaths): Promise<boolean>;
+export declare function ensureCursorHistoryBackfill(cursorHome: string, paths: CollectorPaths): Promise<boolean>;
 export declare function historyScanProgress(home: string, paths: CollectorPaths, source?: CollectorSource): Promise<Readonly<{
     kind: "waiting";
 } | {
@@ -84,4 +88,5 @@ export declare function historyImportSize(home: string, source?: CollectorSource
 }>>;
 export declare function claudeFiles(root: string): Promise<string[]>;
 export declare function sourceFiles(source: CollectorSource, home: string): Promise<string[]>;
+export declare function cursorFiles(root: string): Promise<string[]>;
 export {};

package/dist/storage.js

@@ -7,10 +7,18 @@ import { MAX_TRACE_EVENTS_PER_BATCH, parseTraceEventBatch, } from "iteration-tra
 import * as z from "zod";
 const MAX_OUTBOX_BYTES = 64 * 1024 * 1024;
 export function collectorSource(config) {
-    return "claudeHome" in config ? "claude" : "codex";
+    return "cursorHome" in config
+        ? "cursor"
+        : "claudeHome" in config
+            ? "claude"
+            : "codex";
 }
 export function collectorSourceDirectory(config) {
-    return "claudeHome" in config ? config.claudeHome : config.codexHome;
+    return "cursorHome" in config
+        ? config.cursorHome
+        : "claudeHome" in config
+            ? config.claudeHome
+            : config.codexHome;
 }
 const connectionSchema = {
     endpoint: z.string(),
@@ -28,6 +36,13 @@ const configSchema = z.union([
         claudeHome: z.string(),
     })
         .strict(),
+    z
+        .object({
+        ...connectionSchema,
+        source: z.literal("cursor"),
+        cursorHome: z.string(),
+    })
+        .strict(),
 ]);
 const stateSchema = z
     .object({
@@ -492,6 +507,18 @@ export async function ensureClaudeHistoryBackfill(claudeHome, paths) {
     await writeJsonAtomic(paths.historyBackfill, { version: 1 });
     return true;
 }
+export async function ensureCursorHistoryBackfill(cursorHome, paths) {
+    const version = await readHistoryBackfillVersion(paths);
+    if (version !== null && version >= 1)
+        return false;
+    const state = await loadState(paths);
+    if (!state.initialized || state.sourceDirectory !== path.resolve(cursorHome))
+        throw new Error("Collector state does not match the Cursor directory; reconnect Cursor before uploading.");
+    await cursorFiles(path.join(cursorHome, "projects"));
+    await saveState({ ...state, cursors: {}, skipping: [] }, paths);
+    await writeJsonAtomic(paths.historyBackfill, { version: 1 });
+    return true;
+}
 export async function historyScanProgress(home, paths, source = "codex") {
     if ((await readHistoryBackfillVersion(paths)) === null)
         return { kind: "waiting" };
@@ -677,6 +704,32 @@ export function sourceFiles(source, home) {
         return rolloutFiles(path.join(directory, "sessions"));
     if (source === "claude")
         return claudeFiles(path.join(directory, "projects"));
+    if (source === "cursor")
+        return cursorFiles(path.join(directory, "projects"));
     const unhandled = source;
     throw new Error(`Unsupported collector source: ${unhandled}`);
 }
+export async function cursorFiles(root) {
+    const files = [];
+    for (const project of await directoryEntries(root)) {
+        if (!project.isDirectory())
+            continue;
+        const transcripts = path.join(root, project.name, "agent-transcripts");
+        for (const conversation of await directoryEntries(transcripts)) {
+            if (!conversation.isDirectory())
+                continue;
+            const filename = path.join(transcripts, conversation.name, `${conversation.name}.jsonl`);
+            if ((await fs.stat(filename).catch((error) => {
+                if (error instanceof Error &&
+                    "code" in error &&
+                    error.code === "ENOENT")
+                    return null;
+                throw error;
+            }))?.isFile())
+                files.push(filename);
+            if (files.length > 10_000)
+                throw new Error("Cursor session file count exceeds the scan limit.");
+        }
+    }
+    return files.sort();
+}

package/dist/turn-summary.js

@@ -55,6 +55,8 @@ function hookCommand(paths) {
     return `/bin/sh ${shellQuote(paths.script)}`;
 }
 function agentHookFile(config) {
+    if ("cursorHome" in config)
+        throw new Error("Cursor uses its own trace hooks.");
     return "claudeHome" in config
         ? path.join(config.claudeHome, "settings.json")
         : path.join(config.codexHome, "hooks.json");
@@ -337,7 +339,7 @@ function codexTrustedHash(configToml, key) {
     return trustedHash;
 }
 export async function codexTurnSummaryApproval(config) {
-    if ("claudeHome" in config)
+    if ("claudeHome" in config || "cursorHome" in config)
         return "approved";
     const filename = agentHookFile(config);
     const { file } = await readHookFile(filename);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "iteration-cli",
-  "version": "0.7.2",
+  "version": "0.8.0",
   "type": "module",
   "repository": {
     "type": "git",
@@ -18,7 +18,7 @@
   },
   "dependencies": {
     "zod": "4.6.4",
-    "iteration-trace-contracts": "0.6.0"
+    "iteration-trace-contracts": "0.7.0"
   },
   "scripts": {
     "build": "pnpm --filter iteration-trace-contracts build && tsc -p tsconfig.json"