iteration-cli 0.4.3 → 0.5.0

package/README.md

@@ -4,10 +4,15 @@ Install one CLI for Iteration's supported coding-agent sources:
 
 ```sh
 npm install --global iteration-cli
-iteration
+iteration connect codex
+iteration connect claude
 ```
 
-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 status` to check uploads, or `iteration help` for other commands.
+The collectors currently run on macOS with Node.js 22 or later. Connect either source or both on the same Mac. Each source has its own background process, local checkpoint, and upload queue. Connecting imports existing local sessions and collects new activity. Run `iteration` to see connected sources, `iteration status codex` or `iteration status claude` for details, and `iteration help` for other commands.
+
+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.
+
+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/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,4 +1,5 @@
-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;
     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.");