@tangle-network/harness-sessions 0.0.0-stage → 0.1.0

package/dist/capture.js

@@ -0,0 +1,210 @@
+/**
+ * Reading the native sessions in a capture.
+ *
+ * The sidecar's raw-evidence archive v2 lists each execution's native session copies in
+ * `nativeSessions[]`, with the harness, the session id recorded at spawn, the copy kind and the
+ * files. A capture taken before v2 (provider-tangle's retention layout, `tangle-native-session-
+ * evidence.v1`) has no such list: it holds each execution's private runtime HOME under
+ * `__retention__/sessions/<sandbox session>/native/<source>/<root scope>/`, and its manifest names
+ * the harness and, once an attempt settled, the native session ids. Both are read through the
+ * store layouts the readers declare; no consumer matches session paths itself.
+ */
+import { readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { isRecord, str } from './builder.js';
+import { opencodeSessionsInStore } from './formats/opencode.js';
+import { maybeReaderFor, readerFor, readerForFormat } from './registry.js';
+import { isMissing } from './source.js';
+import { storeGlob } from './stores.js';
+export const RETENTION_SESSIONS = join('__retention__', 'sessions');
+export const RETENTION_MANIFEST_KIND = 'tangle-native-session-evidence.v1';
+async function readJson(path) {
+    try {
+        return JSON.parse(await readFile(path, 'utf8'));
+    }
+    catch (error) {
+        if (isMissing(error))
+            return null;
+        throw error;
+    }
+}
+async function dirs(path) {
+    try {
+        return (await readdir(path, { withFileTypes: true })).filter((e) => e.isDirectory()).map((e) => e.name).sort();
+    }
+    catch (error) {
+        if (isMissing(error))
+            return [];
+        throw error;
+    }
+}
+/** Sessions listed by a v2 archive manifest. Files are resolved against `archiveDir`. */
+async function fromV2(archiveDir, manifest, listing) {
+    for (const copy of manifest.nativeSessions) {
+        const reader = maybeReaderFor(copy.harness) ?? readerForFormatSafe(copy.format);
+        if (!reader) {
+            listing.missing.push({ sandboxSessionId: null, harness: copy.harness, reason: 'no_reader_for_harness', nativeSessionId: copy.nativeSessionId });
+            continue;
+        }
+        const store = reader.stores.find((s) => s.format === copy.format) ?? reader.stores[0];
+        const inStore = (path) => {
+            const marker = `${store.root}/`;
+            const index = path.indexOf(marker);
+            return index === -1 ? null : path.slice(index + marker.length);
+        };
+        const truncated = copy.files.some((f) => f.truncated);
+        if (store.shared) {
+            const db = copy.files.find((f) => inStore(storePathOf(f)) === store.files[0]);
+            if (!db) {
+                listing.missing.push({ sandboxSessionId: null, harness: copy.harness, reason: 'store_file_missing', nativeSessionId: copy.nativeSessionId });
+                continue;
+            }
+            const path = join(archiveDir, db.path);
+            const refs = await opencodeSessionsInStore(path, null, {});
+            const ids = new Set([copy.nativeSessionId]);
+            // Child sessions of the execution's session live in the same store.
+            for (const ref of refs)
+                if (ref.parentNativeSessionId && ids.has(ref.parentNativeSessionId))
+                    ids.add(ref.nativeSessionId);
+            for (const ref of refs.filter((r) => ids.has(r.nativeSessionId))) {
+                listing.sessions.push(captured({ ...ref, truncated }, copy, ref.nativeSessionId === copy.nativeSessionId, archiveDir, path));
+            }
+            if (!refs.some((r) => r.nativeSessionId === copy.nativeSessionId)) {
+                listing.missing.push({ sandboxSessionId: null, harness: copy.harness, reason: 'native_session_not_in_store', nativeSessionId: copy.nativeSessionId });
+            }
+            continue;
+        }
+        const main = storeGlob(reader.globs.session, copy.nativeSessionId);
+        const nested = reader.globs.children ? [storeGlob(reader.globs.children, copy.nativeSessionId)] : [];
+        const mainFile = copy.files.find((f) => { const rel = inStore(storePathOf(f)); return rel !== null && main.test(rel); });
+        if (!mainFile) {
+            listing.missing.push({ sandboxSessionId: null, harness: copy.harness, reason: 'native_session_file_missing', nativeSessionId: copy.nativeSessionId });
+            continue;
+        }
+        const mainPath = join(archiveDir, mainFile.path);
+        const nestedFiles = copy.files.filter((f) => { const rel = inStore(storePathOf(f)); return rel !== null && nested.some((n) => n.test(rel)); }).map((f) => join(archiveDir, f.path));
+        listing.sessions.push(captured({ harness: reader.harness, format: store.format, nativeSessionId: copy.nativeSessionId, path: mainPath, files: [mainPath, ...nestedFiles], home: null, cwd: null, mtimeMs: Date.parse(copy.capturedAt) || 0, parentNativeSessionId: null, truncated: mainFile.truncated }, copy, true, archiveDir, mainPath));
+        for (const file of nestedFiles) {
+            const child = file.split('/').pop().replace(/\.jsonl$/u, '').replace(/^agent-/u, '');
+            listing.sessions.push(captured({ harness: reader.harness, format: store.format, nativeSessionId: child, path: file, files: [file], home: null, cwd: null, mtimeMs: Date.parse(copy.capturedAt) || 0, parentNativeSessionId: copy.nativeSessionId, truncated }, copy, false, archiveDir, file));
+        }
+    }
+}
+/**
+ * The file's path relative to the runtime HOME, which the store globs match. The sidecar's archive
+ * stores payloads under flat member names (`path`) and names the HOME path in `storePath`; a
+ * capture laid out like the HOME carries it in `path` itself.
+ */
+function storePathOf(file) {
+    return file.storePath ?? file.path;
+}
+function readerForFormatSafe(format) {
+    try {
+        return readerForFormat(format);
+    }
+    catch {
+        return undefined;
+    }
+}
+function captured(ref, copy, recordedId, archiveDir, path) {
+    return {
+        ref,
+        harness: ref.harness,
+        sandboxSessionId: null,
+        executionId: copy.executionId,
+        attempt: copy.attempt,
+        copy: copy.copy,
+        recordedId,
+        root: path.startsWith(archiveDir) ? path.slice(archiveDir.length + 1) : path,
+        sourceId: null,
+        rootScope: null,
+    };
+}
+/** Sessions in provider-tangle's retention layout, found through each reader's declared stores. */
+async function fromRetention(captureDir, listing, fallbackHarness) {
+    const sessionsDir = join(captureDir, RETENTION_SESSIONS);
+    for (const sandboxSessionId of await dirs(sessionsDir)) {
+        const dir = join(sessionsDir, sandboxSessionId);
+        const manifest = await readJson(join(dir, 'raw-manifest.json'));
+        const source = isRecord(manifest) && isRecord(manifest.source) ? manifest.source : null;
+        if (isRecord(manifest) && Array.isArray(manifest.nativeSessions)) {
+            await fromV2(dir, manifest, listing);
+            continue;
+        }
+        // The manifest names the harness; a capture whose manifest does not falls back to the
+        // harness the caller ran (the profile's), never to guessing from paths.
+        const harness = (source ? str(source.backendType) : null) ?? fallbackHarness;
+        const reader = harness ? maybeReaderFor(harness) : undefined;
+        if (!reader) {
+            listing.missing.push({ sandboxSessionId, harness, reason: harness ? 'no_reader_for_harness' : 'harness_not_recorded' });
+            continue;
+        }
+        const attempts = source && Array.isArray(source.attempts) ? source.attempts.filter(isRecord) : [];
+        const recorded = new Map();
+        for (const attempt of attempts) {
+            for (const id of Array.isArray(attempt.nativeSessionIds) ? attempt.nativeSessionIds : []) {
+                if (typeof id === 'string')
+                    recorded.set(id, { executionId: str(attempt.executionId), attempt: typeof attempt.ordinal === 'number' ? attempt.ordinal : null });
+            }
+        }
+        if (source && typeof source.nativeSessionId === 'string' && !recorded.has(source.nativeSessionId)) {
+            recorded.set(source.nativeSessionId, { executionId: null, attempt: null });
+        }
+        const lastAttempt = attempts[attempts.length - 1];
+        const found = new Set();
+        // native/<source id>/<root scope>/ is one execution's runtime HOME (or its workspace).
+        for (const sourceId of await dirs(join(dir, 'native'))) {
+            for (const rootScope of await dirs(join(dir, 'native', sourceId))) {
+                const home = join(dir, 'native', sourceId, rootScope);
+                let refs;
+                try {
+                    refs = await reader.locate(home);
+                }
+                catch (error) {
+                    // A store that cannot be opened (a corrupt SQLite file) proves nothing about the turn.
+                    const store = reader.stores[0];
+                    listing.missing.push({ sandboxSessionId, harness: reader.harness, reason: 'store_unreadable', root: home.slice(captureDir.length + 1), path: store.shared ? `${store.root}/${store.files[0]}` : store.root, detail: error instanceof Error ? error.message : String(error) });
+                    continue;
+                }
+                for (const ref of refs) {
+                    const join_ = recorded.get(ref.nativeSessionId) ?? (ref.parentNativeSessionId ? recorded.get(ref.parentNativeSessionId) : undefined);
+                    found.add(ref.nativeSessionId);
+                    listing.sessions.push({
+                        ref,
+                        harness: reader.harness,
+                        sandboxSessionId,
+                        executionId: join_?.executionId ?? (lastAttempt ? str(lastAttempt.executionId) : null) ?? sourceId,
+                        attempt: join_?.attempt ?? (lastAttempt && typeof lastAttempt.ordinal === 'number' ? lastAttempt.ordinal : null),
+                        copy: 'retained',
+                        recordedId: recorded.has(ref.nativeSessionId),
+                        root: home.slice(captureDir.length + 1),
+                        sourceId,
+                        rootScope,
+                    });
+                }
+            }
+        }
+        for (const id of recorded.keys()) {
+            if (!found.has(id))
+                listing.missing.push({ sandboxSessionId, harness: reader.harness, reason: 'native_session_not_in_copy', nativeSessionId: id });
+        }
+    }
+}
+/**
+ * Every native session in a capture: from `manifest.nativeSessions` when a v2 manifest is given
+ * (files relative to `dir`), otherwise from the retention layout under `dir`.
+ */
+export async function listCapture(dir, manifest, options = {}) {
+    const listing = { sessions: [], missing: [] };
+    if (manifest && Array.isArray(manifest.nativeSessions))
+        await fromV2(dir, manifest, listing);
+    else
+        await fromRetention(dir, listing, options.harness ?? null);
+    return listing;
+}
+/** Every native session in a capture, read in full. */
+export async function* readCapture(dir, manifest, options = {}) {
+    const listing = await listCapture(dir, manifest, options);
+    for (const session of listing.sessions)
+        yield await readerFor(session.harness).read(session.ref);
+}

package/dist/catalog.d.ts

@@ -0,0 +1,163 @@
+export declare const SESSION_FORMAT_IDS: readonly ["claude-code.projects-jsonl", "codex.rollout-jsonl", "opencode.sqlite", "pi.session-jsonl", "kimi.session-dir", "factory.session-jsonl", "gemini.chat-json", "amp.thread-json", "forge.sqlite", "hermes.state-sqlite", "prime.session-jsonl", "openclaw.session-jsonl"];
+/** Store layouts, relative to the HOME a harness ran with. */
+export declare const STORES: {
+    readonly 'claude-code.projects-jsonl': {
+        readonly root: '.claude/projects';
+        readonly files: readonly ["*/{id}.jsonl", "*/{id}/subagents/**/*.jsonl"];
+        readonly write: 'jsonl-append';
+        readonly shared: false;
+        readonly format: 'claude-code.projects-jsonl';
+    };
+    readonly 'codex.rollout-jsonl': {
+        readonly root: '.codex/sessions';
+        readonly files: readonly ["*/*/*/rollout-*-{id}.jsonl"];
+        readonly write: 'jsonl-append';
+        readonly shared: false;
+        readonly format: 'codex.rollout-jsonl';
+    };
+    readonly 'opencode.sqlite': {
+        readonly root: '.local/share/opencode';
+        readonly files: readonly ["opencode.db", "opencode.db-wal", "opencode.db-shm"];
+        readonly write: 'sqlite-wal';
+        readonly shared: true;
+        readonly format: 'opencode.sqlite';
+    };
+    readonly 'pi.session-jsonl': {
+        readonly root: '.pi/agent/sessions';
+        readonly files: readonly ["**/*_{id}.jsonl"];
+        readonly write: 'jsonl-append';
+        readonly shared: false;
+        readonly format: 'pi.session-jsonl';
+    };
+    readonly 'kimi.session-dir': {
+        readonly root: '.kimi/sessions';
+        readonly files: readonly ["*/{id}/**", "*/{id}.jsonl"];
+        readonly write: 'jsonl-append';
+        readonly shared: false;
+        readonly format: 'kimi.session-dir';
+    };
+    readonly 'factory.session-jsonl': {
+        readonly root: '.factory/sessions';
+        readonly files: readonly ["*/{id}.jsonl", "*/{id}.settings.json"];
+        readonly write: 'jsonl-append';
+        readonly shared: false;
+        readonly format: 'factory.session-jsonl';
+    };
+    readonly 'gemini.chat-json': {
+        readonly root: '.gemini/tmp';
+        readonly files: readonly ["*/chats/session-*{id}*.json"];
+        readonly write: 'json-rewrite';
+        readonly shared: false;
+        readonly format: 'gemini.chat-json';
+    };
+    readonly 'amp.thread-json': {
+        readonly root: '.local/share/amp/threads';
+        readonly files: readonly ["{id}.json"];
+        readonly write: 'json-rewrite';
+        readonly shared: false;
+        readonly format: 'amp.thread-json';
+    };
+    readonly 'forge.sqlite': {
+        readonly root: '.forge';
+        readonly files: readonly [".forge.db", ".forge.db-wal", ".forge.db-shm"];
+        readonly write: 'sqlite-wal';
+        readonly shared: true;
+        readonly format: 'forge.sqlite';
+    };
+    readonly 'hermes.state-sqlite': {
+        readonly root: '.hermes';
+        readonly files: readonly ["state.db", "state.db-wal", "state.db-shm"];
+        readonly write: 'sqlite-wal';
+        readonly shared: true;
+        readonly format: 'hermes.state-sqlite';
+    };
+    readonly 'prime.session-jsonl': {
+        readonly root: '.prime-provider/prime-agent-dirs';
+        readonly files: readonly ["**/*_{id}.jsonl"];
+        readonly write: 'jsonl-append';
+        readonly shared: false;
+        readonly format: 'prime.session-jsonl';
+    };
+    readonly 'openclaw.session-jsonl': {
+        readonly root: '.openclaw/agents';
+        readonly files: readonly ["**/{id}.jsonl"];
+        readonly write: 'jsonl-append';
+        readonly shared: false;
+        readonly format: 'openclaw.session-jsonl';
+    };
+};
+/**
+ * Where each format's served model, usage and ending error come from. `turn-context` means the
+ * model the harness was configured or asked for (Codex `turn_context`, OpenCode's message
+ * `modelID`, Factory's settings); `none` means the session records no model at all.
+ */
+export declare const EVIDENCE: {
+    readonly 'claude-code.projects-jsonl': {
+        readonly servedModel: 'provider-response';
+        readonly usage: 'per-response';
+        readonly endingError: 'session-record';
+    };
+    readonly 'codex.rollout-jsonl': {
+        readonly servedModel: 'turn-context';
+        readonly usage: 'cumulative';
+        readonly endingError: 'session-record';
+    };
+    readonly 'opencode.sqlite': {
+        readonly servedModel: 'turn-context';
+        readonly usage: 'per-response';
+        readonly endingError: 'session-record';
+    };
+    readonly 'pi.session-jsonl': {
+        readonly servedModel: 'session-record';
+        readonly usage: 'per-response';
+        readonly endingError: 'session-record';
+    };
+    readonly 'kimi.session-dir': {
+        readonly servedModel: 'none';
+        readonly usage: 'per-response';
+        readonly endingError: 'session-record';
+    };
+    readonly 'factory.session-jsonl': {
+        readonly servedModel: 'turn-context';
+        readonly usage: 'session-total';
+        readonly endingError: 'none';
+    };
+    readonly 'gemini.chat-json': {
+        readonly servedModel: 'session-record';
+        readonly usage: 'per-response';
+        readonly endingError: 'none';
+    };
+    readonly 'amp.thread-json': {
+        readonly servedModel: 'session-record';
+        readonly usage: 'per-response';
+        readonly endingError: 'none';
+    };
+    readonly 'forge.sqlite': {
+        readonly servedModel: 'session-record';
+        readonly usage: 'per-response';
+        readonly endingError: 'none';
+    };
+    readonly 'hermes.state-sqlite': {
+        readonly servedModel: 'session-record';
+        readonly usage: 'session-total';
+        readonly endingError: 'none';
+    };
+    readonly 'prime.session-jsonl': {
+        readonly servedModel: 'session-record';
+        readonly usage: 'per-response';
+        readonly endingError: 'session-record';
+    };
+    readonly 'openclaw.session-jsonl': {
+        readonly servedModel: 'session-record';
+        readonly usage: 'per-response';
+        readonly endingError: 'none';
+    };
+};
+/**
+ * Compile one store glob. `*` matches within a path segment, `**` matches any number of
+ * segments, and `{id}` matches the native session id: the literal id when one is given, any
+ * segment text otherwise (the reader then takes the id from the session's own header).
+ */
+export declare function storeGlob(glob: string, nativeSessionId?: string): RegExp;
+/** A store root must be a normalized path relative to HOME: not absolute, no `.`/`..` segments. */
+export declare function assertStoreRoot(root: string): void;

package/dist/catalog.js

@@ -0,0 +1,163 @@
+export const SESSION_FORMAT_IDS = [
+    'claude-code.projects-jsonl',
+    'codex.rollout-jsonl',
+    'opencode.sqlite',
+    'pi.session-jsonl',
+    'kimi.session-dir',
+    'factory.session-jsonl',
+    'gemini.chat-json',
+    'amp.thread-json',
+    'forge.sqlite',
+    'hermes.state-sqlite',
+    'prime.session-jsonl',
+    'openclaw.session-jsonl',
+];
+/** Store layouts, relative to the HOME a harness ran with. */
+export const STORES = {
+    'claude-code.projects-jsonl': {
+        root: '.claude/projects',
+        files: ['*/{id}.jsonl', '*/{id}/subagents/**/*.jsonl'],
+        write: 'jsonl-append',
+        shared: false,
+        format: 'claude-code.projects-jsonl',
+    },
+    'codex.rollout-jsonl': {
+        root: '.codex/sessions',
+        files: ['*/*/*/rollout-*-{id}.jsonl'],
+        write: 'jsonl-append',
+        shared: false,
+        format: 'codex.rollout-jsonl',
+    },
+    'opencode.sqlite': {
+        root: '.local/share/opencode',
+        files: ['opencode.db', 'opencode.db-wal', 'opencode.db-shm'],
+        write: 'sqlite-wal',
+        shared: true,
+        format: 'opencode.sqlite',
+    },
+    'pi.session-jsonl': {
+        root: '.pi/agent/sessions',
+        files: ['**/*_{id}.jsonl'],
+        write: 'jsonl-append',
+        shared: false,
+        format: 'pi.session-jsonl',
+    },
+    // A session directory: wire.jsonl (the event stream read here), context.jsonl and its rotated
+    // context_N.jsonl copies, and state.json.
+    'kimi.session-dir': {
+        root: '.kimi/sessions',
+        files: ['*/{id}/**', '*/{id}.jsonl'],
+        write: 'jsonl-append',
+        shared: false,
+        format: 'kimi.session-dir',
+    },
+    'factory.session-jsonl': {
+        root: '.factory/sessions',
+        files: ['*/{id}.jsonl', '*/{id}.settings.json'],
+        write: 'jsonl-append',
+        shared: false,
+        format: 'factory.session-jsonl',
+    },
+    'gemini.chat-json': {
+        root: '.gemini/tmp',
+        files: ['*/chats/session-*{id}*.json'],
+        write: 'json-rewrite',
+        shared: false,
+        format: 'gemini.chat-json',
+    },
+    'amp.thread-json': {
+        root: '.local/share/amp/threads',
+        files: ['{id}.json'],
+        write: 'json-rewrite',
+        shared: false,
+        format: 'amp.thread-json',
+    },
+    'forge.sqlite': {
+        root: '.forge',
+        files: ['.forge.db', '.forge.db-wal', '.forge.db-shm'],
+        write: 'sqlite-wal',
+        shared: true,
+        format: 'forge.sqlite',
+    },
+    'hermes.state-sqlite': {
+        root: '.hermes',
+        files: ['state.db', 'state.db-wal', 'state.db-shm'],
+        write: 'sqlite-wal',
+        shared: true,
+        format: 'hermes.state-sqlite',
+    },
+    'prime.session-jsonl': {
+        root: '.prime-provider/prime-agent-dirs',
+        files: ['**/*_{id}.jsonl'],
+        write: 'jsonl-append',
+        shared: false,
+        format: 'prime.session-jsonl',
+    },
+    'openclaw.session-jsonl': {
+        root: '.openclaw/agents',
+        files: ['**/{id}.jsonl'],
+        write: 'jsonl-append',
+        shared: false,
+        format: 'openclaw.session-jsonl',
+    },
+};
+/**
+ * Where each format's served model, usage and ending error come from. `turn-context` means the
+ * model the harness was configured or asked for (Codex `turn_context`, OpenCode's message
+ * `modelID`, Factory's settings); `none` means the session records no model at all.
+ */
+export const EVIDENCE = {
+    'claude-code.projects-jsonl': { servedModel: 'provider-response', usage: 'per-response', endingError: 'session-record' },
+    'codex.rollout-jsonl': { servedModel: 'turn-context', usage: 'cumulative', endingError: 'session-record' },
+    'opencode.sqlite': { servedModel: 'turn-context', usage: 'per-response', endingError: 'session-record' },
+    'pi.session-jsonl': { servedModel: 'session-record', usage: 'per-response', endingError: 'session-record' },
+    'kimi.session-dir': { servedModel: 'none', usage: 'per-response', endingError: 'session-record' },
+    'factory.session-jsonl': { servedModel: 'turn-context', usage: 'session-total', endingError: 'none' },
+    'gemini.chat-json': { servedModel: 'session-record', usage: 'per-response', endingError: 'none' },
+    'amp.thread-json': { servedModel: 'session-record', usage: 'per-response', endingError: 'none' },
+    'forge.sqlite': { servedModel: 'session-record', usage: 'per-response', endingError: 'none' },
+    'hermes.state-sqlite': { servedModel: 'session-record', usage: 'session-total', endingError: 'none' },
+    'prime.session-jsonl': { servedModel: 'session-record', usage: 'per-response', endingError: 'session-record' },
+    'openclaw.session-jsonl': { servedModel: 'session-record', usage: 'per-response', endingError: 'none' },
+};
+const REGEX_SPECIALS = /[.+^$()|[\]\\]/gu;
+/**
+ * Compile one store glob. `*` matches within a path segment, `**` matches any number of
+ * segments, and `{id}` matches the native session id: the literal id when one is given, any
+ * segment text otherwise (the reader then takes the id from the session's own header).
+ */
+export function storeGlob(glob, nativeSessionId) {
+    let pattern = '';
+    for (let i = 0; i < glob.length; i += 1) {
+        const rest = glob.slice(i);
+        if (rest.startsWith('{id}')) {
+            pattern += nativeSessionId === undefined ? '[^/]+' : nativeSessionId.replace(REGEX_SPECIALS, '\\$&').replace(/[*?{}]/gu, '\\$&');
+            i += 3;
+        }
+        else if (rest.startsWith('**/')) {
+            pattern += '(?:[^/]+/)*';
+            i += 2;
+        }
+        else if (rest.startsWith('**')) {
+            pattern += '.*';
+            i += 1;
+        }
+        else if (glob[i] === '*') {
+            pattern += '[^/]*';
+        }
+        else if (glob[i] === '?') {
+            pattern += '[^/]';
+        }
+        else {
+            pattern += glob[i].replace(REGEX_SPECIALS, '\\$&');
+        }
+    }
+    return new RegExp(`^${pattern}$`, 'u');
+}
+/** A store root must be a normalized path relative to HOME: not absolute, no `.`/`..` segments. */
+export function assertStoreRoot(root) {
+    const segments = root.split('/');
+    if (root.startsWith('/') || segments.some((s) => s === '' || s === '.' || s === '..')) {
+        throw new Error(`store root must be a normalized path relative to HOME: ${root}`);
+    }
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+/**
+ * harness-sessions read <file|home|capture> [--harness h] [--session id] [--cwd dir] [--summary] [--json]
+ *
+ * Reads native harness sessions into the normalized form, for callers that are not JavaScript.
+ * A file is one session file (or an OpenCode store); a directory is a capture when it holds
+ * `__retention__/sessions`, otherwise a HOME searched through every reader's store layout.
+ * `--json` prints one JSON document per session, one per line.
+ */
+import { stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { listCapture, RETENTION_SESSIONS } from './capture.js';
+import { claudeCodeRefForFile } from './formats/claude-code.js';
+import { codexRefForFile } from './formats/codex.js';
+import { opencodeSessionsInStore } from './formats/opencode.js';
+import { piRefForFile } from './formats/pi.js';
+import { kimiRefForFile } from './formats/kimi.js';
+import { factoryRefForFile } from './formats/factory.js';
+import { listReaders, readerFor } from './registry.js';
+function usage() {
+    process.stderr.write('usage: harness-sessions read <file|home|capture> [--harness h] [--session id] [--cwd dir] [--summary] [--json]\n');
+    process.exit(2);
+}
+async function isDir(path) {
+    try {
+        return (await stat(path)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function harnessOfFile(path) {
+    if (/\.db$/u.test(path))
+        return 'opencode';
+    if (/(^|\/)\.claude\/projects\//u.test(path))
+        return 'claude-code';
+    if (/(^|\/)\.codex\/sessions\//u.test(path) || /rollout-[^/]*\.jsonl$/u.test(path))
+        return 'codex';
+    if (/(^|\/)\.pi\/agent\/sessions\//u.test(path))
+        return 'pi';
+    if (/(^|\/)\.kimi\/sessions\/.+\/wire\.jsonl$/u.test(path))
+        return 'kimi-code';
+    if (/(^|\/)\.factory\/sessions\//u.test(path))
+        return 'factory-droids';
+    return null;
+}
+async function refsForFile(path, harness, session) {
+    const h = harness ?? harnessOfFile(path);
+    if (h === null)
+        throw new Error(`cannot tell which harness wrote ${path}; pass --harness`);
+    const reader = readerFor(h);
+    if (reader.harness === 'opencode')
+        return opencodeSessionsInStore(path, null, session ? { nativeSessionId: session } : {});
+    const ref = reader.harness === 'claude-code'
+        ? claudeCodeRefForFile(path, /\/subagents\//u.test(path) ? 'parent' : null)
+        : reader.harness === 'codex' ? codexRefForFile(path) : reader.harness === 'kimi-code' ? kimiRefForFile(path) : reader.harness === 'factory-droids' ? factoryRefForFile(path) : piRefForFile(path);
+    return [ref];
+}
+async function main(argv) {
+    const [command, target, ...rest] = argv;
+    if (command !== 'read' || !target)
+        usage();
+    let harness = null;
+    let session = null;
+    let cwd = null;
+    let summary = false;
+    let json = false;
+    for (let i = 0; i < rest.length; i += 1) {
+        const arg = rest[i];
+        if (arg === '--harness')
+            harness = rest[++i] ?? usage();
+        else if (arg === '--session')
+            session = rest[++i] ?? usage();
+        else if (arg === '--cwd')
+            cwd = rest[++i] ?? usage();
+        else if (arg === '--summary')
+            summary = true;
+        else if (arg === '--json')
+            json = true;
+        else
+            usage();
+    }
+    const refs = [];
+    if (await isDir(target)) {
+        if (await isDir(join(target, RETENTION_SESSIONS))) {
+            const listing = await listCapture(target);
+            for (const missing of listing.missing)
+                process.stderr.write(`missing: ${JSON.stringify(missing)}\n`);
+            refs.push(...listing.sessions.map((s) => s.ref).filter((r) => !harness || readerFor(harness).harness === r.harness));
+        }
+        else {
+            const readers = harness ? [readerFor(harness)] : listReaders();
+            for (const reader of readers)
+                refs.push(...(await reader.locate(target, session ? { nativeSessionId: session } : {})));
+        }
+    }
+    else {
+        refs.push(...(await refsForFile(target, harness, session)));
+    }
+    const selected = refs.filter((r) => (!session || r.nativeSessionId === session) && (!cwd || r.cwd === cwd));
+    for (const ref of selected) {
+        const reader = readerFor(ref.harness);
+        const value = summary ? await reader.summarize(ref) : await reader.read(ref);
+        if (json) {
+            process.stdout.write(`${JSON.stringify(value)}\n`);
+            continue;
+        }
+        const s = summary ? value : await reader.summarize(ref);
+        process.stdout.write(`${s.harness}\t${s.nativeSessionId}\tcalls=${s.modelCalls}\treplies=${s.replies}\ttools=${s.toolCalls}\tending=${s.ending.status}\tmodels=${Object.keys(s.servedModels).join(',')}\t${ref.path}\n`);
+    }
+}
+main(process.argv.slice(2)).catch((error) => {
+    process.stderr.write(`harness-sessions: ${error instanceof Error ? error.message : String(error)}\n`);
+    process.exit(1);
+});

package/dist/formats/claude-code.d.ts

@@ -0,0 +1,9 @@
+import { SessionBuilder, type BuildMode } from '../builder.js';
+import type { HarnessSessionReader, ReadOptions, SessionRef } from '../schema.js';
+import { type RecordSource, type SourceStats } from '../source.js';
+import { type SessionFold } from './fold.js';
+export declare function createFold(ref: SessionRef, mode: BuildMode, stats: SourceStats): SessionFold;
+export declare function fold(ref: SessionRef, mode: BuildMode, options: ReadOptions, source?: RecordSource): Promise<SessionBuilder>;
+export declare const claudeCodeReader: HarnessSessionReader;
+/** A reader for one transcript file outside a HOME layout (the CLI, a retained copy). */
+export declare function claudeCodeRefForFile(path: string, parentNativeSessionId?: string | null): SessionRef;