@zleap-ai/dsh-sag 0.1.0

package/lib/tools/documents.js

@@ -0,0 +1,134 @@
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { jsonRender, localOperation, requireToolCapability, selectSource } from './local.js';
+const DOCUMENT = {
+    type: 'object', additionalProperties: false, properties: {
+        id: { type: 'string', required: true }, sourceId: { type: 'string' },
+        filename: { type: 'string' }, status: { type: 'string', enum: ['pending', 'loading', 'extracting', 'pausing', 'paused', 'deleting', 'delete_failed', 'ready', 'failed'] },
+        progress: { type: 'integer' }, chunkCount: { type: 'integer' },
+        error: { oneOf: [{ type: 'string' }, { type: 'null' }] },
+        errorLayer: { oneOf: [{ type: 'string' }, { type: 'null' }] },
+        errorStage: { oneOf: [{ type: 'string' }, { type: 'null' }] },
+    },
+};
+function documentValue(document) {
+    return {
+        id: document.id,
+        ...(typeof document.sourceId === 'string' ? { sourceId: document.sourceId } : {}),
+        ...(typeof document.filename === 'string' ? { filename: document.filename } : {}),
+        ...(typeof document.status === 'string' ? { status: document.status } : {}),
+        ...(typeof document.progress === 'number' ? { progress: document.progress } : {}),
+        ...(typeof document.chunkCount === 'number' ? { chunkCount: document.chunkCount } : {}),
+        ...(document.error === null || typeof document.error === 'string' ? { error: document.error } : {}),
+        ...(document.errorLayer === null || typeof document.errorLayer === 'string' ? { errorLayer: document.errorLayer } : {}),
+        ...(document.errorStage === null || typeof document.errorStage === 'string' ? { errorStage: document.errorStage } : {}),
+    };
+}
+/** Require user approval for irreversible SAG document deletion. */
+export function sagDeleteApprovalGate(exec, next) {
+    if (exec.name !== 'sag_delete_document')
+        return next();
+    return Promise.resolve({ kind: 'ask', reason: '删除 SAG 文档后无法恢复' });
+}
+/** Build local SAG document inspection, reprocessing, and deletion tools. */
+export function createDocumentTools(manager, config) {
+    const list = defineTool({
+        name: 'sag_list_documents',
+        description: 'List documents and current processing states in a selected local SAG knowledge base.',
+        parameters: { source_id: { type: 'string', description: 'Knowledge-base id.' } },
+        output: {
+            schema: { type: 'object', additionalProperties: false, properties: {
+                    sourceId: { type: 'string', required: true }, documents: { type: 'array', required: true, items: DOCUMENT },
+                } },
+            render: (_args, value) => jsonRender(value),
+        },
+        timeoutMs: config.requestTimeoutMs,
+        isConcurrencySafe: () => true,
+        async execute(args, exec) {
+            return localOperation(manager, exec.signal, async (connection) => {
+                requireToolCapability(connection, 'sag_list_documents');
+                const sourceId = await selectSource(connection, args.source_id, exec.signal);
+                return { sourceId, documents: (await connection.gateway.listDocuments(sourceId, exec.signal)).map(documentValue) };
+            });
+        },
+        presentCall: args => ({ card: 'generic', title: 'List SAG documents', kind: 'read', rawInput: args.source_id }),
+    });
+    const get = defineTool({
+        name: 'sag_get_document',
+        description: 'Get one local SAG document and its current background processing status.',
+        parameters: {
+            document_id: { type: 'string', required: true, description: 'Document id.' },
+            source_id: { type: 'string', description: 'Knowledge-base id.' },
+        },
+        output: { schema: DOCUMENT, render: (_args, value) => jsonRender(value) },
+        timeoutMs: config.requestTimeoutMs,
+        isConcurrencySafe: () => true,
+        async execute(args, exec) {
+            return localOperation(manager, exec.signal, async (connection) => {
+                requireToolCapability(connection, 'sag_get_document');
+                const sourceId = await selectSource(connection, args.source_id, exec.signal);
+                return documentValue(await connection.gateway.getDocument(sourceId, args.document_id, exec.signal));
+            });
+        },
+        presentCall: args => ({ card: 'generic', title: 'Read SAG document status', kind: 'read', rawInput: args.document_id }),
+    });
+    const reprocess = defineTool({
+        name: 'sag_reprocess_document',
+        description: 'Queue asynchronous reprocessing for one local SAG document and return the accepted job state.',
+        parameters: {
+            document_id: { type: 'string', required: true, description: 'Document id.' },
+            source_id: { type: 'string', description: 'Knowledge-base id.' },
+        },
+        output: { schema: {
+                type: 'object', additionalProperties: false, properties: {
+                    accepted: { type: 'boolean', required: true }, jobId: { type: 'string', required: true },
+                    documentId: { type: 'string', required: true }, sourceId: { type: 'string', required: true },
+                    status: { type: 'string', enum: ['queued', 'running', 'paused', 'succeeded', 'failed'], required: true },
+                    type: { type: 'string', const: 'reprocess_document', required: true },
+                    progress: { type: 'number' }, attempts: { type: 'integer' },
+                    error: { oneOf: [{ type: 'string' }, { type: 'null' }] },
+                },
+            }, render: (_args, value) => jsonRender(value) },
+        timeoutMs: config.requestTimeoutMs,
+        async execute(args, exec) {
+            return localOperation(manager, exec.signal, async (connection) => {
+                requireToolCapability(connection, 'sag_reprocess_document');
+                const sourceId = await selectSource(connection, args.source_id, exec.signal);
+                const job = await connection.gateway.reprocessDocument(sourceId, args.document_id, exec.signal);
+                return {
+                    accepted: true, jobId: job.id, documentId: job.documentId ?? args.document_id,
+                    sourceId: job.sourceId ?? sourceId, status: job.status,
+                    type: job.type,
+                    ...(job.progress === undefined ? {} : { progress: job.progress }),
+                    ...(job.attempts === undefined ? {} : { attempts: job.attempts }),
+                    ...(job.error === undefined ? {} : { error: job.error }),
+                };
+            });
+        },
+        presentCall: args => ({ card: 'generic', title: 'Reprocess SAG document', kind: 'execute', rawInput: args.document_id }),
+    });
+    const remove = defineTool({
+        name: 'sag_delete_document',
+        description: 'Permanently delete one document from a local SAG knowledge base after dsh user approval.',
+        parameters: {
+            document_id: { type: 'string', required: true, description: 'Document id.' },
+            source_id: { type: 'string', description: 'Knowledge-base id.' },
+        },
+        output: { schema: {
+                type: 'object', additionalProperties: false, properties: {
+                    deleted: { type: 'boolean', required: true }, documentId: { type: 'string', required: true }, sourceId: { type: 'string', required: true },
+                },
+            }, render: (_args, value) => jsonRender(value) },
+        timeoutMs: config.requestTimeoutMs,
+        async execute(args, exec) {
+            return localOperation(manager, exec.signal, async (connection) => {
+                requireToolCapability(connection, 'sag_delete_document');
+                const sourceId = await selectSource(connection, args.source_id, exec.signal);
+                await connection.gateway.deleteDocument(sourceId, args.document_id, exec.signal);
+                return { deleted: true, documentId: args.document_id, sourceId };
+            });
+        },
+        presentCall: args => ({ card: 'generic', title: 'Delete SAG document', kind: 'delete', rawInput: args.document_id }),
+    });
+    return [list, get, reprocess, remove];
+}
+//# sourceMappingURL=documents.js.map

package/lib/tools/ingest.d.ts

@@ -0,0 +1,5 @@
+import type { ResolvedLocalConfig } from '../config.js';
+import { type ConnectionManager } from './local.js';
+/** Build direct text ingestion for one local SAG knowledge base. */
+export declare function createIngestTextTool(manager: ConnectionManager, config: ResolvedLocalConfig): import("@deepseek-ai/dsh-tools").ToolDefinition;
+//# sourceMappingURL=ingest.d.ts.map

package/lib/tools/ingest.js

@@ -0,0 +1,35 @@
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { jsonRender, localInputError, localOperation, requireToolCapability, selectSource } from './local.js';
+const INGEST_OUTPUT = {
+    type: 'object', additionalProperties: false, properties: {
+        accepted: { type: 'boolean', required: true }, documentId: { type: 'string', required: true },
+        sourceId: { type: 'string', required: true }, status: { type: 'string', required: true },
+    },
+};
+/** Build direct text ingestion for one local SAG knowledge base. */
+export function createIngestTextTool(manager, config) {
+    return defineTool({
+        name: 'sag_ingest_text',
+        description: 'Submit text to a SAG knowledge base and return the accepted document processing status.',
+        parameters: {
+            text: { type: 'string', required: true, description: 'Text to ingest.' },
+            title: { type: 'string', description: 'Optional document title.' },
+            source_id: { type: 'string', description: 'Target knowledge-base id; omitted only when a default or single source exists.' },
+        },
+        output: { schema: INGEST_OUTPUT, render: (_args, value) => jsonRender(value) },
+        timeoutMs: config.requestTimeoutMs,
+        async execute(args, exec) {
+            return localOperation(manager, exec.signal, async (connection) => {
+                requireToolCapability(connection, 'sag_ingest_text');
+                const text = args.text.trim();
+                if (!text)
+                    localInputError('sag_ingest_text text must not be empty');
+                const sourceId = await selectSource(connection, args.source_id, exec.signal);
+                const document = await connection.gateway.ingestText({ sourceId, text, ...(args.title === undefined ? {} : { title: args.title }) }, exec.signal);
+                return { accepted: true, documentId: document.id, sourceId, status: document.status ?? 'pending' };
+            });
+        },
+        presentCall: args => ({ card: 'generic', title: 'Ingest text into SAG', kind: 'edit', rawInput: args.title ?? `${args.text.slice(0, 80)}${args.text.length > 80 ? '…' : ''}` }),
+    });
+}
+//# sourceMappingURL=ingest.js.map

package/lib/tools/local.d.ts

@@ -0,0 +1,40 @@
+import type { SagConnectionManager } from '../connection/manager.js';
+import type { SagConnectionDescriptor, SagCapabilityDescriptor } from '../connection/types.js';
+import type { SagGateway } from '../local/gateway.js';
+export declare const SAG_NOT_FOUND_MESSAGE = "\u6CA1\u6709\u53D1\u73B0\u6B63\u5728\u8FD0\u884C\u7684 SAG\u3002\u8BF7\u5148\u542F\u52A8 SAG \u540E\u91CD\u8BD5\uFF1B\u4E5F\u53EF\u8FD0\u884C dsh plugin --profile web exec dsh-sag setup \u91CD\u65B0\u53D1\u73B0\u3002";
+export interface LocalConnection {
+    readonly descriptor: SagConnectionDescriptor;
+    readonly capabilities: SagCapabilityDescriptor;
+    readonly gateway: SagGateway;
+    readonly sourceCount: number;
+}
+export type ConnectionManager = Pick<SagConnectionManager, 'ensureConnected'>;
+/** Current SAG v1 capability required by each endpoint-backed local Tool. */
+export declare const SAG_TOOL_CAPABILITY: {
+    readonly sag_list_sources: "sources.list";
+    readonly sag_create_source: "sources.create";
+    readonly sag_search: "knowledge.search";
+    readonly sag_read: "knowledge.read";
+    readonly sag_list_documents: "documents.list";
+    readonly sag_get_document: "documents.get";
+    readonly sag_upload_file: "documents.upload";
+    readonly sag_ingest_text: "documents.ingest";
+    readonly sag_reprocess_document: "documents.reprocess";
+    readonly sag_delete_document: "documents.delete";
+};
+export type CapabilityGatedToolName = keyof typeof SAG_TOOL_CAPABILITY;
+/** Raise a model-actionable input/configuration failure from inside an operation. */
+export declare function localInputError(message: string): never;
+/** Resolve one ready local connection without exposing credentials or transport details. */
+export declare function connectLocal(manager: ConnectionManager, signal: AbortSignal): Promise<LocalConnection>;
+/** Stop before transport when the connected SAG does not advertise an operation. */
+export declare function requireToolCapability(connection: LocalConnection, toolName: CapabilityGatedToolName): void;
+/** Execute one complete local tool operation behind a credential-safe failure boundary. */
+export declare function localOperation<T>(manager: ConnectionManager, signal: AbortSignal, operation: (connection: LocalConnection) => Promise<T>): Promise<T>;
+/** Choose a source deterministically or return model-actionable candidates. */
+export declare function selectSource(connection: LocalConnection, explicitSourceId: string | undefined, signal: AbortSignal): Promise<string>;
+export declare function jsonRender(value: unknown): {
+    type: "text";
+    text: string;
+}[];
+//# sourceMappingURL=local.d.ts.map

package/lib/tools/local.js

@@ -0,0 +1,111 @@
+import { FsError } from '@deepseek-ai/dsh-fs';
+import { SAG_DOCTOR_COMMAND, SAG_SETUP_COMMAND } from '../connection/guidance.js';
+import { SagApiError } from '../local/api-client.js';
+export const SAG_NOT_FOUND_MESSAGE = `没有发现正在运行的 SAG。请先启动 SAG 后重试；也可运行 ${SAG_SETUP_COMMAND} 重新发现。`;
+/** Current SAG v1 capability required by each endpoint-backed local Tool. */
+export const SAG_TOOL_CAPABILITY = {
+    sag_list_sources: 'sources.list',
+    sag_create_source: 'sources.create',
+    sag_search: 'knowledge.search',
+    sag_read: 'knowledge.read',
+    sag_list_documents: 'documents.list',
+    sag_get_document: 'documents.get',
+    sag_upload_file: 'documents.upload',
+    sag_ingest_text: 'documents.ingest',
+    sag_reprocess_document: 'documents.reprocess',
+    sag_delete_document: 'documents.delete',
+};
+class LocalToolInputError extends Error {
+}
+/** Raise a model-actionable input/configuration failure from inside an operation. */
+export function localInputError(message) {
+    throw new LocalToolInputError(message);
+}
+function connectionError(report) {
+    switch (report.status) {
+        case 'not-found':
+            return new Error(SAG_NOT_FOUND_MESSAGE);
+        case 'unreachable':
+            return new Error(`SAG 已发现但当前无法连接。请确认 SAG 正在运行，然后重试或运行 ${SAG_DOCTOR_COMMAND}。`);
+        case 'incompatible':
+            return new Error(`当前 SAG 版本与 dsh-sag 不兼容。请升级 SAG，然后运行 ${SAG_DOCTOR_COMMAND}。`);
+        case 'ready':
+            return new Error(`SAG 连接缺少必要信息。请运行 ${SAG_SETUP_COMMAND} 重新配置。`);
+    }
+}
+/** Resolve one ready local connection without exposing credentials or transport details. */
+export async function connectLocal(manager, signal) {
+    let report;
+    try {
+        report = await manager.ensureConnected(signal);
+    }
+    catch {
+        if (signal.aborted)
+            throw signal.reason;
+        throw new Error(`无法检查 SAG 连接。请确认 SAG 正在运行，然后重试或运行 ${SAG_DOCTOR_COMMAND}。`);
+    }
+    if (report.status !== 'ready' || report.descriptor === undefined || report.gateway === undefined || report.capabilities === undefined) {
+        throw connectionError(report);
+    }
+    return { descriptor: report.descriptor, capabilities: report.capabilities, gateway: report.gateway, sourceCount: report.sourceCount };
+}
+/** Stop before transport when the connected SAG does not advertise an operation. */
+export function requireToolCapability(connection, toolName) {
+    const capability = SAG_TOOL_CAPABILITY[toolName];
+    if (!connection.capabilities.capabilities.includes(capability)) {
+        localInputError(`This SAG version does not provide ${capability}. Upgrade SAG or use sag_status to inspect available capabilities.`);
+    }
+}
+function redacted(value, token) {
+    return value?.split(token).join('<redacted>');
+}
+function publicApiError(error, token) {
+    const prefix = `SAG API ${error.status} ${error.code}: `;
+    const detail = error.message.startsWith(prefix) ? error.message.slice(prefix.length) : error.message;
+    return new SagApiError(error.status, redacted(error.code, token), redacted(detail, token), error.retryable, redacted(error.requestId, token), redacted(error.layer, token), redacted(error.stage, token));
+}
+/** Execute one complete local tool operation behind a credential-safe failure boundary. */
+export async function localOperation(manager, signal, operation) {
+    const connection = await connectLocal(manager, signal);
+    try {
+        return await operation(connection);
+    }
+    catch (error) {
+        if (signal.aborted)
+            throw signal.reason;
+        if (error instanceof LocalToolInputError || error instanceof FsError)
+            throw error;
+        if (error instanceof SagApiError)
+            throw publicApiError(error, connection.descriptor.accessToken);
+        throw new Error(`SAG 连接已中断或返回了不兼容的数据。请确认 SAG 正在运行，然后重试或运行 ${SAG_DOCTOR_COMMAND}。`);
+    }
+}
+/** Choose a source deterministically or return model-actionable candidates. */
+export async function selectSource(connection, explicitSourceId, signal) {
+    const explicit = explicitSourceId?.trim();
+    if (explicit)
+        return explicit;
+    const configured = connection.capabilities.defaultSourceId?.trim();
+    if (configured)
+        return configured;
+    if (connection.capabilities.defaultSourceId === undefined) {
+        const descriptorDefault = connection.descriptor.defaultSourceId?.trim();
+        if (descriptorDefault)
+            return descriptorDefault;
+    }
+    if (!connection.capabilities.capabilities.includes('sources.list')) {
+        localInputError('当前 SAG 未提供 sources.list，且没有默认知识库。请为此操作明确指定 source_id。');
+    }
+    const sources = await connection.gateway.listSources(signal);
+    if (sources.length === 1)
+        return sources[0].id;
+    if (sources.length === 0) {
+        localInputError('SAG 中还没有知识库。请先用 sag_create_source 创建一个知识库。');
+    }
+    const choices = sources.map(source => `${source.id} (${source.name})`).join('、');
+    localInputError(`发现多个知识库且未设置默认项，请指定知识库 source_id。可选知识库：${choices}`);
+}
+export function jsonRender(value) {
+    return [{ type: 'text', text: JSON.stringify(value, null, 2) }];
+}
+//# sourceMappingURL=local.js.map

package/lib/tools/output.d.ts

@@ -0,0 +1,96 @@
+import type { ReadResult, SearchResult } from '../runtime/protocol.js';
+export declare const SEARCH_OUTPUT_SCHEMA: {
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly properties: {
+        readonly query: {
+            readonly type: "string";
+            readonly required: true;
+        };
+        readonly evidences: {
+            readonly type: "array";
+            readonly required: true;
+            readonly items: {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly properties: {
+                    readonly evidenceRef: {
+                        readonly type: "string";
+                        readonly required: true;
+                    };
+                    readonly namespaceId: {
+                        readonly type: "string";
+                        readonly required: true;
+                    };
+                    readonly sourceId: {
+                        readonly type: "string";
+                        readonly required: true;
+                    };
+                    readonly title: {
+                        readonly type: "string";
+                        readonly required: true;
+                    };
+                    readonly excerpt: {
+                        readonly type: "string";
+                        readonly required: true;
+                    };
+                    readonly score: {
+                        readonly type: "number";
+                    };
+                };
+            };
+        };
+    };
+};
+export declare const READ_OUTPUT_SCHEMA: {
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly properties: {
+        readonly title: {
+            readonly type: "string";
+            readonly required: true;
+        };
+        readonly content: {
+            readonly type: "string";
+            readonly required: true;
+        };
+        readonly offset: {
+            readonly type: "integer";
+            readonly required: true;
+        };
+        readonly nextOffset: {
+            readonly type: "integer";
+        };
+        readonly totalChars: {
+            readonly type: "integer";
+            readonly required: true;
+        };
+        readonly events: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly properties: {
+                    readonly id: {
+                        readonly type: "string";
+                    };
+                    readonly title: {
+                        readonly type: "string";
+                    };
+                    readonly summary: {
+                        readonly type: "string";
+                    };
+                    readonly category: {
+                        readonly type: "string";
+                    };
+                    readonly rank: {
+                        readonly type: "integer";
+                    };
+                };
+            };
+        };
+    };
+};
+export declare function renderSearch(result: SearchResult, labels: ReadonlyMap<string, string>): string;
+export declare function renderRead(result: ReadResult): string;
+//# sourceMappingURL=output.d.ts.map

package/lib/tools/output.js

@@ -0,0 +1,67 @@
+export const SEARCH_OUTPUT_SCHEMA = {
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+        query: { type: 'string', required: true },
+        evidences: {
+            type: 'array',
+            required: true,
+            items: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    evidenceRef: { type: 'string', required: true },
+                    namespaceId: { type: 'string', required: true },
+                    sourceId: { type: 'string', required: true },
+                    title: { type: 'string', required: true },
+                    excerpt: { type: 'string', required: true },
+                    score: { type: 'number' },
+                },
+            },
+        },
+    },
+};
+export const READ_OUTPUT_SCHEMA = {
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+        title: { type: 'string', required: true },
+        content: { type: 'string', required: true },
+        offset: { type: 'integer', required: true },
+        nextOffset: { type: 'integer' },
+        totalChars: { type: 'integer', required: true },
+        events: {
+            type: 'array',
+            items: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    id: { type: 'string' },
+                    title: { type: 'string' },
+                    summary: { type: 'string' },
+                    category: { type: 'string' },
+                    rank: { type: 'integer' },
+                },
+            },
+        },
+    },
+};
+export function renderSearch(result, labels) {
+    if (result.evidences.length === 0)
+        return 'No SAG evidence matched the query.';
+    return result.evidences.map((evidence, index) => {
+        const label = labels.get(evidence.namespaceId) ?? evidence.namespaceId;
+        const score = evidence.score === undefined ? '' : ` (score ${evidence.score.toFixed(3)})`;
+        return `${index + 1}. [${label}] ${evidence.title}${score}\n   ${evidence.excerpt}\n   evidence_ref: ${evidence.evidenceRef}`;
+    }).join('\n\n');
+}
+export function renderRead(result) {
+    const events = result.events?.length
+        ? `\n\nRelated events:\n${result.events.map(event => `- ${event.title ?? event.id ?? 'event'}${event.summary ? `: ${event.summary}` : ''}`).join('\n')}`
+        : '';
+    const continuation = result.nextOffset === undefined
+        ? ''
+        : `\n\nContinue with sag_read using the same evidence_ref and offset=${result.nextOffset}.`;
+    return `# ${result.title}\n\n${result.content}${events}${continuation}`;
+}
+//# sourceMappingURL=output.js.map

package/lib/tools/read.d.ts

@@ -0,0 +1,6 @@
+import type { SagConnectionManager } from '../connection/manager.js';
+import type { ResolvedConfig } from '../config.js';
+import type { SagRuntimeClient } from '../runtime/client.js';
+/** Build the mode-specific bounded evidence reader. */
+export declare function createReadTool(client: SagRuntimeClient | Pick<SagConnectionManager, 'ensureConnected'>, config: ResolvedConfig): import("@deepseek-ai/dsh-tools").ToolDefinition;
+//# sourceMappingURL=read.d.ts.map

package/lib/tools/read.js

@@ -0,0 +1,84 @@
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { sagEvidenceRef } from '../brand.js';
+import { decodeLocalEvidenceRef } from '../local/api-client.js';
+import { presentReadCall } from '../presentation.js';
+import { localInputError, localOperation, requireToolCapability } from './local.js';
+import { READ_OUTPUT_SCHEMA, renderRead } from './output.js';
+function readResult(value) {
+    if (value === null || typeof value !== 'object' || !('content' in value))
+        throw new Error('SAG runtime returned the wrong read result type');
+    return value;
+}
+function createEmbeddedReadTool(client, config) {
+    return defineTool({
+        name: 'sag_read', description: 'Read a bounded page from one embedded evidence_ref returned by sag_search.',
+        parameters: {
+            evidence_ref: { type: 'string', required: true, description: 'Opaque reference returned by sag_search.' },
+            offset: { type: 'integer', description: 'Unicode character offset, starting at 0.' },
+            max_chars: { type: 'integer', description: 'Maximum characters to return.' },
+            include_events: { type: 'boolean', description: 'Include bounded related event summaries.' },
+        },
+        output: { schema: READ_OUTPUT_SCHEMA, render: (_args, value) => [{ type: 'text', text: renderRead(value) }] },
+        timeoutMs: config.requestTimeoutMs, isConcurrencySafe: () => true,
+        async execute(args, exec) {
+            const evidenceRef = sagEvidenceRef(args.evidence_ref);
+            const offset = args.offset ?? 0;
+            const requestedMaxChars = args.max_chars ?? config.maxReadChars;
+            if (!Number.isInteger(offset) || offset < 0)
+                throw new Error('sag_read offset must not be negative');
+            if (!Number.isInteger(requestedMaxChars) || requestedMaxChars < 1)
+                throw new Error('sag_read max_chars must be positive');
+            return readResult(await client.request('read', {
+                evidenceRef, offset, maxChars: Math.min(requestedMaxChars, config.maxReadChars), includeEvents: args.include_events ?? false,
+            }, exec.signal));
+        },
+        presentCall: args => presentReadCall(args),
+    });
+}
+function createLocalReadTool(manager, config) {
+    return defineTool({
+        name: 'sag_read', description: 'Read a bounded Unicode page from one local evidence_ref returned by sag_search.',
+        parameters: {
+            evidence_ref: { type: 'string', required: true, description: 'Opaque reference returned by sag_search.' },
+            offset: { type: 'integer', description: 'Unicode character offset, starting at 0.' },
+            max_chars: { type: 'integer', description: 'Maximum characters, capped by plugin configuration.' },
+        },
+        output: { schema: READ_OUTPUT_SCHEMA, render: (_args, value) => [{ type: 'text', text: renderRead(value) }] },
+        timeoutMs: config.requestTimeoutMs, isConcurrencySafe: () => true,
+        execute(args, exec) {
+            return localOperation(manager, exec.signal, async (connection) => {
+                requireToolCapability(connection, 'sag_read');
+                const offset = args.offset ?? 0;
+                const requestedMaxChars = args.max_chars ?? config.maxReadChars;
+                if (!Number.isInteger(offset) || offset < 0)
+                    localInputError('sag_read offset must not be negative');
+                if (!Number.isInteger(requestedMaxChars) || requestedMaxChars < 1)
+                    localInputError('sag_read max_chars must be positive');
+                let evidenceRef;
+                try {
+                    decodeLocalEvidenceRef(args.evidence_ref);
+                    evidenceRef = args.evidence_ref;
+                }
+                catch (error) {
+                    localInputError(error instanceof Error ? error.message : 'dsh-sag: invalid local evidence reference');
+                }
+                const chunk = await connection.gateway.read({ evidenceRef }, exec.signal);
+                const characters = Array.from(chunk.content);
+                const boundedMaxChars = Math.min(requestedMaxChars, config.maxReadChars);
+                const content = characters.slice(offset, offset + boundedMaxChars).join('');
+                const consumed = Array.from(content).length;
+                const nextOffset = offset + consumed;
+                return { title: `${chunk.sourceId}/${chunk.chunkId}`, content, offset,
+                    ...(nextOffset < characters.length && consumed > 0 ? { nextOffset } : {}), totalChars: characters.length };
+            });
+        },
+        presentCall: args => presentReadCall(args),
+    });
+}
+/** Build the mode-specific bounded evidence reader. */
+export function createReadTool(client, config) {
+    return config.mode === 'embedded'
+        ? createEmbeddedReadTool(client, config)
+        : createLocalReadTool(client, config);
+}
+//# sourceMappingURL=read.js.map

package/lib/tools/search.d.ts

@@ -0,0 +1,6 @@
+import type { SagConnectionManager } from '../connection/manager.js';
+import type { ResolvedConfig } from '../config.js';
+import type { SagRuntimeClient } from '../runtime/client.js';
+/** Build the mode-specific model-facing SAG search tool. */
+export declare function createSearchTool(client: SagRuntimeClient | Pick<SagConnectionManager, 'ensureConnected'>, config: ResolvedConfig): import("@deepseek-ai/dsh-tools").ToolDefinition;
+//# sourceMappingURL=search.d.ts.map