iteration-cli 0.4.4 → 0.6.0

package/README.md

@@ -4,10 +4,16 @@ Install one CLI for Iteration's supported coding-agent sources:
 
 ```sh
 npm install --global iteration-cli
-iteration
+iteration connect
 ```
 
-The Codex collector currently runs on macOS with Node.js 22 or later. Connecting imports existing local Codex sessions and collects new activity. Run `iteration` to see whether collection and uploads are healthy, `iteration status` for details, or `iteration help` for other commands.
+The collectors currently run on macOS with Node.js 22 or later. `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.
+
+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.
+
+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.
 
 If you previously installed the Codex-specific package, remove it with the package manager you used:
 

package/dist/auto-connect.d.ts

@@ -0,0 +1,30 @@
+import { type CollectorSource } from "iteration-trace-contracts";
+import { type CollectorConfig, type CollectorState } from "./storage.js";
+export type MachineConsent = Readonly<{
+    version: 1;
+    endpoint: string;
+    organizationId: string;
+    anchorSource: CollectorSource;
+    anchorDataDirectory: string;
+    sourceHomes: Readonly<{
+        codex: string;
+        claude: string;
+    }>;
+}>;
+export declare function sourceHome(source: CollectorSource): string;
+export declare function detectedSources(sourceHomes: MachineConsent["sourceHomes"]): Promise<CollectorSource[]>;
+export declare function loadMachineConsent(): Promise<MachineConsent | null>;
+export declare function saveMachineConsent(consent: MachineConsent): Promise<void>;
+export type SourceEnrollment = Readonly<{
+    token: string;
+    organizationId: string;
+    organizationName: string;
+}>;
+export declare function readCollectorScope(anchor: CollectorConfig): Promise<Readonly<{
+    organizationId: string;
+    organizationName: string;
+}>>;
+export declare function expandSource(anchor: CollectorConfig, source: CollectorSource, organizationId: string | null, request?: typeof fetch): Promise<SourceEnrollment>;
+export declare function activateSource(source: CollectorSource, home: string, endpoint: string, enrollment: SourceEnrollment, state: CollectorState): Promise<CollectorConfig>;
+export declare function connectNewDetectedSources(anchor: CollectorConfig, consent: MachineConsent): Promise<CollectorSource[]>;
+export declare function connectedConfig(source: CollectorSource): Promise<CollectorConfig | null>;

package/dist/auto-connect.js

@@ -0,0 +1,220 @@
+import { promises as fs } from "node:fs";
+import { createHmac } from "node:crypto";
+import os from "node:os";
+import path from "node:path";
+import * as z from "zod";
+import { COLLECTOR_SOURCES, parseCollectorEnrollmentResponse, } from "iteration-trace-contracts";
+import { installLaunchAgent } from "./launch-agent.js";
+import { installTurnSummary } from "./turn-summary.js";
+import { assertFreshCollectorDirectory, collectorPaths, defaultCollectorDirectory, ensurePrivateDirectory, loadConfig, prepareSourceInitialState, saveConfig, saveState, validateCollectorEndpoint, } from "./storage.js";
+const consentSchema = z
+    .object({
+    version: z.literal(1),
+    endpoint: z.url(),
+    organizationId: z.uuid(),
+    anchorSource: z.enum(COLLECTOR_SOURCES),
+    anchorDataDirectory: z.string(),
+    sourceHomes: z.object({ codex: z.string(), claude: z.string() }).strict(),
+})
+    .strict();
+function consentPath() {
+    return path.join(os.homedir(), ".config", "iteration", "auto-connect.json");
+}
+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")));
+}
+export async function detectedSources(sourceHomes) {
+    const detected = [];
+    for (const source of COLLECTOR_SOURCES) {
+        const directory = path.join(sourceHomes[source], source === "codex" ? "sessions" : "projects");
+        let stats;
+        try {
+            stats = await fs.stat(directory);
+        }
+        catch (error) {
+            if (error instanceof Error && "code" in error && error.code === "ENOENT")
+                continue;
+            throw new Error(`Could not inspect ${source} sessions at ${directory}.`, {
+                cause: error,
+            });
+        }
+        if (!stats.isDirectory()) {
+            throw new Error(`${source} session path is not a directory: ${directory}.`);
+        }
+        detected.push(source);
+    }
+    return detected;
+}
+export async function loadMachineConsent() {
+    let text;
+    try {
+        text = await fs.readFile(consentPath(), "utf8");
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT")
+            return null;
+        throw new Error("Could not read automatic source connection settings.", {
+            cause: error,
+        });
+    }
+    let decoded;
+    try {
+        decoded = JSON.parse(text);
+    }
+    catch (error) {
+        throw new Error("Automatic source connection settings are invalid.", {
+            cause: error,
+        });
+    }
+    const parsed = consentSchema.safeParse(decoded);
+    if (!parsed.success)
+        throw new Error("Automatic source connection settings are invalid.");
+    validateCollectorEndpoint(parsed.data.endpoint);
+    return parsed.data;
+}
+export async function saveMachineConsent(consent) {
+    const parsed = consentSchema.parse(consent);
+    validateCollectorEndpoint(parsed.endpoint);
+    const filename = consentPath();
+    await ensurePrivateDirectory(path.dirname(filename));
+    const temporary = `${filename}.${process.pid}.tmp`;
+    const handle = await fs.open(temporary, "w", 0o600);
+    try {
+        await handle.writeFile(`${JSON.stringify(parsed)}\n`, "utf8");
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+    await fs.rename(temporary, filename);
+}
+export async function readCollectorScope(anchor) {
+    const endpoint = validateCollectorEndpoint(anchor.endpoint);
+    const response = await fetch(new URL("./collector-auth/expand", endpoint), {
+        headers: { Authorization: `Bearer ${anchor.token}` },
+        signal: AbortSignal.timeout(10_000),
+    });
+    const payload = await response.json();
+    if (!response.ok) {
+        const error = z.object({ error: z.string() }).safeParse(payload);
+        throw new Error(`Could not identify the collector workspace: ${error.success ? error.data.error : `HTTP ${response.status}`}`);
+    }
+    const parsed = z
+        .object({ organizationId: z.uuid(), organizationName: z.string().min(1) })
+        .strict()
+        .safeParse(payload);
+    if (!parsed.success)
+        throw new Error("Iteration returned an invalid collector workspace.");
+    return parsed.data;
+}
+export async function expandSource(anchor, source, organizationId, request = fetch) {
+    const endpoint = validateCollectorEndpoint(anchor.endpoint);
+    const token = createHmac("sha256", anchor.token)
+        .update(`iteration-source:${source}`, "utf8")
+        .digest("base64url");
+    const response = await request(new URL("./collector-auth/expand", endpoint), {
+        method: "POST",
+        headers: {
+            Authorization: `Bearer ${anchor.token}`,
+            "Content-Type": "application/json",
+        },
+        body: JSON.stringify({
+            source,
+            token,
+            ...(organizationId === null ? {} : { organizationId }),
+        }),
+        signal: AbortSignal.timeout(15_000),
+    });
+    const payload = await response.json();
+    if (!response.ok) {
+        const error = z.object({ error: z.string() }).safeParse(payload);
+        throw new Error(`Could not connect ${source}: ${error.success ? error.data.error : `HTTP ${response.status}`}`);
+    }
+    const parsed = parseCollectorEnrollmentResponse(payload);
+    if (!parsed.success || parsed.value.status !== "enrolled") {
+        throw new Error(`Iteration returned an invalid ${source} connection response.`);
+    }
+    if (organizationId !== null &&
+        parsed.value.organizationId !== organizationId) {
+        throw new Error(`Iteration connected ${source} to an unexpected workspace.`);
+    }
+    return parsed.value;
+}
+export async function activateSource(source, home, endpoint, enrollment, state) {
+    const directory = defaultCollectorDirectory(source);
+    const paths = collectorPaths(directory);
+    await assertFreshCollectorDirectory(paths, source);
+    const common = {
+        endpoint,
+        token: enrollment.token,
+        dataDirectory: directory,
+        organizationId: enrollment.organizationId,
+        organizationName: enrollment.organizationName,
+    };
+    const config = source === "codex"
+        ? { ...common, codexHome: home }
+        : { ...common, source: "claude", claudeHome: home };
+    await saveConfig(config, paths);
+    try {
+        await saveState(state, paths);
+        await installLaunchAgent(directory, source);
+    }
+    catch (error) {
+        throw new Error(`${source} was connected, but local startup failed. Run iteration start ${source} to repair it.`, { cause: error });
+    }
+    return config;
+}
+export async function connectNewDetectedSources(anchor, consent) {
+    if (anchor.dataDirectory !== consent.anchorDataDirectory ||
+        anchor.endpoint !== consent.endpoint) {
+        throw new Error("Automatic connection settings do not match the running collector.");
+    }
+    const detected = await detectedSources(consent.sourceHomes);
+    const connected = [];
+    for (const source of detected) {
+        if (source === consent.anchorSource)
+            continue;
+        const paths = collectorPaths(defaultCollectorDirectory(source));
+        try {
+            await fs.access(paths.config);
+            continue;
+        }
+        catch (error) {
+            if (!(error instanceof Error && "code" in error && error.code === "ENOENT"))
+                throw error;
+        }
+        await assertFreshCollectorDirectory(paths, source);
+        const state = await prepareSourceInitialState(source, consent.sourceHomes[source], true);
+        const enrollment = await expandSource(anchor, source, consent.organizationId);
+        const config = await activateSource(source, consent.sourceHomes[source], consent.endpoint, enrollment, state);
+        connected.push(source);
+        try {
+            await installTurnSummary(config);
+        }
+        catch (error) {
+            console.error(JSON.stringify({
+                level: "warning",
+                source,
+                operation: "install_turn_summary",
+                message: error instanceof Error
+                    ? error.message
+                    : "The turn summary could not be installed.",
+            }));
+        }
+    }
+    return connected;
+}
+export async function connectedConfig(source) {
+    const paths = collectorPaths(defaultCollectorDirectory(source));
+    try {
+        await fs.access(paths.config);
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+    return loadConfig(paths);
+}

package/dist/claude-transcript.d.ts

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

package/dist/claude-transcript.js

@@ -0,0 +1,255 @@
+import { createHash } from "node:crypto";
+import path from "node:path";
+import * as z from "zod";
+import { parseTraceEventBatch, } from "iteration-trace-contracts";
+const CONTEXT_RECORD_TYPES = new Set([
+    "attachment",
+    "system",
+    "last-prompt",
+    "mode",
+    "permission-mode",
+    "atis-latch",
+    "ai-title",
+    "file-history-snapshot",
+    "file-history-delta",
+    "cost-state",
+    "queue-operation",
+]);
+function object(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 digest(value) {
+    return createHash("sha256").update(value, "utf8").digest("hex");
+}
+const URL_NAMESPACE = Buffer.from("6ba7b8119dad11d180b400c04fd430c8", "hex");
+function childThreadId(parentId, agentId) {
+    const bytes = createHash("sha1")
+        .update(URL_NAMESPACE)
+        .update(`https://github.com/Thytu/Iteration/claude/${parentId}/agent/${agentId}`)
+        .digest()
+        .subarray(0, 16);
+    bytes[6] = (bytes[6] & 0x0f) | 0x50;
+    bytes[8] = (bytes[8] & 0x3f) | 0x80;
+    const hex = bytes.toString("hex");
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+const SESSION_UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function claudeSessionIdentity(filename) {
+    if (!filename.endsWith(".jsonl"))
+        return null;
+    const basename = path.basename(filename, ".jsonl");
+    if (path.basename(path.dirname(filename)) === "subagents") {
+        const parent = path.basename(path.dirname(path.dirname(filename)));
+        if (!basename.startsWith("agent-") || !SESSION_UUID.test(parent))
+            return null;
+        const agentId = basename.slice("agent-".length);
+        if (agentId.length === 0)
+            return null;
+        const threadId = childThreadId(parent, agentId);
+        const sessionId = `claude:${threadId}`;
+        const runId = `${parent}/agent/${agentId}`;
+        if (sessionId.length > 200 || runId.length > 200)
+            return null;
+        return {
+            sessionId,
+            parentSessionId: `claude:${parent}`,
+            agentId,
+            runId,
+            parentRunId: parent,
+        };
+    }
+    const sessionId = `claude:${basename}`;
+    return sessionId.length <= 200 && SESSION_UUID.test(basename)
+        ? {
+            sessionId,
+            parentSessionId: null,
+            agentId: null,
+            runId: basename,
+            parentRunId: null,
+        }
+        : null;
+}
+function timestamp(record) {
+    const value = string(record.timestamp);
+    return value !== null &&
+        /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/.test(value) &&
+        !Number.isNaN(Date.parse(value))
+        ? value
+        : null;
+}
+function event(identity, record, byteOffset, index, eventType, payload, callId = null, stableKey) {
+    return {
+        eventId: `${String(index).padStart(4, "0")}:${digest(`${identity.sessionId}:${stableKey ?? string(record.uuid) ?? `${byteOffset}:${JSON.stringify(record)}`}`)}`,
+        sessionId: identity.sessionId,
+        sequence: byteOffset,
+        callId,
+        projectId: null,
+        occurredAt: timestamp(record),
+        eventType,
+        payload,
+    };
+}
+function contentText(value) {
+    const literal = string(value);
+    if (literal !== null)
+        return literal;
+    if (!Array.isArray(value))
+        return null;
+    const parts = value.flatMap((part) => {
+        const block = object(part);
+        const text = block === null ? null : string(block.text);
+        return text === null ? [] : [text];
+    });
+    return parts.length > 0 ? parts.join("\n") : null;
+}
+export function parseClaudeLine(line, filename, byteOffset) {
+    const identity = claudeSessionIdentity(filename);
+    if (identity === null)
+        return { events: [], gaps: ["invalid_claude_session_path"] };
+    let decoded;
+    try {
+        decoded = JSON.parse(line);
+    }
+    catch {
+        return { events: [], gaps: ["malformed_jsonl_record"] };
+    }
+    const record = object(decoded);
+    if (record === null)
+        return { events: [], gaps: ["record_is_not_an_object"] };
+    const recordType = string(record.type);
+    const sourceSessionId = string(record.sessionId);
+    if ((identity.agentId !== null && sourceSessionId === null) ||
+        (sourceSessionId !== null &&
+            `claude:${sourceSessionId}` !==
+                (identity.parentSessionId ?? identity.sessionId))) {
+        return { events: [], gaps: ["session_id_does_not_match_path"] };
+    }
+    if (identity.agentId !== null && string(record.agentId) !== identity.agentId)
+        return { events: [], gaps: ["agent_id_does_not_match_path"] };
+    const gaps = [];
+    if (record.timestamp !== undefined && timestamp(record) === null)
+        gaps.push("invalid_source_timestamp");
+    const events = [];
+    const meta = {
+        id: identity.runId,
+        parent_thread_id: identity.parentRunId,
+        cwd: string(record.cwd),
+        git: { branch: string(record.gitBranch) },
+        version: string(record.version),
+        agentId: identity.agentId,
+    };
+    events.push({
+        ...event(identity, record, 0, 0, "session_meta", meta, null, "session_meta"),
+        run: {
+            kind: "identity",
+            id: identity.runId,
+            parentId: identity.parentRunId,
+            ownStart: true,
+            startOrdinal: null,
+        },
+    });
+    if (recordType === "user") {
+        const message = object(record.message);
+        const content = message === null ? null : string(message.content);
+        if (message === null)
+            gaps.push("user_without_message");
+        else if (content !== null) {
+            events.push(event(identity, record, byteOffset, 1, "user_message", {
+                text: content,
+                record,
+            }));
+        }
+        else if (Array.isArray(message.content)) {
+            for (const [index, value] of message.content.entries()) {
+                const block = object(value);
+                if (block === null) {
+                    gaps.push("invalid_user_content_block");
+                    continue;
+                }
+                if (block.type === "tool_result") {
+                    const callId = string(block.tool_use_id);
+                    if (callId === null) {
+                        gaps.push("tool_result_without_call_id");
+                        continue;
+                    }
+                    events.push(event(identity, record, byteOffset, index + 1, "tool_result", {
+                        text: contentText(block.content),
+                        record,
+                    }, callId));
+                }
+                else {
+                    events.push(event(identity, record, byteOffset, index + 1, "user_message", {
+                        text: string(block.text) ?? contentText(block.content),
+                        record,
+                    }));
+                }
+            }
+        }
+        else
+            gaps.push("unsupported_user_content");
+    }
+    else if (recordType === "assistant") {
+        const message = object(record.message);
+        if (message === null || !Array.isArray(message.content))
+            gaps.push("assistant_without_content_blocks");
+        else {
+            for (const [index, value] of message.content.entries()) {
+                const block = object(value);
+                if (block === null) {
+                    gaps.push("invalid_assistant_content_block");
+                    continue;
+                }
+                const blockType = string(block.type);
+                const eventType = blockType === "text"
+                    ? "assistant_message"
+                    : blockType === "thinking" || blockType === "redacted_thinking"
+                        ? "reasoning"
+                        : blockType === "tool_use"
+                            ? "tool_call"
+                            : null;
+                if (eventType === null) {
+                    gaps.push(`unsupported_assistant_block:${blockType ?? "unknown"}`);
+                    continue;
+                }
+                const callId = eventType === "tool_call" ? string(block.id) : null;
+                if (eventType === "tool_call" && callId === null) {
+                    gaps.push("tool_call_without_call_id");
+                    continue;
+                }
+                events.push(event(identity, record, byteOffset, index + 1, eventType, {
+                    text: string(block.text) ?? string(block.thinking),
+                    name: string(block.name),
+                    record,
+                }, callId));
+            }
+            if (object(message.usage) !== null && string(message.id) !== null) {
+                events.push(event(identity, record, byteOffset, 9999, "token_usage_record", { model: string(message.model), usage: message.usage }, null, `usage:${message.id}`));
+            }
+        }
+    }
+    else if (recordType !== null && CONTEXT_RECORD_TYPES.has(recordType)) {
+        const attachment = object(record.attachment);
+        events.push(event(identity, record, byteOffset, 1, "source_record", {
+            sourceType: recordType,
+            subtype: string(record.subtype) ??
+                (attachment === null ? null : string(attachment.type)),
+            record,
+        }));
+    }
+    else
+        gaps.push(`unsupported_claude_record:${recordType ?? "unknown"}`);
+    const valid = [];
+    for (const candidate of events) {
+        const checked = parseTraceEventBatch({ events: [candidate] });
+        if (checked.success)
+            valid.push(candidate);
+        else
+            gaps.push(`invalid_normalized_event:${candidate.eventType}`);
+    }
+    return { events: valid, gaps };
+}

package/dist/clerk-device-auth.d.ts

@@ -1,5 +1,7 @@
-export declare function authenticateAndEnrollCollector(endpoint: URL, deviceNameValue: string, organizationId: string | null): Promise<Readonly<{
+import { type CollectorSource } from "iteration-trace-contracts";
+export declare function authenticateAndEnrollCollector(endpoint: URL, deviceNameValue: string, organizationId: string | null, source?: CollectorSource): Promise<Readonly<{
     token: string;
     deviceId: string;
+    organizationId: string;
     organizationName: string;
 }>>;

package/dist/clerk-device-auth.js

@@ -186,8 +186,10 @@ async function clerkDeviceSignIn(configuration) {
     await openBrowser(verificationUrl);
     return pollForAccessToken(endpoints.tokenUrl, configuration.clientId, challenge.device_code, challenge.expires_in, challenge.interval);
 }
-async function enrollDevice(endpoint, accessToken, deviceName, organizationId) {
+async function enrollDevice(endpoint, accessToken, deviceName, organizationId, source) {
     const body = { deviceName };
+    if (source === "claude")
+        body.source = source;
     if (organizationId !== null)
         body.organizationId = organizationId;
     const response = await fetch(apiRoute(endpoint, "./collector-auth/enroll"), {
@@ -248,7 +250,7 @@ async function chooseOrganization(organizations, hasMore) {
         prompt.close();
     }
 }
-export async function authenticateAndEnrollCollector(endpoint, deviceNameValue, organizationId) {
+export async function authenticateAndEnrollCollector(endpoint, deviceNameValue, organizationId, source = "codex") {
     const deviceName = z
         .string()
         .trim()
@@ -260,10 +262,10 @@ export async function authenticateAndEnrollCollector(endpoint, deviceNameValue,
     }
     const configuration = await loadOAuthConfiguration(endpoint);
     const clerkAccessToken = await clerkDeviceSignIn(configuration);
-    let result = await enrollDevice(endpoint, clerkAccessToken, deviceName.data, organizationId);
+    let result = await enrollDevice(endpoint, clerkAccessToken, deviceName.data, organizationId, source);
     if (result.status === "choose_organization") {
         const selectedOrganizationId = await chooseOrganization(result.organizations, result.hasMore);
-        result = await enrollDevice(endpoint, clerkAccessToken, deviceName.data, selectedOrganizationId);
+        result = await enrollDevice(endpoint, clerkAccessToken, deviceName.data, selectedOrganizationId, source);
     }
     if (result.status !== "enrolled") {
         throw new Error("The collector could not be assigned to that workspace.");
@@ -271,6 +273,7 @@ export async function authenticateAndEnrollCollector(endpoint, deviceNameValue,
     return {
         token: result.token,
         deviceId: result.deviceId,
+        organizationId: result.organizationId,
         organizationName: result.organizationName,
     };
 }