archbyte 0.6.1 → 0.7.1

package/dist/agents/observability/adapters/claude-transcripts.js

@@ -0,0 +1,692 @@
+// Claude Transcripts Adapter — reads native Claude Code JSONL session transcripts
+// from ~/.claude/projects/{encoded-project-path}/
+// Converts full conversation transcripts into AgentSession(s) for the Sessions panel.
+import { readFile, readdir, stat } from "fs/promises";
+import { existsSync } from "fs";
+import { homedir } from "os";
+import path from "path";
+// --- Cost model (USD per million tokens) ---
+const COST_INPUT = 15; // $15/MTok
+const COST_OUTPUT = 75; // $75/MTok
+const COST_CACHE_READ = 1.5; // $1.50/MTok
+const COST_CACHE_CREATE = 18.75; // $18.75/MTok
+const MAX_TRUNCATE = 500; // Max chars for tool input/result truncation
+// --- Per-file mtime cache for scanTranscriptIndex ---
+const _indexCache = new Map();
+/** Invalidate cached index entries. Call with a path to invalidate one file, or no args to clear all. */
+export function invalidateIndexCache(filePath) {
+    if (filePath) {
+        _indexCache.delete(filePath);
+    }
+    else {
+        _indexCache.clear();
+    }
+}
+// --- Discovery helpers ---
+export function getClaudeProjectsDir() {
+    return path.join(homedir(), ".claude", "projects");
+}
+export function encodeProjectPath(cwd) {
+    return "-" + cwd.replace(/^\//, "").replace(/\//g, "-");
+}
+export function getProjectTranscriptDir(cwd) {
+    const dir = path.join(getClaudeProjectsDir(), encodeProjectPath(cwd));
+    return existsSync(dir) ? dir : null;
+}
+async function findSessionFiles(projectDir) {
+    const results = [];
+    try {
+        const entries = await readdir(projectDir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.isFile() && entry.name.endsWith(".jsonl")) {
+                const sessionId = entry.name.replace(/\.jsonl$/, "");
+                const jsonlPath = path.join(projectDir, entry.name);
+                const subDir = path.join(projectDir, sessionId, "subagents");
+                results.push({
+                    sessionId,
+                    jsonlPath,
+                    subagentDir: existsSync(subDir) ? subDir : undefined,
+                });
+            }
+        }
+    }
+    catch {
+        // Permission error or unreadable
+    }
+    return results;
+}
+const WRITE_TOOLS = new Set(["Edit", "Write", "NotebookEdit"]);
+const READ_TOOLS = new Set(["Read", "Glob", "Grep"]);
+const PIPELINE_PROMPT_PATTERNS = [
+    "Analyze this project and identify ALL architecturally significant components",
+    "## Components (use these exact IDs)",
+    "## Components\n",
+    "## Components\r",
+    "Event-driven patterns detected:",
+    "Detected language:",
+    "Import Graph (",
+    "Components (affected",
+    "Components (use these",
+];
+function classifySession(firstPrompt, toolNames, eventCount) {
+    // Pipeline agent calls: short sessions matching known pipeline prompts
+    const hasWriteTools = [...toolNames].some(t => WRITE_TOOLS.has(t));
+    if (eventCount <= 8 && !hasWriteTools) {
+        for (const prefix of PIPELINE_PROMPT_PATTERNS) {
+            if (firstPrompt.startsWith(prefix))
+                return "pipeline";
+        }
+        if (firstPrompt.startsWith("Project: ") && firstPrompt.includes("Detected language:"))
+            return "pipeline";
+        if (firstPrompt.startsWith("## Components") && toolNames.size <= 1)
+            return "pipeline";
+    }
+    // Implementation: used write/edit tools
+    if ([...toolNames].some(t => WRITE_TOOLS.has(t)))
+        return "implementation";
+    // Exploration: used read/search tools but no writes
+    if ([...toolNames].some(t => READ_TOOLS.has(t)))
+        return "exploration";
+    // Conversation: everything else (Q&A, discussions)
+    return "conversation";
+}
+function extractLabel(firstPrompt, category) {
+    if (category === "pipeline")
+        return "pipeline agent";
+    let text = firstPrompt;
+    // Handle command invocations: <command-name>/foo</command-name><command-message>bar</command-message>
+    if (text.startsWith("<command-name>") || text.startsWith("<command-message>")) {
+        const match = text.match(/<command-message>([^<]+)/);
+        if (match)
+            text = `/${match[1].trim()}`;
+    }
+    // Strip local-command-caveat blocks (tag + content)
+    text = text.replace(/<local-command-caveat>[\s\S]*?<\/local-command-caveat>\s*/g, "");
+    // Strip command XML wrappers but keep content
+    text = text.replace(/<\/?(?:command-name|command-args|system-reminder)[^>]*>/g, "");
+    // Strip any remaining XML/HTML tags
+    text = text.replace(/<[^>]+>/g, "").trim();
+    // Strip common prefixes
+    if (text.startsWith("Implement the following plan:")) {
+        text = text.slice("Implement the following plan:".length);
+    }
+    // Extract first meaningful line (skip blank lines, markdown headers)
+    const lines = text.trim().split("\n");
+    text = "";
+    for (const line of lines) {
+        const cleaned = line.replace(/^#+\s*/, "").trim();
+        if (cleaned && cleaned.length > 3) {
+            text = cleaned;
+            break;
+        }
+    }
+    // Truncate
+    if (text.length > 80)
+        text = text.slice(0, 77) + "...";
+    return text || "session";
+}
+function resolveTopLevelDir(filePath) {
+    const segments = filePath.split("/").filter(Boolean);
+    const rootIdx = segments.lastIndexOf("archbyte");
+    if (rootIdx < 0)
+        return null; // skip paths outside project tree
+    const startIdx = rootIdx + 1;
+    if (startIdx < segments.length - 1) {
+        return segments[startIdx];
+    }
+    else if (startIdx < segments.length) {
+        // Single file at project root
+        const ext = segments[segments.length - 1].split(".").pop();
+        if (ext && ["ts", "tsx", "js", "json", "css", "md"].includes(ext)) {
+            return "root";
+        }
+    }
+    return null;
+}
+export async function scanTranscriptIndex(projectDir) {
+    const files = await findSessionFiles(projectDir);
+    const entries = [];
+    for (const file of files) {
+        try {
+            // Check mtime cache — skip re-parsing if file hasn't changed
+            const fileStat = await stat(file.jsonlPath);
+            const cached = _indexCache.get(file.jsonlPath);
+            if (cached && cached.mtimeMs === fileStat.mtimeMs && cached.size === fileStat.size) {
+                if (cached.entry)
+                    entries.push(cached.entry);
+                continue;
+            }
+            const entry = await scanSingleIndex(file);
+            _indexCache.set(file.jsonlPath, { mtimeMs: fileStat.mtimeMs, size: fileStat.size, entry });
+            if (entry)
+                entries.push(entry);
+        }
+        catch {
+            // Skip unreadable files
+        }
+    }
+    return entries;
+}
+async function scanSingleIndex(file) {
+    const raw = await readFile(file.jsonlPath, "utf-8");
+    const lines = raw.split("\n").filter(Boolean);
+    if (lines.length < 2)
+        return null;
+    let startedAt = "";
+    let completedAt = "";
+    let model = "";
+    let version = "";
+    let gitBranch = "";
+    let firstUserPrompt = "";
+    const toolNames = new Set();
+    const touchedFiles = new Set();
+    const fileToolOps = [];
+    let eventCount = 0;
+    let totalInputTokens = 0;
+    let totalOutputTokens = 0;
+    let totalCacheReadTokens = 0;
+    let totalCacheCreateTokens = 0;
+    const seenRequestIds = new Set();
+    for (const line of lines) {
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        const type = parsed.type;
+        if (type === "file-history-snapshot" || type === "queue-operation" || type === "progress")
+            continue;
+        eventCount++;
+        const ts = parsed.timestamp || "";
+        if (ts && !startedAt)
+            startedAt = ts;
+        if (ts)
+            completedAt = ts;
+        if (!version && parsed.version)
+            version = parsed.version;
+        if (!gitBranch && parsed.gitBranch)
+            gitBranch = parsed.gitBranch;
+        if (type === "user") {
+            const msg = parsed.message;
+            const content = msg?.content;
+            if (!firstUserPrompt) {
+                if (typeof content === "string") {
+                    firstUserPrompt = content;
+                }
+                else if (Array.isArray(content)) {
+                    const textBlock = content.find((b) => b.type === "text");
+                    if (textBlock)
+                        firstUserPrompt = textBlock.text || "";
+                }
+            }
+        }
+        else if (type === "assistant") {
+            const msg = parsed.message;
+            if (msg?.model && !model)
+                model = msg.model;
+            // Aggregate token usage (deduplicate by requestId)
+            const reqId = parsed.requestId || "";
+            const usage = msg?.usage;
+            if (usage && reqId) {
+                if (!seenRequestIds.has(reqId)) {
+                    seenRequestIds.add(reqId);
+                    totalInputTokens += usage.input_tokens || 0;
+                    totalOutputTokens += usage.output_tokens || 0;
+                    totalCacheReadTokens += usage.cache_read_input_tokens || 0;
+                    totalCacheCreateTokens += usage.cache_creation_input_tokens || 0;
+                }
+            }
+            const content = msg?.content;
+            if (Array.isArray(content)) {
+                for (const block of content) {
+                    const b = block;
+                    if (b.type === "tool_use" && b.name) {
+                        const toolName = b.name;
+                        toolNames.add(toolName);
+                        // Extract file paths from tool inputs
+                        const input = b.input;
+                        if (input) {
+                            const fp = (input.file_path || input.path || input.notebook_path);
+                            if (fp) {
+                                touchedFiles.add(fp);
+                                if (WRITE_TOOLS.has(toolName) || READ_TOOLS.has(toolName)) {
+                                    fileToolOps.push({ filePath: fp, toolName });
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
+    if (!startedAt || eventCount === 0)
+        return null;
+    const category = classifySession(firstUserPrompt, toolNames, eventCount);
+    // Filter pipeline noise from the index entirely
+    if (category === "pipeline")
+        return null;
+    // Count subagent files
+    let subagentCount = 0;
+    if (file.subagentDir) {
+        try {
+            const subFiles = await readdir(file.subagentDir);
+            subagentCount = subFiles.filter(f => f.endsWith(".jsonl")).length;
+        }
+        catch { /* skip */ }
+    }
+    const label = extractLabel(firstUserPrompt, category);
+    // Map file paths to top-level project directories
+    const dirs = new Set();
+    for (const fp of touchedFiles) {
+        const dir = resolveTopLevelDir(fp);
+        if (dir)
+            dirs.add(dir);
+    }
+    // Build per-dir read/write metrics
+    const dirMetrics = {};
+    for (const op of fileToolOps) {
+        const dir = resolveTopLevelDir(op.filePath);
+        if (!dir)
+            continue;
+        if (!dirMetrics[dir])
+            dirMetrics[dir] = { reads: 0, writes: 0 };
+        if (WRITE_TOOLS.has(op.toolName)) {
+            dirMetrics[dir].writes++;
+        }
+        else {
+            dirMetrics[dir].reads++;
+        }
+    }
+    // Compute estimated cost from token usage
+    const costInput = (totalInputTokens / 1_000_000) * COST_INPUT;
+    const costOutput = (totalOutputTokens / 1_000_000) * COST_OUTPUT;
+    const costCacheRead = (totalCacheReadTokens / 1_000_000) * COST_CACHE_READ;
+    const costCacheCreate = (totalCacheCreateTokens / 1_000_000) * COST_CACHE_CREATE;
+    const estimatedCost = costInput + costOutput + costCacheRead + costCacheCreate;
+    return {
+        sessionId: file.sessionId,
+        startedAt,
+        completedAt: completedAt || undefined,
+        status: "success",
+        runCount: 1 + subagentCount,
+        phases: subagentCount > 0 ? ["orchestrator", "subagent"] : ["orchestrator"],
+        source: "claude-transcript",
+        model,
+        version,
+        gitBranch,
+        subagentCount,
+        category,
+        label,
+        touchedDirs: dirs.size > 0 ? [...dirs] : undefined,
+        eventCount,
+        dirMetrics: Object.keys(dirMetrics).length > 0 ? dirMetrics : undefined,
+        estimatedCost: estimatedCost > 0 ? estimatedCost : undefined,
+    };
+}
+function truncate(s, max = MAX_TRUNCATE) {
+    const str = typeof s === "string" ? s : JSON.stringify(s ?? "");
+    return str.length > max ? str.slice(0, max) + "..." : str;
+}
+function classifyAgentType(firstPrompt) {
+    const lower = firstPrompt.toLowerCase();
+    if (lower.includes("explore") || lower.includes("search") || lower.includes("find"))
+        return "explorer";
+    if (lower.includes("plan") || lower.includes("design") || lower.includes("architect"))
+        return "planner";
+    if (lower.includes("test") || lower.includes("verify") || lower.includes("check"))
+        return "tester";
+    if (lower.includes("git") || lower.includes("worktree") || lower.includes("branch"))
+        return "git";
+    if (lower.includes("docker") || lower.includes("container"))
+        return "docker";
+    return "general";
+}
+function parseTranscriptFile(raw, agentId, agentSlug) {
+    const events = [];
+    const usage = new Map();
+    const models = new Set();
+    let firstTimestamp = "";
+    let lastTimestamp = "";
+    let firstUserPrompt = "";
+    const payloadFiles = [];
+    const pendingToolUses = new Map();
+    const lines = raw.split("\n");
+    for (const line of lines) {
+        if (!line)
+            continue;
+        let entry;
+        try {
+            entry = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        const { type } = entry;
+        if (type === "file-history-snapshot" || type === "queue-operation" || type === "progress")
+            continue;
+        const ts = entry.timestamp || "";
+        if (ts && !firstTimestamp)
+            firstTimestamp = ts;
+        if (ts)
+            lastTimestamp = ts;
+        if (type === "user") {
+            const content = entry.message?.content;
+            if (typeof content === "string") {
+                if (!firstUserPrompt)
+                    firstUserPrompt = content;
+                events.push({ timestamp: ts, type: "user", agentId, agentSlug, text: truncate(content, 2000) });
+            }
+            else if (Array.isArray(content)) {
+                for (const block of content) {
+                    if (block.type === "text") {
+                        if (!firstUserPrompt)
+                            firstUserPrompt = block.text || "";
+                        events.push({ timestamp: ts, type: "user", agentId, agentSlug, text: truncate(block.text, 2000) });
+                    }
+                    else if (block.type === "tool_result") {
+                        const resultText = typeof block.content === "string"
+                            ? block.content
+                            : Array.isArray(block.content)
+                                ? block.content.map((c) => c.text || "").join("")
+                                : "";
+                        const pending = pendingToolUses.get(block.tool_use_id);
+                        events.push({
+                            timestamp: ts,
+                            type: "tool_result",
+                            agentId,
+                            agentSlug,
+                            toolUseId: block.tool_use_id,
+                            toolName: pending?.name,
+                            toolResult: truncate(resultText),
+                            toolSuccess: !block.is_error,
+                        });
+                        pendingToolUses.delete(block.tool_use_id);
+                    }
+                }
+            }
+        }
+        else if (type === "assistant") {
+            const msg = entry.message;
+            if (!msg)
+                continue;
+            const model = msg.model || "";
+            if (model)
+                models.add(model);
+            // Aggregate usage per requestId (streaming produces duplicates)
+            const reqId = entry.requestId || `anon-${events.length}`;
+            if (msg.usage) {
+                const u = msg.usage;
+                // Only keep the latest usage per requestId (last one has final counts)
+                usage.set(reqId, {
+                    inputTokens: u.input_tokens || 0,
+                    outputTokens: u.output_tokens || 0,
+                    cacheReadTokens: u.cache_read_input_tokens || 0,
+                    cacheCreationTokens: u.cache_creation_input_tokens || 0,
+                });
+            }
+            const content = msg.content;
+            if (Array.isArray(content)) {
+                for (const block of content) {
+                    if (block.type === "text") {
+                        events.push({
+                            timestamp: ts,
+                            type: "assistant",
+                            agentId,
+                            agentSlug,
+                            text: truncate(block.text, 2000),
+                            model,
+                        });
+                    }
+                    else if (block.type === "thinking") {
+                        events.push({
+                            timestamp: ts,
+                            type: "thinking",
+                            agentId,
+                            agentSlug,
+                            text: truncate(block.thinking || block.text, 1000),
+                            model,
+                        });
+                    }
+                    else if (block.type === "tool_use") {
+                        const toolName = block.name || "unknown";
+                        pendingToolUses.set(block.id, { name: toolName, timestamp: ts });
+                        // Extract payload files from Read tool calls
+                        if (toolName === "Read" && block.input) {
+                            const filePath = typeof block.input === "object" ? block.input.file_path : undefined;
+                            if (filePath) {
+                                payloadFiles.push({ path: filePath, timestamp: ts, agentId });
+                            }
+                        }
+                        events.push({
+                            timestamp: ts,
+                            type: "tool_use",
+                            agentId,
+                            agentSlug,
+                            toolName,
+                            toolUseId: block.id,
+                            toolInput: truncate(block.input),
+                            model,
+                        });
+                    }
+                }
+            }
+        }
+        else if (type === "system") {
+            events.push({
+                timestamp: ts,
+                type: "system",
+                agentId,
+                agentSlug,
+                text: entry.subtype || "system",
+            });
+        }
+    }
+    return { events, usage, models, firstTimestamp, lastTimestamp, firstUserPrompt, payloadFiles };
+}
+function computeCloudStats(usageMaps, allModels) {
+    let totalInput = 0;
+    let totalOutput = 0;
+    let totalCacheRead = 0;
+    let totalCacheCreate = 0;
+    let apiCalls = 0;
+    for (const usageMap of usageMaps) {
+        for (const u of usageMap.values()) {
+            totalInput += u.inputTokens;
+            totalOutput += u.outputTokens;
+            totalCacheRead += u.cacheReadTokens;
+            totalCacheCreate += u.cacheCreationTokens;
+            apiCalls++;
+        }
+    }
+    const costInput = (totalInput / 1_000_000) * COST_INPUT;
+    const costOutput = (totalOutput / 1_000_000) * COST_OUTPUT;
+    const costCacheRead = (totalCacheRead / 1_000_000) * COST_CACHE_READ;
+    const costCacheCreate = (totalCacheCreate / 1_000_000) * COST_CACHE_CREATE;
+    return {
+        totalInputTokens: totalInput,
+        totalOutputTokens: totalOutput,
+        totalCacheReadTokens: totalCacheRead,
+        totalCacheCreationTokens: totalCacheCreate,
+        estimatedCost: {
+            input: costInput,
+            output: costOutput,
+            cacheRead: costCacheRead,
+            cacheCreation: costCacheCreate,
+            total: costInput + costOutput + costCacheRead + costCacheCreate,
+        },
+        models: [...allModels],
+        apiCalls,
+    };
+}
+export async function importClaudeTranscript(projectDir, sessionId) {
+    const jsonlPath = path.join(projectDir, `${sessionId}.jsonl`);
+    if (!existsSync(jsonlPath))
+        return null;
+    let raw;
+    try {
+        raw = await readFile(jsonlPath, "utf-8");
+    }
+    catch {
+        return null;
+    }
+    const lines = raw.split("\n").filter(Boolean);
+    if (lines.length < 2)
+        return null;
+    // Parse main transcript
+    const main = parseTranscriptFile(raw);
+    // Filter warmup — if first user prompt is literally "warmup" and < 5 entries, skip
+    if (main.firstUserPrompt.trim().toLowerCase() === "warmup" && main.events.length < 5) {
+        return null;
+    }
+    const runs = [];
+    const allUsageMaps = [main.usage];
+    const allModels = new Set(main.models);
+    let allEvents = [...main.events];
+    let allPayload = [...main.payloadFiles];
+    // Orchestrator run
+    const mainTokens = { input: 0, output: 0 };
+    for (const u of main.usage.values()) {
+        mainTokens.input += u.inputTokens;
+        mainTokens.output += u.outputTokens;
+    }
+    const mainElapsed = main.firstTimestamp && main.lastTimestamp
+        ? (new Date(main.lastTimestamp).getTime() - new Date(main.firstTimestamp).getTime()) / 1000
+        : 0;
+    runs.push({
+        runId: `${sessionId}-orchestrator`,
+        sessionId,
+        phase: "orchestrator",
+        passId: "orchestrator",
+        agent: "Claude",
+        model: [...main.models][0] || "unknown",
+        iteration: 1,
+        startedAt: main.firstTimestamp,
+        completedAt: main.lastTimestamp || undefined,
+        elapsedSeconds: Math.max(0, mainElapsed),
+        status: "success",
+        tokens: mainTokens,
+        agentType: "orchestrator",
+        transcript: main.events,
+    });
+    // Parse subagents
+    const subagentDir = path.join(projectDir, sessionId, "subagents");
+    if (existsSync(subagentDir)) {
+        try {
+            const subFiles = await readdir(subagentDir);
+            for (const subFile of subFiles) {
+                if (!subFile.endsWith(".jsonl"))
+                    continue;
+                const agentIdMatch = subFile.match(/^agent-(.+)\.jsonl$/);
+                if (!agentIdMatch)
+                    continue;
+                const agentId = agentIdMatch[1];
+                try {
+                    const subRaw = await readFile(path.join(subagentDir, subFile), "utf-8");
+                    // Extract agentId and slug from first line
+                    let slug = "";
+                    try {
+                        const firstLine = JSON.parse(subRaw.split("\n")[0]);
+                        slug = firstLine.slug || "";
+                    }
+                    catch { /* skip */ }
+                    const sub = parseTranscriptFile(subRaw, agentId, slug);
+                    // Filter warmup agents
+                    if (sub.firstUserPrompt.trim().toLowerCase() === "warmup" || sub.events.length < 3)
+                        continue;
+                    const agentType = classifyAgentType(sub.firstUserPrompt);
+                    const subTokens = { input: 0, output: 0 };
+                    for (const u of sub.usage.values()) {
+                        subTokens.input += u.inputTokens;
+                        subTokens.output += u.outputTokens;
+                    }
+                    const subElapsed = sub.firstTimestamp && sub.lastTimestamp
+                        ? (new Date(sub.lastTimestamp).getTime() - new Date(sub.firstTimestamp).getTime()) / 1000
+                        : 0;
+                    for (const m of sub.models)
+                        allModels.add(m);
+                    allUsageMaps.push(sub.usage);
+                    allEvents.push(...sub.events);
+                    allPayload.push(...sub.payloadFiles);
+                    runs.push({
+                        runId: `${sessionId}-agent-${agentId}`,
+                        sessionId,
+                        phase: "subagent",
+                        passId: `agent-${agentId}`,
+                        agent: slug ? `${slug} (${agentType})` : `agent-${agentId} (${agentType})`,
+                        model: [...sub.models][0] || "unknown",
+                        iteration: 1,
+                        startedAt: sub.firstTimestamp,
+                        completedAt: sub.lastTimestamp || undefined,
+                        elapsedSeconds: Math.max(0, subElapsed),
+                        status: "success",
+                        tokens: subTokens,
+                        agentType,
+                        transcript: sub.events,
+                    });
+                }
+                catch {
+                    // Skip unreadable subagent files
+                }
+            }
+        }
+        catch {
+            // Skip if subagent dir unreadable
+        }
+    }
+    // Sort all events by timestamp
+    allEvents.sort((a, b) => (a.timestamp || "").localeCompare(b.timestamp || ""));
+    // Compute cloud stats
+    const cloudStats = computeCloudStats(allUsageMaps, allModels);
+    // Compute totals
+    const totalTokens = { input: 0, output: 0 };
+    for (const usageMap of allUsageMaps) {
+        for (const u of usageMap.values()) {
+            totalTokens.input += u.inputTokens;
+            totalTokens.output += u.outputTokens;
+        }
+    }
+    const totalElapsed = runs.reduce((sum, r) => sum + (r.elapsedSeconds ?? 0), 0);
+    // Extract metadata from first few lines
+    let version = "";
+    let gitBranch = "";
+    try {
+        for (let i = 0; i < Math.min(5, lines.length); i++) {
+            const parsed = JSON.parse(lines[i]);
+            if (!version && parsed.version)
+                version = parsed.version;
+            if (!gitBranch && parsed.gitBranch)
+                gitBranch = parsed.gitBranch;
+            if (version && gitBranch)
+                break;
+        }
+    }
+    catch { /* skip */ }
+    return {
+        sessionId,
+        projectName: gitBranch ? `branch: ${gitBranch}` : undefined,
+        startedAt: main.firstTimestamp,
+        completedAt: main.lastTimestamp || undefined,
+        status: "success",
+        source: "claude-transcript",
+        projectMeta: {
+            model: [...allModels].join(", "),
+            mode: version ? `Claude Code ${version}` : undefined,
+        },
+        summary: {
+            totalRuns: runs.length,
+            successfulRuns: runs.length,
+            failedRuns: 0,
+            skippedRuns: 0,
+            totalElapsedSeconds: totalElapsed,
+            totalTokens,
+            phases: [...new Set(runs.map(r => r.phase))],
+            models: [...allModels],
+        },
+        runs,
+        transcript: allEvents,
+        cloudStats,
+        payload: allPayload,
+    };
+}

package/dist/agents/observability/reader.d.ts

@@ -0,0 +1,7 @@
+import type { AgentSession, SessionIndex } from "./types.js";
+/** Load session index — reads index.json, or scans session dirs if missing */
+export declare function loadSessionIndex(projectRoot: string): Promise<SessionIndex>;
+/** Load a full session by ID */
+export declare function loadSession(projectRoot: string, sessionId: string): Promise<AgentSession | null>;
+/** Read recent activity log entries (newest first) */
+export declare function loadRecentActivity(projectRoot: string, limit?: number): Promise<string[]>;