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

package/dist/formats/codex.js

@@ -0,0 +1,379 @@
+/**
+ * Codex: `~/.codex/sessions/YYYY/MM/DD/rollout-<timestamp>-<thread id>.jsonl`, one
+ * `{timestamp, type, payload}` record per line.
+ *
+ * `response_item` records are the conversation (messages, reasoning, tool calls and their
+ * outputs); `event_msg` records are the harness's events (`token_count` after each model response,
+ * `error`, `stream_error`, `turn_aborted`, `task_complete`). Codex records the model it was
+ * configured with in `turn_context`, not the model the provider answered with, so the served
+ * model here has source `turn-context`. Usage is per response (`last_token_usage`) and cumulative
+ * (`total_token_usage`); the cumulative counter is the session total.
+ */
+import { basename } from 'node:path';
+import { SessionBuilder, argumentsOf, count, isRecord, sessionError, str, textOf, usageOrNull, } from '../builder.js';
+import { fileRecords } from '../source.js';
+import { runFold } from './fold.js';
+import { EVIDENCE, STORES, mtimeMs, storeGlob, walkFiles } from '../stores.js';
+import { headRecord } from './head.js';
+import { join } from 'node:path';
+const FORMAT = 'codex.rollout-jsonl';
+const STORE = STORES[FORMAT];
+const HARNESS = 'codex';
+const ID_IN_NAME = /([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\.jsonl$/u;
+/** Codex counts cached tokens inside `input_tokens`; the normalized input excludes them. */
+function usageOf(value) {
+    if (!isRecord(value))
+        return null;
+    const input = count(value.input_tokens);
+    const cached = count(value.cached_input_tokens);
+    return usageOrNull({
+        input: input === null ? null : Math.max(0, input - (cached ?? 0)),
+        output: count(value.output_tokens),
+        reasoning: count(value.reasoning_output_tokens),
+        cacheRead: cached,
+        cacheWrite: count(value.cache_write_input_tokens),
+    });
+}
+function signature(value) {
+    return isRecord(value)
+        ? ['input_tokens', 'cached_input_tokens', 'output_tokens', 'reasoning_output_tokens', 'total_tokens'].map((k) => String(value[k] ?? '')).join(',')
+        : '';
+}
+function addTotals(a, b) {
+    if (a === null)
+        return b;
+    if (b === null)
+        return a;
+    const sum = (x, y) => (x === null && y === null ? null : (x ?? 0) + (y ?? 0));
+    return { input: sum(a.input, b.input), output: sum(a.output, b.output), reasoning: sum(a.reasoning, b.reasoning), cacheRead: sum(a.cacheRead, b.cacheRead), cacheWrite: sum(a.cacheWrite, b.cacheWrite) };
+}
+// Text the harness puts in a user-role message: environment context, instructions, shell output.
+const INJECTED_USER_TEXT = /^\s*(?:<[a-z_]+(?:\s[^>]*)?>|# AGENTS\.md instructions)/u;
+function contentParts(content) {
+    const parts = [];
+    if (!Array.isArray(content))
+        return parts;
+    for (const item of content) {
+        if (!isRecord(item))
+            continue;
+        if ((item.type === 'input_text' || item.type === 'output_text' || item.type === 'text') && typeof item.text === 'string') {
+            parts.push({ type: 'text', text: item.text });
+        }
+        else if (item.type === 'input_image') {
+            parts.push({ type: 'attachment', mediaType: 'image', ref: typeof item.image_url === 'string' && !item.image_url.startsWith('data:') ? item.image_url : 'inline' });
+        }
+    }
+    return parts;
+}
+function outputOf(output) {
+    if (typeof output === 'string')
+        return { output, text: output, isError: false };
+    if (isRecord(output)) {
+        const content = output.content ?? output.output;
+        return { output, text: textOf(content) ?? (typeof content === 'string' ? content : null), isError: output.success === false };
+    }
+    return { output: output ?? null, text: textOf(output), isError: false };
+}
+const MODEL_OUTPUT = new Set(['message', 'reasoning']);
+export function createFold(ref, mode, stats) {
+    const builder = new SessionBuilder(HARNESS, FORMAT, EVIDENCE[FORMAT].servedModel, mode, ref.nativeSessionId, ref.parentNativeSessionId);
+    let provider = null;
+    let model = null;
+    let open = null;
+    let openMessage = null;
+    let calls = 0;
+    let lastTotalSignature = '';
+    let lastTotal = null;
+    let lastTotalRaw = null;
+    let committedTotal = null;
+    let aborted = null;
+    let sawMeta = false;
+    let compacted = 0;
+    // A forked rollout replays the parent's history after the parent's own session_meta; that
+    // history is copied context, not this session's turns. It ends at this session's first turn,
+    // whose (time-ordered, UUIDv7) turn id sorts at or after the session id.
+    let forked = false;
+    let inherited = false;
+    let inheritedRecords = 0;
+    const foreignThreads = new Set();
+    const openCall = (at) => {
+        if (open)
+            return open;
+        calls += 1;
+        open = builder.modelCall({ id: `${builder.nativeSessionId}:response:${calls}`, at, provider, servedModel: model, requestedModel: model, usage: null, costUsd: null, stopReason: null, error: null });
+        openMessage = null;
+        return open;
+    };
+    const assistantMessage = (at, call, parts) => {
+        if (openMessage === null) {
+            openMessage = `${call.id}:message`;
+            builder.message({ id: openMessage, role: 'assistant', actor: 'agent', at, modelCallId: call.id, parts });
+        }
+        else {
+            builder.appendParts(openMessage, parts);
+        }
+    };
+    const observe = (record) => {
+        const payload = isRecord(record.payload) ? record.payload : {};
+        if (inherited) {
+            const turnId = str(payload.turn_id);
+            if (record.type === 'event_msg' && payload.type === 'task_started' && turnId !== null && turnId >= builder.nativeSessionId) {
+                inherited = false;
+            }
+            else {
+                inheritedRecords += 1;
+                if (record.type === 'response_item' && payload.type === 'message') {
+                    const role = str(payload.role);
+                    builder.message({ id: str(payload.id) ?? `${builder.nativeSessionId}:inherited:${inheritedRecords}`, role: role === 'assistant' ? 'assistant' : role === 'user' ? 'user' : 'system', actor: 'injected', at: null, modelCallId: null, parts: contentParts(payload.content) });
+                }
+                return;
+            }
+        }
+        const at = builder.seen(record.timestamp);
+        switch (record.type) {
+            case 'session_meta': {
+                if (sawMeta) {
+                    if (forked)
+                        inherited = true;
+                    break;
+                }
+                sawMeta = true;
+                const id = str(payload.id);
+                if (id && id !== builder.nativeSessionId)
+                    builder.nativeSessionId = id;
+                builder.cwd = str(payload.cwd);
+                provider = str(payload.model_provider);
+                forked = typeof payload.forked_from_id === 'string';
+                const source = isRecord(payload.source) ? payload.source : {};
+                const spawn = isRecord(source.subagent) && isRecord(source.subagent.thread_spawn) ? source.subagent.thread_spawn : {};
+                const parent = str(payload.parent_thread_id) ?? str(spawn.parent_thread_id) ?? str(payload.forked_from_id);
+                if (parent)
+                    builder.parentNativeSessionId = parent;
+                break;
+            }
+            case 'turn_context': {
+                model = str(payload.model) ?? model;
+                break;
+            }
+            case 'compacted': {
+                compacted += 1;
+                break;
+            }
+            case 'response_item': {
+                const kind = str(payload.type) ?? '';
+                if (kind === 'agent_message') {
+                    // A message from another agent of the same run (a task or a reply); input to this thread.
+                    open = null;
+                    builder.message({ id: str(payload.id) ?? `${builder.nativeSessionId}:${stats.line}`, role: 'user', actor: 'subagent-spawn', at, modelCallId: null, parts: contentParts(payload.content) });
+                }
+                else if (kind === 'message') {
+                    const role = str(payload.role);
+                    const parts = contentParts(payload.content);
+                    if (role === 'assistant') {
+                        assistantMessage(at, openCall(at), parts);
+                    }
+                    else if (role === 'user') {
+                        open = null;
+                        const text = parts.find((p) => p.type === 'text');
+                        const injected = text?.type === 'text' && INJECTED_USER_TEXT.test(text.text);
+                        builder.message({ id: str(payload.id) ?? `${builder.nativeSessionId}:${stats.line}`, role: 'user', actor: injected ? 'injected' : ref.parentNativeSessionId || builder.parentNativeSessionId ? 'subagent-spawn' : 'human', at, modelCallId: null, parts });
+                    }
+                    else {
+                        builder.message({ id: str(payload.id) ?? `${builder.nativeSessionId}:${stats.line}`, role: 'system', actor: 'injected', at, modelCallId: null, parts });
+                    }
+                }
+                else if (kind === 'reasoning') {
+                    const summary = Array.isArray(payload.summary) ? payload.summary : [];
+                    const text = summary.map((s) => (isRecord(s) && typeof s.text === 'string' ? s.text : '')).filter(Boolean).join('\n');
+                    const content = textOf(payload.content);
+                    const visible = content ?? text;
+                    assistantMessage(at, openCall(at), [{ type: 'reasoning', text: visible, redacted: visible.length === 0 && payload.encrypted_content != null }]);
+                }
+                else if (kind.endsWith('_call') && !MODEL_OUTPUT.has(kind)) {
+                    const callId = str(payload.call_id) ?? str(payload.id) ?? `${builder.nativeSessionId}:call:${stats.line}`;
+                    const name = str(payload.name) ?? kind.replace(/_call$/u, '');
+                    const raw = kind === 'function_call' ? payload.arguments : kind === 'custom_tool_call' ? payload.input : (payload.action ?? payload.arguments ?? payload.input);
+                    const call = openCall(at);
+                    assistantMessage(at, call, [{ type: 'tool-call', toolCallId: callId }]);
+                    builder.toolCall({ id: callId, name, ...argumentsOf(raw), at, messageId: openMessage });
+                    // A web search is answered inside the response; there is no output item.
+                    if (kind === 'web_search_call')
+                        builder.toolResult(callId, { output: payload.action ?? null, text: null, isError: payload.status === 'failed', at, messageId: openMessage });
+                }
+                else if (kind.endsWith('_call_output')) {
+                    const callId = str(payload.call_id) ?? '';
+                    const result = outputOf(payload.output);
+                    const id = `${callId}:output`;
+                    builder.message({ id, role: 'tool', actor: 'tool-result', at, modelCallId: null, parts: [{ type: 'tool-result', toolCallId: callId }] });
+                    builder.toolResult(callId, { ...result, at, messageId: id });
+                }
+                break;
+            }
+            case 'event_msg': {
+                const kind = str(payload.type);
+                if (kind === 'item_completed') {
+                    // Items of this thread repeat its response items. Items of another thread are a child
+                    // thread's activity (a review or a sub-agent) logged in this rollout; that thread is its
+                    // own session.
+                    const thread = str(payload.thread_id);
+                    if (thread && thread !== builder.nativeSessionId && !foreignThreads.has(thread)) {
+                        foreignThreads.add(thread);
+                        builder.child(thread, null);
+                    }
+                }
+                else if (kind === 'token_count') {
+                    const info = isRecord(payload.info) ? payload.info : null;
+                    if (info === null)
+                        break;
+                    const totalSignature = signature(info.total_token_usage);
+                    // Codex repeats a token_count without a new response (rate-limit refreshes); a
+                    // response is counted once, when the cumulative counter moves.
+                    if (totalSignature !== '' && totalSignature === lastTotalSignature)
+                        break;
+                    if (isRecord(info.total_token_usage)) {
+                        const raw = info.total_token_usage;
+                        // A resumed process restarts the counter; bank what the previous process reported.
+                        if (lastTotalRaw && count(raw.total_tokens) !== null && count(lastTotalRaw.total_tokens) !== null && raw.total_tokens < lastTotalRaw.total_tokens) {
+                            committedTotal = addTotals(committedTotal, lastTotal);
+                        }
+                        lastTotalRaw = raw;
+                        lastTotal = usageOf(raw);
+                        lastTotalSignature = totalSignature;
+                    }
+                    const usage = usageOf(info.last_token_usage);
+                    if (usage === null)
+                        break;
+                    const call = openCall(at);
+                    call.usage = usage;
+                    open = null;
+                }
+                else if (kind === 'error') {
+                    const message = str(payload.message) ?? 'error';
+                    const call = openCall(at);
+                    call.error = sessionError('error', message, at, httpStatusOf(payload));
+                    open = null;
+                }
+                else if (kind === 'stream_error') {
+                    // A dropped stream that Codex retries. It is a model request that returned no answer.
+                    calls += 1;
+                    builder.modelCall({ id: `${builder.nativeSessionId}:response:${calls}`, at, provider, servedModel: model, requestedModel: model, usage: null, costUsd: null, stopReason: null, error: sessionError('stream_error', str(payload.message) ?? 'stream error', at, httpStatusOf(payload)) });
+                }
+                else if (kind === 'turn_aborted') {
+                    aborted = { at, reason: str(payload.reason) ?? 'aborted' };
+                    open = null;
+                }
+                else if (kind === 'task_started') {
+                    aborted = null;
+                    open = null;
+                }
+                else if (kind === 'task_complete') {
+                    aborted = null;
+                    open = null;
+                    // Codex 0.145 records a turn that ended on a failed request only here: the request that
+                    // failed returned no answer, so it is a model call with that error and no served model.
+                    if (isRecord(payload.error)) {
+                        const failure = payload.error;
+                        calls += 1;
+                        builder.modelCall({ id: `${builder.nativeSessionId}:response:${calls}`, at, provider, servedModel: null, requestedModel: model, usage: null, costUsd: null, stopReason: null, error: sessionError(str(failure.codex_error_info) ?? 'error', str(failure.message) ?? 'error', at, httpStatusOf(failure)) });
+                    }
+                }
+                break;
+            }
+            default:
+                break;
+        }
+    };
+    const finish = () => {
+        builder.source(stats);
+        if (compacted > 0)
+            builder.gap(`${compacted} compaction records replaced earlier context`);
+        if (inheritedRecords > 0)
+            builder.gap(`${inheritedRecords} records replay the history of the session this one was forked from`);
+        if (foreignThreads.size > 0)
+            builder.gap(`${foreignThreads.size} child threads logged their items in this rollout; they are not read as this session`);
+        const total = addTotals(committedTotal, lastTotal);
+        if (total !== null)
+            builder.setSessionUsage(total);
+        const last = builder.modelCalls[builder.modelCalls.length - 1];
+        builder.inferEnding(aborted && !last?.error ? { at: aborted.at, error: sessionError('turn_aborted', aborted.reason, aborted.at, null) } : undefined);
+        return builder;
+    };
+    return { builder, observe, finish };
+}
+export async function fold(ref, mode, options, source = fileRecords(ref.path, { strict: options.corruption === 'strict', signal: options.signal })) {
+    return runFold(createFold(ref, mode, source.stats), source);
+}
+function httpStatusOf(payload) {
+    const info = payload.codex_error_info;
+    if (isRecord(info)) {
+        for (const value of Object.values(info)) {
+            if (isRecord(value)) {
+                const status = count(value.http_status_code);
+                if (status !== null)
+                    return status;
+            }
+        }
+    }
+    return null;
+}
+async function locate(home, opts) {
+    const root = join(home, STORE.root);
+    const pattern = storeGlob(STORE.files[0], opts.nativeSessionId);
+    const refs = [];
+    for (const rel of await walkFiles(root)) {
+        if (!pattern.test(rel))
+            continue;
+        const path = join(root, rel);
+        const mtime = await mtimeMs(path);
+        if (opts.sinceMs && mtime < opts.sinceMs)
+            continue;
+        const meta = await headRecord(path, (r) => r.type === 'session_meta', 4);
+        const payload = meta && isRecord(meta.payload) ? meta.payload : {};
+        const cwd = str(payload.cwd);
+        if (opts.cwd && (cwd === null || !cwd.startsWith(opts.cwd)))
+            continue;
+        const id = str(payload.id) ?? ID_IN_NAME.exec(rel)?.[1] ?? basename(rel, '.jsonl');
+        const source = isRecord(payload.source) ? payload.source : {};
+        const spawn = isRecord(source.subagent) && isRecord(source.subagent.thread_spawn) ? source.subagent.thread_spawn : {};
+        refs.push({
+            harness: HARNESS,
+            format: FORMAT,
+            nativeSessionId: id,
+            path,
+            files: [path],
+            home,
+            cwd,
+            mtimeMs: mtime,
+            parentNativeSessionId: str(payload.parent_thread_id) ?? str(spawn.parent_thread_id),
+        });
+    }
+    return refs.sort((a, b) => b.mtimeMs - a.mtimeMs);
+}
+export const codexReader = {
+    harness: HARNESS,
+    aliases: ['codex-acp', 'codex-cli'],
+    formats: [FORMAT],
+    stores: [STORE],
+    globs: { session: STORE.files[0] },
+    evidence: EVIDENCE[FORMAT],
+    locate: (home, opts = {}) => locate(home, opts),
+    async read(ref, opts = {}) {
+        return (await fold(ref, 'full', opts)).build();
+    },
+    async summarize(ref, opts = {}) {
+        return (await fold(ref, 'summary', opts)).summary();
+    },
+};
+export function codexRefForFile(path) {
+    return {
+        harness: HARNESS,
+        format: FORMAT,
+        nativeSessionId: ID_IN_NAME.exec(path)?.[1] ?? basename(path, '.jsonl'),
+        path,
+        files: [path],
+        home: null,
+        cwd: null,
+        mtimeMs: 0,
+        parentNativeSessionId: null,
+    };
+}

package/dist/formats/factory.d.ts

@@ -0,0 +1,13 @@
+import { SessionBuilder, type BuildMode } from '../builder.js';
+import type { HarnessSessionReader, ReadOptions, SessionRef, TokenUsage } from '../schema.js';
+import { type RecordSource, type SourceStats } from '../source.js';
+import { type SessionFold } from './fold.js';
+interface FactorySettings {
+    model: string | null;
+    usage: TokenUsage | null;
+}
+export declare function createFold(ref: SessionRef, mode: BuildMode, stats: SourceStats, settings?: FactorySettings): SessionFold;
+export declare function fold(ref: SessionRef, mode: BuildMode, options: ReadOptions, source?: RecordSource): Promise<SessionBuilder>;
+export declare const factoryReader: HarnessSessionReader;
+export declare function factoryRefForFile(path: string): SessionRef;
+export {};

package/dist/formats/factory.js

@@ -0,0 +1,155 @@
+/**
+ * Factory Droid: `~/.factory/sessions/<encoded cwd>/<session id>.jsonl` plus a
+ * `<session id>.settings.json` beside it.
+ *
+ * The JSONL holds a `session_start` line (id, cwd) and `message` lines whose `message.content[]`
+ * carries Anthropic-style blocks (`text`, `thinking`, `tool_use`, `tool_result`). Each assistant
+ * line is one model response. The transcript records no model and no per-response usage: the
+ * settings file holds the configured model and the session's token totals, so the model here has
+ * source `turn-context` (configured, not served) and usage is the session total.
+ */
+import { readFile } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+import { SessionBuilder, count, isRecord, str, textOf, usageOrNull } from '../builder.js';
+import { fileRecords, isMissing } from '../source.js';
+import { EVIDENCE, STORES, mtimeMs, storeGlob, walkFiles } from '../stores.js';
+import { runFold } from './fold.js';
+import { headRecord } from './head.js';
+const FORMAT = 'factory.session-jsonl';
+const STORE = STORES[FORMAT];
+const HARNESS = 'factory-droids';
+function settingsOf(value) {
+    if (!isRecord(value))
+        return { model: null, usage: null };
+    const tokens = isRecord(value.tokenUsage) ? value.tokenUsage : null;
+    return {
+        model: str(value.model),
+        usage: tokens === null ? null : usageOrNull({
+            input: count(tokens.inputTokens),
+            output: count(tokens.outputTokens),
+            reasoning: count(tokens.thinkingTokens),
+            cacheRead: count(tokens.cacheReadTokens),
+            cacheWrite: count(tokens.cacheCreationTokens),
+        }),
+    };
+}
+const INJECTED = /^\s*(?:<system-reminder>|<[a-z-]+>)/u;
+export function createFold(ref, mode, stats, settings = { model: null, usage: null }) {
+    const builder = new SessionBuilder(HARNESS, FORMAT, EVIDENCE[FORMAT].servedModel, mode, ref.nativeSessionId, ref.parentNativeSessionId);
+    const observe = (record) => {
+        if (record.type === 'session_start') {
+            if (typeof record.id === 'string')
+                builder.nativeSessionId = record.id;
+            builder.cwd = str(record.cwd);
+            return;
+        }
+        if (record.type !== 'message' || !isRecord(record.message))
+            return;
+        const at = builder.seen(record.timestamp);
+        const id = str(record.id) ?? `${builder.nativeSessionId}:${stats.line}`;
+        const message = record.message;
+        const content = Array.isArray(message.content) ? message.content.filter(isRecord) : [];
+        if (message.role === 'assistant') {
+            const parts = [];
+            builder.modelCall({ id, at, provider: null, servedModel: settings.model, requestedModel: settings.model, usage: null, costUsd: null, stopReason: null, error: null });
+            for (const block of content) {
+                if (block.type === 'text' && typeof block.text === 'string')
+                    parts.push({ type: 'text', text: block.text });
+                else if (block.type === 'thinking')
+                    parts.push({ type: 'reasoning', text: str(block.thinking) ?? '', redacted: !block.thinking });
+                else if (block.type === 'tool_use' && typeof block.id === 'string') {
+                    parts.push({ type: 'tool-call', toolCallId: block.id });
+                    builder.toolCall({ id: block.id, name: str(block.name) ?? 'unknown', input: block.input ?? null, inputText: null, at, messageId: id });
+                }
+            }
+            builder.message({ id, role: 'assistant', actor: 'agent', at, modelCallId: id, parts });
+            return;
+        }
+        const toolParts = [];
+        const textParts = [];
+        for (const block of content) {
+            if (block.type === 'tool_result' && typeof block.tool_use_id === 'string') {
+                toolParts.push({ type: 'tool-result', toolCallId: block.tool_use_id });
+                builder.toolResult(block.tool_use_id, { output: block.content ?? null, text: textOf(block.content), isError: block.is_error === true, at, messageId: `${id}:tool` });
+            }
+            else if (block.type === 'text' && typeof block.text === 'string') {
+                textParts.push({ type: 'text', text: block.text });
+            }
+        }
+        if (toolParts.length > 0)
+            builder.message({ id: `${id}:tool`, role: 'tool', actor: 'tool-result', at, modelCallId: null, parts: toolParts });
+        if (textParts.length > 0) {
+            const first = textParts[0];
+            const injected = id.startsWith('context-') || (first?.type === 'text' && INJECTED.test(first.text));
+            builder.message({ id, role: 'user', actor: injected ? 'injected' : ref.parentNativeSessionId ? 'subagent-spawn' : 'human', at, modelCallId: null, parts: textParts });
+        }
+    };
+    const finish = () => {
+        builder.source(stats);
+        // Factory records only the session's token totals, in its settings file.
+        if (settings.usage !== null)
+            builder.setSessionUsage(settings.usage);
+        builder.inferEnding();
+        return builder;
+    };
+    return { builder, observe, finish };
+}
+async function readSettings(path) {
+    try {
+        return settingsOf(JSON.parse(await readFile(path.replace(/\.jsonl$/u, '.settings.json'), 'utf8')));
+    }
+    catch (error) {
+        if (isMissing(error) || error instanceof SyntaxError)
+            return { model: null, usage: null };
+        throw error;
+    }
+}
+export async function fold(ref, mode, options, source = fileRecords(ref.path, { strict: options.corruption === 'strict', signal: options.signal })) {
+    return runFold(createFold(ref, mode, source.stats, await readSettings(ref.path)), source);
+}
+async function locate(home, opts) {
+    const root = join(home, STORE.root);
+    const pattern = storeGlob(STORE.files[0], opts.nativeSessionId);
+    const refs = [];
+    for (const rel of await walkFiles(root)) {
+        if (!pattern.test(rel))
+            continue;
+        const path = join(root, rel);
+        const mtime = await mtimeMs(path);
+        if (opts.sinceMs && mtime < opts.sinceMs)
+            continue;
+        const settings = path.replace(/\.jsonl$/u, '.settings.json');
+        refs.push({ harness: HARNESS, format: FORMAT, nativeSessionId: basename(path, '.jsonl'), path, files: (await mtimeMs(settings)) > 0 ? [path, settings] : [path], home, cwd: null, mtimeMs: mtime, parentNativeSessionId: null });
+    }
+    const filtered = [];
+    for (const ref of refs) {
+        if (opts.cwd) {
+            // The directory name encodes the cwd with `/` as `-`; the session_start line holds it exactly.
+            const head = await headRecord(ref.path, (r) => r.type === 'session_start', 1);
+            const cwd = head ? str(head.cwd) : null;
+            ref.cwd = cwd;
+            if (!cwd || !cwd.startsWith(opts.cwd))
+                continue;
+        }
+        filtered.push(ref);
+    }
+    return filtered.sort((a, b) => b.mtimeMs - a.mtimeMs);
+}
+export const factoryReader = {
+    harness: HARNESS,
+    aliases: ['factory', 'droid'],
+    formats: [FORMAT],
+    stores: [STORE],
+    globs: { session: STORE.files[0] },
+    evidence: EVIDENCE[FORMAT],
+    locate: (home, opts = {}) => locate(home, opts),
+    async read(ref, opts = {}) {
+        return (await fold(ref, 'full', opts)).build();
+    },
+    async summarize(ref, opts = {}) {
+        return (await fold(ref, 'summary', opts)).summary();
+    },
+};
+export function factoryRefForFile(path) {
+    return { harness: HARNESS, format: FORMAT, nativeSessionId: basename(path, '.jsonl'), path, files: [path], home: null, cwd: null, mtimeMs: 0, parentNativeSessionId: null };
+}

package/dist/formats/fold.d.ts

@@ -0,0 +1,13 @@
+import type { SessionBuilder } from '../builder.js';
+import type { RecordSource } from '../source.js';
+/**
+ * One format's fold, driven by whoever has the records: `observe` takes each record in order and
+ * `finish` closes the session. Reading a file drives it asynchronously; text or parsed records in
+ * memory drive it synchronously. Either way it is the same fold.
+ */
+export interface SessionFold {
+    builder: SessionBuilder;
+    observe(record: Record<string, unknown>): void;
+    finish(): SessionBuilder;
+}
+export declare function runFold(fold: SessionFold, source: RecordSource): Promise<SessionBuilder>;

package/dist/formats/fold.js

@@ -0,0 +1,5 @@
+export async function runFold(fold, source) {
+    for await (const record of source.records)
+        fold.observe(record);
+    return fold.finish();
+}

package/dist/formats/head.d.ts

@@ -0,0 +1,5 @@
+/**
+ * The first record among a session file's first `limit` records that satisfies `match`, read
+ * without consuming the rest of the file. Used to learn a session's id and cwd while locating.
+ */
+export declare function headRecord(path: string, match: (record: Record<string, unknown>) => boolean, limit?: number): Promise<Record<string, unknown> | null>;

package/dist/formats/head.js

@@ -0,0 +1,23 @@
+import { newSourceStats, readJsonlRecords } from '../source.js';
+/**
+ * The first record among a session file's first `limit` records that satisfies `match`, read
+ * without consuming the rest of the file. Used to learn a session's id and cwd while locating.
+ */
+export async function headRecord(path, match, limit = 64) {
+    let seen = 0;
+    try {
+        for await (const record of readJsonlRecords(path, newSourceStats(path))) {
+            if (match(record))
+                return record;
+            seen += 1;
+            if (seen >= limit)
+                return null;
+        }
+    }
+    catch (error) {
+        if (error?.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+    return null;
+}

package/dist/formats/kimi.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 kimiReader: HarnessSessionReader;
+/** A session read from its `wire.jsonl` outside a HOME layout. */
+export declare function kimiRefForFile(path: string): SessionRef;