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

package/dist/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * `@tangle-network/harness-sessions` — one reader for every coding-agent harness's native session.
+ *
+ * Every harness persists its session in its own store (Claude Code and Pi append JSONL, Codex
+ * appends a rollout, OpenCode writes SQLite). This package declares each store's layout once and
+ * parses each format into one normalized {@link HarnessSession}: messages, tool calls with their
+ * inputs and results, the model calls with the model that served them, usage and the error a
+ * session ended with. The sidecar's capture contract, the Discovery gate, agent-eval,
+ * agent-record and the blog read sessions only through it.
+ */
+export type { HarnessSession, HarnessSessionReader, LocateOptions, ModelCall, NativeSessionCopy, NativeSessionStore, Part, RawEvidenceArchiveManifestV2, ReadOptions, SessionEnding, SessionError, SessionEvidenceSources, SessionFormatId, SessionIntegrity, SessionMessage, SessionRef, SessionSummary, SessionToolCall, TokenUsage, } from './schema.js';
+export { HARNESS_SESSION_SCHEMA } from './schema.js';
+export { EVIDENCE, SESSION_FORMAT_IDS, STORES, assertStoreRoot, storeGlob } from './catalog.js';
+export { knownHarnesses, listReaders, maybeReaderFor, readerFor, readerForFormat } from './registry.js';
+export { claudeCodeReader, claudeCodeRefForFile } from './formats/claude-code.js';
+export { codexReader, codexRefForFile } from './formats/codex.js';
+export { opencodeReader, opencodeSessionsInStore } from './formats/opencode.js';
+export { piReader, piRefForFile } from './formats/pi.js';
+export { kimiReader, kimiRefForFile } from './formats/kimi.js';
+export { factoryReader, factoryRefForFile } from './formats/factory.js';
+export { listCapture, readCapture, RETENTION_MANIFEST_KIND, RETENTION_SESSIONS, type CaptureListing, type CapturedSessionRef, } from './capture.js';
+export { SessionParseError } from './source.js';
+export { servedModelKey } from './builder.js';
+export { toChatMessages, type ChatMessage, type ChatProjectionOptions, type ChatToolCall } from './projections/chat.js';
+export { primaryModel, summarizeText, toTurns, type Turn, type TurnOptions, type TurnToolCall } from './projections/turns.js';
+export { toOtlpSpans, type OtlpProjectionOptions } from './projections/otlp.js';
+export { readSessionInput, summarizeSessionInput, type SessionInput, type SessionInputInit } from './input.js';

package/dist/index.js

@@ -0,0 +1,16 @@
+export { HARNESS_SESSION_SCHEMA } from './schema.js';
+export { EVIDENCE, SESSION_FORMAT_IDS, STORES, assertStoreRoot, storeGlob } from './catalog.js';
+export { knownHarnesses, listReaders, maybeReaderFor, readerFor, readerForFormat } from './registry.js';
+export { claudeCodeReader, claudeCodeRefForFile } from './formats/claude-code.js';
+export { codexReader, codexRefForFile } from './formats/codex.js';
+export { opencodeReader, opencodeSessionsInStore } from './formats/opencode.js';
+export { piReader, piRefForFile } from './formats/pi.js';
+export { kimiReader, kimiRefForFile } from './formats/kimi.js';
+export { factoryReader, factoryRefForFile } from './formats/factory.js';
+export { listCapture, readCapture, RETENTION_MANIFEST_KIND, RETENTION_SESSIONS, } from './capture.js';
+export { SessionParseError } from './source.js';
+export { servedModelKey } from './builder.js';
+export { toChatMessages } from './projections/chat.js';
+export { primaryModel, summarizeText, toTurns } from './projections/turns.js';
+export { toOtlpSpans } from './projections/otlp.js';
+export { readSessionInput, summarizeSessionInput } from './input.js';

package/dist/input.d.ts

@@ -0,0 +1,18 @@
+import type { HarnessSession, ReadOptions, SessionSummary } from './schema.js';
+export type SessionInput = {
+    text: string;
+} | {
+    records: readonly unknown[];
+};
+export interface SessionInputInit {
+    /** The native session id when the caller knows it; JSONL formats also read it from their records. */
+    nativeSessionId?: string;
+    /** Set for a subagent's own transcript; its records are the subagent's, not sidechain noise. */
+    parentNativeSessionId?: string | null;
+    /** Names the source in integrity records (a path, a blob ref). */
+    label?: string;
+}
+/** Read a JSONL-format session (Claude Code, Codex, Pi, Kimi) from text or parsed records, synchronously. */
+export declare function readSessionInput(harness: string, input: SessionInput, init?: SessionInputInit, options?: Pick<ReadOptions, 'corruption'>): HarnessSession;
+/** Summarize a JSONL-format session from text or parsed records, synchronously. */
+export declare function summarizeSessionInput(harness: string, input: SessionInput, init?: SessionInputInit, options?: Pick<ReadOptions, 'corruption'>): SessionSummary;

package/dist/input.js

@@ -0,0 +1,46 @@
+import { createFold as claudeCodeFold } from './formats/claude-code.js';
+import { createFold as codexFold } from './formats/codex.js';
+import { createFold as kimiFold } from './formats/kimi.js';
+import { createFold as factoryFold } from './formats/factory.js';
+import { createFold as piFold } from './formats/pi.js';
+import { readerFor } from './registry.js';
+import { arrayRecordsSync, memoryStats, textRecordsSync } from './source.js';
+const FOLDS = {
+    'claude-code': claudeCodeFold,
+    codex: codexFold,
+    pi: piFold,
+    'kimi-code': kimiFold,
+    'factory-droids': (ref, mode, stats) => factoryFold(ref, mode, stats),
+};
+function foldInput(harness, input, init, mode, options) {
+    const reader = readerFor(harness);
+    const create = FOLDS[reader.harness];
+    if (!create)
+        throw new Error(`${reader.harness} sessions are a store, not a record stream; read them with readerFor('${reader.harness}').read`);
+    const label = init.label ?? `${reader.harness}:${init.nativeSessionId ?? 'input'}`;
+    const stats = memoryStats(label, 'text' in input ? input.text : undefined);
+    const ref = {
+        harness: reader.harness,
+        format: reader.formats[0],
+        nativeSessionId: init.nativeSessionId ?? label,
+        path: label,
+        files: [],
+        home: null,
+        cwd: null,
+        mtimeMs: 0,
+        parentNativeSessionId: init.parentNativeSessionId ?? null,
+    };
+    const fold = create(ref, mode, stats);
+    const records = 'text' in input ? textRecordsSync(input.text, stats, { strict: options.corruption === 'strict' }) : arrayRecordsSync(input.records, stats);
+    for (const record of records)
+        fold.observe(record);
+    return fold.finish();
+}
+/** Read a JSONL-format session (Claude Code, Codex, Pi, Kimi) from text or parsed records, synchronously. */
+export function readSessionInput(harness, input, init = {}, options = {}) {
+    return foldInput(harness, input, init, 'full', options).build();
+}
+/** Summarize a JSONL-format session from text or parsed records, synchronously. */
+export function summarizeSessionInput(harness, input, init = {}, options = {}) {
+    return foldInput(harness, input, init, 'summary', options).summary();
+}

package/dist/projections/chat.d.ts

@@ -0,0 +1,31 @@
+import type { HarnessSession } from '../schema.js';
+/** agent-eval's chat-with-tools message (`src/rollout/schema.ts`), declared here structurally. */
+export interface ChatToolCall {
+    id: string;
+    type: 'function';
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+export interface ChatMessage {
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    content: string | null;
+    reasoning_content?: string;
+    tool_calls?: ChatToolCall[];
+    tool_call_id?: string;
+    name?: string;
+    is_copied_context?: boolean;
+}
+export interface ChatProjectionOptions {
+    /** Keep messages the harness injected (environment context, instructions). Default true. */
+    injected?: boolean;
+    /** Keep `system` messages. Default true. */
+    system?: boolean;
+}
+/**
+ * The session as chat-with-tools messages: each assistant message carries its text, reasoning
+ * and tool calls; each tool result is a `tool` message answering its call. Content is complete;
+ * a projection that needs less trims it itself.
+ */
+export declare function toChatMessages(session: HarnessSession, options?: ChatProjectionOptions): ChatMessage[];

package/dist/projections/chat.js

@@ -0,0 +1,79 @@
+function texts(message, type) {
+    return message.parts
+        .filter((p) => p.type === type)
+        .map((p) => p.text)
+        .filter((t) => t.length > 0)
+        .join('\n');
+}
+function resultContent(output, text) {
+    if (text !== null)
+        return text;
+    if (typeof output === 'string')
+        return output;
+    if (output === null || output === undefined)
+        return '';
+    return JSON.stringify(output);
+}
+/**
+ * The session as chat-with-tools messages: each assistant message carries its text, reasoning
+ * and tool calls; each tool result is a `tool` message answering its call. Content is complete;
+ * a projection that needs less trims it itself.
+ */
+export function toChatMessages(session, options = {}) {
+    const keepInjected = options.injected !== false;
+    const keepSystem = options.system !== false;
+    const calls = new Map(session.toolCalls.map((c) => [c.id, c]));
+    const out = [];
+    for (const message of session.messages) {
+        if (message.actor === 'injected' && !keepInjected)
+            continue;
+        if (message.role === 'system') {
+            if (keepSystem)
+                out.push({ role: 'system', content: texts(message, 'text') });
+            continue;
+        }
+        if (message.role === 'user') {
+            const content = texts(message, 'text');
+            if (content.length === 0 && !message.parts.some((p) => p.type === 'attachment'))
+                continue;
+            out.push({ role: 'user', content });
+            continue;
+        }
+        if (message.role === 'tool') {
+            for (const part of message.parts) {
+                if (part.type !== 'tool-result')
+                    continue;
+                const call = calls.get(part.toolCallId);
+                out.push({
+                    role: 'tool',
+                    tool_call_id: part.toolCallId,
+                    ...(call ? { name: call.name } : {}),
+                    content: resultContent(call?.result?.output, call?.result?.text ?? null),
+                });
+            }
+            continue;
+        }
+        const text = texts(message, 'text');
+        const reasoning = texts(message, 'reasoning');
+        const toolCalls = [];
+        for (const part of message.parts) {
+            if (part.type !== 'tool-call')
+                continue;
+            const call = calls.get(part.toolCallId);
+            toolCalls.push({
+                id: part.toolCallId,
+                type: 'function',
+                function: { name: call?.name ?? 'unknown', arguments: call?.inputText ?? JSON.stringify(call?.input ?? {}) },
+            });
+        }
+        if (text.length === 0 && reasoning.length === 0 && toolCalls.length === 0)
+            continue;
+        out.push({
+            role: 'assistant',
+            content: text.length > 0 ? text : null,
+            ...(reasoning.length > 0 ? { reasoning_content: reasoning } : {}),
+            ...(toolCalls.length > 0 ? { tool_calls: toolCalls } : {}),
+        });
+    }
+    return out;
+}

package/dist/projections/otlp.d.ts

@@ -0,0 +1,12 @@
+import { type ContractSpan } from '@tangle-network/agent-trace-contract';
+import type { HarnessSession } from '../schema.js';
+export interface OtlpProjectionOptions {
+    /** Characters of message text kept per span attribute. Default 8000; 0 keeps none. */
+    contentChars?: number;
+}
+/**
+ * The session as contract spans: one AGENT span for the session, one LLM span per model call
+ * (served model, tokens, cost, error status) and one TOOL span per tool call under the model call
+ * that made it. Ids derive from the native session id, so two exports of one session join.
+ */
+export declare function toOtlpSpans(session: HarnessSession, options?: OtlpProjectionOptions): ContractSpan[];

package/dist/projections/otlp.js

@@ -0,0 +1,91 @@
+import { contractSpan, deriveHexId, llmSpan, toolSpan, } from '@tangle-network/agent-trace-contract';
+const cap = (text, n) => (text.length <= n ? text : `${text.slice(0, n)}…`);
+/**
+ * The session as contract spans: one AGENT span for the session, one LLM span per model call
+ * (served model, tokens, cost, error status) and one TOOL span per tool call under the model call
+ * that made it. Ids derive from the native session id, so two exports of one session join.
+ */
+export function toOtlpSpans(session, options = {}) {
+    const chars = options.contentChars ?? 8000;
+    const traceId = deriveHexId(`${session.harness}:${session.nativeSessionId}`, 16);
+    const spanId = (key) => deriveHexId(`${session.harness}:${session.nativeSessionId}:${key}`, 8);
+    const rootId = spanId('session');
+    const start = session.startedAt ?? new Date(0).toISOString();
+    const end = session.endedAt ?? start;
+    const spans = [
+        contractSpan({
+            traceId,
+            spanId: rootId,
+            parentSpanId: null,
+            name: 'session',
+            kind: 'AGENT',
+            startTime: start,
+            endTime: end,
+            status: session.ending.status === 'error'
+                ? { code: 'STATUS_CODE_ERROR', message: session.ending.error?.message ?? 'session ended in error' }
+                : session.ending.status === 'completed' ? { code: 'STATUS_CODE_OK' } : { code: 'STATUS_CODE_UNSET' },
+            attributes: {
+                'tangle.sessionId': session.nativeSessionId,
+                'tangle.harness': session.harness,
+                'tangle.harness_session.format': session.format,
+                'tangle.harness_session.ending': session.ending.status,
+                ...(session.parentNativeSessionId ? { 'tangle.harness_session.parent': session.parentNativeSessionId } : {}),
+            },
+        }),
+    ];
+    const messageByCall = new Map();
+    for (const message of session.messages)
+        if (message.modelCallId)
+            messageByCall.set(message.modelCallId, message);
+    const llmIdByMessage = new Map();
+    for (const call of session.modelCalls) {
+        const id = spanId(`llm:${call.id}`);
+        const message = messageByCall.get(call.id);
+        if (message)
+            llmIdByMessage.set(message.id, id);
+        const text = message ? message.parts.filter((p) => p.type === 'text').map((p) => p.text).join('\n') : '';
+        spans.push(llmSpan({
+            traceId,
+            spanId: id,
+            parentSpanId: rootId,
+            name: 'llm.call',
+            startTime: call.at ?? start,
+            status: call.error ? { code: 'STATUS_CODE_ERROR', message: call.error.message } : { code: 'STATUS_CODE_OK' },
+            ...(call.servedModel ? { model: call.servedModel } : {}),
+            ...(call.provider ? { system: call.provider } : {}),
+            ...(call.usage?.input != null ? { inputTokens: call.usage.input } : {}),
+            ...(call.usage?.output != null ? { outputTokens: call.usage.output } : {}),
+            ...(call.costUsd != null ? { costUsd: call.costUsd } : {}),
+            attributes: {
+                ...(call.usage?.cacheRead != null ? { 'gen_ai.usage.cache_read.input_tokens': call.usage.cacheRead } : {}),
+                ...(call.usage?.cacheWrite != null ? { 'gen_ai.usage.cache_creation.input_tokens': call.usage.cacheWrite } : {}),
+                ...(call.usage?.reasoning != null ? { 'gen_ai.usage.reasoning_tokens': call.usage.reasoning } : {}),
+                ...(call.stopReason ? { 'gen_ai.response.finish_reasons': [call.stopReason] } : {}),
+                ...(call.error?.httpStatus != null ? { 'http.response.status_code': call.error.httpStatus } : {}),
+                'tangle.harness_session.model_source': session.modelSource,
+                ...(chars > 0 && text ? { 'output.value': cap(text, chars) } : {}),
+            },
+        }));
+    }
+    for (const call of session.toolCalls) {
+        spans.push(toolSpan({
+            traceId,
+            spanId: spanId(`tool:${call.id}`),
+            parentSpanId: llmIdByMessage.get(call.messageId) ?? rootId,
+            name: `tool.${call.name}`,
+            toolName: call.name,
+            startTime: call.startedAt ?? start,
+            endTime: call.endedAt ?? call.startedAt ?? start,
+            status: call.status === 'error'
+                ? { code: 'STATUS_CODE_ERROR', message: cap(call.result?.text ?? 'tool reported an error', 500) }
+                : call.status === 'completed' ? { code: 'STATUS_CODE_OK' } : { code: 'STATUS_CODE_UNSET' },
+            attributes: {
+                'gen_ai.tool.call.id': call.id,
+                'tangle.tool.status': call.status,
+                ...(chars > 0 ? { 'input.value': cap(call.inputText ?? JSON.stringify(call.input ?? null), chars) } : {}),
+                ...(chars > 0 && call.result?.text ? { 'output.value': cap(call.result.text, chars) } : {}),
+            },
+        }));
+    }
+    return spans;
+}

package/dist/projections/turns.d.ts

@@ -0,0 +1,51 @@
+import type { HarnessSession, SessionError, SessionToolCall, TokenUsage } from '../schema.js';
+/** One tool invocation in a turn, previewed for storage beside a post. */
+export interface TurnToolCall {
+    name: string;
+    input_preview?: string;
+    file_path?: string;
+    result_preview?: string;
+    is_error?: boolean;
+}
+/** One turn of agent activity, the blog's trace unit (drewstone.github.io tools/harness/types.ts). */
+export interface Turn {
+    role: 'user' | 'assistant' | 'system' | 'tool';
+    seq?: number;
+    text?: string;
+    text_summary?: string;
+    tool_calls?: number;
+    tool_names?: string[];
+    tool_call_details?: TurnToolCall[];
+    files_touched?: string[];
+    had_thinking?: boolean;
+    /** The model that answered this turn, as the session recorded it. */
+    model?: string;
+    usage?: TokenUsage;
+    /** The error the model call ended with, when it failed. */
+    error?: SessionError;
+    ts: string;
+}
+export interface TurnOptions {
+    /** Working directory to make touched paths relative to. Defaults to the session cwd. */
+    cwd?: string | null;
+    /** Characters kept in `text`. Default 8000. */
+    textChars?: number;
+    /** Characters kept in `text_summary`. Default 280. */
+    summaryChars?: number;
+    /** Characters kept in a tool input or result preview. Default 600. */
+    previewChars?: number;
+    /**
+     * The files a tool call touched. Defaults to the path of an edit or write tool and the files a
+     * patch names; a caller with its own notion (paths mentioned anywhere in the input) passes it.
+     */
+    filesOf?: (call: SessionToolCall) => string[];
+}
+export declare function summarizeText(text: string, n: number): string;
+/**
+ * The session as the blog's turns: one turn per human message and per assistant message, with
+ * the tool calls an assistant message made, the files they touched, the model that answered,
+ * its usage and the error it ended with.
+ */
+export declare function toTurns(session: HarnessSession, options?: TurnOptions): Turn[];
+/** The model a session was answered by most often, or null when it recorded none. */
+export declare function primaryModel(session: Pick<HarnessSession, 'modelCalls'>): string | null;

package/dist/projections/turns.js

@@ -0,0 +1,136 @@
+import { isRecord } from '../builder.js';
+export function summarizeText(text, n) {
+    const t = text.replace(/\s+/gu, ' ').trim();
+    return t.length <= n ? t : `${t.slice(0, n - 1)}…`;
+}
+const EDIT_TOOLS = /^(?:Edit|Write|MultiEdit|NotebookEdit|edit|write|multiedit|patch|apply_patch|str_replace_editor|create_file)$/u;
+function stringField(input, ...keys) {
+    if (!isRecord(input))
+        return undefined;
+    for (const key of keys)
+        if (typeof input[key] === 'string')
+            return input[key];
+    return undefined;
+}
+/** Paths a patch touches, from `*** Update File:` / `*** Add File:` / `*** Delete File:` headers. */
+function patchPaths(text) {
+    return [...text.matchAll(/^\*\*\* (?:Update|Add|Delete) File: (.+)$/gmu)].map((m) => m[1].trim());
+}
+function touched(call) {
+    if (!EDIT_TOOLS.test(call.name))
+        return [];
+    const path = stringField(call.input, 'file_path', 'filePath', 'path', 'notebook_path');
+    if (path)
+        return [path];
+    const text = typeof call.input === 'string' ? call.input : stringField(call.input, 'patch', 'input', 'content') ?? call.inputText ?? '';
+    return patchPaths(text);
+}
+function inputPreview(call) {
+    const input = call.input;
+    const command = stringField(input, 'command', 'cmd');
+    if (command)
+        return command;
+    if (Array.isArray(isRecord(input) ? input.command : undefined))
+        return input.command.join(' ');
+    const oldString = stringField(input, 'old_string', 'oldString');
+    if (oldString !== undefined) {
+        const head = (s) => s.split('\n').slice(0, 3).join('\n');
+        return `- ${head(oldString)}\n+ ${head(stringField(input, 'new_string', 'newString') ?? '')}`;
+    }
+    const content = stringField(input, 'content');
+    if (content !== undefined && EDIT_TOOLS.test(call.name))
+        return content.split('\n').slice(0, 6).join('\n');
+    const pattern = stringField(input, 'pattern');
+    if (pattern) {
+        const path = stringField(input, 'path');
+        return path ? `${pattern}  in  ${path}` : pattern;
+    }
+    const path = stringField(input, 'file_path', 'filePath', 'path');
+    if (path)
+        return path;
+    if (typeof input === 'string')
+        return input;
+    try {
+        return JSON.stringify(input) ?? '';
+    }
+    catch {
+        return '';
+    }
+}
+function text(message, type) {
+    return message.parts.filter((p) => p.type === type).map((p) => p.text).join('\n');
+}
+/**
+ * The session as the blog's turns: one turn per human message and per assistant message, with
+ * the tool calls an assistant message made, the files they touched, the model that answered,
+ * its usage and the error it ended with.
+ */
+export function toTurns(session, options = {}) {
+    const textChars = options.textChars ?? 8000;
+    const summaryChars = options.summaryChars ?? 280;
+    const previewChars = options.previewChars ?? 600;
+    const root = (options.cwd ?? session.cwd ?? '').replace(/\/$/u, '');
+    const relativize = (path) => (root && path.startsWith(`${root}/`) ? path.slice(root.length + 1) : path);
+    const calls = new Map(session.toolCalls.map((c) => [c.id, c]));
+    const modelCalls = new Map(session.modelCalls.map((c) => [c.id, c]));
+    const turns = [];
+    let seq = 0;
+    for (const message of session.messages) {
+        const ts = message.at ?? '';
+        if (message.role === 'user') {
+            const body = text(message, 'text');
+            if (!body)
+                continue;
+            turns.push({ role: 'user', seq: seq++, text: body.length > textChars ? summarizeText(body, textChars) : body, ts });
+            continue;
+        }
+        if (message.role !== 'assistant')
+            continue;
+        const body = text(message, 'text');
+        const toolCalls = message.parts.filter((p) => p.type === 'tool-call').map((p) => calls.get(p.toolCallId)).filter((c) => c !== undefined);
+        const call = message.modelCallId ? modelCalls.get(message.modelCallId) : undefined;
+        if (!body && toolCalls.length === 0 && !call?.error)
+            continue;
+        const filesOf = options.filesOf ?? touched;
+        const files = toolCalls.flatMap(filesOf).map(relativize);
+        const details = toolCalls.map((c) => {
+            const preview = inputPreview(c);
+            const path = (options.filesOf ?? touched)(c)[0];
+            const result = c.result?.text ?? (typeof c.result?.output === 'string' ? c.result.output : undefined);
+            return {
+                name: c.name,
+                ...(preview ? { input_preview: summarizeText(preview, previewChars) } : {}),
+                ...(path ? { file_path: relativize(path) } : {}),
+                ...(result ? { result_preview: summarizeText(result, previewChars) } : {}),
+                ...(c.result?.isError ? { is_error: true } : {}),
+            };
+        });
+        const model = call?.servedModel ?? undefined;
+        turns.push({
+            seq: seq++,
+            role: 'assistant',
+            ...(body ? { text: body.length > textChars ? summarizeText(body, textChars) : body, text_summary: summarizeText(body, summaryChars) } : {}),
+            ...(toolCalls.length > 0 ? { tool_calls: toolCalls.length, tool_names: [...new Set(toolCalls.map((c) => c.name))].slice(0, 6), tool_call_details: details } : {}),
+            ...(files.length > 0 ? { files_touched: [...new Set(files)] } : {}),
+            ...(message.parts.some((p) => p.type === 'reasoning') ? { had_thinking: true } : {}),
+            ...(model ? { model } : {}),
+            ...(call?.usage ? { usage: call.usage } : {}),
+            ...(call?.error ? { error: call.error } : {}),
+            ts,
+        });
+    }
+    return turns;
+}
+/** The model a session was answered by most often, or null when it recorded none. */
+export function primaryModel(session) {
+    const counts = new Map();
+    for (const call of session.modelCalls)
+        if (call.servedModel)
+            counts.set(call.servedModel, (counts.get(call.servedModel) ?? 0) + 1);
+    let best = null;
+    let bestCount = 0;
+    for (const [model, n] of counts)
+        if (n > bestCount)
+            [best, bestCount] = [model, n];
+    return best;
+}

package/dist/registry.d.ts

@@ -0,0 +1,11 @@
+import type { HarnessSessionReader, SessionFormatId } from './schema.js';
+/** Every reader this package ships. */
+export declare function listReaders(): readonly HarnessSessionReader[];
+/** Harness ids and aliases that resolve to a reader. */
+export declare function knownHarnesses(): string[];
+/** The reader for a harness id or alias. Throws for a harness with no reader. */
+export declare function readerFor(harnessOrAlias: string): HarnessSessionReader;
+/** The reader for a harness, or undefined when none exists. */
+export declare function maybeReaderFor(harnessOrAlias: string): HarnessSessionReader | undefined;
+/** The reader that owns a session format. */
+export declare function readerForFormat(format: SessionFormatId): HarnessSessionReader;

package/dist/registry.js

@@ -0,0 +1,39 @@
+import { claudeCodeReader } from './formats/claude-code.js';
+import { codexReader } from './formats/codex.js';
+import { kimiReader } from './formats/kimi.js';
+import { factoryReader } from './formats/factory.js';
+import { opencodeReader } from './formats/opencode.js';
+import { piReader } from './formats/pi.js';
+const READERS = [claudeCodeReader, codexReader, opencodeReader, piReader, kimiReader, factoryReader];
+const BY_NAME = new Map();
+for (const reader of READERS) {
+    BY_NAME.set(reader.harness, reader);
+    for (const alias of reader.aliases)
+        BY_NAME.set(alias, reader);
+}
+/** Every reader this package ships. */
+export function listReaders() {
+    return READERS;
+}
+/** Harness ids and aliases that resolve to a reader. */
+export function knownHarnesses() {
+    return [...BY_NAME.keys()].sort();
+}
+/** The reader for a harness id or alias. Throws for a harness with no reader. */
+export function readerFor(harnessOrAlias) {
+    const reader = BY_NAME.get(harnessOrAlias) ?? BY_NAME.get(harnessOrAlias.toLowerCase());
+    if (!reader)
+        throw new Error(`no session reader for harness "${harnessOrAlias}"; known: ${knownHarnesses().join(', ')}`);
+    return reader;
+}
+/** The reader for a harness, or undefined when none exists. */
+export function maybeReaderFor(harnessOrAlias) {
+    return BY_NAME.get(harnessOrAlias) ?? BY_NAME.get(harnessOrAlias.toLowerCase());
+}
+/** The reader that owns a session format. */
+export function readerForFormat(format) {
+    const reader = READERS.find((r) => r.formats.includes(format));
+    if (!reader)
+        throw new Error(`no session reader for format "${format}"`);
+    return reader;
+}