dsh-reference-anything 0.3.1 → 0.3.3

package/lib/sources/cloud-drive/registry.js

@@ -0,0 +1,101 @@
+/**
+ * Which drives this package can talk to, and how a reference names one.
+ *
+ * Kept pure — no cordis, no `node:fs` — so the routing rules can be tested
+ * without mounting a plugin or reaching a network.
+ *
+ * @module dsh-reference-anything/cloud-drive/registry
+ */
+import { ReferenceAnythingError } from "../../errors.js";
+import { OpenListDriveProvider } from "./providers/openlist.js";
+/** Every drive the package supports. */
+export const DRIVE_KINDS = ['openlist'];
+/**
+ * Constructors for the drives that actually work.
+ *
+ * `Partial` keeps startup validation explicit if a future declared drive has no
+ * implementation.
+ */
+export const DRIVE_PROVIDERS = {
+    openlist: options => new OpenListDriveProvider(options),
+};
+/**
+ * Build the provider for one drive.
+ *
+ * @param kind - which drive.
+ * @param options - transport and clock seams passed through to the provider.
+ * @returns the provider, or `undefined` when that drive has no implementation.
+ */
+export function providerFor(kind, options) {
+    return DRIVE_PROVIDERS[kind]?.(options);
+}
+/** Separator between the drive name and the drive's own file id. */
+const REF_SEPARATOR = ':';
+/**
+ * Compose the `id` half of a reference to one drive file.
+ *
+ * The drive name is carried in the id rather than in the source id so that all
+ * drives share one `ReferenceSource`, one grant gate, and one menu group.
+ *
+ * @param kind - which drive owns the file.
+ * @param fileId - the provider's own opaque id.
+ */
+export function encodeDriveId(kind, fileId) {
+    if (kind !== 'openlist')
+        throw new ReferenceAnythingError('cloud-drive: unsupported drive', 'REFERENCE_INVALID_URI');
+    const path = normalizeOpenListPath(fileId);
+    return `${kind}${REF_SEPARATOR}${Buffer.from(JSON.stringify({ v: 1, path }), 'utf8').toString('base64url')}`;
+}
+/**
+ * Split a reference id back into a drive and the provider's file id.
+ *
+ * Splits on the *first* separator only: a provider's id may itself contain
+ * one.
+ *
+ * @param id - the `id` half of a `dsh-ref:` reference this source owns.
+ * @throws ReferenceAnythingError when the id names no known drive.
+ */
+export function decodeDriveId(id) {
+    if (id.startsWith('baidu:') || id.startsWith('pds:')) {
+        throw new ReferenceAnythingError('cloud-drive: 旧版百度网盘/PDS 引用不能再读取；请在 OpenList 中重新选择该文件以迁移引用。', 'REFERENCE_INVALID_URI');
+    }
+    const cut = id.indexOf(REF_SEPARATOR);
+    const kind = cut === -1 ? '' : id.slice(0, cut);
+    const payload = cut === -1 ? '' : id.slice(cut + 1);
+    if (payload === '' || !isDriveKind(kind)) {
+        throw new ReferenceAnythingError(`cloud-drive: malformed reference id`, 'REFERENCE_INVALID_URI');
+    }
+    try {
+        if (!/^[A-Za-z0-9_-]+$/.test(payload))
+            throw new Error('not base64url');
+        const decoded = JSON.parse(Buffer.from(payload, 'base64url').toString('utf8'));
+        if (!isOpenListRef(decoded))
+            throw new Error('invalid shape');
+        return { kind, fileId: normalizeOpenListPath(decoded.path) };
+    }
+    catch {
+        throw new ReferenceAnythingError('cloud-drive: malformed OpenList reference id', 'REFERENCE_INVALID_URI');
+    }
+}
+/** Whether a string is one of the declared drive names. */
+export function isDriveKind(value) {
+    return DRIVE_KINDS.includes(value);
+}
+/** Normalize absolute OpenList paths and reject traversal rather than resolving it. */
+export function normalizeOpenListPath(value) {
+    if (typeof value !== 'string' || value.length === 0 || !value.startsWith('/') || value.includes('\\') || value.includes('\0')) {
+        throw new ReferenceAnythingError('cloud-drive: OpenList path must be absolute', 'REFERENCE_INVALID_URI');
+    }
+    const parts = value.split('/');
+    if (parts.some(part => part === '..')) {
+        throw new ReferenceAnythingError('cloud-drive: OpenList path traversal is not allowed', 'REFERENCE_INVALID_URI');
+    }
+    const clean = parts.filter(part => part !== '' && part !== '.');
+    return clean.length === 0 ? '/' : `/${clean.join('/')}`;
+}
+function isOpenListRef(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const row = value;
+    return row.v === 1 && typeof row.path === 'string' && Object.keys(row).length === 2;
+}

package/lib/sources/cloud-drive/types.d.ts

@@ -0,0 +1,169 @@
+/**
+ * Vocabulary for referencing files that live in a personal cloud drive.
+ *
+ * A drive is not a conversation, and the difference shapes everything here. A
+ * transcript is append-only and self-describing; a drive holds arbitrary bytes
+ * behind an authenticated, rate-limited, latency-bound API, and the same file
+ * can be reachable three different ways depending on what the provider has
+ * already indexed. So a provider is not a parser — it is a small transport
+ * that answers three questions: what is in here, is there text I can have
+ * without downloading, and can I read a byte range.
+ *
+ * The types are free of `node:fs` and cordis so a provider can be exercised
+ * against a stub `fetch` without mounting a plugin.
+ *
+ * @module dsh-reference-anything/cloud-drive/types
+ */
+import type { FetchLike } from './providers/http.ts';
+/**
+ * One supported drive product.
+ *
+ * OpenList is the only supported drive surface. Its stable locator is an
+ * absolute, normalized path encoded by the registry.
+ */
+export type DriveKind = 'openlist';
+/**
+ * One file or folder as listing sees it, without its bytes.
+ *
+ * Deliberately smaller than a `ReferenceSummary`: this is the provider's own
+ * vocabulary, and the mapping into the package's public wire types happens in
+ * one place so a provider cannot accidentally widen what reaches the client.
+ */
+export interface DriveEntry {
+    /** Which provider owns {@link DriveEntry.id}. */
+    readonly kind: DriveKind;
+    /**
+     * Provider-scoped opaque id, stable across listings.
+     *
+     * Never exposed as a raw download URL. OpenList uses an absolute normalized
+     * path internally and the registry encodes it into the public reference id.
+     */
+    readonly id: string;
+    /** Basename for display, never empty — a nameless file falls back to its id. */
+    readonly name: string;
+    /**
+     * Full path as the provider displays it.
+     *
+     * User-facing only: it is a label and never an argument.
+     */
+    readonly path: string;
+    /** Size in bytes; `0` for a folder. */
+    readonly size: number;
+    /** Last modification in Unix epoch milliseconds, when the provider reports it. */
+    readonly modifiedAt?: number;
+    /** Folders are listed so the menu can show structure, but they are not readable. */
+    readonly isDirectory: boolean;
+    /**
+     * Server-extracted passage that came back with this entry, if any.
+     *
+     * Only semantic search produces this — a directory listing never does. It is
+     * a *recalled passage*, not the document, so it is a preview and never a
+     * substitute for a real read.
+     *
+     * Never copied into a `ReferenceSummary`: summaries flow to the client and
+     * into snippet-adjacent surfaces, and body text belongs only inside
+     * `reference_read`'s untrusted-data envelope.
+     */
+    readonly excerpt?: string;
+    /** True only when this row came from a bounded traversal after indexed search was unavailable. */
+    readonly searchIncomplete?: boolean;
+}
+/** What one ranged read actually returned. */
+export interface DriveReadResult {
+    /** The bytes received, which may be fewer than requested at end of file. */
+    readonly bytes: Uint8Array;
+    /**
+     * Whether the provider honoured the requested range.
+     *
+     * `false` means it answered a range request with the whole file. The caller
+     * must be able to tell, because silently absorbing a multi-gigabyte body is
+     * the exact failure a ranged read exists to prevent.
+     */
+    readonly ranged: boolean;
+    /** Total file size when the response disclosed it, in bytes. */
+    readonly totalSize?: number;
+}
+/**
+ * One drive's transport: authentication, listing, and reading.
+ *
+ * Kept minimal on purpose. OpenList owns authentication, driver-specific
+ * details, and pagination behind its single filesystem surface.
+ */
+/**
+ * Construction-time seams every provider accepts.
+ *
+ * `root` is the absolute OpenList directory where browsing begins. Credentials
+ * live in the host-only OpenList credential file rather than plugin config.
+ */
+export interface DriveProviderOptions {
+    /** Where listing starts when the user has typed no query. */
+    readonly root?: string;
+    /** HTTP transport; defaults to the global `fetch`. */
+    readonly fetch?: FetchLike;
+    /** Clock in epoch milliseconds, for credential expiry and signed-URL aging. */
+    readonly now?: () => number;
+    /** Host-only OpenList credential file; defaults to the managed location. */
+    readonly configPath?: string;
+    /** Host-local credential supplier; ignored by non-OpenList transports. */
+    readonly credentials?: (refresh?: boolean) => Promise<{
+        readonly endpoint: string;
+        readonly token?: string;
+    } | undefined>;
+}
+export interface DriveProvider {
+    readonly kind: DriveKind;
+    /** Product name for menus and error text. */
+    readonly displayName: string;
+    /**
+     * Whether a usable credential exists locally.
+     *
+     * Must stay local: no network, no subprocess. Discovery calls this on every
+     * source before fanning out, and a configured-but-offline drive should
+     * report available and fail inside {@link DriveProvider.list} instead, so a
+     * dead network reads as a failed listing rather than a vanished menu group.
+     */
+    credentialed(): Promise<boolean>;
+    /**
+     * Enumerate entries matching a query.
+     * @param query - free text; empty means "the default directory listing".
+     * @param limit - hard cap on returned entries.
+     * @param signal - cancellation from the caller.
+     */
+    list(query: string, limit: number, signal?: AbortSignal): Promise<readonly DriveEntry[]>;
+    /**
+     * Describe one file without downloading it.
+     *
+     * Exists because a reference outlives the listing that produced it: a
+     * mention pasted into tomorrow's session names an id and nothing else, and
+     * the read that follows still has to report a label and decide whether the
+     * file is text before it spends a byte of transfer quota.
+     *
+     * @param id - a {@link DriveEntry.id} this provider owns.
+     * @param signal - cancellation from the caller.
+     * @returns the entry, or `undefined` when no such file exists.
+     */
+    describe(id: string, signal?: AbortSignal): Promise<DriveEntry | undefined>;
+    /**
+     * Tier 1: text the server already extracted, with no download.
+     * @returns the passage, or `undefined` when the provider has none — which is
+     * the common case and not an error.
+     */
+    extractedText(id: string, signal?: AbortSignal): Promise<string | undefined>;
+    /**
+     * Whether ranged reads work, or `undefined` until the first read has probed.
+     *
+     * Resolved at runtime rather than declared. A range request answered with
+     * `200` demotes the provider for the rest of the process.
+     */
+    supportsRange: boolean | undefined;
+    /**
+     * Read bytes `[start, end)`.
+     *
+     * @param id - a {@link DriveEntry.id} this provider owns.
+     * @param start - first byte, counted from zero.
+     * @param end - exclusive upper bound.
+     * @param signal - cancellation from the caller.
+     * @returns the bytes plus whether the range was honoured.
+     */
+    read(id: string, start: number, end: number, signal?: AbortSignal): Promise<DriveReadResult>;
+}

package/lib/sources/cloud-drive/types.js

@@ -0,0 +1,17 @@
+/**
+ * Vocabulary for referencing files that live in a personal cloud drive.
+ *
+ * A drive is not a conversation, and the difference shapes everything here. A
+ * transcript is append-only and self-describing; a drive holds arbitrary bytes
+ * behind an authenticated, rate-limited, latency-bound API, and the same file
+ * can be reachable three different ways depending on what the provider has
+ * already indexed. So a provider is not a parser — it is a small transport
+ * that answers three questions: what is in here, is there text I can have
+ * without downloading, and can I read a byte range.
+ *
+ * The types are free of `node:fs` and cordis so a provider can be exercised
+ * against a stub `fetch` without mounting a plugin.
+ *
+ * @module dsh-reference-anything/cloud-drive/types
+ */
+export {};

package/lib/sources/file.d.ts

@@ -46,6 +46,8 @@ export declare class FileReferenceSource implements ReferenceSource {
     private readonly roots;
     private readonly extensions;
     readonly id = "file";
+    /** Ungated on purpose: the configured roots are already inside the task's scope. */
+    readonly requiresGrant = false;
     /**
      * @param roots - absolute or process-relative directories to search.
      * @param extensions - file extensions treated as exports.

package/lib/sources/file.js

@@ -30,6 +30,8 @@ export class FileReferenceSource {
     roots;
     extensions;
     id = FILE_SOURCE_ID;
+    /** Ungated on purpose: the configured roots are already inside the task's scope. */
+    requiresGrant = false;
     /**
      * @param roots - absolute or process-relative directories to search.
      * @param extensions - file extensions treated as exports.

package/lib/sources/local-agent/adapters/claude-code.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Claude Code transcripts: `~/.claude/projects/<project-slug>/<uuid>.jsonl`.
+ *
+ * The file is an append-only log of everything the CLI drew, not a
+ * conversation: on a measured 70-file sample it held 6,277 `user` records of
+ * which only 565 carried a string body — the other 5,712 were arrays of
+ * `tool_result` blocks — against 11,434 `assistant` records that split text,
+ * reasoning, and each tool call into separate entries. Both facts drive the
+ * fold below, because projecting records one-to-one would bury the
+ * conversation under its own plumbing.
+ *
+ * @module dsh-reference-anything/local-agent/adapters/claude-code
+ */
+import type { TranscriptAdapter } from '../types.ts';
+/** Reads Claude Code's session transcripts. */
+export declare const claudeCodeAdapter: TranscriptAdapter;

package/lib/sources/local-agent/adapters/claude-code.js

@@ -0,0 +1,171 @@
+/**
+ * Claude Code transcripts: `~/.claude/projects/<project-slug>/<uuid>.jsonl`.
+ *
+ * The file is an append-only log of everything the CLI drew, not a
+ * conversation: on a measured 70-file sample it held 6,277 `user` records of
+ * which only 565 carried a string body — the other 5,712 were arrays of
+ * `tool_result` blocks — against 11,434 `assistant` records that split text,
+ * reasoning, and each tool call into separate entries. Both facts drive the
+ * fold below, because projecting records one-to-one would bury the
+ * conversation under its own plumbing.
+ *
+ * @module dsh-reference-anything/local-agent/adapters/claude-code
+ */
+import { joinLocalPath } from "../path.js";
+import { COMPACTION_MARKER, arrayField, cleanUserText, createSharedState, emitUser, flushAssistant, normalizeTitle, objectField, parseRecord, parseTimestamp, pushAssistant, renderToolCall, pushToolResults, stringField, } from "./shared.js";
+/** Reads Claude Code's session transcripts. */
+export const claudeCodeAdapter = {
+    kind: 'claude-code',
+    displayName: 'Claude Code',
+    defaultRoots(home) {
+        return [joinLocalPath(home, '.claude', 'projects')];
+    },
+    matches(relativePath) {
+        return relativePath.toLowerCase().endsWith('.jsonl');
+    },
+    createState() {
+        return createSharedState();
+    },
+    step(line, state, options) {
+        const record = parseRecord(line);
+        if (record === undefined)
+            return [];
+        // `isMeta` marks records the CLI generated about itself — the caveat that
+        // precedes a slash command's output, for one. They read as the user
+        // speaking and are not.
+        if (record['isMeta'] === true)
+            return [];
+        if (record['isSidechain'] === true && !options.includeSidechains)
+            return [];
+        const type = record['type'];
+        if (type === 'user')
+            return stepUser(record, state, options);
+        if (type === 'assistant')
+            return stepAssistant(record, state, options);
+        // Every other record type — `ai-title`, `last-prompt`, `mode`,
+        // `attachment`, `file-history-*`, `atis-latch` — is CLI state, not
+        // conversation. Titles come from head() instead, where a bounded probe can
+        // reach the newest one.
+        return [];
+    },
+    flush(state, _options) {
+        return flushAssistant(state);
+    },
+    head(headLines, tailLines) {
+        const found = {};
+        // Head first, then tail, and later wins for every field that can be
+        // rewritten: Claude Code re-emits `ai-title` as its guess improves — 1,421
+        // times across the same sample — so a head-only read gets a stale name.
+        for (const line of [...headLines, ...tailLines]) {
+            const record = parseRecord(line);
+            if (record === undefined)
+                continue;
+            const type = record['type'];
+            if (type === 'ai-title')
+                found.aiTitle = stringField(record, 'aiTitle') ?? found.aiTitle;
+            else if (type === 'summary')
+                found.summary = stringField(record, 'summary') ?? found.summary;
+            else if (type === 'last-prompt')
+                found.lastPrompt = stringField(record, 'lastPrompt') ?? found.lastPrompt;
+            found.slug = stringField(record, 'slug') ?? found.slug;
+            found.cwd = stringField(record, 'cwd') ?? found.cwd;
+            if (found.createdAt === undefined)
+                found.createdAt = parseTimestamp(record['timestamp']);
+        }
+        // The opening prompt comes from the head alone — the tail's user records
+        // are the newest ones and would name the wrong thing.
+        for (const line of headLines) {
+            const record = parseRecord(line);
+            if (record === undefined || record['type'] !== 'user')
+                continue;
+            if (record['isMeta'] === true || record['isCompactSummary'] === true)
+                continue;
+            const text = userText(record);
+            if (text !== undefined) {
+                found.firstPrompt = text;
+                break;
+            }
+        }
+        const title = normalizeTitle(found.aiTitle ?? found.summary ?? found.lastPrompt ?? found.slug ?? found.firstPrompt ?? '');
+        return {
+            ...title === '' ? {} : { title },
+            ...found.cwd === undefined ? {} : { cwd: found.cwd },
+            ...found.firstPrompt === undefined ? {} : { firstPrompt: found.firstPrompt },
+            ...found.createdAt === undefined ? {} : { createdAt: found.createdAt },
+        };
+    },
+};
+/** Fold one `user` record, which is a real turn far less often than it looks. */
+function stepUser(record, state, options) {
+    if (record['isCompactSummary'] === true || record['subtype'] === 'compact_boundary') {
+        state.compacted = true;
+        const summary = userText(record);
+        const closed = flushAssistant(state);
+        return summary === undefined
+            ? closed
+            : [...closed, { role: 'assistant', text: `${COMPACTION_MARKER}\n\n${summary}` }];
+    }
+    pushToolResults(state, objectField(record, 'message')?.['content'], options);
+    const text = userText(record);
+    return text === undefined ? [] : emitUser(state, text);
+}
+/** Fold one `assistant` record into the open run rather than into a turn of its own. */
+function stepAssistant(record, state, options) {
+    const blocks = arrayField(objectField(record, 'message'), 'content');
+    if (blocks === undefined)
+        return [];
+    for (const block of blocks) {
+        if (typeof block !== 'object' || block === null)
+            continue;
+        const entry = block;
+        switch (entry['type']) {
+            case 'text':
+                pushAssistant(state, typeof entry['text'] === 'string' ? entry['text'] : undefined);
+                break;
+            case 'thinking':
+                if (options.includeThinking) {
+                    pushAssistant(state, typeof entry['thinking'] === 'string' ? entry['thinking'] : undefined);
+                }
+                break;
+            case 'tool_use':
+                pushAssistant(state, renderToolCall(entry['name'], entry['input'], options.toolCalls, options.toolSummaryChars));
+                break;
+            default:
+                // `redacted_thinking` and anything a later CLI adds carry nothing a
+                // reader can use; silently skipping keeps new record shapes harmless.
+                break;
+        }
+    }
+    return [];
+}
+/**
+ * The words a person actually typed in one `user` record, if any.
+ *
+ * A string body is always a real turn. An array body is usually a batch of
+ * `tool_result` blocks the CLI attributes to the user role — plumbing, and the
+ * overwhelming majority — but occasionally carries `text` blocks, such as the
+ * note left when someone interrupts a tool call. So the discriminator is the
+ * block type, not the container type.
+ * @param record - one `user` record.
+ * @returns the user's text, or undefined when the record is not a turn.
+ */
+function userText(record) {
+    const content = objectField(record, 'message')?.['content'];
+    if (typeof content === 'string')
+        return blank(cleanUserText(content));
+    if (!Array.isArray(content))
+        return undefined;
+    const parts = [];
+    for (const block of content) {
+        if (typeof block !== 'object' || block === null)
+            continue;
+        const entry = block;
+        if (entry['type'] === 'text' && typeof entry['text'] === 'string')
+            parts.push(entry['text']);
+    }
+    return parts.length === 0 ? undefined : blank(cleanUserText(parts.join('\n')));
+}
+/** Collapse an empty result to `undefined`, so callers test one thing. */
+function blank(text) {
+    return text.trim() === '' ? undefined : text.trim();
+}

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

@@ -0,0 +1,20 @@
+/**
+ * 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 type { TranscriptAdapter } from '../types.ts';
+/** Reads Codex CLI rollout logs. */
+export declare const codexAdapter: TranscriptAdapter;