dsh-reference-anything 0.3.1 → 0.3.3

package/lib/sources/local-agent/adapters/sqlite-shared.d.ts

@@ -0,0 +1,92 @@
+/**
+ * What the three database-backed formats have in common.
+ *
+ * opencode, its fork mimocode, and zcode all store a conversation the same
+ * way — a `session` row, `message` rows under it, and `part` rows under those,
+ * each part a JSON blob naming its own type. The queries differ (zcode filters
+ * to main sessions, and each probes its own optional columns) and the message-level
+ * rules differ (zcode drops system prompts, opencode honours a `tail_start_id`),
+ * but the part-level projection is identical, and it is where all the fiddly
+ * work is. It lives here so one change to how a tool call renders reaches every
+ * database format at once.
+ *
+ * Everything below is pure: it takes a {@link SqliteReader}, never a driver.
+ *
+ * @module dsh-reference-anything/local-agent/adapters/sqlite-shared
+ */
+import type { AdapterState, ConvertOptions, ParsedTurn, SqliteReader } from '../types.ts';
+/** One message row with the parts that belong to it, in order. */
+export interface SessionMessage {
+    readonly id: string;
+    /** The message's own JSON payload: `role`, `path.cwd`, `agent`, `summary`… */
+    readonly data: Record<string, unknown>;
+    /** Its parts' JSON payloads, oldest first. */
+    readonly parts: readonly Record<string, unknown>[];
+}
+/** A session's messages, and whether older ones were left behind. */
+export interface SessionMessages {
+    readonly messages: readonly SessionMessage[];
+    /** The record cap was reached, so the oldest messages were not read. */
+    readonly truncated: boolean;
+}
+/**
+ * Read one session's messages, newest-anchored and bounded.
+ *
+ * Bounded from the *end* rather than the start, for the same reason the
+ * line-local reader anchors an oversized file to its tail: the newest turns are
+ * the ones a reader asking about a conversation almost always wants, and a
+ * bound that kept the oldest would return the setup and drop the answer.
+ * @param db - a read-only reader over the database.
+ * @param sessionId - the conversation to read.
+ * @param maxRecords - most message rows to materialize.
+ * @returns the messages oldest-first, and whether the cap cut any off.
+ */
+export declare function readSessionMessages(db: SqliteReader, sessionId: string, maxRecords: number): SessionMessages;
+/**
+ * The text a user typed, joined from the message's text parts.
+ *
+ * These agents inject their own material through the same `user` role a person
+ * types into — a `<system-reminder>` appended to a real question, a whole
+ * `AGENTS.md` wrapped in `<INSTRUCTIONS>` — so the same stripping the JSONL
+ * adapters apply is applied here. A message that was nothing but machinery
+ * collapses to an empty string and the caller emits no turn for it.
+ * @param message - one message row.
+ * @param strip - whether to remove harness-injected wrappers.
+ * @returns the prompt, or an empty string when the message carried no words.
+ */
+export declare function userPromptText(message: SessionMessage, strip?: boolean): string;
+/**
+ * Fold one assistant message's parts into the open assistant run.
+ *
+ * Structural parts — `step-start`, `step-finish`, `compaction`, `timeline`, and
+ * whatever a later build adds — carry nothing a reader can use and are skipped,
+ * which is what keeps a new part type from breaking an old adapter.
+ * @param state - fold state, mutated in place.
+ * @param message - the assistant message whose parts to project.
+ * @param options - projection settings.
+ */
+export declare function pushSessionParts(state: AdapterState, message: SessionMessage, options: ConvertOptions): void;
+/**
+ * Fold one message into the running conversation.
+ * @param state - fold state, mutated in place.
+ * @param message - the message to fold.
+ * @param options - projection settings.
+ * @returns turns this message completed, in order.
+ */
+export declare function stepSessionMessage(state: AdapterState, message: SessionMessage, options: ConvertOptions): readonly ParsedTurn[];
+/**
+ * Parse a `data` column, which every one of these schemas stores as JSON text.
+ * @param value - the raw column value.
+ * @returns the object, or undefined when the column is absent or not a JSON object.
+ */
+export declare function parseBlob(value: unknown): Record<string, unknown> | undefined;
+/** Read a nested string, treating a blank one as absent. */
+export declare function asText(value: unknown): string | undefined;
+/**
+ * Read a string field from a nested object, for the `path.cwd` shape both forks use.
+ * @param data - the message payload.
+ * @param outer - the containing object's key.
+ * @param inner - the key inside it.
+ * @returns the value, or undefined when either level is missing.
+ */
+export declare function nestedText(data: Record<string, unknown>, outer: string, inner: string): string | undefined;

package/lib/sources/local-agent/adapters/sqlite-shared.js

@@ -0,0 +1,215 @@
+/**
+ * What the three database-backed formats have in common.
+ *
+ * opencode, its fork mimocode, and zcode all store a conversation the same
+ * way — a `session` row, `message` rows under it, and `part` rows under those,
+ * each part a JSON blob naming its own type. The queries differ (zcode filters
+ * to main sessions, and each probes its own optional columns) and the message-level
+ * rules differ (zcode drops system prompts, opencode honours a `tail_start_id`),
+ * but the part-level projection is identical, and it is where all the fiddly
+ * work is. It lives here so one change to how a tool call renders reaches every
+ * database format at once.
+ *
+ * Everything below is pure: it takes a {@link SqliteReader}, never a driver.
+ *
+ * @module dsh-reference-anything/local-agent/adapters/sqlite-shared
+ */
+import { cleanUserText, emitUser, pushAssistant, renderToolCall, renderToolResult } from "./shared.js";
+/**
+ * Message ids bound into one `IN (…)` clause.
+ *
+ * SQLite accepts far more parameters than this, but a bounded chunk keeps the
+ * statement cache from being churned by a different arity per session.
+ */
+const ID_CHUNK = 400;
+/**
+ * Read one session's messages, newest-anchored and bounded.
+ *
+ * Bounded from the *end* rather than the start, for the same reason the
+ * line-local reader anchors an oversized file to its tail: the newest turns are
+ * the ones a reader asking about a conversation almost always wants, and a
+ * bound that kept the oldest would return the setup and drop the answer.
+ * @param db - a read-only reader over the database.
+ * @param sessionId - the conversation to read.
+ * @param maxRecords - most message rows to materialize.
+ * @returns the messages oldest-first, and whether the cap cut any off.
+ */
+export function readSessionMessages(db, sessionId, maxRecords) {
+    const cap = Math.max(1, Math.trunc(maxRecords));
+    const rows = db.all('SELECT id, time_created, data FROM message WHERE session_id = ? ORDER BY time_created DESC, id DESC LIMIT ?', sessionId, cap);
+    const ordered = [...rows].reverse();
+    const ids = ordered.map(row => String(row['id']));
+    const parts = readParts(db, ids);
+    const messages = [];
+    for (const row of ordered) {
+        const data = parseBlob(row['data']);
+        // A message whose payload is not JSON is dirty data, not a reason to fail
+        // the whole read; the conversation around it is still worth returning.
+        if (data === undefined)
+            continue;
+        const id = String(row['id']);
+        messages.push({ id, data, parts: parts.get(id) ?? [] });
+    }
+    return { messages, truncated: rows.length >= cap };
+}
+/** Fetch the parts of exactly the messages that were kept. */
+function readParts(db, ids) {
+    const byMessage = new Map();
+    for (let at = 0; at < ids.length; at += ID_CHUNK) {
+        const chunk = ids.slice(at, at + ID_CHUNK);
+        if (chunk.length === 0)
+            continue;
+        const holes = chunk.map(() => '?').join(',');
+        const rows = db.all(`SELECT message_id, data FROM part WHERE message_id IN (${holes}) ORDER BY time_created, id`, ...chunk);
+        for (const row of rows) {
+            const data = parseBlob(row['data']);
+            if (data === undefined)
+                continue;
+            const key = String(row['message_id']);
+            const bucket = byMessage.get(key);
+            if (bucket === undefined)
+                byMessage.set(key, [data]);
+            else
+                bucket.push(data);
+        }
+    }
+    return byMessage;
+}
+/**
+ * The text a user typed, joined from the message's text parts.
+ *
+ * These agents inject their own material through the same `user` role a person
+ * types into — a `<system-reminder>` appended to a real question, a whole
+ * `AGENTS.md` wrapped in `<INSTRUCTIONS>` — so the same stripping the JSONL
+ * adapters apply is applied here. A message that was nothing but machinery
+ * collapses to an empty string and the caller emits no turn for it.
+ * @param message - one message row.
+ * @param strip - whether to remove harness-injected wrappers.
+ * @returns the prompt, or an empty string when the message carried no words.
+ */
+export function userPromptText(message, strip = true) {
+    const texts = [];
+    for (const part of message.parts) {
+        if (part['type'] !== 'text')
+            continue;
+        const text = part['text'];
+        if (typeof text === 'string' && text.trim() !== '')
+            texts.push(text.trim());
+    }
+    const joined = texts.join('\n');
+    return strip ? cleanUserText(joined) : joined;
+}
+/**
+ * Fold one assistant message's parts into the open assistant run.
+ *
+ * Structural parts — `step-start`, `step-finish`, `compaction`, `timeline`, and
+ * whatever a later build adds — carry nothing a reader can use and are skipped,
+ * which is what keeps a new part type from breaking an old adapter.
+ * @param state - fold state, mutated in place.
+ * @param message - the assistant message whose parts to project.
+ * @param options - projection settings.
+ */
+export function pushSessionParts(state, message, options) {
+    for (const part of message.parts) {
+        switch (part['type']) {
+            case 'text':
+                pushAssistant(state, asText(part['text']));
+                break;
+            case 'reasoning':
+                if (options.includeThinking)
+                    pushAssistant(state, asText(part['text']));
+                break;
+            case 'tool': {
+                const state_ = part['state'];
+                const input = typeof state_ === 'object' && state_ !== null
+                    ? state_['input']
+                    : undefined;
+                pushAssistant(state, renderToolCall(part['tool'], input, options.toolCalls, options.toolSummaryChars));
+                if (typeof state_ === 'object' && state_ !== null) {
+                    const result = state_;
+                    const output = result['output'] ?? result['result'];
+                    if (output !== undefined)
+                        pushAssistant(state, renderToolResult(output, options.toolResults, options.toolSummaryChars));
+                }
+                break;
+            }
+            case 'file':
+                // No attachment handle is emitted: `reference_attachment_read` only
+                // serves the web-chat source, so a handle here would be a dead end.
+                pushAssistant(state, `[attachment: ${asText(part['filename']) ?? 'unknown'}]`);
+                break;
+            case 'patch': {
+                const files = part['files'];
+                pushAssistant(state, `[patch: ${Array.isArray(files) ? files.length : 0} files]`);
+                break;
+            }
+            case 'subtask': {
+                const command = asText(part['command']) ?? '';
+                const description = asText(part['description']) ?? '';
+                const detail = [command, description].filter(entry => entry !== '').join(' — ');
+                pushAssistant(state, `[subtask${detail === '' ? '' : `: ${detail}`}]`);
+                break;
+            }
+            default:
+                break;
+        }
+    }
+}
+/**
+ * Fold one message into the running conversation.
+ * @param state - fold state, mutated in place.
+ * @param message - the message to fold.
+ * @param options - projection settings.
+ * @returns turns this message completed, in order.
+ */
+export function stepSessionMessage(state, message, options) {
+    const role = message.data['role'];
+    if (role === 'user') {
+        const prompt = userPromptText(message, options.stripEnvironmentPreamble);
+        return prompt === '' ? [] : emitUser(state, prompt);
+    }
+    if (role !== 'assistant')
+        return [];
+    pushSessionParts(state, message, options);
+    return [];
+}
+/**
+ * Parse a `data` column, which every one of these schemas stores as JSON text.
+ * @param value - the raw column value.
+ * @returns the object, or undefined when the column is absent or not a JSON object.
+ */
+export function parseBlob(value) {
+    const text = typeof value === 'string'
+        ? value
+        : value instanceof Uint8Array
+            ? Buffer.from(value).toString('utf8')
+            : undefined;
+    if (text === undefined)
+        return undefined;
+    try {
+        const parsed = JSON.parse(text);
+        return typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)
+            ? parsed
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Read a nested string, treating a blank one as absent. */
+export function asText(value) {
+    return typeof value === 'string' && value.trim() !== '' ? value : undefined;
+}
+/**
+ * Read a string field from a nested object, for the `path.cwd` shape both forks use.
+ * @param data - the message payload.
+ * @param outer - the containing object's key.
+ * @param inner - the key inside it.
+ * @returns the value, or undefined when either level is missing.
+ */
+export function nestedText(data, outer, inner) {
+    const nested = data[outer];
+    if (typeof nested !== 'object' || nested === null)
+        return undefined;
+    return asText(nested[inner]);
+}

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

@@ -0,0 +1,41 @@
+/**
+ * Reads zcode's SQLite history.
+ *
+ * zcode (z.ai's CLI) keeps every session in `~/.zcode/cli/db/db.sqlite` with the
+ * same three tables opencode uses, which is why the part-level projection is
+ * shared. Three rules are its own:
+ *
+ * - **Subagent sessions are hidden.** A row with a `parent_id` is work zcode
+ *   spawned for itself; listing it would put a fragment of a conversation in the
+ *   menu beside the conversation it belongs to.
+ * - **System prompts are dropped.** zcode stores them as `role: 'system'`
+ *   messages in the same table as the conversation.
+ * - **Compaction is recorded twice.** A `compaction` part carries the summary,
+ *   and older builds hang it on the message instead. Either way the carrier is a
+ *   marker rather than something the user said, so the message is dropped and
+ *   the summary re-emitted once, ahead of the turns that survived.
+ *
+ * @module dsh-reference-anything/local-agent/adapters/zcode
+ */
+import type { QueryAdapter } from '../types.ts';
+import type { SessionMessage } from './sqlite-shared.ts';
+/** Reads zcode's session database. */
+export declare const zcodeAdapter: QueryAdapter;
+/**
+ * The summary carried by a `compaction` part, if this message has one.
+ *
+ * The part itself never reaches the reader — `pushSessionParts` skips every
+ * structural type — so this is the only thing that recovers it.
+ * @param message - one message row with its parts.
+ * @returns the summary text, or undefined when no part carried one.
+ */
+export declare function partSummary(message: SessionMessage): string | undefined;
+/**
+ * The summary hung on the message itself, which is where older builds put it.
+ *
+ * A message shaped this way is a marker rather than something the user said:
+ * its own body is a lead-in to the summary. The caller drops it.
+ * @param message - one message row.
+ * @returns the summary text, or undefined when this is ordinary conversation.
+ */
+export declare function messageSummary(message: SessionMessage): string | undefined;

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

@@ -0,0 +1,159 @@
+/**
+ * Reads zcode's SQLite history.
+ *
+ * zcode (z.ai's CLI) keeps every session in `~/.zcode/cli/db/db.sqlite` with the
+ * same three tables opencode uses, which is why the part-level projection is
+ * shared. Three rules are its own:
+ *
+ * - **Subagent sessions are hidden.** A row with a `parent_id` is work zcode
+ *   spawned for itself; listing it would put a fragment of a conversation in the
+ *   menu beside the conversation it belongs to.
+ * - **System prompts are dropped.** zcode stores them as `role: 'system'`
+ *   messages in the same table as the conversation.
+ * - **Compaction is recorded twice.** A `compaction` part carries the summary,
+ *   and older builds hang it on the message instead. Either way the carrier is a
+ *   marker rather than something the user said, so the message is dropped and
+ *   the summary re-emitted once, ahead of the turns that survived.
+ *
+ * @module dsh-reference-anything/local-agent/adapters/zcode
+ */
+import { joinLocalPath } from "../path.js";
+import { COMPACTION_MARKER, createSharedState, flushAssistant, normalizeTitle, parseTimestamp } from "./shared.js";
+import { readSessionMessages, stepSessionMessage } from "./sqlite-shared.js";
+/**
+ * The select list both queries share, with `$recency` standing for whichever
+ * timestamp column this build has. Aliased so the projection below reads one
+ * column name regardless.
+ */
+const SESSION_FIELDS = 'id, title, directory, $recency AS recency';
+/** Reads zcode's session database. */
+export const zcodeAdapter = {
+    kind: 'zcode',
+    displayName: 'zcode',
+    query: true,
+    defaultRoots(home) {
+        return [joinLocalPath(home, '.zcode', 'cli', 'db')];
+    },
+    matches(relativePath) {
+        // Exact, so SQLite's `-wal` and `-shm` sidecars are not opened as databases.
+        return relativePath.split(/[\\/]/u).at(-1) === 'db.sqlite';
+    },
+    sessions(db, limit) {
+        const columns = db.columns('session');
+        if (columns.size === 0)
+            return [];
+        // A build that predates `parent_id` has no subagent rows to exclude, so the
+        // predicate is dropped rather than made into a query error.
+        const scope = columns.has('parent_id') ? "WHERE parent_id IS NULL OR parent_id = ''" : '';
+        const recency = columns.has('time_updated') ? 'time_updated' : 'time_created';
+        const rows = db.all(`SELECT ${SESSION_FIELDS.replace('$recency', recency)} FROM session ${scope} ORDER BY recency DESC, id DESC LIMIT ?`, Math.max(1, Math.trunc(limit)));
+        const sessions = [];
+        for (const row of rows) {
+            const session = toSession(row);
+            if (session !== undefined)
+                sessions.push(session);
+        }
+        return sessions;
+    },
+    session(db, sessionId) {
+        const columns = db.columns('session');
+        if (columns.size === 0)
+            return undefined;
+        const recency = columns.has('time_updated') ? 'time_updated' : 'time_created';
+        // No `parent_id` predicate here: the subagent filter is about what the menu
+        // offers, and a caller holding an id has already got past the menu.
+        const [row] = db.all(`SELECT ${SESSION_FIELDS.replace('$recency', recency)} FROM session WHERE id = ? LIMIT 1`, sessionId);
+        return row === undefined ? undefined : toSession(row);
+    },
+    turns(db, sessionId, options, maxRecords) {
+        const { messages, truncated } = readSessionMessages(db, sessionId, maxRecords);
+        const state = createSharedState();
+        const items = [];
+        let summary;
+        const conversation = [];
+        for (const message of messages) {
+            if (message.data['role'] === 'system')
+                continue;
+            // Last compaction wins: an older summary describes history a newer one has
+            // already folded into itself.
+            const onPart = partSummary(message);
+            if (onPart !== undefined)
+                summary = onPart;
+            const onMessage = messageSummary(message);
+            if (onMessage !== undefined) {
+                // The older shape puts the summary on a message whose own body is just
+                // a lead-in, so the whole message goes; the part shape marks up a
+                // message that still carries conversation, and only the part goes.
+                summary = onMessage;
+                continue;
+            }
+            conversation.push(message);
+        }
+        if (summary !== undefined)
+            items.push({ role: 'assistant', text: `${COMPACTION_MARKER}\n\n${summary}` });
+        for (const message of conversation)
+            items.push(...stepSessionMessage(state, message, options));
+        items.push(...flushAssistant(state));
+        return { items, truncated, compacted: summary !== undefined };
+    },
+};
+/**
+ * Project one `session` row.
+ *
+ * zcode records a single timestamp per session in the column this build has, so
+ * a conversation's start and its last activity are the same instant here.
+ * @param row - the row as read, with its timestamp aliased to `recency`.
+ * @returns the session, or undefined when the row has no usable id.
+ */
+function toSession(row) {
+    const id = typeof row['id'] === 'string' ? row['id'] : String(row['id'] ?? '');
+    if (id === '')
+        return undefined;
+    const at = parseTimestamp(row['recency']) ?? 0;
+    return {
+        id,
+        title: normalizeTitle(row['title']),
+        cwd: typeof row['directory'] === 'string' ? row['directory'] : '',
+        createdAt: at,
+        updatedAt: at,
+    };
+}
+/**
+ * The summary carried by a `compaction` part, if this message has one.
+ *
+ * The part itself never reaches the reader — `pushSessionParts` skips every
+ * structural type — so this is the only thing that recovers it.
+ * @param message - one message row with its parts.
+ * @returns the summary text, or undefined when no part carried one.
+ */
+export function partSummary(message) {
+    for (const part of message.parts) {
+        if (part['type'] !== 'compaction')
+            continue;
+        const body = summaryBody(part['summary']);
+        if (body !== undefined)
+            return body;
+    }
+    return undefined;
+}
+/**
+ * The summary hung on the message itself, which is where older builds put it.
+ *
+ * A message shaped this way is a marker rather than something the user said:
+ * its own body is a lead-in to the summary. The caller drops it.
+ * @param message - one message row.
+ * @returns the summary text, or undefined when this is ordinary conversation.
+ */
+export function messageSummary(message) {
+    return summaryBody(message.data['summary']);
+}
+/** Read `summary.body`, which is where both shapes keep the text. */
+function summaryBody(summary) {
+    if (typeof summary !== 'object' || summary === null)
+        return undefined;
+    const body = summary['body'];
+    if (typeof body !== 'string')
+        return undefined;
+    const trimmed = body.trim();
+    return trimmed === '' ? undefined : trimmed;
+}