@1agents/session-reader 0.1.1

package/dist/src/parsers/claude.js

@@ -0,0 +1,214 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { readJsonl } from '../util/jsonl.js';
+import { canonicalizePath } from '../util/paths.js';
+import { oneLine, stripPromptEnvelope } from '../util/text.js';
+import { emptyProviderStats, } from '../types.js';
+import { toolArgsOf } from './provider.js';
+const PROJECTS_DIR = path.join(os.homedir(), '.claude', 'projects');
+/** Claude prefixes a failed shell result with its exit status. */
+const EXIT_CODE = /^\s*Exit code (\d+)/;
+/** `tool_result.content` is either a string or a list of text blocks. */
+function flattenResult(content) {
+    if (typeof content === 'string')
+        return content;
+    if (Array.isArray(content)) {
+        return content
+            .map((block) => (typeof block === 'string' ? block : (block?.text ?? '')))
+            .filter(Boolean)
+            .join('\n');
+    }
+    return content == null ? '' : JSON.stringify(content);
+}
+export const claudeAdapter = {
+    provider: 'claude',
+    async listCandidates() {
+        let projects;
+        try {
+            projects = await fs.readdir(PROJECTS_DIR);
+        }
+        catch {
+            return [];
+        }
+        const found = [];
+        for (const project of projects) {
+            const dir = path.join(PROJECTS_DIR, project);
+            const files = await fs.readdir(dir).catch(() => []);
+            for (const file of files) {
+                if (!file.endsWith('.jsonl'))
+                    continue;
+                const full = path.join(dir, file);
+                const stat = await fs.stat(full).catch(() => undefined);
+                if (!stat?.isFile())
+                    continue;
+                found.push({
+                    id: file.replace(/\.jsonl$/, ''),
+                    path: full,
+                    mtimeMs: stat.mtimeMs,
+                    sizeBytes: stat.size,
+                });
+            }
+        }
+        return found.sort((a, b) => b.mtimeMs - a.mtimeMs);
+    },
+    /**
+     * Only the head of the file is read, so the title is the opening request —
+     * a session's own `custom-title`/`ai-title` is picked up by {@link parse}.
+     */
+    async scanRef(candidate) {
+        let title;
+        let workspace;
+        let createdAt;
+        for await (const raw of readJsonl(candidate.path, { maxLines: 60 })) {
+            const entry = raw;
+            if (entry.cwd)
+                workspace ??= canonicalizePath(entry.cwd);
+            createdAt ??= entry.timestamp;
+            if (entry.type === 'custom-title' && entry.customTitle)
+                title = entry.customTitle;
+            if (!title && entry.type === 'user' && !entry.isMeta && typeof entry.message?.content === 'string') {
+                title = oneLine(stripPromptEnvelope(entry.message.content), 120);
+            }
+            if (title && workspace)
+                break;
+        }
+        return {
+            id: candidate.id,
+            provider: 'claude',
+            path: candidate.path,
+            title,
+            workspace,
+            createdAt,
+            updatedAt: new Date(candidate.mtimeMs).toISOString(),
+            sizeBytes: candidate.sizeBytes,
+        };
+    },
+    async parse(candidate) {
+        const turns = [];
+        const stats = emptyProviderStats();
+        const tokens = { input: 0, output: 0, total: 0 };
+        let cacheRead = 0;
+        // One assistant message can appear on several entries; count its usage once.
+        const countedUsage = new Set();
+        let title;
+        let firstPrompt;
+        let workspace;
+        let createdAt;
+        let updatedAt;
+        const push = (turn) => {
+            turns.push({ ...turn, index: turns.length, id: `${candidate.id}#${turns.length}` });
+        };
+        for await (const raw of readJsonl(candidate.path)) {
+            const entry = raw;
+            if (entry.cwd)
+                workspace ??= canonicalizePath(entry.cwd);
+            if (entry.timestamp) {
+                createdAt ??= entry.timestamp;
+                updatedAt = entry.timestamp;
+            }
+            if (entry.type === 'custom-title' && entry.customTitle)
+                title = entry.customTitle;
+            if (entry.type === 'ai-title' && typeof entry.title === 'string')
+                title ??= entry.title;
+            if (entry.gitBranch && !stats.branches.includes(entry.gitBranch))
+                stats.branches.push(entry.gitBranch);
+            const model = entry.message?.model;
+            if (model && !stats.models.includes(model))
+                stats.models.push(model);
+            const usage = entry.message?.usage;
+            const usageKey = entry.message?.id ?? entry.requestId ?? entry.uuid;
+            if (usage && usageKey && !countedUsage.has(usageKey)) {
+                countedUsage.add(usageKey);
+                // Cache reads are prefix replays, not input: counting them as input
+                // turns a 200k-context session into "116M tokens".
+                tokens.input += (usage.input_tokens ?? 0) + (usage.cache_creation_input_tokens ?? 0);
+                tokens.output += usage.output_tokens ?? 0;
+                cacheRead += usage.cache_read_input_tokens ?? 0;
+            }
+            if (entry.isSidechain)
+                stats.extras.sidechain = (stats.extras.sidechain ?? 0) + 1;
+            if (entry.type === 'attachment' && entry.attachment?.type) {
+                const key = `attachment:${entry.attachment.type}`;
+                stats.extras[key] = (stats.extras[key] ?? 0) + 1;
+            }
+            if (entry.type === 'file-history-snapshot') {
+                stats.extras.fileSnapshots = (stats.extras.fileSnapshots ?? 0) + 1;
+            }
+            if (entry.isMeta)
+                continue;
+            const timestamp = entry.timestamp;
+            const content = entry.message?.content;
+            if (entry.type === 'user' && typeof content === 'string') {
+                const text = stripPromptEnvelope(content);
+                if (!text)
+                    continue;
+                firstPrompt ??= oneLine(text, 120);
+                push({ kind: 'user', text, timestamp });
+                continue;
+            }
+            if (!Array.isArray(content))
+                continue;
+            for (const block of content) {
+                switch (block.type) {
+                    case 'text':
+                        if (block.text?.trim())
+                            push({ kind: 'assistant', text: block.text, timestamp });
+                        break;
+                    case 'thinking':
+                        if (block.thinking?.trim())
+                            push({ kind: 'thinking', text: block.thinking, timestamp });
+                        break;
+                    case 'tool_use':
+                        push({
+                            kind: 'tool_call',
+                            toolName: block.name,
+                            toolArgs: toolArgsOf(block.input),
+                            timestamp,
+                        });
+                        break;
+                    case 'tool_result': {
+                        const text = flattenResult(block.content);
+                        const exit = EXIT_CODE.exec(text);
+                        push({
+                            kind: 'tool_result',
+                            toolResult: text,
+                            isError: block.is_error === true,
+                            timestamp,
+                            ...(exit ? { exitCode: Number(exit[1]) } : {}),
+                        });
+                        break;
+                    }
+                    default:
+                        break;
+                }
+            }
+        }
+        return {
+            ref: {
+                id: candidate.id,
+                provider: 'claude',
+                path: candidate.path,
+                title: title ?? firstPrompt,
+                workspace,
+                createdAt,
+                updatedAt: updatedAt ?? new Date(candidate.mtimeMs).toISOString(),
+                sizeBytes: candidate.sizeBytes,
+            },
+            turns,
+            artifacts: [],
+            stats: {
+                ...stats,
+                ...(tokens.input || tokens.output
+                    ? {
+                        tokens: {
+                            ...tokens,
+                            total: tokens.input + tokens.output,
+                            ...(cacheRead ? { cacheRead } : {}),
+                        },
+                    }
+                    : {}),
+            },
+        };
+    },
+};

package/dist/src/parsers/codex.d.ts

@@ -0,0 +1,2 @@
+import { type ProviderAdapter } from './provider.js';
+export declare const codexAdapter: ProviderAdapter;

package/dist/src/parsers/codex.js

@@ -0,0 +1,316 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { readJsonl } from '../util/jsonl.js';
+import { canonicalizePath } from '../util/paths.js';
+import { looksLikeInstructions, oneLine, stripPromptEnvelope } from '../util/text.js';
+import { toolArgsOf } from './provider.js';
+import { emptyProviderStats, } from '../types.js';
+const SESSIONS_DIR = path.join(os.homedir(), '.codex', 'sessions');
+const ROLLOUT = /^rollout-.*?-([0-9a-fA-F-]{36})\.jsonl$/;
+const SSH_HOST = /\b[\w.-]+@((?:\d{1,3}(?:\.\d{1,3}){3})|(?:[\w-]+(?:\.[\w-]+)+))/;
+function durationOf(duration) {
+    if (!duration)
+        return undefined;
+    const ms = (duration.secs ?? 0) * 1000 + (duration.nanos ?? 0) / 1e6;
+    return ms > 0 ? Math.round(ms) : undefined;
+}
+const CHANGE_KINDS = {
+    add: 'add',
+    update: 'update',
+    delete: 'delete',
+};
+/**
+ * Absorbs the structured side-channel: authoritative file changes, command
+ * executions with pids, turn boundaries and token accounting. These mirror the
+ * conversation stream, so they feed statistics only — never the turn list.
+ */
+function absorbEvent(line, stats, tokens) {
+    const payload = line.payload ?? {};
+    if (line.type === 'token_usage_record') {
+        const usage = payload.usage;
+        if (usage) {
+            tokens.input += usage.input_tokens ?? 0;
+            tokens.output += usage.output_tokens ?? 0;
+            tokens.total += usage.total_tokens ?? 0;
+        }
+        return;
+    }
+    if (line.type === 'event_msg' && payload.type === 'thread_settings_applied') {
+        const model = payload.thread_settings?.model;
+        if (model && !stats.models.includes(model))
+            stats.models.push(model);
+        return;
+    }
+    if (line.type === 'event_msg' && payload.type === 'task_started') {
+        stats.turnBoundaries.push({
+            id: payload.turn_id,
+            startedAt: line.timestamp,
+            completed: false,
+        });
+        return;
+    }
+    if (line.type === 'event_msg' && payload.type === 'task_complete') {
+        const turnId = payload.turn_id;
+        // Pair by id: this session starts 12 turns but completes only 9, so
+        // matching by position would attribute durations to the wrong turns.
+        const match = stats.turnBoundaries.find((boundary) => boundary.id === turnId && !boundary.completed);
+        if (match) {
+            match.completed = true;
+            match.endedAt = line.timestamp;
+            match.durationMs = payload.duration_ms;
+            match.lastMessage = payload.last_agent_message;
+        }
+        return;
+    }
+    if (line.type !== 'event_msg' || payload.type !== 'item_completed')
+        return;
+    const item = (payload.item ?? {});
+    switch (item.type) {
+        case 'FileChange':
+            for (const [file, detail] of Object.entries(item.changes ?? {})) {
+                const size = detail?.content?.length;
+                stats.fileChanges.push({
+                    path: canonicalizePath(file),
+                    change: CHANGE_KINDS[detail?.type ?? ''] ?? 'update',
+                    ...(size === undefined ? {} : { sizeBytes: size }),
+                });
+            }
+            break;
+        case 'CommandExecution': {
+            stats.commandExecutions = (stats.commandExecutions ?? 0) + 1;
+            const command = Array.isArray(item.command) ? item.command.join(' ') : (item.command ?? '');
+            const record = {
+                eventIndex: -1, // filled in by the ledger, which knows the event stream
+                turn: 0,
+                command,
+                provenance: 'observed',
+                extractor: 'item:CommandExecution',
+                ...(item.process_id ? { pid: item.process_id } : {}),
+                ...(item.cwd ? { cwd: canonicalizePath(item.cwd) } : {}),
+                ...(typeof item.exit_code === 'number' ? { exitCode: item.exit_code } : {}),
+                ...(durationOf(item.duration) ? { durationMs: durationOf(item.duration) } : {}),
+                ...(item.stderr?.trim() ? { stderr: item.stderr.trim() } : {}),
+                ...(line.timestamp ? { timestamp: line.timestamp } : {}),
+            };
+            const host = SSH_HOST.exec(command)?.[1];
+            if (host)
+                record.host = host;
+            stats.commands.push(record);
+            break;
+        }
+        case 'Extension':
+            stats.extras[`web:${item.kind ?? 'unknown'}`] = (stats.extras[`web:${item.kind ?? 'unknown'}`] ?? 0) + 1;
+            break;
+        case 'Reasoning':
+        case 'AgentMessage':
+        case 'UserMessage':
+            break;
+        default:
+            if (item.type)
+                stats.extras[item.type] = (stats.extras[item.type] ?? 0) + 1;
+    }
+}
+function textOf(content) {
+    if (typeof content === 'string')
+        return content;
+    if (!Array.isArray(content))
+        return '';
+    return content
+        .map((block) => block?.text ?? '')
+        .filter(Boolean)
+        .join('\n');
+}
+function parseArguments(value) {
+    if (typeof value === 'string') {
+        try {
+            return toolArgsOf(JSON.parse(value)) ?? { input: value };
+        }
+        catch {
+            return { input: value };
+        }
+    }
+    return toolArgsOf(value);
+}
+/** Walks `sessions/<YYYY>/<MM>/<DD>/rollout-*.jsonl`. */
+async function walkRollouts(dir, out, depth = 0) {
+    const entries = await fs.readdir(dir, { withFileTypes: true }).catch(() => []);
+    for (const entry of entries) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory() && depth < 4)
+            await walkRollouts(full, out, depth + 1);
+        else if (entry.isFile() && ROLLOUT.test(entry.name))
+            out.push(full);
+    }
+}
+export const codexAdapter = {
+    provider: 'codex',
+    async listCandidates() {
+        const files = [];
+        await walkRollouts(SESSIONS_DIR, files);
+        const found = [];
+        for (const file of files) {
+            const stat = await fs.stat(file).catch(() => undefined);
+            if (!stat)
+                continue;
+            found.push({
+                id: ROLLOUT.exec(path.basename(file))?.[1] ?? path.basename(file),
+                path: file,
+                mtimeMs: stat.mtimeMs,
+                sizeBytes: stat.size,
+            });
+        }
+        return found.sort((a, b) => b.mtimeMs - a.mtimeMs);
+    },
+    async scanRef(candidate) {
+        let title;
+        let workspace;
+        let createdAt;
+        for await (const raw of readJsonl(candidate.path, { maxLines: 120 })) {
+            const line = raw;
+            const payload = line.payload ?? {};
+            if (line.type === 'session_meta') {
+                createdAt ??= payload.timestamp ?? line.timestamp;
+                if (typeof payload.cwd === 'string')
+                    workspace ??= canonicalizePath(payload.cwd);
+            }
+            if (!workspace && line.type === 'turn_context' && typeof payload.cwd === 'string') {
+                workspace = canonicalizePath(payload.cwd);
+            }
+            if (!title && line.type === 'response_item' && payload.type === 'message' && payload.role === 'user') {
+                const text = stripPromptEnvelope(textOf(payload.content));
+                if (text && !looksLikeInstructions(text))
+                    title = oneLine(text, 120);
+            }
+            if (title && workspace)
+                break;
+        }
+        return {
+            id: candidate.id,
+            provider: 'codex',
+            path: candidate.path,
+            title,
+            workspace,
+            createdAt: createdAt ?? timestampFromFilename(candidate.path),
+            updatedAt: new Date(candidate.mtimeMs).toISOString(),
+            sizeBytes: candidate.sizeBytes,
+        };
+    },
+    async parse(candidate) {
+        const turns = [];
+        const stats = emptyProviderStats();
+        const tokens = { input: 0, output: 0, total: 0 };
+        let title;
+        let workspace;
+        let createdAt;
+        let updatedAt;
+        const push = (turn) => {
+            turns.push({ ...turn, index: turns.length, id: `${candidate.id}#${turns.length}` });
+        };
+        for await (const raw of readJsonl(candidate.path)) {
+            const line = raw;
+            const payload = line.payload ?? {};
+            const timestamp = line.timestamp;
+            if (timestamp) {
+                createdAt ??= timestamp;
+                updatedAt = timestamp;
+            }
+            if (line.type === 'session_meta' || line.type === 'turn_context') {
+                if (typeof payload.cwd === 'string')
+                    workspace ??= canonicalizePath(payload.cwd);
+                continue;
+            }
+            if (line.type !== 'response_item') {
+                absorbEvent(line, stats, tokens);
+                continue;
+            }
+            switch (payload.type) {
+                case 'message': {
+                    const text = stripPromptEnvelope(textOf(payload.content));
+                    if (!text)
+                        break;
+                    if (payload.role === 'assistant') {
+                        push({ kind: 'assistant', text, timestamp });
+                    }
+                    else if (payload.role === 'user') {
+                        if (looksLikeInstructions(text))
+                            break;
+                        title ??= oneLine(text, 120);
+                        push({ kind: 'user', text, timestamp });
+                    }
+                    break;
+                }
+                case 'reasoning': {
+                    const summary = Array.isArray(payload.summary)
+                        ? payload.summary.map((b) => b?.text ?? '').filter(Boolean).join('\n')
+                        : '';
+                    if (summary)
+                        push({ kind: 'thinking', text: summary, timestamp });
+                    break;
+                }
+                case 'function_call':
+                    push({
+                        kind: 'tool_call',
+                        toolName: payload.name,
+                        toolArgs: parseArguments(payload.arguments),
+                        timestamp,
+                    });
+                    break;
+                case 'custom_tool_call':
+                    push({
+                        kind: 'tool_call',
+                        toolName: payload.name,
+                        toolArgs: { input: payload.input },
+                        timestamp,
+                    });
+                    break;
+                case 'local_shell_call':
+                    push({
+                        kind: 'tool_call',
+                        toolName: 'shell',
+                        toolArgs: toolArgsOf(payload.action) ?? {},
+                        timestamp,
+                    });
+                    break;
+                case 'function_call_output':
+                case 'custom_tool_call_output': {
+                    const output = textOf(payload.output) || String(payload.output ?? '');
+                    push({
+                        kind: 'tool_result',
+                        toolResult: output,
+                        // A bare "error" substring matches ordinary prose; require a real
+                        // non-zero exit or a fatal marker at the start of a line.
+                        isError: /"exit_code":\s*[1-9]/.test(output.slice(0, 400)) ||
+                            /^(?:Traceback|fatal:|error:|[\w.]+Error:)/im.test(output.slice(0, 400)),
+                        timestamp,
+                    });
+                    break;
+                }
+                default:
+                    break;
+            }
+        }
+        return {
+            ref: {
+                id: candidate.id,
+                provider: 'codex',
+                path: candidate.path,
+                title,
+                workspace,
+                createdAt,
+                updatedAt: updatedAt ?? new Date(candidate.mtimeMs).toISOString(),
+                sizeBytes: candidate.sizeBytes,
+            },
+            turns,
+            artifacts: [],
+            stats: { ...stats, ...(tokens.total ? { tokens } : {}) },
+        };
+    },
+};
+function timestampFromFilename(file) {
+    const stamp = /rollout-(\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2})/.exec(path.basename(file))?.[1];
+    if (!stamp)
+        return undefined;
+    const [date, time] = stamp.split('T');
+    return `${date}T${time?.replace(/-/g, ':')}`;
+}

package/dist/src/parsers/provider.d.ts

@@ -0,0 +1,24 @@
+import type { AgentProvider, NormalizedSession, SessionRef } from '../types.js';
+/** A session file found on disk, before any parsing. */
+export interface SessionCandidate {
+    id: string;
+    path: string;
+    mtimeMs: number;
+    sizeBytes: number;
+}
+export interface ProviderAdapter {
+    provider: AgentProvider;
+    /** Cheap `stat`-only discovery, newest first. */
+    listCandidates(): Promise<SessionCandidate[]>;
+    /** Reads just enough of the head of a file to fill a {@link SessionRef}. */
+    scanRef(candidate: SessionCandidate): Promise<SessionRef>;
+    /** Full parse into ordered turns. */
+    parse(candidate: SessionCandidate): Promise<NormalizedSession>;
+    /**
+     * Extra identity for providers whose `parse` reads more than the transcript
+     * (antigravity also picks up artifacts next to it). Folded into the index
+     * fingerprint so those side files cannot go stale unnoticed.
+     */
+    auxFingerprint?(candidate: SessionCandidate): Promise<string | undefined>;
+}
+export declare function toolArgsOf(value: unknown): Record<string, unknown> | undefined;

package/dist/src/parsers/provider.js

@@ -0,0 +1,5 @@
+export function toolArgsOf(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : undefined;
+}

package/dist/src/resolver.d.ts

@@ -0,0 +1,42 @@
+import type { ProviderAdapter, SessionCandidate } from './parsers/provider.js';
+import type { AgentProvider, NormalizedSession, SessionRef } from './types.js';
+export declare const adapters: ProviderAdapter[];
+export interface ListOptions {
+    limit?: number;
+    /**
+     * How many session files may be opened. Defaults to a small budget so an
+     * unfiltered `list` stays cheap; pass `Infinity` when completeness matters
+     * more than latency (indexing, search).
+     */
+    scan?: number;
+    workspace?: string;
+    provider?: AgentProvider;
+    /** Only sessions updated at or after this moment (`24h`, `7d`, ISO date). */
+    since?: string | Date;
+}
+export interface ResolvedSession {
+    ref: SessionRef;
+    adapter: ProviderAdapter;
+    candidate: SessionCandidate;
+}
+/** Accepts `24h`, `90m`, `7d`, `2026-09-01` or a Date. */
+export declare function parseSince(since: string | Date | undefined): number | undefined;
+/** Discovery that keeps the adapter handle, so callers can parse without a second scan. */
+export declare function listResolvedSessions(options?: ListOptions): Promise<ResolvedSession[]>;
+export declare function listRecentSessions(options?: ListOptions): Promise<SessionRef[]>;
+export declare function findSessionsByWorkspace(workspacePath: string, options?: Omit<ListOptions, 'workspace'>): Promise<SessionRef[]>;
+export declare function findResolvedByWorkspace(workspacePath: string, options?: Omit<ListOptions, 'workspace'>): Promise<ResolvedSession[]>;
+/** Locates a session by full id, id prefix, or native file path. */
+export declare function resolveSession(sessionId: string): Promise<ResolvedSession | undefined>;
+export declare function parseSession(sessionId: string): Promise<NormalizedSession>;
+export interface LoadOptions {
+    /** Set false to bypass the index entirely (CI, read-only checkouts). */
+    useIndex?: boolean;
+    force?: boolean;
+}
+/**
+ * The one seam every command loads sessions through. Whether the events come
+ * from the index or straight off disk, the object handed back is the same, so
+ * `buildOverview` / `fileLedger` / `summarizeTurns` never learn about caching.
+ */
+export declare function loadSession(sessionId: string, options?: LoadOptions): Promise<NormalizedSession>;