dsh-reference-anything 0.4.4 → 0.5.0

package/lib/contract.d.ts

@@ -3,7 +3,7 @@ import type { InvocationDescriptor } from '@deepseek-ai/dsh-typert-protocol';
 /**
  * One local-agent transcript as the `@` menu sees it.
  *
- * `id` is the source-scoped `kind:relPath`, not a `dsh-ref:` URI — the client
+ * `id` is a source-scoped `kind:relPath` or an opaque import-only selection, not a `dsh-ref:` URI — the client
  * wraps it, the way it does for web chats, so the `'local-agent'` source string
  * stays hardcoded in exactly one place. Deliberately carries no `origin`: the
  * absolute path adds nothing a menu row can use and everything a screen-share
@@ -15,9 +15,19 @@ export declare const agentCandidateSchema: z.ZodReadonly<z.ZodObject<{
     label: z.ZodString;
     provider: z.ZodString;
     updatedAt: z.ZodOptional<z.ZodNumber>;
+    referenceId: z.ZodOptional<z.ZodString>;
+    importOnly: z.ZodOptional<z.ZodBoolean>;
+    importStatus: z.ZodOptional<z.ZodEnum<{
+        imported: "imported";
+        partial: "partial";
+        "not-imported": "not-imported";
+        archived: "archived";
+    }>>;
+    warning: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>>;
 export declare const agentStatsSchema: z.ZodReadonly<z.ZodObject<{
     agent: z.ZodEnum<{
+        chatgpt: "chatgpt";
         kimi: "kimi";
         "claude-code": "claude-code";
         codex: "codex";
@@ -32,8 +42,26 @@ export declare const agentStatsSchema: z.ZodReadonly<z.ZodObject<{
         opencode: "opencode";
         mimocode: "mimocode";
         zcode: "zcode";
+        antigravity: "antigravity";
+        kilocode: "kilocode";
+        workbuddy: "workbuddy";
+        qwen: "qwen";
+        continue: "continue";
+        cline: "cline";
+        goose: "goose";
+        dsh4: "dsh4";
+        zed: "zed";
+        crush: "crush";
+        teleagent: "teleagent";
+        trae: "trae";
+        vibe: "vibe";
+        dsh: "dsh";
     }>;
     conversations: z.ZodNumber;
+    error: z.ZodOptional<z.ZodString>;
+    unavailable: z.ZodOptional<z.ZodBoolean>;
+    paths: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    readable: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>>;
 export declare const driveCandidateSchema: z.ZodReadonly<z.ZodObject<{
     id: z.ZodString;
@@ -71,8 +99,8 @@ export declare const searchInputSchema: z.ZodReadonly<z.ZodObject<{
     limit: z.ZodNumber;
 }, z.core.$strip>>;
 export declare const matchedViaSchema: z.ZodEnum<{
-    recent: "recent";
     title: "title";
+    recent: "recent";
     content: "content";
 }>;
 export declare const searchResultSchema: z.ZodReadonly<z.ZodObject<{
@@ -92,8 +120,8 @@ export declare const searchResultSchema: z.ZodReadonly<z.ZodObject<{
     partial: z.ZodBoolean;
     syncedAt: z.ZodString;
     matchedVia: z.ZodEnum<{
-        recent: "recent";
         title: "title";
+        recent: "recent";
         content: "content";
     }>;
     snippet: z.ZodOptional<z.ZodString>;
@@ -120,6 +148,9 @@ export declare const healthSchema: z.ZodReadonly<z.ZodObject<{
     }>;
     extensionVersion: z.ZodOptional<z.ZodString>;
     profileCount: z.ZodOptional<z.ZodNumber>;
+    latestExtensionVersion: z.ZodOptional<z.ZodString>;
+    extensionUpdateAvailable: z.ZodOptional<z.ZodBoolean>;
+    extensionCompatible: z.ZodOptional<z.ZodBoolean>;
     opencliCompatible: z.ZodBoolean;
     daemonVersion: z.ZodOptional<z.ZodString>;
     daemonStale: z.ZodBoolean;
@@ -155,6 +186,8 @@ export declare const packageUpdateStatusSchema: z.ZodReadonly<z.ZodObject<{
     releaseNotes: z.ZodOptional<z.ZodString>;
     releaseUrl: z.ZodOptional<z.ZodString>;
     error: z.ZodOptional<z.ZodString>;
+    currentReleaseNotes: z.ZodOptional<z.ZodString>;
+    currentReleaseUrl: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>>;
 export declare const packageUpdateResultSchema: z.ZodReadonly<z.ZodObject<{
     version: z.ZodString;
@@ -465,4 +498,18 @@ export declare const openListDisableMountSchema: z.ZodReadonly<z.ZodObject<{
 export declare const openListUpgradeInputSchema: z.ZodReadonly<z.ZodObject<{
     rollback: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strict>>;
+export declare const chatImportCompatibilitySchema: z.ZodReadonly<z.ZodObject<{
+    state: z.ZodEnum<{
+        unavailable: "unavailable";
+        disabled: "disabled";
+        ready: "ready";
+        incompatible: "incompatible";
+        installing: "installing";
+        "restart-required": "restart-required";
+    }>;
+    version: z.ZodString;
+    missing: z.ZodArray<z.ZodString>;
+    canUpgrade: z.ZodBoolean;
+    error: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>>;
 export declare const REFERENCE_ANYTHING_INVOCATIONS: readonly InvocationDescriptor[];

package/lib/contract.js

@@ -3,14 +3,14 @@ import { localAgentSchema, providerSchema, settingsRecordSchema } from "./wire.j
 /**
  * One local-agent transcript as the `@` menu sees it.
  *
- * `id` is the source-scoped `kind:relPath`, not a `dsh-ref:` URI — the client
+ * `id` is a source-scoped `kind:relPath` or an opaque import-only selection, not a `dsh-ref:` URI — the client
  * wraps it, the way it does for web chats, so the `'local-agent'` source string
  * stays hardcoded in exactly one place. Deliberately carries no `origin`: the
  * absolute path adds nothing a menu row can use and everything a screen-share
  * leaks.
  */
-export const agentCandidateSchema = z.object({ id: z.string(), kind: z.string(), label: z.string(), provider: z.string(), updatedAt: z.number().optional() }).readonly();
-export const agentStatsSchema = z.object({ agent: localAgentSchema, conversations: z.number().int().nonnegative() }).readonly();
+export const agentCandidateSchema = z.object({ id: z.string(), kind: z.string(), label: z.string(), provider: z.string(), updatedAt: z.number().optional(), referenceId: z.string().optional(), importOnly: z.boolean().optional(), importStatus: z.enum(['imported', 'partial', 'not-imported', 'archived']).optional(), warning: z.string().optional() }).readonly();
+export const agentStatsSchema = z.object({ agent: localAgentSchema, conversations: z.number().int().nonnegative(), error: z.string().optional(), unavailable: z.boolean().optional(), paths: z.array(z.string()).optional(), readable: z.boolean().optional() }).readonly();
 // `origin` is the drive's own display path, shown under the candidate. It is
 // never a download URL: those are signed with the account's credential and
 // must not cross this wire.
@@ -49,6 +49,7 @@ export const healthSchema = z.object({
     version: z.string(), daemon: z.string(), pluginInstalled: z.boolean(),
     daemonRunning: z.boolean(), extensionConnected: z.boolean(), extensionState: extensionStateSchema,
     extensionVersion: z.string().optional(), profileCount: z.number().int().nonnegative().optional(),
+    latestExtensionVersion: z.string().optional(), extensionUpdateAvailable: z.boolean().optional(), extensionCompatible: z.boolean().optional(),
     opencliCompatible: z.boolean(), daemonVersion: z.string().optional(), daemonStale: z.boolean(),
     connectivityOk: z.boolean(), connectivityChecked: z.boolean(), pluginVersion: z.string().optional(), adapterCommandsReady: z.boolean(), adapterCompatible: z.boolean(), latestVersion: z.string().optional(), updateAvailable: z.boolean(),
     versionError: z.string().optional(), daemonError: z.string().optional(), pluginError: z.string().optional(), doctorError: z.string().optional(),
@@ -60,6 +61,7 @@ export const openCliDiscoverySchema = z.object({
 export const packageUpdateStatusSchema = z.object({
     currentVersion: z.string(), latestVersion: z.string(), updateAvailable: z.boolean(),
     checkedAt: z.number().int().nonnegative(), releaseNotes: z.string().max(12_000).optional(), releaseUrl: z.string().url().optional(), error: z.string().optional(),
+    currentReleaseNotes: z.string().max(12_000).optional(), currentReleaseUrl: z.string().url().optional(),
 }).readonly();
 export const packageUpdateResultSchema = z.object({
     version: z.string(), restartRequired: z.boolean(),
@@ -125,8 +127,16 @@ export const openListMountCreateSchema = z.object({ id: z.string().min(1).option
 export const openListMountInputSchema = z.object({ id: z.string().min(1) }).strict().readonly();
 export const openListDisableMountSchema = z.object({ id: z.string().min(1), disabled: z.boolean().optional() }).strict().readonly();
 export const openListUpgradeInputSchema = z.object({ rollback: z.boolean().optional() }).strict().readonly();
+export const chatImportCompatibilitySchema = z.object({
+    state: z.enum(['ready', 'incompatible', 'unavailable', 'disabled', 'installing', 'restart-required']),
+    version: z.string(), missing: z.array(z.string()), canUpgrade: z.boolean(), error: z.string().optional(),
+}).strict().readonly();
 export const REFERENCE_ANYTHING_INVOCATIONS = [
-    descriptor('agentSearch', [agentLookup, { name: 'input', wire: 'input', source: 'json', codec: strict('AgentSearchInput', z.object({ query: z.string(), limit: z.number().int().min(1).max(100) }).readonly()) }], strict('AgentCandidate[]', z.array(agentCandidateSchema)), true),
+    descriptor('chatImportStatus', [], strict('ChatImportCompatibility', chatImportCompatibilitySchema)),
+    descriptor('chatImportUpgradeInstall', [], strict('ChatImportCompatibility', chatImportCompatibilitySchema), true),
+    descriptor('agentResume', [agentLookup, { name: 'input', wire: 'input', source: 'json', codec: strict('AgentResumeInput', z.object({ id: z.string().min(1) }).strict().readonly()) }], strict('ResumeSummary', z.string().min(1)), true),
+    descriptor('agentImport', [agentLookup, { name: 'input', wire: 'input', source: 'json', codec: strict('AgentImportInput', z.object({ id: z.string().min(1) }).strict().readonly()) }], strict('ImportedSessionId', z.string().min(1)), true),
+    descriptor('agentSearch', [agentLookup, { name: 'input', wire: 'input', source: 'json', codec: strict('AgentSearchInput', z.object({ query: z.string(), limit: z.number().int().min(1).max(100), kind: localAgentSchema.optional() }).readonly()) }], strict('AgentCandidate[]', z.array(agentCandidateSchema)), true),
     descriptor('agentStats', [], strict('AgentStats[]', z.array(agentStatsSchema)), true),
     // No session lookup, unlike `agentSearch`: a drive is the same drive from
     // every workspace, so there is nothing to scope the query to.

package/lib/conversation-availability.d.ts

@@ -0,0 +1,13 @@
+import type { ChatImportTarget } from './chat-import-reader.ts';
+/** Unknown/error rows stay visible. One background parser never delays discovery. */
+export declare class ConversationAvailability {
+    private cache;
+    private queued;
+    private worker?;
+    private active?;
+    private timer?;
+    visible(target: ChatImportTarget): Promise<boolean>;
+    private next;
+    private failed;
+    dispose(): void;
+}

package/lib/conversation-availability.js

@@ -0,0 +1,76 @@
+import { stat } from 'node:fs/promises';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+/** Unknown/error rows stay visible. One background parser never delays discovery. */
+export class ConversationAvailability {
+    cache = new Map();
+    queued = new Map();
+    worker;
+    active;
+    timer;
+    async visible(target) {
+        const key = JSON.stringify(target);
+        const entry = this.cache.get(key);
+        if (entry) {
+            const unchanged = (await Promise.all(entry.dependencies.map(async ([path, version]) => {
+                try {
+                    const s = await stat(path);
+                    return version === `${s.size}:${s.mtimeMs}:${s.ctimeMs}`;
+                }
+                catch (error) {
+                    return error.code === 'ENOENT' && version === 'missing';
+                }
+            }))).every(Boolean);
+            if (unchanged && (entry.state !== 'unknown' || Date.now() - entry.checked < 300_000))
+                return entry.state !== 'empty';
+            this.cache.delete(key);
+        }
+        if (this.active !== key && this.queued.size < 128)
+            this.queued.set(key, target);
+        this.next();
+        return true;
+    }
+    next() {
+        if (this.active || !this.queued.size)
+            return;
+        const [id, target] = this.queued.entries().next().value;
+        this.queued.delete(id);
+        this.active = id;
+        if (!this.worker) {
+            // Native parser failures and V8 OOM must not terminate the DSH host.
+            this.worker = spawn(process.execPath, ['--max-old-space-size=256', fileURLToPath(new URL('../vendor/chat-import-reader/availability-worker.mjs', import.meta.url))], {
+                windowsHide: true, stdio: ['ignore', 'ignore', 'ignore', 'ipc'],
+            });
+            this.worker.on('message', (result) => {
+                if (result.id !== this.active)
+                    return;
+                clearTimeout(this.timer);
+                if (this.cache.size >= 2000)
+                    this.cache.delete(this.cache.keys().next().value);
+                this.cache.set(result.id, { ...result, checked: Date.now() });
+                this.active = undefined;
+                this.next();
+            });
+            this.worker.on('error', () => this.failed());
+            this.worker.on('exit', () => this.failed());
+            this.worker.unref();
+            this.worker.channel?.unref();
+        }
+        this.timer = setTimeout(() => this.failed(), 15_000);
+        this.timer.unref();
+        this.worker.send({ id, target });
+    }
+    failed() {
+        if (this.active)
+            this.cache.set(this.active, { state: 'unknown', dependencies: [], checked: Date.now() });
+        this.dispose();
+        this.next();
+    }
+    dispose() {
+        clearTimeout(this.timer);
+        this.worker?.removeAllListeners();
+        this.worker?.kill();
+        this.worker = undefined;
+        this.active = undefined;
+    }
+}

package/lib/errors.d.ts

@@ -5,9 +5,9 @@
  */
 import { HarnessError } from '@deepseek-ai/dsh-llm';
 /** Stable, machine-routable failure classes; route on these, never on message text. */
-export type ReferenceErrorCode = 
+export type ReferenceErrorCode = 'INVALID_ARGUMENT' | 'SOURCE_DISABLED' | 'ACCESS_DENIED' | 'NOT_FOUND' | 'REVISION_REQUIRED' | 'REVISION_CHANGED' | 'UNSUPPORTED_PART' | 'IMAGE_UNAVAILABLE' | 'IMAGE_TOO_LARGE' | 'BUDGET_TOO_SMALL' | 'READ_FAILED' | 'TIMEOUT' | 'CANCELLED'
 /** Two sources claimed the same registry id. */
-'SOURCE_DUPLICATE'
+ | 'SOURCE_DUPLICATE'
 /** A reference named a source that is not registered. */
  | 'SOURCE_UNKNOWN'
 /** The owning source is registered but reported itself unusable. */

package/lib/host.d.ts

@@ -3,8 +3,50 @@ import { TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
 import type { ChatProvider, SettingsRecord } from './store/spec.ts';
 import type { SyncMode } from './sync/index.ts';
 import type { Agent } from '@deepseek-ai/dsh-agent';
+import { type LocalAgent } from './wire.ts';
+import type { AgentCandidate } from './client/remote.ts';
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        chatImport: {
+            readConversation?(input: {
+                format: string;
+                path: string;
+                sessionId?: string;
+                limit?: number;
+                before?: number;
+                revision?: string;
+                detail?: 'summary' | 'full';
+            }, signal?: AbortSignal): Promise<unknown>;
+            discoveryRoots?(): Record<string, string | string[] | null>;
+            scanDiscover(input: {
+                format?: string;
+                path?: string;
+                query?: string;
+            }, signal?: AbortSignal): Promise<unknown>;
+            importPath(input: {
+                format: string;
+                path: string;
+                sessionIds?: string[];
+            }, signal?: AbortSignal): Promise<unknown>;
+            resumeSummary(input: {
+                format: 'claude' | 'codex';
+                path: string;
+            }, signal?: AbortSignal): Promise<unknown>;
+        };
+    }
+}
 export declare class ReferenceAnythingRemote extends TypertRemoteService {
+    chatImportStatus(): Promise<import("./chat-import-compatibility.ts").ChatImportCompatibility>;
+    chatImportUpgradeInstall(signal: AbortSignal): Promise<import("./chat-import-compatibility.ts").ChatImportCompatibility>;
+    private readonly agentScans;
+    private readonly scannedTargets;
     constructor(ctx: Context);
+    agentResume(_agent: Agent, input: {
+        id: string;
+    }, signal: AbortSignal): Promise<string>;
+    agentImport(_agent: Agent, input: {
+        id: string;
+    }, signal: AbortSignal): Promise<string>;
     /**
      * Discovery for the `@` menu's local-agent group.
      *
@@ -17,18 +59,17 @@ export declare class ReferenceAnythingRemote extends TypertRemoteService {
     agentSearch(agent: Agent, input: {
         query: string;
         limit: number;
-    }, signal: AbortSignal): Promise<{
-        searchIncomplete?: boolean | undefined;
-        updatedAt?: number | undefined;
-        id: string;
-        kind: string;
-        label: string;
-        provider: string;
-    }[]>;
+        kind?: LocalAgent;
+    }, signal: AbortSignal): Promise<AgentCandidate[]>;
     agentStats(signal: AbortSignal): Promise<{
-        agent: import("./sources/local-agent/types.ts").AgentKind;
+        readable: boolean;
+        paths?: string[];
+        agent: LocalAgent;
         conversations: number;
+        error?: string;
+        unavailable?: boolean;
     }[]>;
+    private assertScannedSelection;
     /**
      * Discovery for the `@` menu's cloud-drive group.
      *
@@ -86,10 +127,10 @@ export declare class ReferenceAnythingRemote extends TypertRemoteService {
         historyMode: "metadata-only" | "offline-mirror";
         syncHistoryDays: number | null;
         enabledProviders: ("chatgpt" | "claude" | "gemini" | "deepseek" | "grok" | "kimi")[];
-        enabledAgents: ("kimi" | "claude-code" | "codex" | "cursor" | "qoder" | "reasonix" | "openclaw" | "grokbuild" | "hermes" | "gemini-cli" | "pi" | "opencode" | "mimocode" | "zcode")[];
+        enabledAgents: ("chatgpt" | "kimi" | "claude-code" | "codex" | "cursor" | "qoder" | "reasonix" | "openclaw" | "grokbuild" | "hermes" | "gemini-cli" | "pi" | "opencode" | "mimocode" | "zcode" | "antigravity" | "kilocode" | "workbuddy" | "qwen" | "continue" | "cline" | "goose" | "dsh4" | "zed" | "crush" | "teleagent" | "trae" | "vibe" | "dsh")[];
         maxReadTurns: number;
         inputRenderMode: "pill" | "raw-text";
-        agentDirectories?: Partial<Record<"kimi" | "claude-code" | "codex" | "cursor" | "qoder" | "reasonix" | "openclaw" | "grokbuild" | "hermes" | "gemini-cli" | "pi" | "opencode" | "mimocode" | "zcode", string>> | undefined;
+        agentDirectories?: Partial<Record<"chatgpt" | "kimi" | "claude-code" | "codex" | "cursor" | "qoder" | "reasonix" | "openclaw" | "grokbuild" | "hermes" | "gemini-cli" | "pi" | "opencode" | "mimocode" | "zcode" | "antigravity" | "kilocode" | "workbuddy" | "qwen" | "continue" | "cline" | "goose" | "dsh4" | "zed" | "crush" | "teleagent" | "trae" | "vibe" | "dsh", string>> | undefined;
         enabledDriveMounts?: string[] | undefined;
         picker?: {
             displayMode: "collapse" | "native-scroll";
@@ -140,6 +181,9 @@ export declare class ReferenceAnythingRemote extends TypertRemoteService {
                 maxCandidates: number;
                 sort: "name" | "updated";
                 shortcut: string;
+                showImport: boolean;
+                showSummary: boolean;
+                skipConfirmation: boolean;
                 aliases?: string[] | undefined;
                 sourceAliases?: Record<string, string[]> | undefined;
             };

package/lib/host.js

@@ -1,10 +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.
      *
@@ -18,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.

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.