dsh-reference-anything 0.4.3 → 0.5.0

package/lib/host.js

@@ -1,9 +1,75 @@
+import { AgentScanCache } from "./agent-scan-cache.js";
+import { localConversationRoots } from "./local-conversation-reader.js";
 import { TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
 import { tmpdir } from 'node:os';
 import { spawn } from 'node:child_process';
 import { validateDownloadDirectory } from "./download-directory.js";
+import { resolveLocalPlugins } from "./local-plugins.js";
+import { z } from 'zod';
+import { randomUUID } from 'node:crypto';
+import { discoverySchema, scanFormat, agentKind } from "./chat-import-discovery.js";
+import { ALL_LOCAL_AGENTS, LOCAL_AGENT_LABEL } from "./wire.js";
+import { expandRoot } from "./sources/local-agent/registry.js";
+import { homedir } from 'node:os';
+import { inWorkspace } from "./sources/local-agent/path.js";
+import { chatImportCompatibility, upgradeChatImport } from "./chat-import-compatibility.js";
+const importedItemSchema = z.object({
+    status: z.string(), sessionId: z.string().min(1).optional(),
+    error: z.string().optional(), reason: z.string().optional(), skipReason: z.string().optional(),
+});
+const chatImportResultSchema = z.discriminatedUnion('mode', [
+    importedItemSchema.extend({ mode: z.literal('single') }),
+    z.object({ mode: z.literal('batch'), results: z.array(importedItemSchema) }),
+]);
 export class ReferenceAnythingRemote extends TypertRemoteService {
+    async chatImportStatus() { return chatImportCompatibility(this.ctx); }
+    async chatImportUpgradeInstall(signal) {
+        await upgradeChatImport(this.ctx, signal);
+        return this.chatImportStatus();
+    }
+    agentScans = new AgentScanCache();
+    scannedTargets = new Map();
     constructor(ctx) { super(ctx, 'referenceAnything'); }
+    async agentResume(_agent, input, signal) {
+        signal.throwIfAborted();
+        this.assertScannedSelection(_agent, input.id);
+        const importer = this.ctx.get('chatImport');
+        if (typeof importer?.resumeSummary !== 'function')
+            throw new Error('Chat Import API unavailable. Open Reference Anything settings → Local Agent conversations to check compatibility and upgrade, then restart DSH.');
+        const agents = this.ctx.get('referenceLocalAgents');
+        if (!agents)
+            throw new Error('Local agent conversations are unavailable.');
+        const { format, path } = await agents.importTarget(input.id);
+        if (format !== 'claude' && format !== 'codex')
+            throw new Error('Chat Import Resume supports Claude Code and Codex only.');
+        signal.throwIfAborted();
+        const result = await importer.resumeSummary({ format, path }, signal);
+        return z.object({ summary: z.string().min(1) }).parse(result).summary;
+    }
+    async agentImport(_agent, input, signal) {
+        signal.throwIfAborted();
+        const importer = this.ctx.get('chatImport');
+        if (typeof importer?.importPath !== 'function')
+            throw new Error('Chat Import API unavailable. Open Reference Anything settings → Local Agent conversations to check compatibility and upgrade, then restart DSH.');
+        const agents = this.ctx.get('referenceLocalAgents');
+        if (!agents)
+            throw new Error('Local agent conversations are unavailable.');
+        const scanned = input.id.startsWith('scan:') || input.id.includes(':chat-import:')
+            ? this.scannedTargets.get(`${_agent.session.header.id}:${input.id}`) : undefined;
+        this.assertScannedSelection(_agent, input.id);
+        const target = scanned ? { format: scanned.format, path: scanned.path, sessionIds: scanned.sessionIds } : await agents.importTarget(input.id);
+        signal.throwIfAborted();
+        const result = await importer.importPath(target, signal);
+        const parsed = chatImportResultSchema.parse(result);
+        const items = parsed.mode === 'single' ? [parsed] : parsed.results;
+        if (items.length !== 1)
+            throw new Error('Expected exactly one imported conversation; no conversation was opened.');
+        const item = items[0];
+        if (!['imported', 'replaced', 'already-imported', 'appended'].includes(item.status) || !item.sessionId) {
+            throw new Error(`Conversation was not imported (${item.status}): ${item.error ?? item.reason ?? item.skipReason ?? ''}`);
+        }
+        return item.sessionId;
+    }
     /**
      * Discovery for the `@` menu's local-agent group.
      *
@@ -17,26 +83,144 @@ export class ReferenceAnythingRemote extends TypertRemoteService {
         const agents = this.ctx.get('referenceLocalAgents');
         if (agents === undefined)
             return [];
-        // A session with no cwd of its own is rare and has no workspace to scope
-        // to; falling back to the process's directory is the same guess the
-        // `ReferenceSource.list` seam makes, rather than an empty group.
-        const rows = await agents.listForWorkspace(input.query, input.limit, agent.session.header.cwd ?? process.cwd(), signal);
-        return rows.map(row => ({
-            id: row.ref.id,
-            kind: row.ref.id.slice(0, row.ref.id.indexOf(':')),
-            label: row.label,
-            provider: row.provider ?? '',
-            ...row.updatedAt === undefined ? {} : { updatedAt: row.updatedAt },
-            ...row.searchIncomplete === true ? { searchIncomplete: true } : {},
-        }));
+        const importer = this.ctx.get('chatImport');
+        {
+            const settings = this.ctx.referenceChatHistory.getSettings();
+            agents.setAgentDirectories(settings.agentDirectories ?? {});
+            const policy = agents.discoveryPolicy();
+            const requests = policy.roots.map(root => ({ format: scanFormat(root.kind), path: root.path }));
+            {
+                for (const kind of ALL_LOCAL_AGENTS) {
+                    if (!(settings.enabledAgents ?? ALL_LOCAL_AGENTS).includes(kind))
+                        continue;
+                    const format = scanFormat(kind);
+                    requests.push({ format });
+                    const custom = expandRoot(settings.agentDirectories?.[kind] ?? '', homedir());
+                    if (custom)
+                        requests.push({ format, path: custom });
+                }
+            }
+            const candidates = [];
+            const discovered = [];
+            const warnings = [];
+            const seen = new Set();
+            const owner = agent.session.header.id;
+            // Scope before scanning and deduplicate explicit roots repeated by settings.
+            const scannedRequests = new Set();
+            for (const request of requests) {
+                const kind = agentKind(request.format);
+                if ((input.kind && kind !== input.kind) || !(settings.enabledAgents ?? ALL_LOCAL_AGENTS).includes(kind))
+                    continue;
+                const requestKey = JSON.stringify([request.format, request.path ?? null]);
+                if (scannedRequests.has(requestKey))
+                    continue;
+                scannedRequests.add(requestKey);
+                signal.throwIfAborted();
+                try {
+                    const result = await agents.scanner.scanDiscover(request, signal);
+                    for (const warning of result.warnings)
+                        warnings.push({ id: `warning:${warnings.length}`, kind: 'scan-warning', label: warning.format, provider: '', warning: `${warning.target}: ${warning.error}` });
+                    for (const row of result.sessions) {
+                        const query = input.query.trim().toLowerCase();
+                        if (query && ![row.title, row.project, row.sourcePath].some(value => value?.toLowerCase().includes(query)))
+                            continue;
+                        const key = JSON.stringify([row.format, row.sourcePath, row.sessionId]);
+                        if ((input.kind && agentKind(row.format) !== input.kind) || seen.has(key) || (policy.scope === 'workspace' && !inWorkspace(row.cwd ?? '', agent.session.header.cwd ?? process.cwd())))
+                            continue;
+                        seen.add(key);
+                        discovered.push({ ...row });
+                    }
+                }
+                catch (error) {
+                    signal.throwIfAborted();
+                    warnings.push({ id: `warning:${warnings.length}`, kind: 'scan-warning', label: request.format, provider: '', warning: error instanceof Error ? error.message : String(error) });
+                }
+            }
+            if (importer?.scanDiscover) {
+                const statuses = new Map();
+                await Promise.all([...scannedRequests].map(async (key) => {
+                    const [format, path] = JSON.parse(key);
+                    try {
+                        const result = await this.agentScans.read(importer, '', key, () => importer.scanDiscover({ format, ...(path ? { path } : {}) }, AbortSignal.timeout(2_000)), AbortSignal.any([signal, AbortSignal.timeout(2_000)]));
+                        for (const row of result.sessions)
+                            statuses.set(JSON.stringify([row.format, row.sourcePath, row.sessionId]), row.importStatus);
+                    }
+                    catch {
+                        signal.throwIfAborted();
+                    }
+                }));
+                for (const row of discovered)
+                    row.importStatus = statuses.get(JSON.stringify([row.format, row.sourcePath, row.sessionId]));
+            }
+            discovered.sort((a, b) => (b.lastActiveAt ?? 0) - (a.lastActiveAt ?? 0));
+            for (const row of discovered) {
+                signal.throwIfAborted();
+                if (candidates.length >= input.limit)
+                    break;
+                if (!await agents.conversationAvailability.visible({ format: row.format, path: row.sourcePath, sessionId: row.sessionId }))
+                    continue;
+                const kind = agentKind(row.format);
+                const referenceId = await agents.referenceForDiscovered(kind, row.sourcePath, row.sessionId);
+                if (!referenceId && settings.picker?.agents.showImport === false)
+                    continue;
+                const id = referenceId ?? `scan:${randomUUID()}`;
+                if (!referenceId || referenceId.includes(':chat-import:')) {
+                    this.scannedTargets.set(`${owner}:${id}`, { owner, policy: JSON.stringify(settings), format: row.format, path: row.sourcePath, sessionIds: [row.sessionId] });
+                    if (this.scannedTargets.size > 2000)
+                        this.scannedTargets.delete(this.scannedTargets.keys().next().value);
+                }
+                candidates.push({ id, kind, label: row.title || row.sessionId, provider: LOCAL_AGENT_LABEL[kind] ?? row.format,
+                    ...(referenceId ? { referenceId } : { importOnly: true }), importStatus: row.importStatus,
+                    ...(row.lastActiveAt == null ? {} : { updatedAt: row.lastActiveAt }) });
+            }
+            return [...warnings, ...candidates];
+        }
     }
     async agentStats(signal) {
         signal.throwIfAborted();
         const agents = this.ctx.get('referenceLocalAgents');
         if (agents === undefined)
             return [];
-        agents.setAgentDirectories(this.ctx.referenceChatHistory.getSettings().agentDirectories ?? {});
-        return (await agents.stats(signal)).map(row => ({ agent: row.kind, conversations: row.conversations }));
+        const settings = this.ctx.referenceChatHistory.getSettings();
+        agents.setAgentDirectories(settings.agentDirectories ?? {});
+        const rows = [];
+        for (const kind of ALL_LOCAL_AGENTS) {
+            const format = scanFormat(kind);
+            signal.throwIfAborted();
+            const sessions = new Set();
+            const errors = [];
+            const custom = expandRoot(settings.agentDirectories?.[kind] ?? '', homedir());
+            for (const path of custom ? [undefined, custom] : [undefined]) {
+                try {
+                    const result = discoverySchema.parse(await agents.scanner.scanDiscover({ format, ...(path ? { path } : {}) }, signal));
+                    for (const row of result.sessions) {
+                        if (await agents.conversationAvailability.visible({ format: row.format, path: row.sourcePath, sessionId: row.sessionId }))
+                            sessions.add(JSON.stringify([row.sourcePath, row.sessionId]));
+                    }
+                    errors.push(...result.warnings.map(warning => `${warning.target}: ${warning.error}`));
+                }
+                catch (error) {
+                    signal.throwIfAborted();
+                    errors.push(error instanceof Error ? error.message : String(error));
+                }
+            }
+            rows.push({ agent: kind, conversations: sessions.size, ...(errors.length ? { error: errors.join('\n') } : {}) });
+        }
+        const roots = localConversationRoots();
+        return rows.map(row => {
+            const root = roots?.[scanFormat(row.agent)];
+            const custom = settings.agentDirectories?.[row.agent];
+            const paths = [...new Set([...(Array.isArray(root) ? root : root ? [root] : []), ...(custom ? [custom] : [])])];
+            return { ...row, ...(roots ? { paths } : {}), readable: true };
+        });
+    }
+    assertScannedSelection(agent, id) {
+        if (!id.startsWith('scan:') && !id.includes(':chat-import:'))
+            return;
+        const selected = this.scannedTargets.get(`${agent.session.header.id}:${id}`);
+        if (!selected || selected.owner !== agent.session.header.id || selected.policy !== JSON.stringify(this.ctx.referenceChatHistory.getSettings())) {
+            throw new Error('Conversation selection expired. Search and select it again.');
+        }
     }
     /**
      * Discovery for the `@` menu's cloud-drive group.
@@ -133,4 +317,8 @@ export class ReferenceAnythingRemote extends TypertRemoteService {
     async openListDisableMount(input, signal) { await this.ctx.openListManager.disableMount(input.id, input.disabled ?? true, signal); return true; }
     async openListRemoveMount(input, signal) { await this.ctx.openListManager.removeMount(input.id, signal); return true; }
     openListReindex(input, signal) { return this.ctx.openListManager.reindexMount(input.id, signal); }
+    localPlugins(signal) {
+        signal.throwIfAborted();
+        return resolveLocalPlugins(this.ctx);
+    }
 }

package/lib/index.d.ts

@@ -76,6 +76,8 @@ export default class ReferenceRuntime extends Service {
     assertGranted(sessionId: string | undefined, ref: ReferenceRef): void;
     /** Allow a gated URI granted live or named in this task's durable user/tool-result history. */
     assertSessionGranted(session: Session | undefined, ref: ReferenceRef): void;
+    /** Resolve short handles only against references already named in this task. */
+    resolveReadReference(session: Session | undefined, uri: string): ReferenceRef;
     /** Release task-local grants when a host knows the task is gone. */
     revoke(sessionId: string): void;
     /**
@@ -90,7 +92,7 @@ export default class ReferenceRuntime extends Service {
      * @param signal - cancellation from the caller.
      * @returns matching items, capped at `limit`.
      */
-    list(query?: string, limit?: number, signal?: AbortSignal): Promise<ReferenceSummary[]>;
+    list(query?: string, limit?: number, signal?: AbortSignal, externalOnly?: boolean): Promise<ReferenceSummary[]>;
     /**
      * Read one window of turns from a reference.
      * @param ref - the reference to resolve; its `source` selects the owning implementation.

package/lib/index.js

@@ -12,7 +12,7 @@
 import { Context, Service } from '@deepseek-ai/cordis';
 import z from '@deepseek-ai/schemastery';
 import { ReferenceAnythingError } from "./errors.js";
-import { mayContainReference, parseReferenceText } from "./uri.js";
+import { decodeReferenceUri, mayContainReference, parseReferenceText, referenceReadHandle } from "./uri.js";
 export { ReferenceAnythingError } from "./errors.js";
 export { REFERENCE_SCHEME, decodeReferenceUri, encodeReferenceUri, formatReferenceMention, mayContainReference, parseReferenceText, } from "./uri.js";
 /** Fan-out cap applied to discovery when a caller names no limit of its own. */
@@ -121,6 +121,34 @@ export default class ReferenceRuntime extends Service {
         }
         this.assertGranted(session && String(session.id), ref);
     }
+    /** Resolve short handles only against references already named in this task. */
+    resolveReadReference(session, uri) {
+        if (!uri.startsWith('ref:'))
+            return decodeReferenceUri(uri);
+        const candidates = [];
+        if (session) {
+            for (const key of this.grants.get(String(session.id)) ?? []) {
+                const separator = key.indexOf('\u0000');
+                candidates.push({ source: key.slice(0, separator), id: key.slice(separator + 1) });
+            }
+            for (const event of session.snapshotEvents()) {
+                const blocks = event.type === 'user/message' ? event.data.content
+                    : event.type === 'tool/result' ? event.data.message.content : [];
+                for (const block of blocks) {
+                    if (block.type !== 'text' || !mayContainReference(block.text))
+                        continue;
+                    try {
+                        candidates.push(...parseReferenceText(block.text).references.map(input => input.ref));
+                    }
+                    catch { /* Ignore malformed history. */ }
+                }
+            }
+        }
+        const matched = candidates.find(ref => ref.source !== 'local-agent' && referenceReadHandle(ref) === uri);
+        if (!matched)
+            throw new ReferenceAnythingError('Unknown reference handle in this task; use external_reference_list and copy its uri exactly.', 'CONVERSATION_REFERENCE_NOT_GRANTED');
+        return matched;
+    }
     /** Release task-local grants when a host knows the task is gone. */
     revoke(sessionId) { this.grants.delete(sessionId); }
     /**
@@ -135,9 +163,9 @@ export default class ReferenceRuntime extends Service {
      * @param signal - cancellation from the caller.
      * @returns matching items, capped at `limit`.
      */
-    async list(query = '', limit = this.listLimit, signal) {
+    async list(query = '', limit = this.listLimit, signal, externalOnly = false) {
         throwIfCancelled(signal);
-        const available = await this.availableSources(signal);
+        const available = (await this.availableSources(signal)).filter(source => !externalOnly || source.id !== 'local-agent');
         if (available.length === 0)
             return [];
         const settled = await Promise.allSettled(available.map(source => source.list(query, limit, signal)));

package/lib/local-conversation-reader.d.ts

@@ -0,0 +1,3 @@
+import { defaultRoots, readConversation } from '../vendor/chat-import-reader/parsers.mjs';
+export { defaultRoots as localConversationRoots };
+export declare function readLocalConversation(input: Parameters<typeof readConversation>[1], signal?: AbortSignal): Promise<unknown>;

package/lib/local-conversation-reader.js

@@ -0,0 +1,81 @@
+import { createReadStream } from 'node:fs';
+import { readFile, readdir, stat } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { homedir } from 'node:os';
+import { isAbsolute, join, resolve } from 'node:path';
+import { defaultRoots, readConversation } from '../vendor/chat-import-reader/parsers.mjs';
+export { defaultRoots as localConversationRoots };
+// The parser gets only filesystem reads, never the Cordis host context.
+export async function readLocalConversation(input, signal) {
+    if (!isAbsolute(input.path) || !input.sessionId)
+        throw new Error('Invalid conversation locator');
+    if (!Number.isSafeInteger(input.limit) || input.limit < 1 || input.limit > 100)
+        throw new Error('Invalid conversation page size');
+    if (input.before !== undefined && (!Number.isSafeInteger(input.before) || input.before < 0))
+        throw new Error('Invalid conversation page offset');
+    if (input.format === 'claude' && /\.json$/i.test(input.path)) {
+        const raw = await readFile(input.path, { encoding: 'utf8', signal });
+        let metadata;
+        try {
+            metadata = JSON.parse(raw);
+        }
+        catch { /* Line-based transcripts are parsed below. */ }
+        if (metadata && typeof metadata === 'object' && 'cliSessionId' in metadata && !('messages' in metadata)) {
+            throw new Error('Conversation body unavailable: this Claude Desktop file contains metadata only. Open the conversation in Claude Desktop to restore its transcript, then refresh and reselect it. Do not retry or search unrelated files.');
+        }
+    }
+    const fingerprints = [];
+    const versions = async () => Promise.all([input.path, input.path + '-wal'].map(async (path) => {
+        try {
+            const info = await stat(path);
+            return `${info.size}:${info.mtimeMs}`;
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return 'missing';
+            throw error;
+        }
+    }));
+    const initial = input.structured ? await versions() : [];
+    const target = (path) => ({ displayPath: resolve(path.startsWith('~/') || path.startsWith('~\\') ? join(homedir(), path.slice(2)) : path) });
+    const fs = {
+        streamText: async (value) => createReadStream(value.displayPath, { encoding: 'utf8', signal }),
+        resolve: async (path) => { signal?.throwIfAborted(); return target(path); },
+        processPath: (value) => value.displayPath,
+        stat: async (value) => {
+            signal?.throwIfAborted();
+            try {
+                const info = await stat(value.displayPath);
+                return { type: info.isDirectory() ? 'directory' : 'file', size: info.size, mtimeMs: info.mtimeMs, version: `${info.mtimeMs}:${info.size}` };
+            }
+            catch (error) {
+                if (error.code === 'ENOENT')
+                    return undefined;
+                throw error;
+            }
+        },
+        readText: async (value) => {
+            signal?.throwIfAborted();
+            const text = await readFile(value.displayPath, { encoding: 'utf8', signal });
+            if (input.structured)
+                fingerprints.push(createHash('sha256').update(text).digest('hex'));
+            return text;
+        },
+        listDir: async (value) => {
+            signal?.throwIfAborted();
+            return (await readdir(value.displayPath, { withFileTypes: true })).map(entry => ({
+                name: entry.name, type: entry.isDirectory() ? 'directory' : 'file', target: target(join(value.displayPath, entry.name)),
+            }));
+        },
+    };
+    const result = await readConversation(fs, input.structured ? { ...input, revision: undefined } : input, signal);
+    if (input.structured && result && typeof result === 'object' && 'revision' in result) {
+        const final = await versions();
+        if (JSON.stringify(initial) !== JSON.stringify(final))
+            throw new Error('Conversation changed while reading; retry to refresh the preview');
+        result.revision = createHash('sha256').update(JSON.stringify([result.revision, fingerprints, final])).digest('hex');
+        if (input.revision && input.revision !== result.revision)
+            throw new Error('Conversation changed; read its latest page again');
+    }
+    return result;
+}

package/lib/local-conversation-scanner.d.ts

@@ -0,0 +1,18 @@
+import { discoverySchema } from './chat-import-discovery.ts';
+type Input = {
+    format: string;
+    path?: string;
+    query?: string;
+};
+type Snapshot = ReturnType<typeof discoverySchema.parse>;
+/** Keep SQLite and large export scans outside the DSH event loop. */
+export declare class LocalConversationScanner {
+    private worker?;
+    private sequence;
+    private pending;
+    private cache;
+    scanDiscover(input: Input, signal?: AbortSignal): Promise<Snapshot>;
+    private scan;
+    dispose(error?: Error): void;
+}
+export {};

package/lib/local-conversation-scanner.js

@@ -0,0 +1,55 @@
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { AgentScanCache } from "./agent-scan-cache.js";
+import { discoverySchema } from "./chat-import-discovery.js";
+/** Keep SQLite and large export scans outside the DSH event loop. */
+export class LocalConversationScanner {
+    worker;
+    sequence = 0;
+    pending = new Map();
+    cache = new AgentScanCache(30_000);
+    async scanDiscover(input, signal = new AbortController().signal) {
+        const result = await this.cache.read(this, '', JSON.stringify([input.format, input.path]), () => this.scan(input), signal);
+        const query = input.query?.trim().toLowerCase();
+        return query ? { ...result, sessions: result.sessions.filter(row => [row.title, row.project, row.sourcePath].some(s => s?.toLowerCase().includes(query))) } : result;
+    }
+    scan(input) {
+        if (!this.worker) {
+            const worker = this.worker = spawn(process.execPath, ['--max-old-space-size=512', fileURLToPath(new URL('../vendor/chat-import-reader/scan-worker.mjs', import.meta.url))], {
+                windowsHide: true, stdio: ['ignore', 'ignore', 'ignore', 'ipc'],
+            });
+            worker.on('message', (message) => {
+                const request = this.pending.get(message.id);
+                if (!request)
+                    return;
+                clearTimeout(request.timer);
+                this.pending.delete(message.id);
+                if (message.error)
+                    request.reject(new Error(message.error));
+                else
+                    request.resolve(message.result);
+            });
+            worker.on('error', error => this.dispose(error));
+            worker.on('exit', code => this.dispose(new Error(`Conversation scanner exited (${code})`)));
+            worker.unref();
+            worker.channel?.unref();
+        }
+        return new Promise((resolve, reject) => {
+            const id = ++this.sequence;
+            const timer = setTimeout(() => this.dispose(new Error('Conversation scan timed out')), 30_000);
+            this.pending.set(id, { resolve, reject, timer });
+            this.worker.send({ id, input }, error => { if (error)
+                this.dispose(error); });
+        });
+    }
+    dispose(error = new Error('Conversation scanner stopped')) {
+        this.worker?.removeAllListeners();
+        this.worker?.kill();
+        this.worker = undefined;
+        for (const request of this.pending.values()) {
+            clearTimeout(request.timer);
+            request.reject(error);
+        }
+        this.pending.clear();
+    }
+}

package/lib/local-locator.d.ts

@@ -0,0 +1,14 @@
+/** Readable local locator shared by the composer and host. No Node imports. */
+export interface LocalLocator {
+    source: string;
+    path: string;
+    sessionId: string;
+}
+export declare const LOCAL_REFERENCE_SCHEME = "dsh-local:";
+export declare const LOCAL_REFERENCE_OPEN = "<local-agent-reference>";
+export declare const LOCAL_REFERENCE_CLOSE = "</local-agent-reference>";
+export declare function validateLocalLocator(value: unknown): LocalLocator;
+export declare function localLocatorFromId(id: string): LocalLocator;
+export declare function encodeLocalLocator(locator: LocalLocator): string;
+export declare function decodeLocalLocator(uri: string): LocalLocator;
+export declare function localLocatorId(locator: LocalLocator): string;

package/lib/local-locator.js

@@ -0,0 +1,34 @@
+export const LOCAL_REFERENCE_SCHEME = 'dsh-local:';
+export const LOCAL_REFERENCE_OPEN = '<local-agent-reference>';
+export const LOCAL_REFERENCE_CLOSE = '</local-agent-reference>';
+export function validateLocalLocator(value) {
+    if (!value || typeof value !== 'object')
+        throw new Error('Local reference must contain source, path and sessionId');
+    const { source, path, sessionId } = value;
+    if (![source, path, sessionId].every(v => typeof v === 'string' && v.length > 0 && v.length <= 16384 && !v.includes('\0')))
+        throw new Error('Local reference must contain source, path and sessionId');
+    return { source: source, path: path, sessionId: sessionId };
+}
+export function localLocatorFromId(id) {
+    const encoded = id.split(':chat-import:')[1];
+    if (!encoded)
+        throw new Error('Reselect this local conversation; the old reference protocol is no longer supported');
+    const base64 = encoded.replace(/-/g, '+').replace(/_/g, '/');
+    const parsed = JSON.parse(new TextDecoder().decode(Uint8Array.from(atob(base64), c => c.charCodeAt(0))));
+    return validateLocalLocator({ source: parsed.format, path: parsed.path, sessionId: parsed.sessionId });
+}
+export function encodeLocalLocator(locator) {
+    return LOCAL_REFERENCE_SCHEME + '?' + new URLSearchParams({ ...validateLocalLocator(locator) }).toString().replaceAll('(', '%28').replaceAll(')', '%29');
+}
+export function decodeLocalLocator(uri) {
+    if (!uri.startsWith(LOCAL_REFERENCE_SCHEME + '?'))
+        throw new Error('Invalid local conversation locator');
+    const fields = new URLSearchParams(uri.slice(LOCAL_REFERENCE_SCHEME.length + 1));
+    return validateLocalLocator({ source: fields.get('source'), path: fields.get('path'), sessionId: fields.get('sessionId') });
+}
+export function localLocatorId(locator) {
+    const kind = locator.source === 'claude' ? 'claude-code' : locator.source === 'gemini' ? 'gemini-cli' : locator.source;
+    const bytes = new TextEncoder().encode(JSON.stringify({ format: locator.source, path: locator.path, sessionId: locator.sessionId }));
+    const encoded = btoa(Array.from(bytes, byte => String.fromCharCode(byte)).join('')).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+    return `${kind}:chat-import:${encoded}`;
+}

package/lib/local-plugins.d.ts

@@ -0,0 +1,6 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { LocalPluginCandidate } from './contract.ts';
+import type { ReferenceSource } from './types.ts';
+export declare function createPluginReferenceSource(ctx: Context): ReferenceSource;
+/** Read the active loader's composed entries, including bundle patches and effective disables. */
+export declare function resolveLocalPlugins(ctx: Context): Promise<readonly LocalPluginCandidate[]>;