dsh-reference-anything 0.3.1 → 0.3.2

package/lib/tool.js

@@ -8,12 +8,15 @@
  *
  * @module dsh-reference-anything/tool
  */
-import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import { lstat, mkdtemp, open, readFile, readdir, rm, rmdir, unlink } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
-import { basename, join } from 'node:path';
+import { basename } from 'node:path';
 import z from '@deepseek-ai/schemastery';
 import { defineTool } from '@deepseek-ai/dsh-tools';
 import { AttachmentId } from '@deepseek-ai/dsh-attachment';
+import { appendDownloadDirectoryPrefix, validateDownloadDirectory } from "./download-directory.js";
+import { ReferenceAnythingError } from "./errors.js";
+import { DEFAULT_OPENCLI_MAX_STDOUT_BYTES, OpenCliError, OpenCliRunner } from "./opencli.js";
 import { addUnavailableAttachmentNotices, continuationFooter, frameReferenceBlock } from "./render.js";
 import { retainConversation } from "./retain.js";
 import { decodeReferenceUri, encodeReferenceUri } from "./uri.js";
@@ -30,6 +33,30 @@ export const DEFAULT_TIMEOUT_MS = 30_000;
 export const DEFAULT_READ_TURNS = 10;
 /** Ceiling on the model-supplied turn limit when none is configured. */
 export const DEFAULT_MAX_READ_TURNS = 100;
+/** Hard attachment cap shared by drive and Web materialization. */
+export const MAX_ATTACHMENT_BYTES = 25 * 1024 * 1024;
+/** Successful materializations remain usable for one hour. */
+export const ATTACHMENT_LIFETIME_MS = 60 * 60 * 1000;
+function fileIdentity(stats) {
+    return { dev: stats.dev, ino: stats.ino };
+}
+function sameFileIdentity(left, right) {
+    return left.dev === right.dev && left.ino === right.ino;
+}
+async function selectedBaseIdentity(path) {
+    try {
+        const stats = await lstat(path);
+        if (!stats.isDirectory() || stats.isSymbolicLink()) {
+            throw new ReferenceAnythingError('selected cloud-drive download directory must be a real directory, not a symbolic link', 'REFERENCE_INVALID_CONFIG');
+        }
+        return fileIdentity(stats);
+    }
+    catch (cause) {
+        if (cause instanceof ReferenceAnythingError)
+            throw cause;
+        throw new ReferenceAnythingError('selected cloud-drive download directory is unavailable', 'REFERENCE_INVALID_CONFIG', { cause });
+    }
+}
 /** Runtime schema for {@link Config}. */
 export const Config = z.object({
     listLimit: z.number().step(1).min(1).default(20),
@@ -139,6 +166,11 @@ export function apply(ctx, config = {}) {
                 type: 'string',
                 description: 'Opaque nextCursor returned by the previous page. Do not combine with before.',
             },
+            detail: {
+                type: 'string',
+                enum: ['summary', 'full'],
+                description: 'For external Agent sessions: summary (default) keeps only tool names; full includes complete arguments and outputs.',
+            },
         },
         output: {
             schema: {
@@ -161,11 +193,18 @@ export function apply(ctx, config = {}) {
                             type: 'object',
                             additionalProperties: false,
                             properties: {
-                                role: { type: 'string', required: true, enum: ['user', 'assistant'] },
+                                role: {
+                                    type: 'string',
+                                    required: true,
+                                    enum: ['user', 'assistant', 'document'],
+                                    description: 'Who produced the text. `document` means it is file content rather than '
+                                        + 'anything anyone said, so it carries no speaker\'s authority at all.',
+                                },
                                 text: { type: 'string', required: true },
                             },
                         },
                     },
+                    toolDetail: { type: 'string', enum: ['summary', 'full'] },
                 },
             },
             render: (_args, value) => [{
@@ -181,7 +220,7 @@ export function apply(ctx, config = {}) {
                         ...value.totalTurns === undefined ? {} : { totalTurns: value.totalTurns },
                         hasOlder: value.hasOlder,
                         ...value.nextCursor === undefined ? {} : { nextCursor: value.nextCursor },
-                    })}`,
+                    })}${value.toolDetail === 'summary' ? '\n\n(Tool arguments and outputs are omitted. Rerun this window with detail: "full" when needed.)' : ''}`,
                 }],
             presentationMeta: (_args, value) => ({
                 label: value.label,
@@ -194,12 +233,14 @@ export function apply(ctx, config = {}) {
         isConcurrencySafe: () => true,
         async execute(args, exec) {
             const ref = decodeReferenceUri(args.uri);
-            ctx.references.assertGranted(exec.agent ? String(exec.agent.session.id) : undefined, ref);
+            ctx.references.assertSessionGranted(exec.agent?.session, ref);
             const chatHistory = ctx.get('referenceChatHistory');
             const userMaximum = ref.source === 'web-chat' && chatHistory
                 ? Math.min(maxReadTurns, chatHistory.store.settings.maxReadTurns)
                 : maxReadTurns;
-            const window = parseWindow(args, Math.min(readTurns, userMaximum), userMaximum);
+            const toolDetail = ref.source === 'local-agent' ? args.detail ?? 'summary' : undefined;
+            const window = { ...parseWindow(args, Math.min(readTurns, userMaximum), userMaximum),
+                ...toolDetail === undefined ? {} : { detail: toolDetail } };
             const snapshot = await ctx.references.read(ref, window, exec.signal);
             const slice = snapshot.body;
             // The turn window is the model's bound; this byte budget is only a
@@ -220,6 +261,7 @@ export function apply(ctx, config = {}) {
                 omittedBytes: outcome.omittedBytes,
                 ...(snapshot.revision ? { revision: snapshot.revision } : {}),
                 ...(slice.nextCursor && dropped === 0 ? { nextCursor: slice.nextCursor } : {}),
+                ...toolDetail === undefined ? {} : { toolDetail },
                 messages: outcome.items.map(item => ({ role: item.role, text: item.text })),
             };
         },
@@ -230,13 +272,235 @@ export function apply(ctx, config = {}) {
             rawInput: args.uri,
         }),
     })), 'reference-tool.reference_read()');
-    const tempRoots = new Set();
+    const tempRoots = new Map();
+    let disposed = false;
+    const scheduleTempCleanup = (root, delay) => {
+        const state = tempRoots.get(root);
+        if (!state || disposed)
+            return;
+        if (state.timer !== undefined)
+            clearTimeout(state.timer);
+        const timer = setTimeout(() => {
+            void removeTempRoot(root).catch(() => {
+                ctx.logger.warn('reference attachment temporary cleanup failed; the tracked path will be retried');
+            });
+        }, delay);
+        timer.unref?.();
+        state.timer = timer;
+    };
+    const removeTempRoot = async (root) => {
+        const state = tempRoots.get(root);
+        if (!state) {
+            ctx.logger.warn('ignored cleanup request for an untracked attachment temporary directory');
+            return;
+        }
+        if (state.removal)
+            return state.removal;
+        if (state.timer !== undefined)
+            clearTimeout(state.timer);
+        state.timer = undefined;
+        state.removed = false;
+        const removal = (async () => {
+            if (state.selectedRootIdentity) {
+                if (!state.selectedBasePath || !state.selectedBaseIdentity) {
+                    ctx.logger.warn('selected attachment temporary directory lost its base identity; cleanup was abandoned');
+                    return 'abandoned';
+                }
+                let currentBase;
+                try {
+                    const baseStats = await lstat(state.selectedBasePath);
+                    if (!baseStats.isDirectory() || baseStats.isSymbolicLink()) {
+                        ctx.logger.warn('selected attachment base directory changed type; cleanup was abandoned');
+                        return 'abandoned';
+                    }
+                    currentBase = fileIdentity(baseStats);
+                }
+                catch (cause) {
+                    if (cause.code === 'ENOENT') {
+                        ctx.logger.warn('selected attachment base directory disappeared; cleanup was abandoned');
+                        return 'abandoned';
+                    }
+                    throw cause;
+                }
+                if (!sameFileIdentity(currentBase, state.selectedBaseIdentity)) {
+                    ctx.logger.warn('selected attachment base directory identity changed; cleanup was abandoned');
+                    return 'abandoned';
+                }
+                let current;
+                try {
+                    current = fileIdentity(await lstat(root));
+                }
+                catch (cause) {
+                    if (cause.code === 'ENOENT')
+                        return 'missing';
+                    throw cause;
+                }
+                if (!sameFileIdentity(current, state.selectedRootIdentity)) {
+                    ctx.logger.warn('selected attachment temporary directory identity changed; cleanup was abandoned');
+                    return 'abandoned';
+                }
+                const selectedFiles = state.selectedFiles ?? new Map();
+                for (const [name, expected] of selectedFiles) {
+                    let actual;
+                    try {
+                        actual = fileIdentity(await lstat(appendDownloadDirectoryPrefix(root, name)));
+                    }
+                    catch (cause) {
+                        if (cause.code === 'ENOENT') {
+                            selectedFiles.delete(name);
+                            continue;
+                        }
+                        ctx.logger.warn('selected attachment temporary file identity could not be verified; cleanup was abandoned');
+                        return 'abandoned';
+                    }
+                    if (!sameFileIdentity(actual, expected)) {
+                        ctx.logger.warn('selected attachment temporary file identity changed; cleanup was abandoned');
+                        return 'abandoned';
+                    }
+                }
+                const rootBeforeUnlink = fileIdentity(await lstat(root));
+                if (!sameFileIdentity(rootBeforeUnlink, state.selectedRootIdentity)) {
+                    ctx.logger.warn('selected attachment temporary directory identity changed; cleanup was abandoned');
+                    return 'abandoned';
+                }
+                for (const name of [...selectedFiles.keys()]) {
+                    try {
+                        await unlink(appendDownloadDirectoryPrefix(root, name));
+                    }
+                    catch (cause) {
+                        if (cause.code !== 'ENOENT')
+                            throw cause;
+                    }
+                    selectedFiles.delete(name);
+                }
+                if ((await readdir(root)).length !== 0) {
+                    ctx.logger.warn('selected attachment temporary directory contains foreign entries; directory removal was abandoned');
+                    return 'abandoned';
+                }
+                const rootBeforeRemoval = fileIdentity(await lstat(root));
+                if (!sameFileIdentity(rootBeforeRemoval, state.selectedRootIdentity)) {
+                    ctx.logger.warn('selected attachment temporary directory identity changed; cleanup was abandoned');
+                    return 'abandoned';
+                }
+                await rmdir(root);
+                return 'removed';
+            }
+            await rm(root, { recursive: true, force: true, maxRetries: 3, retryDelay: 50 });
+            return 'removed';
+        })()
+            .then((outcome) => {
+            state.removal = undefined;
+            if (outcome === 'removed' || outcome === 'missing') {
+                state.removed = true;
+                if (state.activeOperations === 0)
+                    tempRoots.delete(root);
+            }
+            else if (!disposed && state.retries < 3) {
+                state.retries += 1;
+                scheduleTempCleanup(root, 1_000);
+            }
+        })
+            .catch((cause) => {
+            state.removal = undefined;
+            if (!disposed && state.retries < 3) {
+                state.retries += 1;
+                scheduleTempCleanup(root, 1_000);
+            }
+            throw new ReferenceAnythingError('could not remove attachment temporary files', 'REFERENCE_READ_FAILED', { cause });
+        });
+        state.removal = removal;
+        return removal;
+    };
+    const createTempRoot = async (base, prefix, expectedBaseIdentity) => {
+        if (disposed)
+            throw new ReferenceAnythingError('attachment materializer has been disposed', 'REFERENCE_CANCELLED');
+        const selectedBase = expectedBaseIdentity !== undefined;
+        if (expectedBaseIdentity) {
+            const currentBaseIdentity = await selectedBaseIdentity(base);
+            if (!sameFileIdentity(currentBaseIdentity, expectedBaseIdentity)) {
+                throw new ReferenceAnythingError('selected cloud-drive download directory changed before temporary storage was created', 'REFERENCE_INVALID_CONFIG');
+            }
+        }
+        let root;
+        try {
+            root = await mkdtemp(appendDownloadDirectoryPrefix(base, prefix));
+        }
+        catch (cause) {
+            throw new ReferenceAnythingError(selectedBase
+                ? 'selected cloud-drive download directory is unavailable or not writable'
+                : 'could not create attachment temporary storage', selectedBase ? 'REFERENCE_INVALID_CONFIG' : 'REFERENCE_READ_FAILED', { cause });
+        }
+        let selectedRootIdentity;
+        if (selectedBase) {
+            try {
+                selectedRootIdentity = fileIdentity(await lstat(root));
+            }
+            catch (cause) {
+                ctx.logger.warn('could not record selected attachment temporary directory identity; cleanup was abandoned');
+                throw new ReferenceAnythingError('could not secure selected cloud-drive temporary storage', 'REFERENCE_INVALID_CONFIG', { cause });
+            }
+        }
+        tempRoots.set(root, {
+            retries: 0,
+            activeOperations: 0,
+            removed: false,
+            ...(selectedRootIdentity && expectedBaseIdentity ? {
+                selectedBasePath: base,
+                selectedBaseIdentity: expectedBaseIdentity,
+                selectedRootIdentity,
+                selectedFiles: new Map(),
+            } : {}),
+        });
+        if (expectedBaseIdentity) {
+            const baseAfterCreation = await selectedBaseIdentity(base);
+            if (!sameFileIdentity(baseAfterCreation, expectedBaseIdentity)) {
+                ctx.logger.warn('selected attachment base changed while temporary storage was being created; cleanup was abandoned');
+                throw new ReferenceAnythingError('selected cloud-drive download directory changed while temporary storage was created', 'REFERENCE_INVALID_CONFIG');
+            }
+        }
+        if (disposed) {
+            await removeTempRoot(root);
+            throw new ReferenceAnythingError('attachment materializer has been disposed', 'REFERENCE_CANCELLED');
+        }
+        return root;
+    };
+    const retainTempRoot = async (root) => {
+        if (disposed) {
+            await removeTempRoot(root);
+            throw new ReferenceAnythingError('attachment materializer has been disposed', 'REFERENCE_CANCELLED');
+        }
+        scheduleTempCleanup(root, ATTACHMENT_LIFETIME_MS);
+    };
+    const beginTempRootOperation = (root) => {
+        const state = tempRoots.get(root);
+        if (!state)
+            throw new ReferenceAnythingError('attachment temporary storage is no longer tracked', 'REFERENCE_CANCELLED');
+        state.activeOperations += 1;
+    };
+    const endTempRootOperation = (root) => {
+        const state = tempRoots.get(root);
+        if (!state)
+            return;
+        state.activeOperations = Math.max(0, state.activeOperations - 1);
+        if (state.activeOperations === 0 && state.removed && !state.removal)
+            tempRoots.delete(root);
+    };
+    const registerSelectedTempFile = (root, localPath, identity) => {
+        const selectedFiles = tempRoots.get(root)?.selectedFiles;
+        if (!selectedFiles)
+            return;
+        selectedFiles.set(basename(localPath), identity);
+    };
     ctx.effect(() => async () => {
-        await Promise.all([...tempRoots].map(path => rm(path, { recursive: true, force: true }).catch(() => { })));
+        disposed = true;
+        const settled = await Promise.allSettled([...tempRoots.keys()].map(removeTempRoot));
+        const failure = settled.find(result => result.status === 'rejected');
+        if (failure?.status === 'rejected')
+            throw failure.reason;
     }, 'reference-tool.attachmentTempCleanup()');
     ctx.effect(() => ctx.tools.register(defineTool({
         name: 'reference_attachment_read',
-        description: 'Read one attachment from an authorized Web conversation. The bytes are fetched on demand through the logged-in provider page.',
+        description: 'Materialize one authorized Web-conversation attachment or cloud-drive document on demand.',
         parameters: {
             uri: { type: 'string', required: true, description: 'The dsh-ref URI that exposed the attachment.' },
             attachmentId: { type: 'string', required: true, description: 'Attachment id exactly as shown in the conversation page.' },
@@ -270,45 +534,107 @@ export function apply(ctx, config = {}) {
         isConcurrencySafe: () => true,
         async execute(args, exec) {
             const ref = decodeReferenceUri(args.uri);
-            ctx.references.assertGranted(exec.agent ? String(exec.agent.session.id) : undefined, ref);
-            if (ref.source !== 'web-chat')
-                throw new Error('attachments are available only for synchronized Web conversations');
+            ctx.references.assertSessionGranted(exec.agent?.session, ref);
+            if (ref.source === 'cloud-drive') {
+                if (args.attachmentId !== 'file') {
+                    throw new ReferenceAnythingError('cloud-drive documents use attachmentId "file" exactly as shown by reference_read', 'ATTACHMENT_UNAVAILABLE');
+                }
+                const service = ctx.get('referenceCloudDrive');
+                if (!service)
+                    throw new ReferenceAnythingError('cloud-drive service is not mounted', 'SOURCE_UNAVAILABLE');
+                const history = ctx.get('referenceChatHistory');
+                const configuredValue = history?.store.settings
+                    ?.cloudDriveDownloadDirectory;
+                if (configuredValue !== undefined && typeof configuredValue !== 'string') {
+                    throw new ReferenceAnythingError('selected cloud-drive download directory must be a string path', 'REFERENCE_INVALID_CONFIG');
+                }
+                const configuredBase = await validateDownloadDirectory(configuredValue ?? '');
+                const usesConfiguredBase = configuredBase !== '';
+                const configuredBaseIdentity = usesConfiguredBase ? await selectedBaseIdentity(configuredBase) : undefined;
+                let attachment;
+                try {
+                    attachment = await service.attachment(ref, MAX_ATTACHMENT_BYTES, exec.signal);
+                }
+                catch (error) {
+                    throw attachmentFailure(error, exec.signal, 'cloud-drive');
+                }
+                if (attachment.bytes.byteLength > MAX_ATTACHMENT_BYTES) {
+                    throw new ReferenceAnythingError('cloud-drive attachment exceeds 25 MiB', 'ATTACHMENT_TOO_LARGE');
+                }
+                const root = await createTempRoot(usesConfiguredBase ? configuredBase : tmpdir(), 'dsh-reference-drive-', configuredBaseIdentity);
+                beginTempRootOperation(root);
+                try {
+                    const localPath = attachmentLocalPath(root, attachment.name);
+                    const handle = await open(localPath, 'wx', 0o600);
+                    try {
+                        registerSelectedTempFile(root, localPath, fileIdentity(await handle.stat()));
+                        await handle.writeFile(attachment.bytes);
+                    }
+                    finally {
+                        await handle.close();
+                    }
+                    const bytes = Buffer.from(attachment.bytes);
+                    const mimeType = sniffMime(bytes, attachment.mimeType);
+                    const image = isRenderableImage(mimeType) ? await saveImage(ctx, bytes, mimeType, attachment.name) : undefined;
+                    await retainTempRoot(root);
+                    return { name: attachment.name, mimeType, size: bytes.byteLength, localPath, ...(image ? { image } : {}) };
+                }
+                catch (error) {
+                    await removeTempRoot(root);
+                    throw attachmentFailure(error, exec.signal, 'cloud-drive');
+                }
+                finally {
+                    endTempRootOperation(root);
+                }
+            }
+            if (ref.source !== 'web-chat') {
+                throw new ReferenceAnythingError('attachments are available only for synchronized Web conversations and cloud-drive documents', 'ATTACHMENT_UNAVAILABLE');
+            }
             const service = ctx.get('referenceChatHistory');
             if (!service)
-                throw new Error('Web conversation history service is not mounted');
+                throw new ReferenceAnythingError('Web conversation history service is not mounted', 'SOURCE_UNAVAILABLE');
             const conversation = service.store.conversations.get(ref.id);
             const revision = conversation?.currentRevision;
             if (!conversation)
-                throw new Error('conversation is not in the local title index');
+                throw new ReferenceAnythingError('conversation is not in the local title index', 'REFERENCE_NOT_FOUND');
+            if (!/^[a-f0-9]{64}$/.test(conversation.accountScope)) {
+                throw new ReferenceAnythingError(`conversation has no verified ${conversation.provider} account scope; ask the user to sync ${conversation.provider} and reselect the conversation from the refreshed @ list, then retry`, 'REFERENCE_ACCOUNT_MISMATCH');
+            }
             const attachment = service.store.settings.historyMode === 'metadata-only'
                 ? service.liveAttachment(ref.id, args.attachmentId)
                 : revision ? service.store.attachment(ref.id, revision, args.attachmentId) : undefined;
             if (!attachment?.locator || attachment.status !== 'available') {
-                throw new Error('ATTACHMENT_UNAVAILABLE: provider supplied no stable attachment locator');
+                throw new ReferenceAnythingError('provider supplied no stable attachment locator', 'ATTACHMENT_UNAVAILABLE');
+            }
+            const root = await createTempRoot(tmpdir(), 'dsh-reference-attachment-');
+            beginTempRootOperation(root);
+            try {
+                const localPath = attachmentLocalPath(root, attachment.name);
+                const settings = service.store.settings;
+                const runner = new OpenCliRunner({
+                    executable: settings.opencliPath, profile: settings.profile, timeoutMs,
+                    maxStdoutBytes: DEFAULT_OPENCLI_MAX_STDOUT_BYTES,
+                });
+                await runner.attachment(conversation.provider, attachment.locator, localPath, MAX_ATTACHMENT_BYTES, exec.signal, conversation.accountScope);
+                const bytes = await readFile(localPath);
+                if (bytes.byteLength > MAX_ATTACHMENT_BYTES) {
+                    throw new ReferenceAnythingError('attachment exceeds 25 MiB', 'ATTACHMENT_TOO_LARGE');
+                }
+                const mimeType = sniffMime(bytes, attachment.mimeType);
+                const image = isRenderableImage(mimeType) ? await saveImage(ctx, bytes, mimeType, attachment.name) : undefined;
+                await retainTempRoot(root);
+                return {
+                    name: attachment.name, mimeType, size: bytes.byteLength, localPath,
+                    ...(image ? { image } : {}),
+                };
+            }
+            catch (error) {
+                await removeTempRoot(root);
+                throw attachmentFailure(error, exec.signal, conversation.provider);
+            }
+            finally {
+                endTempRootOperation(root);
             }
-            const root = await mkdtemp(join(tmpdir(), 'dsh-reference-attachment-'));
-            tempRoots.add(root);
-            const safeName = basename(attachment.name).replace(/[<>:"/\\|?*\x00-\x1f]/g, '_') || 'attachment';
-            const localPath = join(root, safeName);
-            const settings = service.store.settings;
-            const runner = new (await import("./opencli.js")).OpenCliRunner({
-                executable: settings.opencliPath, profile: settings.profile, timeoutMs, maxStdoutBytes: 32 * 1024 * 1024,
-            });
-            await runner.attachment(conversation.provider, attachment.locator, localPath, 25 * 1024 * 1024, exec.signal);
-            const bytes = await readFile(localPath);
-            if (bytes.byteLength > 25 * 1024 * 1024)
-                throw new Error('ATTACHMENT_TOO_LARGE: attachment exceeds 25 MiB');
-            const mimeType = sniffMime(bytes, attachment.mimeType);
-            const timer = setTimeout(() => {
-                tempRoots.delete(root);
-                void rm(root, { recursive: true, force: true });
-            }, 60 * 60 * 1000);
-            timer.unref?.();
-            const image = mimeType.startsWith('image/') ? await saveImage(ctx, bytes, mimeType, attachment.name) : undefined;
-            return {
-                name: attachment.name, mimeType, size: bytes.byteLength, localPath,
-                ...(image ? { image } : {}),
-            };
         },
         presentCall: args => ({ card: 'generic', title: 'Read conversation attachment', kind: 'read', rawInput: args.attachmentId }),
     })), 'reference-tool.reference_attachment_read()');
@@ -349,16 +675,63 @@ function sniffMime(bytes, declared) {
                 : detected.subarray(0, 4).toString('ascii') === 'RIFF' && detected.subarray(8, 12).toString('ascii') === 'WEBP' ? 'image/webp'
                     : detected.subarray(0, 5).toString('ascii') === '%PDF-' ? 'application/pdf'
                         : 'application/octet-stream';
-    if (declared.startsWith('image/') && !mime.startsWith('image/'))
-        throw new Error('ATTACHMENT_UNAVAILABLE: attachment MIME did not match its bytes');
+    if (isRenderableImage(declared) && mime !== declared) {
+        throw new ReferenceAnythingError('attachment MIME did not match its bytes', 'ATTACHMENT_UNAVAILABLE');
+    }
     return mime === 'application/octet-stream' && declared ? declared : mime;
 }
+function isRenderableImage(mimeType) {
+    return mimeType === 'image/png' || mimeType === 'image/jpeg' || mimeType === 'image/webp' || mimeType === 'image/gif';
+}
+function safeAttachmentName(name) {
+    const leaf = basename(name).replace(/[<>:"/\\|?*\x00-\x1f]/g, '_').replace(/[. ]+$/g, '_') || 'file';
+    return `attachment-${leaf}`;
+}
+function attachmentLocalPath(root, name) {
+    // `safeAttachmentName` guarantees one leaf segment. Preserve the exact root
+    // string so a validated symlink/`..` path keeps the same OS resolution
+    // semantics for creation, use, and cleanup.
+    return appendDownloadDirectoryPrefix(root, safeAttachmentName(name));
+}
 async function saveImage(ctx, bytes, mimeType, name) {
     const attachments = ctx.get('attachments');
-    if (!attachments)
-        throw new Error('ATTACHMENT_UNAVAILABLE: no DSH attachment store is mounted for image output');
-    if (mimeType !== 'image/png' && mimeType !== 'image/jpeg' && mimeType !== 'image/webp' && mimeType !== 'image/gif') {
-        throw new Error(`ATTACHMENT_UNAVAILABLE: unsupported image type ${mimeType}`);
+    if (!attachments) {
+        throw new ReferenceAnythingError('no DSH attachment store is mounted for image output', 'ATTACHMENT_UNAVAILABLE');
+    }
+    let saved;
+    try {
+        saved = await attachments.saveImage({ data: bytes, mediaType: mimeType, name });
+    }
+    catch (error) {
+        throw new ReferenceAnythingError('DSH image storage refused the attachment', 'ATTACHMENT_UNAVAILABLE', { cause: error });
+    }
+    if (!saved || typeof saved.attachmentId !== 'string' || !isRenderableImage(saved.mediaType)
+        || !Number.isInteger(saved.bytes) || !Number.isInteger(saved.width) || !Number.isInteger(saved.height)) {
+        throw new ReferenceAnythingError('DSH image storage returned invalid metadata', 'ATTACHMENT_UNAVAILABLE');
+    }
+    return {
+        attachmentId: saved.attachmentId,
+        mediaType: saved.mediaType,
+        bytes: saved.bytes,
+        width: saved.width,
+        height: saved.height,
+        ...(typeof saved.name === 'string' ? { name: saved.name } : {}),
+    };
+}
+function attachmentFailure(error, signal, provider) {
+    if (error instanceof ReferenceAnythingError)
+        return error;
+    if (signal?.aborted) {
+        return new ReferenceAnythingError('attachment materialization was cancelled', 'REFERENCE_CANCELLED', { cause: signal.reason });
+    }
+    if (error instanceof OpenCliError && error.code === 'PROVIDER_ACCOUNT_MISMATCH') {
+        return new ReferenceAnythingError(`attachment belongs to a different logged-in ${provider} account; ask the user to sync ${provider} and reselect the conversation from the refreshed @ list, then retry`, 'REFERENCE_ACCOUNT_MISMATCH', { cause: error });
+    }
+    if (error instanceof OpenCliError && error.code === 'ATTACHMENT_TOO_LARGE') {
+        return new ReferenceAnythingError('attachment exceeds 25 MiB', 'ATTACHMENT_TOO_LARGE', { cause: error });
+    }
+    if (error instanceof OpenCliError && error.code === 'PROVIDER_RATE_LIMIT') {
+        return new ReferenceAnythingError(`${provider} rate-limited account verification; wait before retrying the attachment`, 'PROVIDER_RATE_LIMIT', { cause: error });
     }
-    return await attachments.saveImage({ data: bytes, mediaType: mimeType, name });
+    return new ReferenceAnythingError(`could not materialize the attachment from ${provider}`, 'REFERENCE_READ_FAILED', { cause: error });
 }

package/lib/typert.js

@@ -5,6 +5,8 @@ export const TYPERT_MANIFEST = {
                 key: 'referenceAnything', exportName: 'ReferenceAnythingRemote',
                 description: 'Local conversation mirror, synchronization, and settings for @Conversation.', tags: [],
                 members: [
+                    { kind: 'method', name: 'agentSearch', signature: 'agentSearch(agent: Agent, input: AgentSearchInput, signal: AbortSignal): Promise<AgentCandidate[]>' },
+                    { kind: 'method', name: 'driveSearch', signature: 'driveSearch(input: DriveSearchInput, signal: AbortSignal): Promise<DriveCandidate[]>' },
                     { kind: 'method', name: 'search', signature: 'search(input: SearchInput): Promise<SearchResult[]>' },
                     { kind: 'method', name: 'health', signature: 'health(signal: AbortSignal): Promise<Health>' },
                     { kind: 'method', name: 'quickHealth', signature: 'quickHealth(signal: AbortSignal): Promise<Health>' },
@@ -26,10 +28,20 @@ export const TYPERT_MANIFEST = {
                     { kind: 'method', name: 'deleteConversation', signature: 'deleteConversation(input: DeleteInput): Promise<boolean>' },
                     { kind: 'method', name: 'storageStats', signature: 'storageStats(): StorageStats' },
                     { kind: 'method', name: 'clearProvider', signature: 'clearProvider(input: ClearProviderInput): Promise<number>' },
-                    { kind: 'method', name: 'clearOlder', signature: 'clearOlder(input: ClearOlderInput): Promise<number>' },
                     { kind: 'method', name: 'clearRemoteMissing', signature: 'clearRemoteMissing(signal: AbortSignal): Promise<number>' },
                     { kind: 'method', name: 'clearOldAccounts', signature: 'clearOldAccounts(signal: AbortSignal): Promise<number>' },
                     { kind: 'method', name: 'syncStates', signature: 'syncStates(): ProviderSyncState[]' },
+                    { kind: 'method', name: 'openListStatus', signature: 'openListStatus(signal: AbortSignal): Promise<OpenListStatus>' },
+                    { kind: 'method', name: 'openListInstall', signature: 'openListInstall(signal: AbortSignal): Promise<OpenListStatus>' },
+                    { kind: 'method', name: 'openListUpgrade', signature: 'openListUpgrade(input: OpenListUpgradeInput, signal: AbortSignal): Promise<OpenListStatus>' },
+                    { kind: 'method', name: 'openListConnectExternal', signature: 'openListConnectExternal(input: OpenListExternalConnect, signal: AbortSignal): Promise<OpenListStatus>' },
+                    { kind: 'method', name: 'openListDisconnect', signature: 'openListDisconnect(signal: AbortSignal): Promise<OpenListStatus>' },
+                    { kind: 'method', name: 'openListDrivers', signature: 'openListDrivers(signal: AbortSignal): Promise<OpenListDriver[]>' },
+                    { kind: 'method', name: 'openListMounts', signature: 'openListMounts(signal: AbortSignal): Promise<OpenListMount[]>' },
+                    { kind: 'method', name: 'openListCreateMount', signature: 'openListCreateMount(input: OpenListMountCreate, signal: AbortSignal): Promise<OpenListMount>' },
+                    { kind: 'method', name: 'openListDisableMount', signature: 'openListDisableMount(input: OpenListDisableMountInput, signal: AbortSignal): Promise<boolean>' },
+                    { kind: 'method', name: 'openListRemoveMount', signature: 'openListRemoveMount(input: OpenListMountInput, signal: AbortSignal): Promise<boolean>' },
+                    { kind: 'method', name: 'openListReindex', signature: 'openListReindex(input: OpenListMountInput, signal: AbortSignal): Promise<OpenListReindex>' },
                 ], types: [],
             }], events: [], objects: [] },
     invocations: REFERENCE_ANYTHING_INVOCATIONS,

package/lib/types.d.ts

@@ -44,10 +44,25 @@ export interface ReferenceSummary {
     readonly messageCount?: number;
     readonly partial?: boolean;
     readonly syncedAt?: number;
+    /** Discovery used a bounded fallback and may not cover the whole source. */
+    readonly searchIncomplete?: boolean;
+    /** Picker navigation row; directories are never inserted as references. */
+    readonly isDirectory?: boolean;
 }
-/** One projected turn of a referenced conversation. */
+/** One projected turn of a referenced conversation, or one block of a referenced file. */
 export interface ConversationItem {
-    readonly role: 'user' | 'assistant';
+    /**
+     * Who produced this text.
+     *
+     * `document` exists because not every referent is a conversation. A file
+     * pulled from a cloud drive has an author, but not one of these two, and
+     * labelling its contents `assistant` would assert that some model said them
+     * while labelling it `user` would assert the current user did — the second
+     * being the more dangerous lie, since text that appears to come from the
+     * user reads as instruction rather than as data. A third value states the
+     * provenance instead of picking the least-wrong falsehood.
+     */
+    readonly role: 'user' | 'assistant' | 'document';
     /** Visible text of that turn. Tool calls, reasoning, and injected context are not projected. */
     readonly text: string;
     /** Attachment metadata only; bytes stay behind an explicit authorized read. */
@@ -78,6 +93,8 @@ export interface ReferenceWindow {
     readonly before?: number;
     /** Opaque revision-pinned continuation returned by a previous read. */
     readonly cursor?: string;
+    /** Local-agent tool fidelity for this read; other sources ignore it. */
+    readonly detail?: 'summary' | 'full';
 }
 /**
  * The turns a source returned, and where they sit in the whole conversation.
@@ -131,6 +148,15 @@ export interface ReferenceSnapshot extends ReferenceSummary {
 export interface ReferenceSource {
     /** Stable registry key, also the `source` half of every {@link ReferenceRef} it owns. */
     readonly id: string;
+    /**
+     * Whether reading this source's items needs a per-task grant.
+     *
+     * Sources whose items live outside the task's own workspace — another
+     * assistant's transcript, a remote drive — opt in, so the model can only
+     * read what its user actually named. Omitting it means ungated, which is
+     * right only when the material is already inside the task's scope.
+     */
+    readonly requiresGrant?: boolean;
     /**
      * Whether this source can currently be used. Must stay cheap and local —
      * no network calls, no subprocess launches — because discovery calls it on