@chengxianglibra/dsh-data-analysis 0.1.1 → 0.2.0

package/lib/presentation/rpc.js

@@ -0,0 +1,186 @@
+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 { PresentationContractError, parsePresentationBuildId, parsePresentationReceipt, } from "./contracts/index.js";
+import { MARIVO_PRESENTATION_RPC_CHANNEL } from "./receipt.js";
+import { listReports, publishPresentation, readReceiptDocument, readReportHistory, resolvePresentation, } from "./reports.js";
+export class MarivoPresentationFileService {
+    #resolve;
+    #resolveId;
+    #abort = new AbortController();
+    #tasks = new PendingTasks();
+    #closing;
+    constructor(resolve, resolveId) {
+        this.#resolve = resolve;
+        this.#resolveId = resolveId;
+    }
+    async #workspace(input) {
+        try {
+            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) {
+        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/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);
+        if (!workspace)
+            throw new Error('workspace-unavailable');
+        const root = path.resolve(workspace.path);
+        const check = async () => {
+            signal.throwIfAborted();
+            const current = await this.#workspace(input);
+            if (!current || current.id !== workspace.id || path.resolve(current.path) !== root)
+                throw new Error('workspace-changed');
+        };
+        await check();
+        const receipt = await resolvePresentation(root, workspace.id, reportId, signal);
+        await check();
+        if (endpoint === 'reports/resolve')
+            return receipt;
+        const expectedBuildId = parsePresentationBuildId(input.expectedBuildId);
+        if (receipt.buildId !== expectedBuildId)
+            throw new Error('report-save-conflict');
+        const base = await readReceiptDocument(root, receipt, signal);
+        let edited;
+        try {
+            edited = applyPresentationEdits(base, input.edits);
+        }
+        catch {
+            throw new Error('invalid-report-edits');
+        }
+        await check();
+        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) {
+        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', 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);
+        if (!workspace || workspace.id !== receipt.workspaceId)
+            throw new Error('workspace-unavailable');
+        const root = path.resolve(workspace.path);
+        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();
+        return {
+            workspaceId: workspace.id,
+            reportId: receipt.reportId,
+            buildId: receipt.buildId,
+            asset,
+            mimeType: asset === 'presentation.json' ? 'application/json' : 'text/html',
+            sha256,
+            bytes: bytes.length,
+            bodyBase64: bytes.toString('base64'),
+        };
+    }
+}
+export function registerMarivoPresentationRpc(connection, service) {
+    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');
+        }
+        catch (error) {
+            const message = signal.aborted
+                ? 'cancelled'
+                : 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: {} } };
+        }
+    });
+    let closing;
+    return () => (closing ??= finishCleanup([unregister, () => service.close()]));
+}

package/lib/presentation/tool.js

@@ -0,0 +1,118 @@
+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 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, 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',
+                required: true,
+                description: 'Workspace-relative path of the complete presentation draft JSON. Updates replace the whole report content; omitted content is not preserved.',
+            },
+            report_id: {
+                type: 'string',
+                description: 'Existing Report ID in the current Workspace to update. Must be provided together with expected_build_id; omit both to create a new Report.',
+            },
+            expected_build_id: {
+                type: 'string',
+                description: 'Build ID of the report version you have read and based this complete draft on. Must be provided together with report_id. A stale version fails with report-save-conflict; read and reconcile the current report before retrying.',
+            },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: { deliveryJson: { type: 'string', required: true } },
+            },
+            render: (_args, value) => [
+                {
+                    type: 'text',
+                    text: presentationReceiptText(parsePresentationDelivery(JSON.parse(value.deliveryJson)).receipt),
+                },
+            ],
+            presentationMeta: (_args, value) => JSON.parse(value.deliveryJson),
+        },
+        timeoutMs: 120_000,
+        async execute(args, exec) {
+            const signal = lifecycleSignal ? AbortSignal.any([exec.signal, lifecycleSignal]) : exec.signal;
+            if (typeof args.draft_path !== 'string' ||
+                args.draft_path.length === 0 ||
+                args.draft_path.length > 4096)
+                throw new Error('invalid-draft-path');
+            const hasReportId = args.report_id !== undefined;
+            const hasExpectedBuildId = args.expected_build_id !== undefined;
+            if (hasReportId !== hasExpectedBuildId)
+                throw new Error('invalid-report-update-target');
+            const reportId = hasReportId
+                ? parsePresentationBuildId(args.report_id, '/report_id')
+                : randomUUID();
+            const expectedBuildId = hasExpectedBuildId
+                ? parsePresentationBuildId(args.expected_build_id, '/expected_build_id')
+                : null;
+            const owner = exec.agent;
+            if (!owner || owner.session !== session)
+                throw new Error('presentation-session-mismatch');
+            const rootCallId = String(exec.rootCallId ?? exec.callId);
+            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)
+                throw new Error('presentation-turn-unavailable');
+            signal.throwIfAborted();
+            const binding = await source();
+            const identity = {
+                workspaceId: binding.workspaceId,
+                projectRoot: binding.projection.binding.projectRoot,
+                fingerprint: binding.projection.binding.fingerprint,
+            };
+            const check = async () => {
+                signal.throwIfAborted();
+                if (owner.session !== session)
+                    throw new Error('presentation-session-mismatch');
+                const current = await source();
+                if (current.projection.status !== 'ready' ||
+                    current.workspaceId !== identity.workspaceId ||
+                    current.projection.binding.projectRoot !== identity.projectRoot ||
+                    current.projection.binding.fingerprint !== identity.fingerprint ||
+                    current.projection.binding !== binding.projection.binding)
+                    throw new Error('presentation-workspace-changed');
+                signal.throwIfAborted();
+            };
+            await check();
+            if (expectedBuildId !== null) {
+                const current = await resolvePresentation(identity.projectRoot, identity.workspaceId, reportId, signal);
+                await check();
+                if (current.buildId !== expectedBuildId)
+                    throw new Error('report-save-conflict');
+            }
+            const draft = await binding.projection.readDraft(args.draft_path, signal);
+            await check();
+            const document = await binding.projection.project(draft, {
+                workspaceId: binding.workspaceId,
+                reportId,
+                buildId: randomUUID(),
+                signal,
+            });
+            await check();
+            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,
+                    schemaVersion: 2,
+                    dshSessionId: String(session.id),
+                    turn: call.data.turn,
+                    receipt,
+                })),
+            };
+        },
+    });
+}
+export function registerMarivoPresentTool(ctx, source, session) {
+    return registerMarivoTool(ctx, createMarivoPresentTool(source, session));
+}

package/lib/python-execution-contracts.js

@@ -0,0 +1 @@
+export {};

package/lib/python-execution.js

@@ -0,0 +1,232 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { link, lstat, mkdir, open, realpath, unlink } from 'node:fs/promises';
+import path from 'node:path';
+import { resolveDshHome } from '@deepseek-ai/dsh-home-paths';
+const CODE_BYTES = 131072;
+const RECORD_BYTES = 262144;
+const EXECUTION_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+const DIGEST = /^[0-9a-f]{64}$/;
+function invalid() {
+    throw new Error('Python execution source is unavailable or invalid');
+}
+function same(left, right) {
+    return left.dev === right.dev && left.ino === right.ino;
+}
+async function directory(filename) {
+    const stat = await lstat(filename);
+    if (!stat.isDirectory() || stat.isSymbolicLink() || (await realpath(filename)) !== filename)
+        invalid();
+    return stat;
+}
+async function directories(workspaceRoot, create, signal) {
+    signal?.throwIfAborted();
+    const root = await realpath(workspaceRoot);
+    if (root !== path.resolve(workspaceRoot))
+        invalid();
+    const workspaceIdentity = await directory(root);
+    const hostRoot = path.resolve(resolveDshHome());
+    const paths = [
+        hostRoot,
+        path.join(hostRoot, 'dsh-data-analysis'),
+        path.join(hostRoot, 'dsh-data-analysis', 'python-executions'),
+        path.join(hostRoot, 'dsh-data-analysis', 'python-executions', sha256(Buffer.from(root))),
+    ];
+    const identities = [];
+    const check = async (checkSignal = true) => {
+        if (checkSignal)
+            signal?.throwIfAborted();
+        if (!same(await directory(root), workspaceIdentity) ||
+            path.resolve(resolveDshHome()) !== hostRoot)
+            invalid();
+        for (const [index, expected] of identities.entries())
+            if (!same(await directory(paths[index]), expected))
+                invalid();
+        if (checkSignal)
+            signal?.throwIfAborted();
+    };
+    for (const [index, filename] of paths.entries()) {
+        await check();
+        if (create && index > 0) {
+            try {
+                await mkdir(filename, { mode: 0o700 });
+            }
+            catch (error) {
+                if (error.code !== 'EEXIST')
+                    throw error;
+            }
+        }
+        identities.push(await directory(filename));
+    }
+    await check();
+    return { root, parent: paths[3], check };
+}
+function sourceText(text) {
+    return (typeof text === 'string' &&
+        !!text.trim() &&
+        !text.includes('\0') &&
+        !/[\uD800-\uDFFF]/u.test(text) &&
+        Buffer.byteLength(text) <= CODE_BYTES);
+}
+function timestamp(value) {
+    return (typeof value === 'string' &&
+        Number.isFinite(Date.parse(value)) &&
+        new Date(value).toISOString() === value);
+}
+function sha256(bytes) {
+    return createHash('sha256').update(bytes).digest('hex');
+}
+/** Publish a complete record once. Its final name never exposes a partial write or overwrites. */
+export async function savePythonExecution(workspaceRoot, input, signal) {
+    try {
+        signal?.throwIfAborted();
+        const { text, startedAt, finishedAt } = input;
+        if (!sourceText(text) ||
+            !timestamp(startedAt) ||
+            !timestamp(finishedAt) ||
+            finishedAt < startedAt)
+            invalid();
+        const workspace = await directories(workspaceRoot, true, signal);
+        const executionId = randomUUID();
+        const bytes = Buffer.from(JSON.stringify({
+            schemaVersion: 1,
+            executionId,
+            projectRoot: workspace.root,
+            language: 'python',
+            text,
+            startedAt,
+            finishedAt,
+            exitCode: 0,
+        }));
+        if (bytes.length > RECORD_BYTES)
+            invalid();
+        const ref = { executionId, sha256: sha256(bytes) };
+        const temporary = path.join(workspace.parent, `.${executionId}.pending`);
+        const final = path.join(workspace.parent, `${executionId}.json`);
+        await workspace.check();
+        const file = await open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+        const identity = await file.stat();
+        let published = false;
+        try {
+            await file.writeFile(bytes, { signal });
+            await file.sync();
+            await workspace.check();
+            if (!same(await lstat(temporary), identity))
+                invalid();
+            // Hard-link publication is atomic and fails if a final path already exists.
+            await link(temporary, final);
+            published = true;
+            await workspace.check();
+            if (!same(await lstat(final), identity))
+                invalid();
+            const verified = await readPythonExecution(workspace.root, ref, signal);
+            if (verified.text !== text)
+                invalid();
+            await workspace.check();
+            return ref;
+        }
+        catch (error) {
+            if (published) {
+                try {
+                    await workspace.check(false);
+                    if (same(await lstat(final), identity))
+                        await unlink(final);
+                }
+                catch {
+                    /* Do not remove a replaced path or hide the original error. */
+                }
+            }
+            throw error;
+        }
+        finally {
+            await file.close();
+            try {
+                await workspace.check(false);
+                if (same(await lstat(temporary), identity))
+                    await unlink(temporary);
+            }
+            catch {
+                /* Cleanup cannot override successful execution or follow a replaced parent. */
+            }
+        }
+    }
+    catch {
+        signal?.throwIfAborted();
+        invalid();
+    }
+}
+/** Resolve Host-stored execution identities for the bound Workspace. Never executes code. */
+export async function readPythonExecution(workspaceRoot, ref, signal) {
+    try {
+        signal?.throwIfAborted();
+        if (!ref || !EXECUTION_ID.test(ref.executionId) || !DIGEST.test(ref.sha256))
+            invalid();
+        const { executionId, sha256: expectedDigest } = ref;
+        const workspace = await directories(workspaceRoot, false, signal);
+        const filename = path.join(workspace.parent, `${executionId}.json`);
+        const expected = await lstat(filename);
+        if (!expected.isFile() || expected.isSymbolicLink() || (await realpath(filename)) !== filename)
+            invalid();
+        const file = await open(filename, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+        try {
+            const before = await file.stat();
+            if (!before.isFile() || !same(before, expected) || before.size > RECORD_BYTES)
+                invalid();
+            const bytes = Buffer.alloc(RECORD_BYTES + 1);
+            let length = 0;
+            while (length < bytes.length) {
+                signal?.throwIfAborted();
+                const { bytesRead } = await file.read(bytes, length, bytes.length - length, null);
+                if (!bytesRead)
+                    break;
+                length += bytesRead;
+            }
+            const after = await file.stat();
+            const current = await lstat(filename);
+            await workspace.check();
+            if (length > RECORD_BYTES ||
+                length !== after.size ||
+                !same(current, after) ||
+                !current.isFile() ||
+                before.size !== after.size ||
+                before.mtimeMs !== after.mtimeMs ||
+                before.ctimeMs !== after.ctimeMs ||
+                (await realpath(filename)) !== filename)
+                invalid();
+            const raw = bytes.subarray(0, length);
+            if (sha256(raw) !== expectedDigest)
+                invalid();
+            const record = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(raw));
+            if (!record ||
+                typeof record !== 'object' ||
+                Array.isArray(record) ||
+                Object.keys(record).sort().join(',') !==
+                    'executionId,exitCode,finishedAt,language,projectRoot,schemaVersion,startedAt,text' ||
+                record.schemaVersion !== 1 ||
+                record.executionId !== executionId ||
+                record.projectRoot !== workspace.root ||
+                record.language !== 'python' ||
+                record.exitCode !== 0 ||
+                !sourceText(record.text) ||
+                !timestamp(record.startedAt) ||
+                !timestamp(record.finishedAt) ||
+                record.finishedAt < record.startedAt)
+                invalid();
+            signal?.throwIfAborted();
+            return {
+                language: 'python',
+                text: record.text,
+                provenance: 'execution',
+                executionId,
+                sha256: expectedDigest,
+            };
+        }
+        finally {
+            await file.close();
+        }
+    }
+    catch {
+        signal?.throwIfAborted();
+        invalid();
+    }
+}

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';
+}