@chengxianglibra/dsh-data-analysis 0.1.2 → 0.2.0

package/lib/presentation/projection/sql-code.js

@@ -12,7 +12,7 @@ def sql_code_snapshot(session, artifact):
         succeeded_run = mv.SucceededRun
         get_run = session.get_run
     except Exception:
-        return {"snippets": [], "notices": ["当前 Marivo 未提供读取持久化 SQL 所需的公开 Run 能力。"]}
+        return {"snippets": [], "notices": ["marivo.presentation.sql-capability-unavailable"]}
 
     pending = [(artifact.ref, artifact)]
     scheduled, runs, seen_queries = {artifact.ref}, {}, set()
@@ -22,30 +22,30 @@ def sql_code_snapshot(session, artifact):
             current = known_artifact if known_artifact is not None else session.artifact(expected_ref)
             meta, contract = current.meta, current.contract()
             if current.ref != expected_ref or contract.ref != expected_ref or meta.session_id != session.id or Path(meta.project_root).resolve() != Path.cwd().resolve():
-                notice("部分上游 Artifact 的身份或 Workspace 不一致，已拒绝读取其 SQL。")
+                notice("marivo.presentation.sql-artifact-mismatch")
                 continue
             producer = meta.produced_by_job
             if producer is None:
-                notice("部分 Artifact 未保存生产 Run 标识，无法读取其生成 SQL。")
+                notice("marivo.presentation.sql-producer-missing")
                 continue
             if not valid_string(producer, 512):
-                notice("部分 Artifact 的生产 Run 标识无效，已拒绝读取其 SQL。")
+                notice("marivo.presentation.sql-producer-invalid")
                 continue
             run = runs.get(producer)
             if run is None:
                 run = get_run(producer)
                 runs[producer] = run
             if not isinstance(run, succeeded_run) or run.run_id != producer or run.output_mode != "produced" or run.output_artifact_ref != expected_ref:
-                notice("部分生产 Run 的身份、完成状态或产出不匹配，已拒绝读取其 SQL。")
+                notice("marivo.presentation.sql-run-mismatch")
                 continue
             for query in run.queries:
                 if query_count >= 32:
-                    notice("SQL 快照最多读取 32 条查询记录，其余记录未纳入。")
+                    notice("marivo.presentation.sql-query-limit")
                     break
                 query_count += 1
                 query_id = query.query_id
                 if not valid_string(query_id, 512):
-                    notice("部分 SQL 记录的查询标识无效，未纳入代码快照。")
+                    notice("marivo.presentation.sql-query-invalid")
                     continue
                 query_key = (producer, query_id)
                 if query_key in seen_queries:
@@ -53,27 +53,27 @@ def sql_code_snapshot(session, artifact):
                 seen_queries.add(query_key)
                 sql = query.sql
                 if not valid_string(sql, 32768) or not sql.strip():
-                    notice("部分 SQL 为空、包含不支持的字符或超过 32768 字符，未截断也未纳入快照。")
+                    notice("marivo.presentation.sql-sql-invalid")
                     continue
                 snippets.append({"language": "sql", "text": sql, "provenance": "execution", "runId": producer, "queryId": query_id, "artifactRef": expected_ref})
             for input_index, input_ref in enumerate(run.input_artifact_refs):
                 if input_index >= 65:
-                    notice("SQL 追溯最多读取 64 个上游 Artifact，其余来源未纳入。")
+                    notice("marivo.presentation.sql-upstream-limit")
                     break
                 if not valid_string(input_ref, 512):
-                    notice("部分上游 Artifact 标识无效，已停止该分支的 SQL 追溯。")
+                    notice("marivo.presentation.sql-upstream-invalid")
                     continue
                 if input_ref in scheduled:
                     continue
                 if len(scheduled) >= 65:
-                    notice("SQL 追溯最多读取 64 个上游 Artifact，其余来源未纳入。")
+                    notice("marivo.presentation.sql-upstream-limit")
                     break
                 scheduled.add(input_ref)
                 pending.append((input_ref, None))
         except Exception:
             # A missing record or capability affects code only. Never return exception text.
-            notice("部分持久化生产记录无法通过当前 Workspace 的公开 API 读取，SQL 快照可能不完整。")
+            notice("marivo.presentation.sql-read-unavailable")
     if not snippets and not notices:
-        notice("该 Artifact 及已读取的上游生产记录未保存 SQL。")
+        notice("marivo.presentation.sql-not-saved")
     return {"snippets": snippets, "notices": notices}
 `.trim();

package/lib/presentation/reports.js

@@ -1,10 +1,11 @@
 import { randomUUID } from 'node:crypto';
 import { constants } from 'node:fs';
-import { lstat, open, realpath, rename, rm } from 'node:fs/promises';
+import { lstat, open, opendir, realpath, rename, rm } from 'node:fs/promises';
 import path from 'node:path';
 import { withFileLock } from '@deepseek-ai/dsh-atomic-write';
 import { buildPresentation } from "./build/index.js";
 import { commitPresentation } from "./commit.js";
+import { parseReportHistory, REPORT_HISTORY_BYTES, REPORT_HISTORY_LIMIT, } from "./contracts/catalog.js";
 import { parsePresentationDocument, parsePresentationReceipt, } from "./contracts/index.js";
 import { presentationAssetPath, presentationReportPath, presentationSha256, readPresentationAsset, readReportFile, } from "./files.js";
 export async function readReceiptDocument(root, receipt, signal) {
@@ -24,26 +25,101 @@ export async function readReceiptDocument(root, receipt, signal) {
         throw new Error('asset-owner-mismatch');
     return document;
 }
-export async function resolvePresentation(root, workspaceId, reportId, signal) {
-    const bytes = await readReportFile(root, path.join(presentationReportPath(root, reportId), 'current.json'), 20 * 1024, signal);
+/** Current and its publication history become visible through one atomic rename. */
+export async function readReportHistory(root, workspaceId, reportId, signal) {
+    const bytes = await readReportFile(root, path.join(presentationReportPath(root, reportId), 'current.json'), REPORT_HISTORY_BYTES, signal);
     const current = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes));
-    if (!current ||
-        Object.keys(current).sort().join(',') !== 'receipt,reportId,schemaVersion,workspaceId' ||
-        current.schemaVersion !== 2 ||
-        current.workspaceId !== workspaceId ||
-        current.reportId !== reportId)
+    if (!current || current.workspaceId !== workspaceId || current.reportId !== reportId)
         throw new Error('invalid-report-current');
     const receipt = parsePresentationReceipt(current.receipt);
     if (receipt.workspaceId !== workspaceId || receipt.reportId !== reportId)
         throw new Error('asset-owner-mismatch');
+    if (current.schemaVersion === 2 &&
+        Object.keys(current).sort().join(',') === 'receipt,reportId,schemaVersion,workspaceId') {
+        return {
+            workspaceId,
+            reportId,
+            currentBuildId: receipt.buildId,
+            legacyHistoryUnavailable: true,
+            versions: [{ receipt, publishedAt: null, source: null }],
+        };
+    }
+    if (current.schemaVersion !== 3 ||
+        Object.keys(current).sort().join(',') !==
+            'legacyHistoryUnavailable,receipt,reportId,schemaVersion,versions,workspaceId')
+        throw new Error('invalid-report-current');
+    const history = parseReportHistory({
+        workspaceId,
+        reportId,
+        currentBuildId: receipt.buildId,
+        legacyHistoryUnavailable: current.legacyHistoryUnavailable,
+        versions: current.versions,
+    });
+    if (JSON.stringify(history.versions[0].receipt) !== JSON.stringify(receipt))
+        throw new Error('invalid-report-history');
+    return history;
+}
+export async function resolvePresentation(root, workspaceId, reportId, signal) {
+    const history = await readReportHistory(root, workspaceId, reportId, signal);
+    const receipt = history.versions[0].receipt;
     await readReceiptDocument(root, receipt, signal);
     return receipt;
 }
+/** Enumerate only publication pointers, never completed-but-unpublished build directories. */
+export async function listReports(root, workspaceId, signal) {
+    const directory = path.dirname(presentationReportPath(root, 'catalog'));
+    const parents = [root, path.dirname(directory), directory];
+    const identities = [];
+    try {
+        for (const name of parents) {
+            const stat = await lstat(name);
+            if (!stat.isDirectory() || stat.isSymbolicLink() || (await realpath(name)) !== name)
+                throw new Error('asset-path-mismatch');
+            identities.push(stat);
+        }
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return { workspaceId, reports: [], unavailable: 0 };
+        throw error;
+    }
+    const reports = [];
+    let unavailable = 0, count = 0;
+    for await (const entry of await opendir(directory)) {
+        signal?.throwIfAborted();
+        if (++count > 4096)
+            throw new Error('report-catalog-too-large');
+        if (entry.name.startsWith('.'))
+            continue;
+        try {
+            if (!entry.isDirectory() || entry.isSymbolicLink())
+                throw new Error('asset-not-file');
+            const history = await readReportHistory(root, workspaceId, entry.name, signal);
+            reports.push(history.versions[0]);
+        }
+        catch (error) {
+            signal?.throwIfAborted();
+            if (error.code !== 'ENOENT')
+                unavailable++;
+        }
+    }
+    for (const [index, name] of parents.entries()) {
+        const stat = await lstat(name);
+        if (stat.dev !== identities[index].dev ||
+            stat.ino !== identities[index].ino ||
+            stat.isSymbolicLink() ||
+            (await realpath(name)) !== name)
+            throw new Error('asset-path-mismatch');
+    }
+    reports.sort((a, b) => (b.publishedAt ?? '').localeCompare(a.publishedAt ?? '') ||
+        a.receipt.reportId.localeCompare(b.receipt.reportId));
+    return { workspaceId, reports, unavailable };
+}
 /** The mutable pointer is the publication boundary; completed builds are never overwritten. */
-export async function publishPresentation(root, document, expectedBuildId, assertOwner, signal) {
+export async function publishPresentation(root, document, expectedBuildId, assertOwner, signal, source = null) {
     await assertOwner();
     signal?.throwIfAborted();
-    const built = await buildPresentation(document);
+    const built = await buildPresentation(document, { html: false });
     await assertOwner();
     const receipt = await commitPresentation(root, built, assertOwner, signal);
     const directory = presentationReportPath(root, document.reportId);
@@ -66,9 +142,12 @@ export async function publishPresentation(root, document, expectedBuildId, asser
     await check();
     await withFileLock(currentPath, async () => {
         await check();
+        let history;
         let current;
         try {
-            current = await resolvePresentation(root, document.workspaceId, document.reportId, signal);
+            history = await readReportHistory(root, document.workspaceId, document.reportId, signal);
+            current = history.versions[0].receipt;
+            await readReceiptDocument(root, current, signal);
         }
         catch (error) {
             if (expectedBuildId !== null || error.code !== 'ENOENT')
@@ -85,17 +164,35 @@ export async function publishPresentation(root, document, expectedBuildId, asser
         }
         if ((current?.buildId ?? null) !== expectedBuildId)
             throw new Error('report-save-conflict');
+        const versions = [
+            { receipt, publishedAt: new Date().toISOString(), source },
+            ...(history?.versions ?? []),
+        ];
+        if (versions.length > REPORT_HISTORY_LIMIT)
+            throw new Error('report-history-full');
+        parseReportHistory({
+            workspaceId: document.workspaceId,
+            reportId: document.reportId,
+            currentBuildId: receipt.buildId,
+            legacyHistoryUnavailable: history?.legacyHistoryUnavailable ?? false,
+            versions,
+        });
+        const pointer = JSON.stringify({
+            schemaVersion: 3,
+            workspaceId: document.workspaceId,
+            reportId: document.reportId,
+            receipt,
+            versions,
+            legacyHistoryUnavailable: history?.legacyHistoryUnavailable ?? false,
+        });
+        if (Buffer.byteLength(pointer) > REPORT_HISTORY_BYTES)
+            throw new Error('report-history-full');
         const temporary = path.join(directory, `.current-${randomUUID()}.tmp`);
         let published = false;
         try {
             const file = await open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
             try {
-                await file.writeFile(JSON.stringify({
-                    schemaVersion: 2,
-                    workspaceId: document.workspaceId,
-                    reportId: document.reportId,
-                    receipt,
-                }), { signal });
+                await file.writeFile(pointer, { signal });
                 await file.sync();
             }
             finally {

package/lib/presentation/rpc.js

@@ -1,48 +1,101 @@
 import { randomUUID } from 'node:crypto';
 import path from 'node:path';
+import { finishCleanup, PendingTasks } from "../lifecycle.js";
+import { registerPluginRpc } from "../rpc.js";
+import { readReceiptAsset } from "./asset.js";
 import { applyPresentationEdits } from "./contracts/editing.js";
-import { parsePresentationBuildId, parsePresentationDocument, parsePresentationReceipt, } from "./contracts/index.js";
-import { presentationAssetPath, presentationSha256, readPresentationAsset } from "./files.js";
+import { PresentationContractError, parsePresentationBuildId, parsePresentationReceipt, } from "./contracts/index.js";
 import { MARIVO_PRESENTATION_RPC_CHANNEL } from "./receipt.js";
-import { publishPresentation, readReceiptDocument, resolvePresentation } from "./reports.js";
+import { listReports, publishPresentation, readReceiptDocument, readReportHistory, resolvePresentation, } from "./reports.js";
 export class MarivoPresentationFileService {
     #resolve;
+    #resolveId;
     #abort = new AbortController();
-    constructor(resolve) {
+    #tasks = new PendingTasks();
+    #closing;
+    constructor(resolve, resolveId) {
         this.#resolve = resolve;
+        this.#resolveId = resolveId;
     }
-    async #workspace(sessionId) {
+    async #workspace(input) {
         try {
-            return await this.#resolve(sessionId);
+            if ('workspaceId' in input) {
+                const workspace = await this.#resolveId?.(input.workspaceId);
+                if (workspace && workspace.id !== input.workspaceId)
+                    throw new Error('workspace-unavailable');
+                return workspace;
+            }
+            return await this.#resolve(input.sessionId);
         }
         catch {
             throw new Error('workspace-unavailable');
         }
     }
+    #scope(input) {
+        const scope = 'workspaceId' in input ? 'workspaceId' : 'sessionId';
+        if (typeof input[scope] !== 'string' ||
+            !input[scope].trim() ||
+            input[scope].length > 512 ||
+            ('workspaceId' in input && 'sessionId' in input))
+            throw new Error('invalid-request');
+        return scope;
+    }
+    catalog(endpoint, payload, caller = new AbortController().signal) {
+        return this.#tasks.track(this.#catalog(endpoint, payload, caller));
+    }
+    async #catalog(endpoint, payload, caller = new AbortController().signal) {
+        const signal = AbortSignal.any([caller, this.#abort.signal]);
+        signal.throwIfAborted();
+        if (!payload || typeof payload !== 'object' || Array.isArray(payload))
+            throw new Error('invalid-request');
+        const input = payload;
+        const scope = this.#scope(input);
+        const expected = endpoint === 'reports/list' ? scope : ['reportId', scope].sort().join(',');
+        if (Object.keys(input).sort().join(',') !== expected)
+            throw new Error('invalid-request');
+        const workspace = await this.#workspace(input);
+        if (!workspace)
+            throw new Error('workspace-unavailable');
+        const root = path.resolve(workspace.path);
+        const result = endpoint === 'reports/list'
+            ? await listReports(root, workspace.id, signal)
+            : await readReportHistory(root, workspace.id, parsePresentationBuildId(input.reportId), signal);
+        const current = await this.#workspace(input);
+        if (!current || current.id !== workspace.id || path.resolve(current.path) !== root)
+            throw new Error('workspace-changed');
+        signal.throwIfAborted();
+        return result;
+    }
     close() {
         this.#abort.abort();
+        this.#closing ??= finishCleanup([() => this.#tasks.drain()]);
+        return this.#closing;
+    }
+    report(endpoint, payload, caller = new AbortController().signal) {
+        return this.#tasks.track(this.#report(endpoint, payload, caller));
     }
-    async report(endpoint, payload, caller = new AbortController().signal) {
+    async #report(endpoint, payload, caller = new AbortController().signal) {
         const signal = AbortSignal.any([caller, this.#abort.signal]);
+        signal.throwIfAborted();
         if (!payload || typeof payload !== 'object' || Array.isArray(payload))
             throw new Error('invalid-request');
         const input = payload;
-        const expected = endpoint === 'reports/save'
-            ? 'edits,expectedBuildId,reportId,sessionId'
-            : 'reportId,sessionId';
-        if (Object.keys(input).sort().join(',') !== expected ||
-            typeof input.sessionId !== 'string' ||
-            !input.sessionId.trim() ||
-            input.sessionId.length > 512)
+        const scope = this.#scope(input);
+        const expected = (endpoint === 'reports/save'
+            ? ['edits', 'expectedBuildId', 'reportId', scope]
+            : ['reportId', scope])
+            .sort()
+            .join(',');
+        if (Object.keys(input).sort().join(',') !== expected)
             throw new Error('invalid-request');
         const reportId = parsePresentationBuildId(input.reportId, '/reportId');
-        const workspace = await this.#workspace(input.sessionId);
+        const workspace = await this.#workspace(input);
         if (!workspace)
             throw new Error('workspace-unavailable');
         const root = path.resolve(workspace.path);
         const check = async () => {
             signal.throwIfAborted();
-            const current = await this.#workspace(input.sessionId);
+            const current = await this.#workspace(input);
             if (!current || current.id !== workspace.id || path.resolve(current.path) !== root)
                 throw new Error('workspace-changed');
         };
@@ -63,46 +116,29 @@ export class MarivoPresentationFileService {
             throw new Error('invalid-report-edits');
         }
         await check();
-        return publishPresentation(root, { ...edited, buildId: randomUUID(), generatedAt: new Date().toISOString() }, expectedBuildId, check, signal);
+        return publishPresentation(root, { ...edited, buildId: randomUUID(), generatedAt: new Date().toISOString() }, expectedBuildId, check, signal, { kind: 'reader', sessionId: typeof input.sessionId === 'string' ? input.sessionId : null });
+    }
+    read(payload, caller = new AbortController().signal) {
+        return this.#tasks.track(this.#read(payload, caller));
     }
-    async read(payload, caller = new AbortController().signal) {
+    async #read(payload, caller = new AbortController().signal) {
         const signal = AbortSignal.any([caller, this.#abort.signal]);
         signal.throwIfAborted();
         if (!payload || typeof payload !== 'object' || Array.isArray(payload))
             throw new Error('invalid-request');
         const input = payload;
-        if (Object.keys(input).sort().join(',') !== 'asset,receipt,sessionId' ||
-            typeof input.sessionId !== 'string' ||
-            !input.sessionId.trim() ||
-            input.sessionId.length > 512 ||
+        if (Object.keys(input).sort().join(',') !==
+            ['asset', 'receipt', this.#scope(input)].sort().join(',') ||
             (input.asset !== 'presentation.json' && input.asset !== 'index.html'))
             throw new Error('invalid-request');
         const receipt = structuredClone(parsePresentationReceipt(input.receipt));
         const asset = input.asset;
-        const workspace = await this.#workspace(input.sessionId);
+        const workspace = await this.#workspace(input);
         if (!workspace || workspace.id !== receipt.workspaceId)
             throw new Error('workspace-unavailable');
         const root = path.resolve(workspace.path);
-        for (const file of Object.values(receipt.files))
-            if (file.path !== presentationAssetPath(root, receipt.reportId, receipt.buildId, file.asset))
-                throw new Error('asset-path-mismatch');
-        const documentBytes = await readPresentationAsset(root, receipt.reportId, receipt.buildId, 'presentation.json', signal);
-        if (documentBytes.length !== receipt.files.document.bytes ||
-            presentationSha256(documentBytes) !== receipt.files.document.sha256)
-            throw new Error('asset-digest-mismatch');
-        const document = parsePresentationDocument(JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(documentBytes)));
-        if (document.workspaceId !== workspace.id ||
-            document.reportId !== receipt.reportId ||
-            document.buildId !== receipt.buildId ||
-            document.title !== receipt.title)
-            throw new Error('asset-owner-mismatch');
-        const bytes = asset === 'presentation.json'
-            ? documentBytes
-            : await readPresentationAsset(root, receipt.reportId, receipt.buildId, asset, signal);
-        const file = asset === 'presentation.json' ? receipt.files.document : receipt.files.html;
-        if (bytes.length !== file.bytes || presentationSha256(bytes) !== file.sha256)
-            throw new Error('asset-digest-mismatch');
-        const current = await this.#workspace(input.sessionId);
+        const { bytes, sha256 } = await readReceiptAsset(root, workspace.id, receipt, asset, signal);
+        const current = await this.#workspace(input);
         if (!current || current.id !== workspace.id || path.resolve(current.path) !== root)
             throw new Error('workspace-changed');
         signal.throwIfAborted();
@@ -112,17 +148,19 @@ export class MarivoPresentationFileService {
             buildId: receipt.buildId,
             asset,
             mimeType: asset === 'presentation.json' ? 'application/json' : 'text/html',
-            sha256: file.sha256,
+            sha256,
             bytes: bytes.length,
             bodyBase64: bytes.toString('base64'),
         };
     }
 }
 export function registerMarivoPresentationRpc(connection, service) {
-    const unregister = connection.rpc.handle(MARIVO_PRESENTATION_RPC_CHANNEL, async (endpoint, payload, signal) => {
+    const unregister = registerPluginRpc(connection, MARIVO_PRESENTATION_RPC_CHANNEL, ['reports/resolve', 'reports/save', 'reports/list', 'reports/history', 'files/read'], async (endpoint, payload, signal) => {
         try {
             if (endpoint === 'reports/resolve' || endpoint === 'reports/save')
                 return { ok: true, value: await service.report(endpoint, payload, signal) };
+            if (endpoint === 'reports/list' || endpoint === 'reports/history')
+                return { ok: true, value: await service.catalog(endpoint, payload, signal) };
             if (endpoint === 'files/read')
                 return { ok: true, value: await service.read(payload, signal) };
             throw new Error('unknown-endpoint');
@@ -130,19 +168,19 @@ export function registerMarivoPresentationRpc(connection, service) {
         catch (error) {
             const message = signal.aborted
                 ? 'cancelled'
-                : error?.code === 'ENOENT'
-                    ? 'asset-missing'
-                    : error instanceof Error &&
-                        /^(invalid-request|workspace-unavailable|workspace-changed|asset-path-mismatch|asset-not-file|asset-too-large|asset-changed|asset-digest-mismatch|asset-owner-mismatch|unknown-endpoint|invalid-report-current|invalid-report-edits|report-save-conflict|presentation-directory-changed)$/.test(error.message)
-                        ? error.message
-                        : error instanceof Error && /lock.*timed out|timed out.*lock/i.test(error.message)
-                            ? 'report-save-busy'
-                            : 'presentation-operation-failed';
+                : error instanceof PresentationContractError
+                    ? error.code
+                    : error?.code === 'ENOENT'
+                        ? 'asset-missing'
+                        : error instanceof Error &&
+                            /^(invalid-request|workspace-unavailable|workspace-changed|asset-path-mismatch|asset-not-file|asset-too-large|asset-changed|asset-digest-mismatch|asset-owner-mismatch|unknown-endpoint|invalid-report-current|invalid-report-history|report-history-full|report-catalog-too-large|invalid-report-edits|report-save-conflict|presentation-directory-changed)$/.test(error.message)
+                            ? error.message
+                            : error instanceof Error && /lock.*timed out|timed out.*lock/i.test(error.message)
+                                ? 'report-save-busy'
+                                : 'presentation-operation-failed';
             return { ok: false, error: { code: 'internal', message, details: {} } };
         }
-    }, { authority: 'trusted-host' });
-    return async () => {
-        service.close();
-        await unregister();
-    };
+    });
+    let closing;
+    return () => (closing ??= finishCleanup([unregister, () => service.close()]));
 }

package/lib/presentation/tool.js

@@ -1,13 +1,14 @@
 import { randomUUID } from 'node:crypto';
 import { defineTool } from '@deepseek-ai/dsh-tools';
+import { registerMarivoTool } from "../tool-lifecycle.js";
 import { parsePresentationBuildId } from "./contracts/index.js";
 import { MARIVO_PRESENT_TOOL_NAME, MARIVO_PRESENTATION_DELIVERY_KIND, parsePresentationDelivery, presentationReceiptText, } from "./receipt.js";
 import { publishPresentation, resolvePresentation } from "./reports.js";
-/** One call projects a draft, builds both assets, commits them, then emits the receipt. */
+/** One call projects a draft, builds the document, commits them, then emits the receipt. */
 export function createMarivoPresentTool(source, session, lifecycleSignal) {
     return defineTool({
         name: MARIVO_PRESENT_TOOL_NAME,
-        description: 'Present a complete Workspace-relative analysis draft as one saved document and self-contained offline HTML. Omit report_id and expected_build_id to create a Report; provide both to replace an existing Report with a new immutable Build based on the version you have read. A report-save-conflict requires reading the current report and reconciling the draft; never retry by only changing expected_build_id. Returns the exact published receipt, file locations, and a reader card. Only saved Artifact and computed snapshots are read; sources are declarations, not verification of calculations.',
+        description: 'Present a complete Workspace-relative analysis draft as one saved document, automatically opened in the right-side report tab. HTML is generated only when explicitly exporting or publishing the report. Omit report_id and expected_build_id to create a Report; provide both to replace an existing Report with a new immutable Build based on the version you have read. A report-save-conflict requires reading the current report and reconciling the draft; never retry by only changing expected_build_id. Returns the exact published receipt, file locations, for the report reader. Only saved Artifact and computed snapshots are read; sources are declarations, not verification of calculations.',
         parameters: {
             draft_path: {
                 type: 'string',
@@ -58,7 +59,7 @@ export function createMarivoPresentTool(source, session, lifecycleSignal) {
             if (!owner || owner.session !== session)
                 throw new Error('presentation-session-mismatch');
             const rootCallId = String(exec.rootCallId ?? exec.callId);
-            const call = [...session.events]
+            const call = [...session.snapshotEvents()]
                 .reverse()
                 .find((event) => event.type === 'tool/call' && String(event.data.callId) === rootCallId);
             if (call?.type !== 'tool/call' || !Number.isSafeInteger(call.data.turn) || call.data.turn < 0)
@@ -99,7 +100,7 @@ export function createMarivoPresentTool(source, session, lifecycleSignal) {
                 signal,
             });
             await check();
-            const receipt = await publishPresentation(identity.projectRoot, document, expectedBuildId, check, signal);
+            const receipt = await publishPresentation(identity.projectRoot, document, expectedBuildId, check, signal, { kind: 'agent', sessionId: String(session.id) });
             return {
                 deliveryJson: JSON.stringify(parsePresentationDelivery({
                     kind: MARIVO_PRESENTATION_DELIVERY_KIND,
@@ -113,10 +114,5 @@ export function createMarivoPresentTool(source, session, lifecycleSignal) {
     });
 }
 export function registerMarivoPresentTool(ctx, source, session) {
-    const controller = new AbortController();
-    const unregister = ctx.tools.register(createMarivoPresentTool(source, session, controller.signal));
-    return () => {
-        controller.abort();
-        unregister();
-    };
+    return registerMarivoTool(ctx, createMarivoPresentTool(source, session));
 }

package/lib/report-publishing/adapters.js

@@ -0,0 +1,111 @@
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { z } from 'zod';
+import { PRESENTATION_BUDGETS, parsePresentationBuildId } from "../presentation/contracts/index.js";
+import { registerPluginRpc } from "../rpc.js";
+import { registerMarivoTool } from "../tool-lifecycle.js";
+export const PUBLISHING_CHANNEL = '/dsh-report-publishing';
+const identity = z.string().transform((value) => parsePresentationBuildId(value));
+const field = z.enum(['accessKeyId', 'secretAccessKey', 'sessionToken']);
+export function registerPublishingCredentials(connection, service, workspaceExists) {
+    return registerPluginRpc(connection, PUBLISHING_CHANNEL, ['describe', 'set', 'unset', 'publish'], async (endpoint, payload, signal) => {
+        try {
+            const base = { workspaceId: z.string().min(1).max(512) };
+            const { workspaceId } = z.object(base).parse(payload);
+            if (!workspaceExists(workspaceId))
+                throw new Error('workspace-unavailable');
+            signal.throwIfAborted();
+            const mutation = { ...base, configId: z.string().uuid() };
+            if (endpoint !== 'describe')
+                service.assertConfig(z.object(mutation).parse(payload).configId);
+            if (endpoint === 'publish') {
+                const input = z
+                    .object({
+                    ...mutation,
+                    reportId: identity,
+                    buildId: identity,
+                    viewHtml: z.string().max(PRESENTATION_BUDGETS.htmlBytes).optional(),
+                })
+                    .strict()
+                    .parse(payload);
+                return {
+                    ok: true,
+                    value: await service.publish({ workspaceId }, input.reportId, input.buildId, AbortSignal.any([signal, AbortSignal.timeout(110_000)]), input.viewHtml),
+                };
+            }
+            if (endpoint === 'set') {
+                const input = z
+                    .object({ ...mutation, field, value: z.string().min(1).max(65536) })
+                    .strict()
+                    .parse(payload);
+                await service.change(input.field, input.value, signal);
+            }
+            else if (endpoint === 'unset') {
+                const input = z
+                    .object({ ...mutation, field })
+                    .strict()
+                    .parse(payload);
+                await service.change(input.field, undefined, signal);
+            }
+            else
+                z.object(base).strict().parse(payload);
+            return { ok: true, value: await service.describe() };
+        }
+        catch (error) {
+            const message = publishingError(error);
+            return { ok: false, error: { code: 'internal', message, details: {} } };
+        }
+    });
+}
+export function registerReportPublishTool(ctx, service, sessionId) {
+    return registerMarivoTool(ctx, defineTool({
+        name: 'marivo_publish_report',
+        description: 'Publish a saved report Build as self-contained HTML to the configured object storage only when the user requests publication. Returns the immutable URL. Does not run analysis or include unsaved edits or temporary filters. Credentials are configured under 数据源与凭证 → 报告发布凭证. An unconfirmed upload may already exist; retry the same Build safely. Never send credentials or storage settings as tool arguments.',
+        parameters: {
+            report_id: {
+                type: 'string',
+                required: true,
+                description: 'Saved Report ID from the presentation receipt.',
+            },
+            build_id: {
+                type: 'string',
+                required: true,
+                description: 'Exact saved Build ID to publish.',
+            },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                properties: { publicationJson: { type: 'string', required: true } },
+                additionalProperties: false,
+            },
+            render: (_args, value) => [{ type: 'text', text: value.publicationJson }],
+        },
+        timeoutMs: 120_000,
+        async execute(args, exec) {
+            if (!exec.agent || exec.agent.session.id !== sessionId)
+                throw new Error('presentation-session-mismatch');
+            const input = z.object({ report_id: identity, build_id: identity }).strict().parse(args);
+            try {
+                return {
+                    publicationJson: JSON.stringify(await service.publish({ sessionId }, input.report_id, input.build_id, AbortSignal.any([exec.signal, AbortSignal.timeout(110_000)]))),
+                };
+            }
+            catch (error) {
+                throw new Error(publishingError(error));
+            }
+        },
+    }));
+}
+function publishingError(error) {
+    return error instanceof Error &&
+        [
+            'report-publishing-config-changed',
+            'report-publishing-disabled',
+            'report-publishing-build-unavailable',
+            'report-publishing-credentials-missing',
+            'report-publishing-upload-unconfirmed',
+            'report-publishing-view-invalid',
+        ].includes(error.message)
+        ? error.message
+        : 'report-publishing-operation-failed';
+}