dsh-reference-anything 0.3.0 → 0.3.2

package/lib/sources/local-agent/adapters/codex.js

@@ -0,0 +1,204 @@
+/**
+ * Codex CLI rollouts: `~/.codex/sessions/<yyyy>/<mm>/<dd>/rollout-*.jsonl`.
+ *
+ * Each line is an envelope `{timestamp, ordinal?, type, payload}`. Measured
+ * across 170 rollouts, seven envelope types occur — `response_item`,
+ * `event_msg`, `session_meta`, `turn_context`, `world_state`, `compacted`, and
+ * `inter_agent_communication_metadata` — but only `response_item` carries
+ * conversation.
+ *
+ * `event_msg` is the trap. Its `agent_message` and `user_message` payloads look
+ * like the assistant and the user speaking, and they are: they restate what
+ * `response_item` already recorded. Counted per file, `event_msg.agent_message`
+ * matched `response_item.message` with `role: 'assistant'` one for one across
+ * every rollout that had any, so consuming both would double the transcript.
+ *
+ * @module dsh-reference-anything/local-agent/adapters/codex
+ */
+import { joinLocalPath } from "../path.js";
+import { arrayField, cleanUserText, createSharedState, emitUser, flushAssistant, normalizeTitle, objectField, parseRecord, parseTimestamp, pushAssistant, renderToolCall, renderToolResult, stringField, } from "./shared.js";
+/** Reads Codex CLI rollout logs. */
+export const codexAdapter = {
+    kind: 'codex',
+    displayName: 'Codex',
+    defaultRoots(home) {
+        return [joinLocalPath(home, '.codex', 'sessions')];
+    },
+    matches(relativePath) {
+        return relativePath.toLowerCase().endsWith('.jsonl');
+    },
+    createState() {
+        return createSharedState();
+    },
+    step(line, state, options) {
+        const record = parseRecord(line);
+        if (record === undefined)
+            return [];
+        const envelope = record['type'];
+        if (envelope === 'compacted') {
+            // Codex's analogue of a compact boundary: `payload.replacement_history`
+            // stands in for everything before it, which is no longer in this file.
+            state.compacted = true;
+            return [];
+        }
+        if (envelope !== 'response_item')
+            return [];
+        const payload = objectField(record, 'payload');
+        if (payload === undefined)
+            return [];
+        switch (payload['type']) {
+            case 'message':
+                return stepMessage(payload, state, options);
+            case 'reasoning':
+                if (options.includeThinking)
+                    pushAssistant(state, reasoningText(payload));
+                return [];
+            case 'function_call':
+                pushAssistant(state, renderToolCall(payload['name'], payload['arguments'], options.toolCalls, options.toolSummaryChars));
+                return [];
+            case 'custom_tool_call':
+            case 'local_shell_call':
+                pushAssistant(state, renderToolCall(payload['name'], payload['input'], options.toolCalls, options.toolSummaryChars));
+                return [];
+            case 'function_call_output':
+            case 'custom_tool_call_output':
+                pushAssistant(state, renderToolResult(payload['output'], options.toolResults, options.toolSummaryChars));
+                return [];
+            default:
+                // `agent_message` here is not
+                // the assistant answering the user — it carries `author` and
+                // `recipient` and is one agent dispatching work to another — so it is
+                // plumbing too.
+                return [];
+        }
+    },
+    flush(state, _options) {
+        return flushAssistant(state);
+    },
+    head(headLines, tailLines) {
+        let cwd;
+        let createdAt;
+        let firstPrompt;
+        let firstReply;
+        for (const line of headLines) {
+            const record = parseRecord(line);
+            if (record === undefined)
+                continue;
+            const envelope = record['type'];
+            const payload = objectField(record, 'payload');
+            if (envelope === 'session_meta' && payload !== undefined) {
+                cwd ??= stringField(payload, 'cwd');
+                createdAt ??= parseTimestamp(payload['timestamp'] ?? record['timestamp']);
+                continue;
+            }
+            if (envelope === 'turn_context' && payload !== undefined) {
+                cwd ??= stringField(payload, 'cwd');
+                continue;
+            }
+            if (envelope !== 'response_item' || payload === undefined)
+                continue;
+            if (firstPrompt === undefined && payload['role'] === 'user')
+                firstPrompt = messageText(payload, true);
+            if (firstReply === undefined && payload['role'] === 'assistant')
+                firstReply = messageText(payload, true);
+        }
+        createdAt ??= parseTimestamp(parseRecord(headLines[0] ?? '')?.['timestamp']);
+        // A rollout carries no title of its own, so the opening prompt is the name.
+        // The tail can still supply one when the head's probe fell short of the
+        // first real prompt — Codex's harness preamble alone can run past a
+        // megabyte, and a rollout whose head is all preamble would otherwise show
+        // as its filename.
+        if (firstPrompt === undefined) {
+            for (const line of tailLines) {
+                const record = parseRecord(line);
+                const payload = objectField(record, 'payload');
+                if (record?.['type'] !== 'response_item' || payload?.['role'] !== 'user')
+                    continue;
+                firstPrompt = messageText(payload, true) ?? firstPrompt;
+                if (firstPrompt !== undefined)
+                    break;
+            }
+        }
+        // A rollout a parent agent dispatched has no user text at all: its task
+        // arrived as an `agent_message` whose payload is encrypted, leaving the
+        // injected preamble as the only user-role record. Measured over 25 recent
+        // rollouts, 7 were of this kind. The assistant's opening line is then the
+        // only readable account of what the session was for, and naming the entry
+        // after it beats naming it after its filename.
+        const title = normalizeTitle(firstPrompt ?? firstReply ?? '');
+        return {
+            ...title === '' ? {} : { title },
+            ...cwd === undefined ? {} : { cwd },
+            ...firstPrompt === undefined ? {} : { firstPrompt },
+            ...createdAt === undefined ? {} : { createdAt },
+        };
+    },
+};
+/** Fold one `response_item.message`, whose role decides whether it is conversation at all. */
+function stepMessage(payload, state, options) {
+    const role = payload['role'];
+    if (role === 'user') {
+        const text = messageText(payload, options.stripEnvironmentPreamble);
+        return text === undefined ? [] : emitUser(state, text);
+    }
+    if (role === 'assistant') {
+        pushAssistant(state, messageText(payload, false));
+        return [];
+    }
+    // `developer` is the largest role by count in a modern rollout — skills
+    // instructions, tool contracts, environment context. Projecting it would
+    // read as though the user had said those things.
+    return [];
+}
+/**
+ * Flatten a message's content blocks to text.
+ * @param payload - a `message` payload.
+ * @param stripPreamble - drop the message entirely when it is a harness-injected block.
+ * @returns the text, or undefined when the message contributes nothing.
+ */
+function messageText(payload, stripPreamble) {
+    const blocks = arrayField(payload, 'content');
+    if (blocks === undefined) {
+        const direct = stringField(payload, 'text');
+        return direct === undefined ? undefined : normalizeBody(direct, stripPreamble);
+    }
+    const parts = [];
+    for (const block of blocks) {
+        if (typeof block !== 'object' || block === null)
+            continue;
+        const entry = block;
+        // Assistant blocks arrive as `output_text` and, on some builds, as
+        // `input_text`; both were present in the measured corpus.
+        if (entry['type'] === 'input_text' || entry['type'] === 'output_text' || entry['type'] === 'text') {
+            if (typeof entry['text'] === 'string')
+                parts.push(entry['text']);
+        }
+    }
+    return parts.length === 0 ? undefined : normalizeBody(parts.join('\n'), stripPreamble);
+}
+/** Apply the preamble rules and collapse an empty result to `undefined`. */
+function normalizeBody(text, stripPreamble) {
+    const cleaned = stripPreamble ? cleanUserText(text) : text.trim();
+    return cleaned === '' ? undefined : cleaned;
+}
+/**
+ * The visible part of a `reasoning` payload.
+ *
+ * Codex encrypts its reasoning and leaves `summary` empty in every rollout
+ * measured here, so this usually yields nothing — which is why
+ * `includeThinking` costs a Codex read almost nothing.
+ */
+function reasoningText(payload) {
+    const summary = arrayField(payload, 'summary') ?? [];
+    const parts = [];
+    for (const block of summary) {
+        if (typeof block === 'string')
+            parts.push(block);
+        else if (typeof block === 'object' && block !== null) {
+            const text = block['text'];
+            if (typeof text === 'string')
+                parts.push(text);
+        }
+    }
+    return parts.length === 0 ? undefined : parts.join('\n');
+}

package/lib/sources/local-agent/adapters/cursor.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Cursor agent transcripts:
+ * `~/.cursor/projects/<slug>/agent-transcripts/<composer>/<composer>.jsonl`.
+ *
+ * The record shape is the Messages API's without an envelope — each line is
+ * `{role, message: {content: [...]}}` and nothing else — so the fold is the
+ * shortest of any supported format. Three details are Cursor's own:
+ *
+ * - The opening prompt arrives wrapped in `<user_query>…</user_query>`, which
+ *   is markup Cursor adds rather than anything a person typed.
+ * - Assistant text carries `[REDACTED]` sentinels where the client stripped
+ *   something before writing. Left in, they read as though the model said the
+ *   word.
+ * - There is no `tool_result`, no timestamp, and no `cwd` anywhere in the
+ *   file: results live in a separate bubble store and the composer uuid is the
+ *   only identity. So a Cursor transcript can never be workspace-scoped from
+ *   its contents, which the source handles by listing it under `scope: 'all'`.
+ *
+ * @module dsh-reference-anything/local-agent/adapters/cursor
+ */
+import type { TranscriptAdapter } from '../types.ts';
+/** Reads Cursor agent transcripts. */
+export declare const cursorAdapter: TranscriptAdapter;

package/lib/sources/local-agent/adapters/cursor.js

@@ -0,0 +1,121 @@
+/**
+ * Cursor agent transcripts:
+ * `~/.cursor/projects/<slug>/agent-transcripts/<composer>/<composer>.jsonl`.
+ *
+ * The record shape is the Messages API's without an envelope — each line is
+ * `{role, message: {content: [...]}}` and nothing else — so the fold is the
+ * shortest of any supported format. Three details are Cursor's own:
+ *
+ * - The opening prompt arrives wrapped in `<user_query>…</user_query>`, which
+ *   is markup Cursor adds rather than anything a person typed.
+ * - Assistant text carries `[REDACTED]` sentinels where the client stripped
+ *   something before writing. Left in, they read as though the model said the
+ *   word.
+ * - There is no `tool_result`, no timestamp, and no `cwd` anywhere in the
+ *   file: results live in a separate bubble store and the composer uuid is the
+ *   only identity. So a Cursor transcript can never be workspace-scoped from
+ *   its contents, which the source handles by listing it under `scope: 'all'`.
+ *
+ * @module dsh-reference-anything/local-agent/adapters/cursor
+ */
+import { joinLocalPath } from "../path.js";
+import { arrayField, createSharedState, emitUser, flushAssistant, normalizeTitle, objectField, parseRecord, pushAssistant, renderToolCall, } from "./shared.js";
+/** Wrapper Cursor puts around the prompt it sends, not something anyone typed. */
+const USER_QUERY_TAG = /<\/?user_query>/gu;
+/** Placeholder the client leaves where it removed content before writing. */
+const REDACTED = /\[REDACTED\]/gu;
+/** Reads Cursor agent transcripts. */
+export const cursorAdapter = {
+    kind: 'cursor',
+    displayName: 'Cursor',
+    defaultRoots(home) {
+        return [joinLocalPath(home, '.cursor', 'projects')];
+    },
+    matches(relativePath) {
+        const path = relativePath.toLowerCase();
+        // Scoped to the transcript directory rather than to `.jsonl` alone: the
+        // project tree holds other line-delimited state this adapter cannot read.
+        return path.includes('agent-transcripts/') && path.endsWith('.jsonl');
+    },
+    createState() {
+        return createSharedState();
+    },
+    step(line, state, options) {
+        const record = parseRecord(line);
+        if (record === undefined)
+            return [];
+        const blocks = arrayField(objectField(record, 'message'), 'content') ?? [];
+        if (record['role'] === 'user') {
+            const text = userText(blocks);
+            return text === undefined ? [] : emitUser(state, text);
+        }
+        if (record['role'] !== 'assistant')
+            return [];
+        for (const block of blocks) {
+            if (typeof block !== 'object' || block === null)
+                continue;
+            const entry = block;
+            if (entry['type'] === 'text') {
+                pushAssistant(state, scrub(entry['text']));
+            }
+            else if (entry['type'] === 'tool_use') {
+                // `input` is already an object here; Cursor does not JSON-encode it the
+                // way the wire format does.
+                pushAssistant(state, renderToolCall(entry['name'], entry['input'], options.toolCalls, options.toolSummaryChars));
+            }
+        }
+        return [];
+    },
+    flush(state, _options) {
+        return flushAssistant(state);
+    },
+    head(headLines, tailLines) {
+        let firstPrompt;
+        for (const line of [...headLines, ...tailLines]) {
+            const record = parseRecord(line);
+            if (record?.['role'] !== 'user')
+                continue;
+            firstPrompt = userText(arrayField(objectField(record, 'message'), 'content') ?? []);
+            if (firstPrompt !== undefined)
+                break;
+        }
+        const title = normalizeTitle(firstPrompt ?? '');
+        // No `createdAt` and no `cwd`: the format records neither, and inventing
+        // one from the file's mtime would claim the session started when it was
+        // last written to.
+        return {
+            ...title === '' ? {} : { title },
+            ...firstPrompt === undefined ? {} : { firstPrompt },
+        };
+    },
+};
+/**
+ * The words a person typed, from a user record's content blocks.
+ * @param blocks - the `message.content` array.
+ * @returns the prompt, or undefined when the record carried no text.
+ */
+function userText(blocks) {
+    const parts = [];
+    for (const block of blocks) {
+        if (typeof block !== 'object' || block === null)
+            continue;
+        const entry = block;
+        if (entry['type'] !== 'text' || typeof entry['text'] !== 'string')
+            continue;
+        const text = entry['text'].replace(USER_QUERY_TAG, '').trim();
+        if (text !== '')
+            parts.push(text);
+    }
+    return parts.length === 0 ? undefined : parts.join('\n');
+}
+/**
+ * Assistant text with the client's redaction sentinels removed.
+ * @param value - the block's `text` field, of unknown type.
+ * @returns the text, or undefined when nothing survived the scrub.
+ */
+function scrub(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const text = value.replace(REDACTED, '').trim();
+    return text === '' ? undefined : text;
+}

package/lib/sources/local-agent/adapters/gemini-cli.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Gemini CLI chats: `~/.gemini/history/<slot>/chats/session-*.json`.
+ *
+ * The only supported format that is not line-delimited. One file is one JSON
+ * object — `{sessionId, projectHash, startTime, directories, messages}` — so
+ * half of it is not a shorter conversation, and the adapter declares itself
+ * {@link TranscriptAdapter.document} to say so: records are held verbatim
+ * until the file ends, then parsed once.
+ *
+ * The messages themselves are the simplest of any agent: `user` carries a
+ * parts array, `gemini` carries a plain string plus its `thoughts` and
+ * `toolCalls`, and `info` is the CLI's own banner text. Tool results are
+ * inlined on the call rather than split into a following record, which this
+ * projection drops along with every other result.
+ *
+ * @module dsh-reference-anything/local-agent/adapters/gemini-cli
+ */
+import type { TranscriptAdapter } from '../types.ts';
+/** Reads Gemini CLI chat files. */
+export declare const geminiCliAdapter: TranscriptAdapter;

package/lib/sources/local-agent/adapters/gemini-cli.js

@@ -0,0 +1,141 @@
+/**
+ * Gemini CLI chats: `~/.gemini/history/<slot>/chats/session-*.json`.
+ *
+ * The only supported format that is not line-delimited. One file is one JSON
+ * object — `{sessionId, projectHash, startTime, directories, messages}` — so
+ * half of it is not a shorter conversation, and the adapter declares itself
+ * {@link TranscriptAdapter.document} to say so: records are held verbatim
+ * until the file ends, then parsed once.
+ *
+ * The messages themselves are the simplest of any agent: `user` carries a
+ * parts array, `gemini` carries a plain string plus its `thoughts` and
+ * `toolCalls`, and `info` is the CLI's own banner text. Tool results are
+ * inlined on the call rather than split into a following record, which this
+ * projection drops along with every other result.
+ *
+ * @module dsh-reference-anything/local-agent/adapters/gemini-cli
+ */
+import { joinLocalPath } from "../path.js";
+import { blankToUndefined, createSharedState, emitUser, flushAssistant, holdLine, normalizeTitle, parseDocument, parseTimestamp, pushAssistant, renderToolCall, renderToolResult, takeHeld, } from "./shared.js";
+/** Reads Gemini CLI chat files. */
+export const geminiCliAdapter = {
+    kind: 'gemini-cli',
+    displayName: 'Gemini CLI',
+    document: true,
+    defaultRoots(home) {
+        return [joinLocalPath(home, '.gemini', 'history')];
+    },
+    matches(relativePath) {
+        const path = relativePath.toLowerCase();
+        return path.includes('/chats/') && path.endsWith('.json');
+    },
+    createState() {
+        return createSharedState();
+    },
+    step(line, state, _options) {
+        return holdLine(state, line);
+    },
+    flush(state, options) {
+        const chat = asRecord(parseDocument(takeHeld(state)));
+        const messages = chat?.['messages'];
+        if (!Array.isArray(messages))
+            return [];
+        const turns = [];
+        for (const message of messages) {
+            const entry = asRecord(message);
+            if (entry === undefined)
+                continue;
+            if (entry['type'] === 'user') {
+                const text = blankToUndefined(partsText(entry['content']));
+                if (text !== undefined)
+                    turns.push(...emitUser(state, text));
+            }
+            else if (entry['type'] === 'gemini') {
+                pushGemini(entry, state, options);
+            }
+            // `info` is a CLI banner — an error notice, a cancellation — not speech.
+        }
+        turns.push(...flushAssistant(state));
+        return turns;
+    },
+    head(headLines, tailLines) {
+        // A probe that captured the whole small file parses; one that captured a
+        // prefix of a large file does not, and the entry degrades to its filename
+        // rather than to a guess at the missing half.
+        const chat = asRecord(parseDocument(headLines.join('\n')))
+            ?? asRecord(parseDocument([...headLines, ...tailLines].join('\n')));
+        if (chat === undefined)
+            return {};
+        const messages = Array.isArray(chat['messages']) ? chat['messages'] : [];
+        let firstPrompt;
+        for (const message of messages) {
+            const entry = asRecord(message);
+            if (entry?.['type'] !== 'user')
+                continue;
+            firstPrompt = blankToUndefined(partsText(entry['content']));
+            if (firstPrompt !== undefined)
+                break;
+        }
+        const directories = chat['directories'];
+        const cwd = Array.isArray(directories) && typeof directories[0] === 'string' ? directories[0] : undefined;
+        const createdAt = parseTimestamp(chat['startTime']);
+        const title = normalizeTitle(firstPrompt ?? '');
+        return {
+            ...title === '' ? {} : { title },
+            ...cwd === undefined ? {} : { cwd },
+            ...firstPrompt === undefined ? {} : { firstPrompt },
+            ...createdAt === undefined ? {} : { createdAt },
+        };
+    },
+};
+/** Fold one `gemini` message into the open assistant run. */
+function pushGemini(entry, state, options) {
+    if (typeof entry['content'] === 'string')
+        pushAssistant(state, entry['content']);
+    if (options.includeThinking && Array.isArray(entry['thoughts'])) {
+        for (const thought of entry['thoughts']) {
+            const it = asRecord(thought);
+            if (it === undefined)
+                continue;
+            const parts = [it['subject'], it['description']].filter((v) => typeof v === 'string' && v !== '');
+            if (parts.length > 0)
+                pushAssistant(state, parts.join('：'));
+        }
+    }
+    if (!Array.isArray(entry['toolCalls']))
+        return;
+    for (const call of entry['toolCalls']) {
+        const it = asRecord(call);
+        if (it === undefined)
+            continue;
+        pushAssistant(state, renderToolCall(it['name'], it['args'], options.toolCalls, options.toolSummaryChars));
+        const output = it['result'] ?? it['output'] ?? it['response'];
+        if (output !== undefined)
+            pushAssistant(state, renderToolResult(output, options.toolResults, options.toolSummaryChars));
+    }
+}
+/**
+ * Flatten a `parts`-style content value to text.
+ * @param content - the message's `content`, of unknown shape.
+ * @returns the flattened text; empty when nothing readable was found.
+ */
+function partsText(content) {
+    if (typeof content === 'string')
+        return content;
+    if (!Array.isArray(content))
+        return '';
+    const parts = [];
+    for (const part of content) {
+        const entry = asRecord(part);
+        const text = entry?.['text'];
+        if (typeof text === 'string' && text.trim() !== '')
+            parts.push(text.trim());
+    }
+    return parts.join('\n');
+}
+/** Narrow an unknown to a plain object, which is the only shape this format uses. */
+function asRecord(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return undefined;
+    return value;
+}

package/lib/sources/local-agent/adapters/grokbuild.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Grok Build sessions: `~/.grok/sessions/<slug>/<id>/chat_history.jsonl`, and
+ * the same layout under `~/.grok/archived_sessions/`.
+ *
+ * A session is a *directory*, not a file: `chat_history.jsonl` holds the
+ * conversation while a sibling `summary.json` holds the generated title, the
+ * `cwd`, and the timestamps. A pure adapter reads one file, so the title falls
+ * back to the opening prompt and Grok sessions carry no recorded `cwd` — which
+ * means they list under `scope: 'all'` rather than being matched to a
+ * workspace. That is a real gap, not an oversight; closing it would mean
+ * giving adapters I/O, which is the one thing the interface exists to prevent.
+ *
+ * Records are `{type, content, timestamp}` with `content` either a string or a
+ * Messages-API block array. Two of the five types are dropped: `system` is
+ * harness-injected, and `reasoning` carries Grok's encrypted internal state,
+ * which renders as a wall of base64 rather than as thought.
+ *
+ * @module dsh-reference-anything/local-agent/adapters/grokbuild
+ */
+import type { TranscriptAdapter } from '../types.ts';
+/** Reads Grok Build chat histories. */
+export declare const grokbuildAdapter: TranscriptAdapter;

package/lib/sources/local-agent/adapters/grokbuild.js

@@ -0,0 +1,76 @@
+/**
+ * Grok Build sessions: `~/.grok/sessions/<slug>/<id>/chat_history.jsonl`, and
+ * the same layout under `~/.grok/archived_sessions/`.
+ *
+ * A session is a *directory*, not a file: `chat_history.jsonl` holds the
+ * conversation while a sibling `summary.json` holds the generated title, the
+ * `cwd`, and the timestamps. A pure adapter reads one file, so the title falls
+ * back to the opening prompt and Grok sessions carry no recorded `cwd` — which
+ * means they list under `scope: 'all'` rather than being matched to a
+ * workspace. That is a real gap, not an oversight; closing it would mean
+ * giving adapters I/O, which is the one thing the interface exists to prevent.
+ *
+ * Records are `{type, content, timestamp}` with `content` either a string or a
+ * Messages-API block array. Two of the five types are dropped: `system` is
+ * harness-injected, and `reasoning` carries Grok's encrypted internal state,
+ * which renders as a wall of base64 rather than as thought.
+ *
+ * @module dsh-reference-anything/local-agent/adapters/grokbuild
+ */
+import { joinLocalPath } from "../path.js";
+import { arrayField, contentBlockUserText, createSharedState, emitUser, flushAssistant, normalizeTitle, parseRecord, parseTimestamp, pushAssistant, pushContentBlocks, pushToolResults, } from "./shared.js";
+/** Reads Grok Build chat histories. */
+export const grokbuildAdapter = {
+    kind: 'grokbuild',
+    displayName: 'Grok Build',
+    defaultRoots(home) {
+        return [joinLocalPath(home, '.grok', 'sessions'), joinLocalPath(home, '.grok', 'archived_sessions')];
+    },
+    matches(relativePath) {
+        const path = relativePath.toLowerCase();
+        return path.endsWith('/chat_history.jsonl') || path === 'chat_history.jsonl';
+    },
+    createState() {
+        return createSharedState();
+    },
+    step(line, state, options) {
+        const record = parseRecord(line);
+        if (record === undefined)
+            return [];
+        if (record['type'] === 'user') {
+            pushToolResults(state, record['content'], options);
+            const text = contentBlockUserText(record['content']);
+            return text === undefined ? [] : emitUser(state, text);
+        }
+        if (record['type'] !== 'assistant')
+            return [];
+        const content = record['content'];
+        if (typeof content === 'string')
+            pushAssistant(state, content);
+        else
+            pushContentBlocks(state, arrayField(record, 'content'), options);
+        return [];
+    },
+    flush(state, _options) {
+        return flushAssistant(state);
+    },
+    head(headLines, _tailLines) {
+        let createdAt;
+        let firstPrompt;
+        for (const line of headLines) {
+            const record = parseRecord(line);
+            if (record === undefined)
+                continue;
+            createdAt ??= parseTimestamp(record['timestamp']);
+            if (firstPrompt === undefined && record['type'] === 'user') {
+                firstPrompt = contentBlockUserText(record['content']);
+            }
+        }
+        const title = normalizeTitle(firstPrompt ?? '');
+        return {
+            ...title === '' ? {} : { title },
+            ...firstPrompt === undefined ? {} : { firstPrompt },
+            ...createdAt === undefined ? {} : { createdAt },
+        };
+    },
+};

package/lib/sources/local-agent/adapters/hermes.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Hermes sessions: `~/.hermes/sessions/<id>.jsonl`.
+ *
+ * Hermes writes two record shapes and neither generation is retired, so both
+ * are accepted per line: a flat `{role, content, ts}` and a nested
+ * `{type: 'session' | 'message', message: {role, content}, timestamp}`. The
+ * discriminator is whether a `message` object is present, which costs one
+ * lookup and removes the need to sniff the file first.
+ *
+ * Hermes also keeps its canonical history in a SQLite `state.db` and treats
+ * the JSONL files as an export. Reading the database needs a query interface
+ * rather than a line fold, so it is out of this adapter's scope; a session
+ * that exists only in `state.db` will not appear in the menu.
+ *
+ * @module dsh-reference-anything/local-agent/adapters/hermes
+ */
+import type { TranscriptAdapter } from '../types.ts';
+/** Reads Hermes session exports. */
+export declare const hermesAdapter: TranscriptAdapter;