@chengxianglibra/dsh-data-analysis 0.3.0 → 0.3.1

package/lib/datasource/resolver-program.js

@@ -1,3 +1,4 @@
+import { PYTHON_IMPORT_IDENTITY } from "../environment/identity.js";
 import { PYTHON_EXCEPTION_PROGRAM } from "../python-exception.js";
 import { PYTHON_RESULT_HEADER } from "../python-result-references.js";
 /** Shared Python adapter. All inputs below arrive on a Host-owned pipe. */
@@ -43,12 +44,11 @@ class SnapshotResolver:
             datasource=request.datasource, fields=request.fields)
 `.trim();
 /** The worker checks the exact binding and enters scope before any user code. */
-export const PYTHON_WORKER = `${PYTHON_EXCEPTION_PROGRAM}\n${RESOLVER_PROGRAM}\n${String.raw `
+export const PYTHON_WORKER = `${PYTHON_IMPORT_IDENTITY}\n${PYTHON_EXCEPTION_PROGRAM}\n${RESOLVER_PROGRAM}\n${String.raw `
 payload = json.load(sys.stdin)
 expected = payload["identity"]
-if (os.path.abspath(sys.executable) != expected["pythonExecutable"] or
-    marivo.__version__ != expected["marivoVersion"] or
-    os.path.abspath(marivo.__file__) != expected["packagePath"] or
+if (_dsh_import_identity(sys.executable, marivo.__version__, marivo.__file__) !=
+    _dsh_import_identity(expected["pythonExecutable"], expected["marivoVersion"], expected["packagePath"]) or
     str(Path.cwd().resolve()) != payload["project_root"]):
     raise RuntimeError("Marivo execution identity changed; rebind required")
 resolver = SnapshotResolver(payload)

package/lib/environment/binding.js

@@ -4,6 +4,7 @@ import path from 'node:path';
 import process from 'node:process';
 import { admitDoctorReport, parseDoctorReport } from "./doctor.js";
 import { MarivoEnvironmentError } from "./errors.js";
+import { canonicalImportIdentity, canonicalPythonExecutable, PYTHON_IMPORT_IDENTITY, } from "./identity.js";
 import { FixedSubprocessPolicy } from "./subprocess.js";
 const DOCTOR_LIMITS = Object.freeze({
     timeoutMs: 30_000,
@@ -15,30 +16,24 @@ const IDENTITY_LIMITS = Object.freeze({
     stdoutMaxBytes: 16_384,
     stderrMaxBytes: 16_384,
 });
-const CHECKED_IDENTITY_PRELUDE = String.raw `
+const CHECKED_IDENTITY_PRELUDE = `${PYTHON_IMPORT_IDENTITY}\n${String.raw `
 import json as _dsh_json
 import os as _dsh_os
 import sys as _dsh_sys
 try:
     import marivo as _dsh_marivo
-    _dsh_actual = {
-        "python_executable": _dsh_os.path.abspath(_dsh_sys.executable),
-        "marivo_version": _dsh_marivo.__version__,
-        "package_path": _dsh_os.path.abspath(_dsh_marivo.__file__ or ""),
-    }
+    _dsh_actual = _dsh_import_identity(
+        _dsh_sys.executable, _dsh_marivo.__version__, _dsh_marivo.__file__,
+    )
 except Exception:
     raise SystemExit(78) from None
 
-_dsh_expected = {
-    "python_executable": _dsh_os.path.abspath(_dsh_sys.argv[1]),
-    "marivo_version": _dsh_sys.argv[2],
-    "package_path": _dsh_os.path.abspath(_dsh_sys.argv[3]),
-}
+_dsh_expected = _dsh_import_identity(*_dsh_sys.argv[1:4])
 if _dsh_actual != _dsh_expected:
     print(_dsh_json.dumps({"kind": "identity-mismatch", "actual": _dsh_actual}), file=_dsh_sys.stderr)
     raise SystemExit(78)
 _dsh_sys.argv = [_dsh_sys.argv[0], *_dsh_sys.argv[4:]]
-`.trim();
+`.trim()}`;
 const IMPORT_IDENTITY_PROGRAM = String.raw `
 print(_dsh_json.dumps(_dsh_actual, sort_keys=True))
 `.trim();
@@ -137,7 +132,7 @@ async function resolvePythonExecutable(projectRoot, configured) {
         ? path.join(projectRoot, process.platform === 'win32' ? '.venv/Scripts/python.exe' : '.venv/bin/python')
         : path.normalize(configured);
     await assertExecutable(executable);
-    return executable;
+    return canonicalPythonExecutable(executable);
 }
 function fingerprint(binding) {
     const payload = [
@@ -232,11 +227,11 @@ export class MarivoEnvironment {
             });
         }
         try {
-            const identity = parseImportIdentity(result.stdout);
-            if (normalizeAbsolute(identity.pythonExecutable) !==
-                normalizeAbsolute(this.binding.pythonExecutable) ||
-                identity.marivoVersion !== this.binding.marivoVersion ||
-                normalizeAbsolute(identity.packagePath) !== normalizeAbsolute(this.binding.packagePath))
+            const identity = canonicalImportIdentity(parseImportIdentity(result.stdout));
+            const expected = this.binding;
+            if (identity.pythonExecutable !== expected.pythonExecutable ||
+                identity.marivoVersion !== expected.marivoVersion ||
+                identity.packagePath !== expected.packagePath)
                 throw new Error('identity values differ from binding');
             return identity;
         }
@@ -256,9 +251,7 @@ function createRuntimeRunner(projectRoot, identity, environment) {
     const subprocessPolicy = new FixedSubprocessPolicy(projectRoot, environment);
     const partialBinding = {
         projectRoot,
-        pythonExecutable: identity.pythonExecutable,
-        marivoVersion: identity.marivoVersion,
-        packagePath: identity.packagePath,
+        ...canonicalImportIdentity(identity),
         subprocessPolicyId: subprocessPolicy.id,
     };
     return new MarivoEnvironment({ ...partialBinding, fingerprint: fingerprint(partialBinding) }, subprocessPolicy);
@@ -269,7 +262,7 @@ export async function bindSharedMarivoWorkspace(projectRoot, runtime) {
     const runner = createRuntimeRunner(projectRoot, {
         pythonExecutable,
         marivoVersion: runtime.marivoVersion,
-        packagePath: normalizeAbsolute(runtime.packagePath),
+        packagePath: runtime.packagePath,
     });
     const result = await runner.runChecked({
         program: PROJECT_CONFIG_PROGRAM,
@@ -318,7 +311,7 @@ export async function bindMarivoEnvironment(config, options = {}) {
         projectRoot,
         pythonExecutable,
         marivoVersion: report.marivo.version,
-        packagePath: normalizeAbsolute(report.marivo.package_path),
+        packagePath: await realpath(report.marivo.package_path),
         subprocessPolicyId: subprocessPolicy.id,
     };
     const binding = {

package/lib/environment/doctor.js

@@ -1,5 +1,6 @@
 import path from 'node:path';
 import { MarivoEnvironmentError } from "./errors.js";
+import { canonicalPythonExecutable } from "./identity.js";
 const DOCTOR_STATUSES = new Set(['ok', 'info', 'warning', 'fail', 'skipped']);
 const OVERALL_STATUSES = new Set(['ok', 'warning', 'fail']);
 function isRecord(value) {
@@ -99,7 +100,13 @@ export function admitDoctorReport(report, expectedProjectRoot, expectedPythonExe
     if (normalizeAbsolute(report.project_root) !== normalizeAbsolute(expectedProjectRoot)) {
         admissionFailure('project_root', `reported ${report.project_root}`);
     }
-    if (normalizeAbsolute(report.python_executable) !== normalizeAbsolute(expectedPythonExecutable)) {
+    try {
+        if (canonicalPythonExecutable(report.python_executable) !==
+            canonicalPythonExecutable(expectedPythonExecutable)) {
+            admissionFailure('python_executable', `reported ${report.python_executable}`);
+        }
+    }
+    catch {
         admissionFailure('python_executable', `reported ${report.python_executable}`);
     }
     if (report.marivo.version.length === 0)

package/lib/environment/identity.js

@@ -0,0 +1,32 @@
+import { realpathSync } from 'node:fs';
+import path from 'node:path';
+/** Resolve directory aliases without following a venv's Python link into its base installation. */
+export function canonicalPythonExecutable(executable) {
+    const absolute = path.resolve(executable);
+    return path.join(realpathSync(path.dirname(absolute)), path.basename(absolute));
+}
+export function canonicalImportIdentity(identity) {
+    return {
+        pythonExecutable: canonicalPythonExecutable(identity.pythonExecutable),
+        marivoVersion: identity.marivoVersion,
+        packagePath: realpathSync(identity.packagePath),
+    };
+}
+/** The Python equivalent of canonicalImportIdentity, shared by every execution boundary. */
+export const PYTHON_IMPORT_IDENTITY = String.raw `
+import os.path as _dsh_identity_path
+
+def _dsh_python_executable(executable):
+    absolute = _dsh_identity_path.abspath(executable)
+    return _dsh_identity_path.join(
+        _dsh_identity_path.realpath(_dsh_identity_path.dirname(absolute)),
+        _dsh_identity_path.basename(absolute),
+    )
+
+def _dsh_import_identity(executable, version, package_path):
+    return {
+        "python_executable": _dsh_python_executable(executable),
+        "marivo_version": version,
+        "package_path": _dsh_identity_path.realpath(package_path),
+    }
+`.trim();

package/lib/environment/project-preparation.js

@@ -1,6 +1,7 @@
 import { lstat, realpath } from 'node:fs/promises';
 import path from 'node:path';
 import { MarivoEnvironmentError } from "./errors.js";
+import { PYTHON_IMPORT_IDENTITY } from "./identity.js";
 const locks = new Map();
 const limits = { timeoutMs: 30_000, stdoutMaxBytes: 1_048_576, stderrMaxBytes: 65_536 };
 const cli = String.raw `
@@ -9,19 +10,18 @@ sys.argv = ["marivo", *sys.argv[1:]]
 runpy.run_module("marivo", run_name="__main__")
 `.trim();
 /** The Host Shell owns policy/cancellation; this program only invokes the public CLI. */
-export const MARIVO_PROJECT_INIT_PROGRAM = String.raw `
+export const MARIVO_PROJECT_INIT_PROGRAM = `${PYTHON_IMPORT_IDENTITY}\n${String.raw `
 import json, os, runpy, sys
 from pathlib import Path
 import marivo
 expected = json.load(sys.stdin)
-if (os.path.abspath(sys.executable) != os.path.abspath(expected["pythonExecutable"]) or
-    marivo.__version__ != expected["marivoVersion"] or
-    os.path.abspath(marivo.__file__ or "") != os.path.abspath(expected["packagePath"]) or
+if (_dsh_import_identity(sys.executable, marivo.__version__, marivo.__file__) !=
+    _dsh_import_identity(expected["pythonExecutable"], expected["marivoVersion"], expected["packagePath"]) or
     str(Path.cwd().resolve()) != expected["projectRoot"]):
     raise RuntimeError("Marivo project preparation identity changed; rebind required")
 sys.argv = ["marivo", "init", "--project-root", expected["projectRoot"]]
 runpy.run_module("marivo", run_name="__main__")
-`.trim();
+`.trim()}`;
 async function manifestPresent(root) {
     try {
         const info = await lstat(path.join(root, 'marivo.toml'));

package/lib/environment/runtime.js

@@ -6,6 +6,7 @@ import process from 'node:process';
 import { resolveDshHome } from '@deepseek-ai/dsh-home-paths';
 import { MARIVO_PACKAGE_SPEC, MARIVO_VERSION, RUNTIME_INSTALLATION_VERSION, } from "../compatibility.js";
 import { MarivoEnvironmentError } from "./errors.js";
+import { canonicalPythonExecutable, PYTHON_IMPORT_IDENTITY } from "./identity.js";
 import { FixedSubprocessPolicy } from "./subprocess.js";
 export const SHARED_PYTHON_SPEC = '3.10';
 const PINNED_MARIVO_VERSION = MARIVO_VERSION;
@@ -15,7 +16,7 @@ const INSTALLATION_SCHEMA = RUNTIME_INSTALLATION_VERSION;
 const INSTALLATION_FILENAME = 'installation.json';
 const SKILL_NAMES = ['marivo-analysis', 'marivo-semantic'];
 const SERVICE_SKILL = 'marivo-service';
-const PROBE_SCRIPT = String.raw `
+const PROBE_SCRIPT = `${PYTHON_IMPORT_IDENTITY}\n${String.raw `
 import json
 import os
 import sys
@@ -32,22 +33,20 @@ print(json.dumps({
     "marivo_distribution_version": dist.version,
     "marivo_index_install": dist.read_text("direct_url.json") is None,
     "marivo_import_identity": os.path.realpath(marivo.__file__) == os.path.realpath(dist.locate_file("marivo/__init__.py")),
-    "python_executable": os.path.abspath(sys.executable),
-    "marivo_version": marivo.__version__,
-    "package_path": os.path.abspath(marivo.__file__ or ""),
+    **_dsh_import_identity(sys.executable, marivo.__version__, marivo.__file__),
 }, sort_keys=True))
-`.trim();
-const PYTHON_VERSION_SCRIPT = String.raw `
+`.trim()}`;
+const PYTHON_VERSION_SCRIPT = `${PYTHON_IMPORT_IDENTITY}\n${String.raw `
 import json
 import os
 import sys
 
 print(json.dumps({
-    "python_executable": os.path.abspath(sys.executable),
+    "python_executable": _dsh_python_executable(sys.executable),
     "version": list(sys.version_info[:3]),
     "prefix": os.path.abspath(sys.prefix),
 }, sort_keys=True))
-`.trim();
+`.trim()}`;
 function administratorRepair(executable) {
     const commands = [
         {
@@ -100,7 +99,7 @@ async function assertExecutable(executable) {
         if (!info.isFile())
             throw new Error('not a file');
         await access(selected, process.platform === 'win32' ? constants.F_OK : constants.X_OK);
-        return selected;
+        return canonicalPythonExecutable(selected);
     }
     catch (cause) {
         throw new MarivoEnvironmentError('python-unavailable', `Shared Marivo Python executable is missing or not executable: ${selected}`, { pythonExecutable: selected }, { cause });
@@ -149,8 +148,8 @@ async function probeRuntime(runtimeRoot, executable, environment, timeoutMs, adm
         probe.package_path.length === 0) {
         throw new MarivoEnvironmentError('shared-runtime-identity-mismatch', 'Shared Runtime returned an incomplete or mismatched package identity', { probe, ...(repair === undefined ? {} : { repairCommands: repair.commands }) });
     }
-    const actualPython = await realpath(path.resolve(probe.python_executable));
-    const selectedPython = await realpath(canonical);
+    const actualPython = canonicalPythonExecutable(probe.python_executable);
+    const selectedPython = canonicalPythonExecutable(canonical);
     if (expectedMarivoVersion !== undefined && probe.marivo_version !== expectedMarivoVersion) {
         throw new MarivoEnvironmentError('shared-runtime-version-unsupported', `Shared Marivo runtime version ${probe.marivo_version} is unsupported; install ${expectedMarivoVersion}.${repair === undefined ? '' : ` ${repair.message}`}`, {
             supportedMarivoVersion: expectedMarivoVersion,
@@ -172,7 +171,7 @@ async function probeRuntime(runtimeRoot, executable, environment, timeoutMs, adm
         marivo_import_identity: true,
         python_executable: canonical,
         marivo_version: probe.marivo_version,
-        package_path: path.resolve(probe.package_path),
+        package_path: await realpath(probe.package_path),
     };
 }
 async function availableSkills(skillsRoot) {
@@ -301,14 +300,14 @@ async function validatedExisting(runtimeRoot, configuredPython, environment, tim
         return undefined;
     const expectedPython = configuredPython ?? venvPython(runtimeRoot);
     const expectedSkillsRoot = path.join(runtimeRoot, 'skills');
-    if (path.normalize(record.skillsRoot) !== path.normalize(expectedSkillsRoot))
-        return undefined;
     try {
+        if ((await realpath(record.skillsRoot)) !== (await realpath(expectedSkillsRoot)))
+            return undefined;
         const selectedPython = await assertExecutable(expectedPython);
-        if (path.normalize(record.pythonExecutable) !== selectedPython)
+        if (canonicalPythonExecutable(record.pythonExecutable) !== selectedPython)
             return undefined;
         const probe = await probeRuntime(runtimeRoot, selectedPython, environment, timeoutMs, configuredPython !== undefined, record.marivoVersion);
-        if (path.normalize(probe.package_path) !== path.normalize(record.packagePath))
+        if (probe.package_path !== (await realpath(record.packagePath)))
             return undefined;
         const sourceRoot = path.join(path.dirname(probe.package_path), 'skills');
         await validateSkills(record.skillsRoot, await availableSkills(sourceRoot));

package/lib/plugin-agents.js

@@ -11,6 +11,7 @@ import { SavedWriteProofs } from "./next-steps/saved-writes.js";
 import { AnalysisDrafts } from "./presentation/drafts.js";
 import { installMarivoPresentationCodeDelivery, registerMarivoPresentTool, registerMarivoReportDeleteTool, registerMarivoUiReadTool, } from "./presentation/index.js";
 import { restorePythonResults } from "./python-results-context.js";
+import { registerReportPublishTool } from "./report-publishing/adapters.js";
 import { resolvePresentationWorkspace } from "./workspace-identity.js";
 const ROUTING_PROMPT = [
     'For attachment or Workspace data files, load dsh-data-analysis-files. For governed analysis, load marivo-analysis; load marivo-semantic when shared definitions are needed or authoring is requested. For project HTTP services, load marivo-service when the bound Runtime provides it.',
@@ -92,6 +93,8 @@ export function createMarivoAgentInstallation(ctx, environmentOrResolver, option
             controller.addDisposer(() => credentialService.disposeAgent(agent));
             controller.addDisposer(registerMarivoUiReadTool(agent.ctx, workspace, presentationDrafts));
             controller.addDisposer(registerMarivoReportDeleteTool(agent.ctx, workspace));
+            if (options.reportPublishing)
+                controller.addDisposer(registerReportPublishTool(agent.ctx, options.reportPublishing, agent.session));
             controller.addDisposer(registerMarivoPresentTool(agent.ctx, workspace, agent.session, presentationDrafts, async () => resolveMarivoEnvironmentSource(source), savedWrites.committed));
             controller.addDisposer(installMarivoPresentationCodeDelivery(agent.ctx));
             controller.addDisposer(installNextStepsAgent(ctx, agent, workspace, options.nextStepsPublish ?? (() => { }), savedWrites));
@@ -99,7 +102,9 @@ export function createMarivoAgentInstallation(ctx, environmentOrResolver, option
             controller.addDisposer(agent.ctx.systemPrompt.section({
                 name: 'marivo:routing',
                 order: 180,
-                text: ROUTING_PROMPT,
+                text: options.reportPublishing
+                    ? `${ROUTING_PROMPT}\nThis Host has object-storage publishing enabled. Use marivo_publish_report with the exact saved report ref only when the user explicitly requests publication to object storage.`
+                    : ROUTING_PROMPT,
             }));
             controller.addDisposer(agent.ctx.on('agent/pre-step', async ({ signal }, next) => {
                 const decision = await next();

package/lib/plugin.js

@@ -24,6 +24,9 @@ import { MarivoHelpBridge } from "./disclosure/bridge.js";
 import { createSharedMarivoRuntimeRunner, DEFAULT_SHARED_RUNTIME_INSTALL_TIMEOUT_MS, ensureSharedMarivoRuntime, MarivoWorkspaceEnvironmentManager, } from "./environment/index.js";
 import { AnalysisDrafts } from "./presentation/drafts.js";
 import { MarivoPresentationFileService, registerMarivoPresentationRpc, } from "./presentation/index.js";
+import { registerPublishingRpc } from "./report-publishing/adapters.js";
+import { resolvePublishingConfig } from "./report-publishing/config.js";
+import { ReportPublishingService } from "./report-publishing/service.js";
 import { browserFailure, SemanticBrowserService } from "./semantic-browser/service.js";
 import { registerSemanticReferenceRpc, SemanticReferenceService, SemanticReferenceUsage, } from "./semantic-reference/index.js";
 import { preparePackagedSkillSnapshot } from "./skill-build.js";
@@ -44,6 +47,8 @@ export const inject = [
 ];
 /** Cordis loader schema. Runtime defaults are resolved in {@link apply}. */
 export const Config = z.object({
+    // Validate at apply time so loader errors cannot echo supplied values.
+    reportPublishing: z.any(),
     pythonTimeoutMs: z
         .number()
         .min(1)
@@ -71,6 +76,7 @@ export async function apply(ctx, config = {}) {
 }
 /** Compose an extension at the public seam while retaining the ordinary plugin behavior. */
 export async function applyWithIntegration(ctx, config = {}, integration = {}) {
+    const publishingConfig = resolvePublishingConfig(config.reportPublishing);
     const pythonOptions = currentPythonOptions(config);
     const pythonExecutable = config.pythonExecutable ?? process.env.DSH_DATA_ANALYSIS_PYTHON;
     const runtimeRoot = config.runtimeRoot ?? process.env.DSH_DATA_ANALYSIS_RUNTIME_ROOT;
@@ -105,6 +111,7 @@ export async function applyWithIntegration(ctx, config = {}, integration = {}) {
     let disposeCredentials;
     let disposeReferences;
     let disposePresentation;
+    let disposePublishing;
     let referenceService;
     let agentInstallation;
     let pythonSettings;
@@ -123,6 +130,7 @@ export async function applyWithIntegration(ctx, config = {}, integration = {}) {
             () => pythonSettings?.dispose(),
             () => disposeCredentials?.(),
             disposeChanges,
+            () => disposePublishing?.(),
             () => disposePresentation?.(),
             () => disposeReferences?.(),
             () => browserService.close(),
@@ -165,12 +173,22 @@ export async function applyWithIntegration(ctx, config = {}, integration = {}) {
             return workspace ? { id: String(workspace.id), path: workspace.path } : undefined;
         }, presentationDrafts);
         disposePresentation = registerMarivoPresentationRpc(ctx.connection, presentationFiles);
+        const reportPublishing = publishingConfig
+            ? new ReportPublishingService(publishingConfig, ctx.credentials, presentationFiles, (id) => {
+                const workspace = ctx.workspaceRegistry.get(WorkspaceId(id));
+                if (!workspace)
+                    throw new Error('workspace-unavailable');
+                return workspace.title;
+            })
+            : undefined;
+        disposePublishing = registerPublishingRpc(ctx.connection, reportPublishing, (id) => Boolean(ctx.workspaceRegistry.get(WorkspaceId(id))));
         agentInstallation = createMarivoAgentInstallation(ctx, resolveEnvironment, {
             ...pythonOptions,
             pythonOptionsSource: pythonSettings.get,
             helpBridgeSource: helpBridge,
             credentialService,
             presentationDrafts,
+            ...(reportPublishing ? { reportPublishing } : {}),
             nextStepsPublish: (notice) => nextSteps.publish(notice),
         });
         agentInstallation.install();

package/lib/presentation/rpc.js

@@ -389,6 +389,25 @@ export class MarivoPresentationFileService {
         await check();
         return receipt;
     }
+    readSavedReport(scope, ref, caller) {
+        return this.#tasks.track(this.#readSavedReport(scope, ref, caller));
+    }
+    async #readSavedReport(scope, ref, caller) {
+        const signal = AbortSignal.any([caller, this.#abort.signal]);
+        signal.throwIfAborted();
+        const workspace = await this.#workspace(scope);
+        if (!workspace)
+            throw new Error('workspace-unavailable');
+        if (ref.workspaceId !== workspace.id)
+            throw new Error('report-workspace-mismatch');
+        const root = path.resolve(workspace.path);
+        const document = await readAnalysisRecord(root, workspace.id, ref.reportId, ref.buildId, signal);
+        const current = await this.#workspace(scope);
+        if (!current || current.id !== workspace.id || path.resolve(current.path) !== root)
+            throw new Error('workspace-changed');
+        signal.throwIfAborted();
+        return document;
+    }
     read(payload, caller = new AbortController().signal) {
         return this.#tasks.track(this.#read(payload, caller));
     }

package/lib/report-publishing/adapters.js

@@ -0,0 +1,136 @@
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { z } from 'zod';
+import { parseReportRef } from "../presentation/contracts/report-ref.js";
+import { registerPluginRpc } from "../rpc.js";
+import { registerMarivoTool } from "../tool-lifecycle.js";
+import { publishingFieldSchema, REPORT_PUBLISHING_CHANNEL } from "./credential-contract.js";
+const workspace = z.object({ workspaceId: z.string().min(1).max(512) });
+const describe = workspace.strict();
+const mutation = workspace.extend({ configId: z.string().uuid() });
+const field = publishingFieldSchema;
+const set = mutation.extend({ field, value: z.string().min(1).max(65_536) }).strict();
+const unset = mutation.extend({ field }).strict();
+const refInput = { ref: z.string().min(1).max(4096) };
+const publish = mutation.extend(refInput).strict();
+const toolInput = z.strictObject(refInput);
+function parseSavedRef(value) {
+    const ref = parseReportRef(value);
+    if (ref.kind !== 'saved')
+        throw new Error('report-saved-ref-required');
+    return ref;
+}
+export function registerPublishingRpc(connection, service, workspaceExists) {
+    return registerPluginRpc(connection, REPORT_PUBLISHING_CHANNEL, ['describe', 'set', 'unset', 'publish'], async (endpoint, payload, signal) => {
+        try {
+            signal.throwIfAborted();
+            const { workspaceId } = workspace.parse(payload);
+            if (!workspaceExists(workspaceId))
+                throw new Error('workspace-unavailable');
+            if (endpoint === 'describe') {
+                describe.parse(payload);
+                return {
+                    ok: true,
+                    value: service ? await service.describe() : { enabled: false, fields: [] },
+                };
+            }
+            if (!service)
+                throw new Error('report-publishing-disabled');
+            service.assertConfig(mutation.parse(payload).configId);
+            if (endpoint === 'publish') {
+                const input = publish.parse(payload);
+                return {
+                    ok: true,
+                    value: await service.publish({ workspaceId }, parseSavedRef(input.ref), signal),
+                };
+            }
+            if (endpoint === 'set') {
+                const input = set.parse(payload);
+                await service.change(input.field, input.value, signal);
+            }
+            else {
+                await service.change(unset.parse(payload).field, undefined, signal);
+            }
+            return { ok: true, value: await service.describe() };
+        }
+        catch (error) {
+            return {
+                ok: false,
+                error: { code: 'internal', message: publishingError(error, signal), details: {} },
+            };
+        }
+    });
+}
+export function registerReportPublishTool(ctx, service, session) {
+    return registerMarivoTool(ctx, defineTool({
+        name: 'marivo_publish_report',
+        description: 'Publish one exact saved report version as self-contained HTML to the configured object storage only when the user explicitly asks to publish it. Pass the saved ref from marivo_report_write or marivo_report_read. The HTML includes the saved data snapshots. Returns the URL and upload receipt. An unconfirmed upload may already exist. If credentials are missing, direct the user to the Credential management tab of Datasources and credentials.',
+        parameters: {
+            ref: {
+                type: 'string',
+                required: true,
+                description: 'Exact saved report ref.',
+            },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                properties: {
+                    url: { type: 'string', required: true },
+                    key: { type: 'string', required: true },
+                    storage: { type: 'string', required: true },
+                    bucket: { type: 'string', required: true },
+                    workspaceId: { type: 'string', required: true },
+                    reportId: { type: 'string', required: true },
+                    buildId: { type: 'string', required: true },
+                    sha256: { type: 'string', required: true },
+                    bytes: { type: 'integer', required: true },
+                    publishedAt: { type: 'string', required: true },
+                },
+                additionalProperties: false,
+            },
+            render: (_args, value) => [{ type: 'text', text: JSON.stringify(value) }],
+        },
+        timeoutMs: 120_000,
+        async execute(args, exec) {
+            if (exec.agent?.session !== session)
+                throw new Error('presentation-session-mismatch');
+            try {
+                const input = toolInput.parse(args);
+                return await service.publish({ sessionId: String(session.id) }, parseSavedRef(input.ref), exec.signal);
+            }
+            catch (error) {
+                throw new Error(publishingError(error, exec.signal));
+            }
+        },
+    }));
+}
+function publishingError(error, signal) {
+    if (error instanceof Error && error.message === 'report-publishing-upload-unconfirmed')
+        return error.message;
+    if (signal.aborted)
+        return 'cancelled';
+    if (error instanceof z.ZodError)
+        return 'invalid-request';
+    if (error instanceof Error) {
+        if (error.message.startsWith('report-ref-invalid:'))
+            return 'report-ref-invalid';
+        if (error.message === 'report-build-not-found' || ('code' in error && error.code === 'ENOENT'))
+            return 'report-publishing-build-unavailable';
+        if (error.name === 'TimeoutError')
+            return 'report-publishing-timeout';
+        if ([
+            'workspace-unavailable',
+            'workspace-changed',
+            'report-version-unsupported',
+            'report-document-incompatible',
+            'report-saved-ref-required',
+            'report-workspace-mismatch',
+            'report-publishing-config-changed',
+            'report-publishing-disabled',
+            'report-publishing-disabled-or-field-unavailable',
+            'report-publishing-credentials-missing',
+        ].includes(error.message))
+            return error.message;
+    }
+    return 'report-publishing-operation-failed';
+}

package/lib/report-publishing/config.js

@@ -0,0 +1,58 @@
+import { isCredentialRefName } from '@deepseek-ai/dsh-credentials';
+import { z } from 'zod';
+const reference = z.string().refine(isCredentialRefName);
+const url = z
+    .string()
+    .trim()
+    .url()
+    .refine((value) => {
+    const parsed = URL.parse(value);
+    return (parsed !== null &&
+        (parsed.protocol === 'http:' || parsed.protocol === 'https:') &&
+        !parsed.username &&
+        !parsed.password &&
+        !parsed.search &&
+        !parsed.hash);
+});
+const enabledPublishing = z
+    .strictObject({
+    enabled: z.literal(true),
+    storage: z.strictObject({
+        name: z.string().min(1).max(100),
+        protocol: z.literal('s3').default('s3'),
+        endpoint: url,
+        region: z.string().min(1),
+        bucket: z
+            .string()
+            .min(1)
+            .max(255)
+            .regex(/^[a-zA-Z0-9][a-zA-Z0-9.-]*$/),
+        forcePathStyle: z.boolean().default(false),
+        accessKeyIdRef: reference,
+        secretAccessKeyRef: reference,
+        sessionTokenRef: reference.optional(),
+    }),
+    pathPrefix: z
+        .string()
+        .default('reports')
+        .refine((value) => value === '' ||
+        value.split('/').every((part) => /^[a-zA-Z0-9_-][a-zA-Z0-9._-]*$/.test(part))),
+    publicBaseUrl: url,
+})
+    .refine(({ storage }) => {
+    const refs = [storage.accessKeyIdRef, storage.secretAccessKeyRef, storage.sessionTokenRef];
+    return new Set(refs).size === refs.length;
+});
+export function resolvePublishingConfig(value) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value === 'object' &&
+        value !== null &&
+        !Array.isArray(value) &&
+        (!('enabled' in value) || value.enabled === undefined || value.enabled === false))
+        return undefined;
+    const result = enabledPublishing.safeParse(value);
+    if (!result.success)
+        throw new Error('report-publishing-config-invalid');
+    return result.data;
+}

package/lib/report-publishing/credential-contract.js

@@ -0,0 +1,25 @@
+import { z } from 'zod';
+export const REPORT_PUBLISHING_CHANNEL = '/dsh-report-publishing';
+export const publishingFields = ['accessKeyId', 'secretAccessKey', 'sessionToken'];
+export const publishingFieldSchema = z.enum(publishingFields);
+const publishingCredentialViewSchema = z.discriminatedUnion('enabled', [
+    z.strictObject({ enabled: z.literal(false), fields: z.tuple([]) }),
+    z.strictObject({
+        enabled: z.literal(true),
+        configId: z.string().uuid(),
+        name: z.string(),
+        bucket: z.string(),
+        fields: z.array(z.strictObject({
+            field: publishingFieldSchema,
+            reference: z.string(),
+            required: z.boolean(),
+            configured: z.boolean(),
+            writable: z.boolean(),
+            source: z.string().optional(),
+        })),
+    }),
+]);
+export const publishingCredentialResultSchema = z.discriminatedUnion('ok', [
+    z.object({ ok: z.literal(true), value: publishingCredentialViewSchema }),
+    z.object({ ok: z.literal(false), error: z.object({ message: z.string() }) }),
+]);