dsh-reference-anything 0.3.1 → 0.3.3

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

@@ -0,0 +1,85 @@
+/**
+ * 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 { joinLocalPath } from "../path.js";
+import { arrayField, contentBlockUserText, createSharedState, emitUser, flushAssistant, normalizeTitle, objectField, parseRecord, parseTimestamp, pushAssistant, pushContentBlocks, pushToolResults, stringField, } from "./shared.js";
+/** Reads Hermes session exports. */
+export const hermesAdapter = {
+    kind: 'hermes',
+    displayName: 'Hermes',
+    defaultRoots(home) {
+        return [joinLocalPath(home, '.hermes', 'sessions')];
+    },
+    matches(relativePath) {
+        return relativePath.toLowerCase().endsWith('.jsonl');
+    },
+    createState() {
+        return createSharedState();
+    },
+    step(line, state, options) {
+        const record = parseRecord(line);
+        if (record === undefined)
+            return [];
+        // A `session` record is metadata; head() reads it and the fold ignores it.
+        if (record['type'] === 'session' || record['type'] === 'init')
+            return [];
+        const message = objectField(record, 'message') ?? record;
+        if (message['role'] === 'user') {
+            pushToolResults(state, message['content'], options);
+            const text = contentBlockUserText(message['content']);
+            return text === undefined ? [] : emitUser(state, text);
+        }
+        if (message['role'] !== 'assistant')
+            return [];
+        const content = message['content'];
+        if (typeof content === 'string')
+            pushAssistant(state, content);
+        else
+            pushContentBlocks(state, arrayField(message, 'content'), options);
+        return [];
+    },
+    flush(state, _options) {
+        return flushAssistant(state);
+    },
+    head(headLines, _tailLines) {
+        let recorded;
+        let cwd;
+        let createdAt;
+        let firstPrompt;
+        for (const line of headLines) {
+            const record = parseRecord(line);
+            if (record === undefined)
+                continue;
+            // First non-empty wins for metadata: Hermes may repeat the session
+            // record on resume, and the original values are the session's.
+            recorded ??= stringField(record, 'title');
+            cwd ??= stringField(record, 'cwd');
+            createdAt ??= parseTimestamp(record['timestamp'] ?? record['ts']);
+            if (firstPrompt !== undefined)
+                continue;
+            const message = objectField(record, 'message') ?? record;
+            if (message['role'] === 'user')
+                firstPrompt = contentBlockUserText(message['content']);
+        }
+        const title = normalizeTitle(recorded ?? firstPrompt ?? '');
+        return {
+            ...title === '' ? {} : { title },
+            ...cwd === undefined ? {} : { cwd },
+            ...firstPrompt === undefined ? {} : { firstPrompt },
+            ...createdAt === undefined ? {} : { createdAt },
+        };
+    },
+};

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

@@ -0,0 +1,28 @@
+/**
+ * Kimi CLI and Kimi Code: `wire.jsonl` under
+ * `~/.kimi/sessions/<workdir-md5>/<session>/` (older) or
+ * `~/.kimi-code/sessions/<workspace>/<session>/agents/main/` (newer).
+ *
+ * Both generations are read here because they are the same product and a user
+ * upgrading mid-project leaves both on disk. They are told apart per record:
+ * the old wire wraps everything as `{timestamp, message: {type, payload}}`
+ * with PascalCase event names, the new one writes `{type, time, …}` flat with
+ * dotted ones.
+ *
+ * What makes Kimi different from every other supported format is that its
+ * assistant content is a *stream*: `TextPart` and `content.part` records each
+ * carry a fragment of one sentence, split wherever the model's tokens landed.
+ * They must be concatenated, not joined — the blank line the shared buffer
+ * puts between fragments would fall in the middle of a word. Hence the
+ * chunk-accumulating helpers below, which are this adapter's only real logic.
+ *
+ * A spawned subagent gets its own `wire.jsonl` under `agents/<name>/`, and the
+ * main thread additionally mirrors its events as `SubagentEvent`. Listing both
+ * would duplicate the work, so only `agents/main/` is accepted from the newer
+ * layout and the mirrored events are skipped.
+ *
+ * @module dsh-reference-anything/local-agent/adapters/kimi
+ */
+import type { TranscriptAdapter } from '../types.ts';
+/** Reads Kimi CLI and Kimi Code wire logs. */
+export declare const kimiAdapter: TranscriptAdapter;

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

@@ -0,0 +1,261 @@
+/**
+ * Kimi CLI and Kimi Code: `wire.jsonl` under
+ * `~/.kimi/sessions/<workdir-md5>/<session>/` (older) or
+ * `~/.kimi-code/sessions/<workspace>/<session>/agents/main/` (newer).
+ *
+ * Both generations are read here because they are the same product and a user
+ * upgrading mid-project leaves both on disk. They are told apart per record:
+ * the old wire wraps everything as `{timestamp, message: {type, payload}}`
+ * with PascalCase event names, the new one writes `{type, time, …}` flat with
+ * dotted ones.
+ *
+ * What makes Kimi different from every other supported format is that its
+ * assistant content is a *stream*: `TextPart` and `content.part` records each
+ * carry a fragment of one sentence, split wherever the model's tokens landed.
+ * They must be concatenated, not joined — the blank line the shared buffer
+ * puts between fragments would fall in the middle of a word. Hence the
+ * chunk-accumulating helpers below, which are this adapter's only real logic.
+ *
+ * A spawned subagent gets its own `wire.jsonl` under `agents/<name>/`, and the
+ * main thread additionally mirrors its events as `SubagentEvent`. Listing both
+ * would duplicate the work, so only `agents/main/` is accepted from the newer
+ * layout and the mirrored events are skipped.
+ *
+ * @module dsh-reference-anything/local-agent/adapters/kimi
+ */
+import { joinLocalPath } from "../path.js";
+import { blankToUndefined, createSharedState, emitUser, flushAssistant, normalizeTitle, objectField, parseRecord, parseTimestamp, pushAssistant, renderToolCall, renderToolResult, } from "./shared.js";
+/** Marks the tail of `state.pending` as an open run of streamed text. */
+const OPEN_TEXT = 'kimi:text';
+/** Marks the tail of `state.pending` as an open run of streamed reasoning. */
+const OPEN_THINK = 'kimi:think';
+/** Reads Kimi CLI and Kimi Code wire logs. */
+export const kimiAdapter = {
+    kind: 'kimi',
+    displayName: 'Kimi',
+    defaultRoots(home) {
+        return [joinLocalPath(home, '.kimi', 'sessions'), joinLocalPath(home, '.kimi-code', 'sessions')];
+    },
+    matches(relativePath) {
+        const path = relativePath.toLowerCase();
+        if (!path.endsWith('/wire.jsonl') && path !== 'wire.jsonl')
+            return false;
+        // The newer layout files every agent under `agents/<name>/`; only the main
+        // thread is a session of its own.
+        return !path.includes('/agents/') || path.includes('/agents/main/');
+    },
+    createState() {
+        return createSharedState();
+    },
+    step(line, state, options) {
+        const record = parseRecord(line);
+        if (record === undefined)
+            return [];
+        const legacy = objectField(record, 'message');
+        // The old wire's `message` is itself an event envelope; the new wire's is
+        // an ordinary chat message. The presence of a `type` inside it decides.
+        return typeof legacy?.['type'] === 'string'
+            ? stepLegacy(legacy, state, options)
+            : stepModern(record, state, options);
+    },
+    flush(state, _options) {
+        closeRun(state);
+        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['time'] ?? record['created_at'] ?? record['timestamp']);
+            if (firstPrompt !== undefined)
+                continue;
+            const legacy = objectField(record, 'message');
+            if (typeof legacy?.['type'] === 'string') {
+                if (legacy['type'] !== 'TurnBegin' && legacy['type'] !== 'SteerInput')
+                    continue;
+                firstPrompt = blankToUndefined(partsText(objectField(legacy, 'payload')?.['user_input']));
+                continue;
+            }
+            if (record['type'] === 'turn.prompt') {
+                firstPrompt = blankToUndefined(partsText(record['input']));
+            }
+            else if (record['type'] === 'context.append_message') {
+                const message = objectField(record, 'message');
+                if (message?.['role'] === 'user')
+                    firstPrompt = blankToUndefined(partsText(message['content']));
+            }
+        }
+        // Kimi keeps a renamed session's title in the sibling `state.json`, which a
+        // probe of this file cannot reach, so the opening prompt is the name.
+        const title = normalizeTitle(firstPrompt ?? '');
+        return {
+            ...title === '' ? {} : { title },
+            ...firstPrompt === undefined ? {} : { firstPrompt },
+            ...createdAt === undefined ? {} : { createdAt },
+        };
+    },
+};
+/** Fold one event from the older `{timestamp, message: {type, payload}}` wire. */
+function stepLegacy(message, state, options) {
+    const payload = objectField(message, 'payload') ?? {};
+    switch (message['type']) {
+        case 'TurnBegin':
+        case 'SteerInput': {
+            // `SteerInput` is text typed while the agent was already working. It is
+            // still the user speaking, so it opens a turn like any other prompt.
+            const text = blankToUndefined(partsText(payload['user_input']));
+            if (text === undefined)
+                return [];
+            closeRun(state);
+            return emitUser(state, text);
+        }
+        case 'TextPart':
+            appendChunk(state, OPEN_TEXT, payload['text']);
+            return [];
+        case 'ThinkPart':
+            if (options.includeThinking)
+                appendChunk(state, OPEN_THINK, payload['think']);
+            return [];
+        case 'ToolCall': {
+            closeRun(state);
+            const fn = objectField(payload, 'function') ?? {};
+            pushAssistant(state, renderToolCall(fn['name'], fn['arguments'], options.toolCalls, options.toolSummaryChars));
+            return [];
+        }
+        case 'ToolResult':
+            closeRun(state);
+            pushAssistant(state, renderToolResult(payload['result'] ?? payload['output'] ?? payload['content'], options.toolResults, options.toolSummaryChars));
+            return [];
+        case 'StepBegin':
+        case 'TurnEnd':
+            // A step boundary ends the streamed run without ending the turn: the
+            // next fragment starts a new paragraph rather than the same sentence.
+            closeRun(state);
+            return [];
+        default:
+            // `ToolCallPart` restates arguments the final `ToolCall` already carries,
+            // `SubagentEvent` mirrors another file, and
+            // the status events carry no conversation at all.
+            return [];
+    }
+}
+/** Fold one event from the newer flat `{type, time, …}` wire. */
+function stepModern(record, state, options) {
+    switch (record['type']) {
+        case 'turn.prompt': {
+            const text = blankToUndefined(partsText(record['input']));
+            if (text === undefined)
+                return [];
+            state.seen.add('kimi:prompted');
+            closeRun(state);
+            return emitUser(state, text);
+        }
+        case 'context.append_message': {
+            // The same prompt is also appended to the context, so this is a fallback
+            // for transcripts that carry no `turn.prompt` — taking both would double
+            // every user turn.
+            if (state.seen.has('kimi:prompted'))
+                return [];
+            const message = objectField(record, 'message');
+            if (message?.['role'] !== 'user')
+                return [];
+            const text = blankToUndefined(partsText(message['content']));
+            if (text === undefined)
+                return [];
+            closeRun(state);
+            return emitUser(state, text);
+        }
+        case 'context.append_loop_event':
+            return stepLoopEvent(objectField(record, 'event') ?? {}, state, options);
+        case 'turn.ended':
+            closeRun(state);
+            return [];
+        default:
+            return [];
+    }
+}
+/** Fold one `context.append_loop_event`, where the newer wire keeps assistant content. */
+function stepLoopEvent(event, state, options) {
+    switch (event['type']) {
+        case 'content.part': {
+            const part = objectField(event, 'part') ?? {};
+            if (part['type'] === 'text')
+                appendChunk(state, OPEN_TEXT, part['text']);
+            else if (part['type'] === 'think' && options.includeThinking)
+                appendChunk(state, OPEN_THINK, part['think']);
+            return [];
+        }
+        case 'tool.call':
+            closeRun(state);
+            pushAssistant(state, renderToolCall(event['name'], event['args'], options.toolCalls, options.toolSummaryChars));
+            return [];
+        case 'tool.result':
+            closeRun(state);
+            pushAssistant(state, renderToolResult(event['output'] ?? event['result'] ?? event['content'], options.toolResults, options.toolSummaryChars));
+            return [];
+        case 'step.begin':
+        case 'step.end':
+            closeRun(state);
+            return [];
+        default:
+            // Everything else is internal bookkeeping.
+            return [];
+    }
+}
+/**
+ * Concatenate one streamed fragment onto the run of the same kind.
+ *
+ * Appends in place when a run of this kind is already open, because the
+ * fragments are halves of one sentence. Anything else — a different kind, a
+ * tool call, a step boundary — closes the run first, so the shared buffer's
+ * blank-line join only ever falls between things that really are separate.
+ * @param state - fold state, mutated in place.
+ * @param kind - which run this fragment belongs to.
+ * @param value - the fragment, of unknown type.
+ */
+function appendChunk(state, kind, value) {
+    if (typeof value !== 'string' || value === '')
+        return;
+    const last = state.pending.length - 1;
+    if (last >= 0 && state.seen.has(kind)) {
+        state.pending[last] = `${state.pending[last] ?? ''}${value}`;
+        return;
+    }
+    closeRun(state);
+    state.pending.push(value);
+    state.seen.add(kind);
+}
+/** End any open streamed run, so the next fragment starts its own entry. */
+function closeRun(state) {
+    state.seen.delete(OPEN_TEXT);
+    state.seen.delete(OPEN_THINK);
+}
+/**
+ * Flatten a Kimi `ContentPart` value to text.
+ *
+ * A prompt is a string on some builds and an array of `{text}` parts on
+ * others. Parts are joined without a separator: they are fragments of one
+ * message, not a list of messages.
+ * @param input - the raw value, of unknown shape.
+ * @returns the flattened text; empty when nothing readable was found.
+ */
+function partsText(input) {
+    if (typeof input === 'string')
+        return input;
+    if (!Array.isArray(input))
+        return '';
+    const parts = [];
+    for (const part of input) {
+        if (typeof part === 'string')
+            parts.push(part);
+        else if (typeof part === 'object' && part !== null) {
+            const text = part['text'];
+            if (typeof text === 'string')
+                parts.push(text);
+        }
+    }
+    return parts.join('');
+}

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

@@ -0,0 +1,21 @@
+/**
+ * OpenClaw sessions: `~/.openclaw/agents/<agent>/sessions/<id>.jsonl`.
+ *
+ * An event stream of two shapes: a `session` record carrying the id, `cwd`,
+ * and start time, then `message` records wrapping a Messages-API message whose
+ * content is either a string or a block array.
+ *
+ * The detail that needs handling is OpenClaw's gateway, which appends
+ * `\n[message_id: …]` to text it relays. It is routing metadata, and left in
+ * place it reads as part of what was said, so it is stripped from every body.
+ *
+ * OpenClaw also keeps the session's display name in a sibling `sessions.json`
+ * index rather than in the transcript. A pure adapter cannot open it, so the
+ * title falls to the opening prompt — which is what OpenClaw itself shows for
+ * an unnamed session anyway.
+ *
+ * @module dsh-reference-anything/local-agent/adapters/openclaw
+ */
+import type { TranscriptAdapter } from '../types.ts';
+/** Reads OpenClaw session transcripts. */
+export declare const openclawAdapter: TranscriptAdapter;

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

@@ -0,0 +1,120 @@
+/**
+ * OpenClaw sessions: `~/.openclaw/agents/<agent>/sessions/<id>.jsonl`.
+ *
+ * An event stream of two shapes: a `session` record carrying the id, `cwd`,
+ * and start time, then `message` records wrapping a Messages-API message whose
+ * content is either a string or a block array.
+ *
+ * The detail that needs handling is OpenClaw's gateway, which appends
+ * `\n[message_id: …]` to text it relays. It is routing metadata, and left in
+ * place it reads as part of what was said, so it is stripped from every body.
+ *
+ * OpenClaw also keeps the session's display name in a sibling `sessions.json`
+ * index rather than in the transcript. A pure adapter cannot open it, so the
+ * title falls to the opening prompt — which is what OpenClaw itself shows for
+ * an unnamed session anyway.
+ *
+ * @module dsh-reference-anything/local-agent/adapters/openclaw
+ */
+import { joinLocalPath } from "../path.js";
+import { arrayField, contentBlockUserText, createSharedState, emitUser, flushAssistant, normalizeTitle, objectField, parseRecord, parseTimestamp, pushAssistant, pushContentBlocks, renderToolResult, stringField, } from "./shared.js";
+/** Routing metadata the gateway appends to relayed text. */
+const MESSAGE_ID_SUFFIX = '\n[message_id:';
+/** Reads OpenClaw session transcripts. */
+export const openclawAdapter = {
+    kind: 'openclaw',
+    displayName: 'OpenClaw',
+    defaultRoots(home) {
+        return [joinLocalPath(home, '.openclaw', 'agents')];
+    },
+    matches(relativePath) {
+        const path = relativePath.toLowerCase();
+        return path.includes('/sessions/') && path.endsWith('.jsonl');
+    },
+    createState() {
+        return createSharedState();
+    },
+    step(line, state, options) {
+        const record = parseRecord(line);
+        if (record === undefined || record['type'] !== 'message')
+            return [];
+        const message = objectField(record, 'message');
+        if (message === undefined)
+            return [];
+        const content = message['content'];
+        if (message['role'] === 'user') {
+            const text = contentBlockUserText(content);
+            return text === undefined ? [] : emitUser(state, stripMessageId(text));
+        }
+        if (message['role'] === 'toolResult') {
+            pushAssistant(state, renderToolResult(content, options.toolResults, options.toolSummaryChars));
+            return [];
+        }
+        if (message['role'] !== 'assistant')
+            return [];
+        if (typeof content === 'string')
+            pushAssistant(state, stripMessageId(content));
+        else
+            pushContentBlocks(state, arrayField(message, 'content'), options);
+        return [];
+    },
+    flush(state, _options) {
+        return flushAssistant(state);
+    },
+    head(headLines, _tailLines) {
+        let cwd;
+        let createdAt;
+        let firstPrompt;
+        for (const line of headLines) {
+            const record = parseRecord(line);
+            if (record === undefined)
+                continue;
+            if (record['type'] === 'session') {
+                cwd ??= stringField(record, 'cwd');
+                createdAt ??= parseTimestamp(record['timestamp']);
+                continue;
+            }
+            if (record['type'] !== 'message' || firstPrompt !== undefined)
+                continue;
+            const message = objectField(record, 'message');
+            if (message?.['role'] !== 'user')
+                continue;
+            createdAt ??= parseTimestamp(record['timestamp']);
+            const text = contentBlockUserText(message['content']);
+            if (text !== undefined)
+                firstPrompt = stripMessageId(text);
+        }
+        const title = normalizeTitle(firstPrompt ?? basename(cwd) ?? '');
+        return {
+            ...title === '' ? {} : { title },
+            ...cwd === undefined ? {} : { cwd },
+            ...firstPrompt === undefined ? {} : { firstPrompt },
+            ...createdAt === undefined ? {} : { createdAt },
+        };
+    },
+};
+/**
+ * Drop the gateway's trailing `[message_id: …]` marker.
+ * @param text - one message body.
+ * @returns the body without the marker, or unchanged when it carried none.
+ */
+function stripMessageId(text) {
+    const at = text.lastIndexOf(MESSAGE_ID_SUFFIX);
+    return at === -1 ? text : text.slice(0, at).trimEnd();
+}
+/**
+ * The last segment of a recorded path, as a last-resort session name.
+ *
+ * Deliberately not `node:path`'s: the transcript may have been written on a
+ * different platform than the one reading it, so both separators are honoured
+ * regardless of which one this host uses.
+ * @param path - the recorded `cwd`, if there was one.
+ * @returns the final segment, or undefined when there is nothing to name.
+ */
+function basename(path) {
+    if (path === undefined)
+        return undefined;
+    const trimmed = path.replace(/[\\/]+$/u, '');
+    const segment = trimmed.split(/[\\/]/u).pop();
+    return segment === undefined || segment === '' ? undefined : segment;
+}

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

@@ -0,0 +1,44 @@
+/**
+ * Reads opencode's SQLite history, and mimocode's fork of it.
+ *
+ * opencode keeps every session it has ever run in one database under
+ * `~/.local/share/opencode/`, rather than one file per conversation. That single
+ * fact is why this is a {@link QueryAdapter} instead of a
+ * {@link TranscriptAdapter}: there is no byte offset that means "the start of
+ * this conversation", so a reference has to name the session as well as the
+ * file, and a listing is a query rather than a directory walk.
+ *
+ * mimocode is a fork of it, and older opencode builds differ from newer ones,
+ * so the columns that vary — `time_updated` here, `parent_id` in zcode — are
+ * probed rather than branched on a version number nobody writes down. What
+ * mimocode does not share is its background traffic: MiMo runs
+ * memory-consolidation and distillation sessions through the same tables as the
+ * user's own work, and those are filtered out of discovery.
+ *
+ * @module dsh-reference-anything/local-agent/adapters/opencode
+ */
+import type { QueryAdapter, SqliteReader } from '../types.ts';
+/** Reads opencode's session database. */
+export declare const opencodeAdapter: QueryAdapter;
+/** Reads mimocode's session database, minus its own background traffic. */
+export declare const mimocodeAdapter: QueryAdapter;
+/**
+ * Whether a session is MiMo's own background work rather than the user's.
+ *
+ * Exported for the tests, which is the only way to pin a filter whose whole job
+ * is to be invisible when it works.
+ * @param title - the session's recorded title.
+ * @returns whether discovery should hide it.
+ */
+export declare function isBackgroundSession(title: string): boolean;
+/**
+ * The working directory a session ran in, when the session row did not record one.
+ *
+ * Older opencode databases leave `session.directory` empty and put the path on
+ * each message instead, so this is the fallback discovery uses before deciding
+ * a session belongs to no workspace.
+ * @param db - a read-only reader over the database.
+ * @param sessionId - the conversation to inspect.
+ * @returns the recorded cwd, or undefined when no message carries one.
+ */
+export declare function sessionCwd(db: SqliteReader, sessionId: string): string | undefined;