@chengxianglibra/dsh-data-analysis 0.1.1 → 0.2.0

package/lib/environment/workspace.js

@@ -1,5 +1,6 @@
 import { realpath, stat } from 'node:fs/promises';
 import path from 'node:path';
+import { finishCleanup, PendingTasks } from "../lifecycle.js";
 import { bindMarivoEnvironment } from "./binding.js";
 import { MarivoEnvironmentError } from "./errors.js";
 async function assertDirectory(target, label) {
@@ -26,24 +27,45 @@ async function canonicalWorkspaceRoot(projectRoot) {
 }
 /** Cache one zero-init Workspace binding while retaining project-specific doctor state. */
 export class MarivoWorkspaceEnvironmentManager {
+    #tasks = new PendingTasks();
+    #disposed = false;
+    #closing;
     runtime;
     #bindings = new Map();
     constructor(runtime) {
         this.runtime = runtime;
     }
-    async resolve(projectRoot) {
+    resolve(projectRoot) {
+        return this.#tasks.track(this.#resolve(projectRoot));
+    }
+    async #resolve(projectRoot) {
+        if (this.#disposed)
+            throw new Error('Marivo Workspace manager disposed');
         const canonicalRoot = await canonicalWorkspaceRoot(projectRoot);
+        if (this.#disposed)
+            throw new Error('Marivo Workspace manager disposed');
         let binding = this.#bindings.get(canonicalRoot);
         if (binding === undefined) {
             binding = bindMarivoEnvironment({
                 projectRoot: canonicalRoot,
                 pythonExecutable: this.runtime.pythonExecutable,
+            }, {
+                presentationKit: {
+                    version: this.runtime.presentationKitVersion,
+                    packagePath: this.runtime.presentationKitPackagePath,
+                },
             });
             this.#bindings.set(canonicalRoot, binding);
         }
         return binding;
     }
+    close() {
+        this.dispose();
+        this.#closing ??= finishCleanup([() => this.#tasks.drain()]);
+        return this.#closing;
+    }
     dispose() {
+        this.#disposed = true;
         this.#bindings.clear();
     }
 }

package/lib/index.js

@@ -3,5 +3,5 @@ export * from "./compatibility.js";
 export * from "./datasource/index.js";
 export * from "./disclosure/index.js";
 export * from "./environment/index.js";
-export * from "./evidence/index.js";
 export { apply, Config, inject, installMarivoPlugin, name } from "./plugin.js";
+export * from "./presentation/index.js";

package/lib/lifecycle.js

@@ -0,0 +1,33 @@
+/** Tracks owned work, including work whose caller stopped waiting after cancellation. */
+export class PendingTasks {
+    #tasks = new Set();
+    track(task) {
+        const settled = task.then(() => { }, () => { });
+        this.#tasks.add(settled);
+        void settled.then(() => this.#tasks.delete(settled));
+        return task;
+    }
+    async drain() {
+        while (this.#tasks.size)
+            await Promise.all([...this.#tasks]);
+    }
+}
+/** Start every stop synchronously, then await every cleanup even if another one fails. */
+export function finishCleanup(actions) {
+    const pending = actions.map((action) => {
+        try {
+            return Promise.resolve(action());
+        }
+        catch (error) {
+            return Promise.reject(error);
+        }
+    });
+    const completion = Promise.allSettled(pending).then((results) => {
+        const failures = results.flatMap((result) => result.status === 'rejected' ? [result.reason] : []);
+        if (failures.length)
+            throw new AggregateError(failures, 'Marivo cleanup failed');
+    });
+    // Legacy synchronous callers may ignore completion; awaiting it still reports failures.
+    void completion.catch(() => { });
+    return completion;
+}

package/lib/plugin-agents.js

@@ -0,0 +1,154 @@
+import { createMarivoBridgeSet } from "./bridges.js";
+import { registerMarivoDatasourceConfigureTool } from "./datasource/configure.js";
+import { registerMarivoPythonTool } from "./datasource/python.js";
+import { resolvePythonOptions } from "./datasource/python-options.js";
+import { MarivoCredentialService } from "./datasource/service.js";
+import { registerMarivoDatasourceTestTool } from "./datasource/test.js";
+import { installMarivoExecutionGuidance, MARIVO_ANALYSIS_CLOSEOUT_PROMPT, MARIVO_DATASOURCE_CREDENTIAL_PROMPT, } from "./disclosure/execution-guidance.js";
+import { installMarivoDisclosure, } from "./disclosure/index.js";
+import { MarivoEnvironment, resolveMarivoEnvironmentSource, } from "./environment/index.js";
+import { finishCleanup, PendingTasks } from "./lifecycle.js";
+import { registerMarivoExportHtmlTool } from "./presentation/export-html.js";
+import { installMarivoPresentationCodeDelivery, registerMarivoPresentTool, } from "./presentation/index.js";
+import { registerReportPublishTool } from "./report-publishing/adapters.js";
+import { resolvePresentationWorkspace } from "./workspace-identity.js";
+const PRESENTATION_PROMPT = 'Answer ordinary factual questions in text. For analysis of provided data files, load dsh-data-analysis-files; local pandas or native DuckDB work needs no Marivo semantic setup. For charts, tables, reports, dashboards or a readable source presentation, load dsh-data-analysis-presentation and deliver through marivo_present. When the user requests an offline HTML file, export the saved report with marivo_export_html, then call native present with the returned path before the final response. Use the Runtime skills and live Help when the task needs Marivo analysis or semantic authoring; existing data can be presented directly.';
+/**
+ * Install one already-bound environment into every live or subsequently published Agent scope.
+ * Installation is transactional for existing Agents and is disposed with the Cordis plugin.
+ */
+export function createMarivoAgentInstallation(ctx, environmentOrResolver, options = {}) {
+    const pythonOptions = resolvePythonOptions(options);
+    const installed = new Map();
+    const credentials = options.credentials ?? ctx.credentials;
+    if (credentials === undefined) {
+        throw new Error('dsh-data-analysis requires the DSH credentials service');
+    }
+    const credentialService = options.credentialService ??
+        new MarivoCredentialService(credentials, options.credentialInteraction);
+    const ownsCredentials = options.credentialService === undefined;
+    const retiring = new PendingTasks();
+    const failures = [];
+    const stops = [];
+    let active = true;
+    let closing;
+    const retire = (controller) => {
+        retiring.track(controller.close().catch((error) => {
+            failures.push(error);
+        }));
+    };
+    const close = () => {
+        if (closing)
+            return closing;
+        active = false;
+        closing = finishCleanup([
+            ...stops.reverse(),
+            ...[...installed.values()].map((controller) => () => retire(controller)),
+            ...(ownsCredentials ? [() => credentialService.close()] : []),
+            async () => {
+                await retiring.drain();
+                if (failures.length)
+                    throw new AggregateError(failures, 'Marivo Agent cleanup failed');
+            },
+        ]);
+        installed.clear();
+        return closing;
+    };
+    const bridgeSets = new WeakMap();
+    const install = (agent) => {
+        if (!active || installed.has(agent))
+            return;
+        const source = environmentOrResolver instanceof MarivoEnvironment
+            ? environmentOrResolver
+            : () => Promise.resolve(environmentOrResolver(agent));
+        const resolveBridgeSet = async () => {
+            const environment = await resolveMarivoEnvironmentSource(source);
+            let bridges = bridgeSets.get(environment);
+            if (bridges === undefined) {
+                bridges = createMarivoBridgeSet(environment);
+                bridgeSets.set(environment, bridges);
+            }
+            return bridges;
+        };
+        const helpSource = options.helpBridgeSource ?? (async () => (await resolveBridgeSet()).help);
+        const datasourceSource = async () => (await resolveBridgeSet()).datasource;
+        const presentationSource = async () => {
+            const workspace = resolvePresentationWorkspace(ctx, String(agent.session.id));
+            const projection = (await resolveBridgeSet()).presentation;
+            const current = resolvePresentationWorkspace(ctx, String(agent.session.id));
+            if (workspace.id !== current.id ||
+                workspace.path !== current.path ||
+                projection.binding.projectRoot !== current.path)
+                throw new Error('Presentation Workspace changed or does not match the bound Runtime');
+            return { workspaceId: current.id, projection };
+        };
+        const controller = installMarivoDisclosure(ctx, agent, helpSource, options);
+        try {
+            controller.addDisposer(installMarivoExecutionGuidance(agent, controller));
+            controller.addDisposer(registerMarivoDatasourceTestTool(agent.ctx, datasourceSource, credentialService));
+            controller.addDisposer(registerMarivoDatasourceConfigureTool(agent.ctx, datasourceSource, credentialService));
+            controller.addDisposer(registerMarivoPythonTool(agent.ctx, datasourceSource, credentialService, pythonOptions));
+            controller.addDisposer(() => credentialService.disposeAgent(agent));
+            controller.addDisposer(registerMarivoPresentTool(agent.ctx, presentationSource, agent.session));
+            controller.addDisposer(registerMarivoExportHtmlTool(agent.ctx, () => resolvePresentationWorkspace(ctx, String(agent.session.id)), agent.session));
+            if (options.reportPublishing)
+                controller.addDisposer(registerReportPublishTool(agent.ctx, options.reportPublishing, agent.session.id));
+            controller.addDisposer(installMarivoPresentationCodeDelivery(agent.ctx));
+            controller.addDisposer(agent.ctx.systemPrompt.section({
+                name: 'marivo:presentation',
+                order: 180,
+                text: PRESENTATION_PROMPT,
+            }));
+            controller.addDisposer(agent.ctx.systemPrompt.section({
+                name: 'marivo:datasource-credentials',
+                order: 170,
+                text: () => controller.activeSkills.some((skill) => ['marivo-analysis', 'marivo-semantic'].includes(skill))
+                    ? MARIVO_DATASOURCE_CREDENTIAL_PROMPT
+                    : '',
+            }));
+            controller.addDisposer(agent.ctx.systemPrompt.section({
+                name: 'marivo:analysis-closeout',
+                order: 175,
+                text: () => controller.activeSkills.includes('marivo-analysis')
+                    ? MARIVO_ANALYSIS_CLOSEOUT_PROMPT
+                    : '',
+            }));
+            installed.set(agent, controller);
+        }
+        catch (error) {
+            retire(controller);
+            throw error;
+        }
+    };
+    return {
+        install() {
+            if (!active)
+                throw new Error('Marivo Agent installation disposed');
+            try {
+                stops.push(ctx.on('credentials/reference-updated', (ref) => credentialService.invalidateStorageRef(ref)));
+                for (const agent of ctx.agents.list())
+                    install(agent);
+                stops.push(ctx.on('agent/created', ({ agent }) => {
+                    install(agent);
+                }));
+                stops.push(ctx.on('agent/disposed', ({ agent }) => {
+                    const controller = installed.get(agent);
+                    if (controller)
+                        retire(controller);
+                    installed.delete(agent);
+                }));
+            }
+            catch (error) {
+                void close();
+                throw error;
+            }
+        },
+        close,
+    };
+}
+/** Stops synchronously; the returned Promise also waits for all owned work. */
+export function installMarivoPlugin(...args) {
+    const installation = createMarivoAgentInstallation(...args);
+    installation.install();
+    return installation.close;
+}

package/lib/plugin.js

@@ -1,48 +1,58 @@
+import { CredentialChangesService } from "./datasource/changes.js";
+import { credentialChangesHost } from "./datasource/changes-contract.js";
+import { finishCleanup } from "./lifecycle.js";
+import { createMarivoAgentInstallation } from "./plugin-agents.js";
+import { registerPublishingCredentials } from "./report-publishing/adapters.js";
+import { resolvePublishingConfig } from "./report-publishing/config.js";
+import { ReportPublishingService } from "./report-publishing/service.js";
+import { resolvePresentationWorkspace } from "./workspace-identity.js";
+export { installMarivoPlugin } from "./plugin-agents.js";
+export { resolvePresentationWorkspace } from "./workspace-identity.js";
+import { referenceEnvironmentResolver } from "./semantic-reference/environment.js";
 /** Cordis lifecycle adapter for the Web-profile shared Marivo Runtime. */
-import path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath } from 'node:url';
 import { apply as installSkillFilesystem } from '@deepseek-ai/dsh-skill-filesystem';
+import { WorkspaceId } from '@deepseek-ai/dsh-workspace';
 import z from '@deepseek-ai/schemastery';
-import { createMarivoBridgeSet } from "./bridges.js";
-import { registerMarivoDatasourceAccessTool, registerMarivoDatasourceTestTool, } from "./datasource/index.js";
-import { MarivoShellCredentialLeases, registerMarivoRuntimeShellEnvironment, } from "./datasource/shell-env.js";
+import { MarivoDatasourceBridge } from "./datasource/bridge.js";
+import { DEFAULT_PYTHON_MAX_TIMEOUT_MS, DEFAULT_PYTHON_TIMEOUT_MS, resolvePythonOptions, } from "./datasource/python-options.js";
+import { registerCredentialRpc } from "./datasource/rpc.js";
+import { MarivoCredentialService } from "./datasource/service.js";
+import { registerMarivoRuntimeShellEnvironment } from "./datasource/shell-env.js";
 import { MarivoHelpBridge } from "./disclosure/bridge.js";
-import { installMarivoDisclosure, } from "./disclosure/index.js";
-import { createSharedMarivoRuntimeRunner, DEFAULT_SHARED_RUNTIME_INSTALL_TIMEOUT_MS, ensureSharedMarivoRuntime, MarivoEnvironment, MarivoWorkspaceEnvironmentManager, resolveMarivoEnvironmentSource, } from "./environment/index.js";
-import { installMarivoEvidenceSourcesCodeDelivery, registerMarivoEvidenceSourcesTool, } from "./evidence/index.js";
+import { createSharedMarivoRuntimeRunner, DEFAULT_SHARED_RUNTIME_INSTALL_TIMEOUT_MS, ensureSharedMarivoRuntime, MarivoWorkspaceEnvironmentManager, } from "./environment/index.js";
+import { MarivoPresentationFileService, registerMarivoPresentationRpc, } from "./presentation/index.js";
+import { browserFailure, SemanticBrowserService } from "./semantic-browser/service.js";
+import { registerSemanticReferenceRpc, SemanticReferenceService, SemanticReferenceUsage, } from "./semantic-reference/index.js";
+export { MARIVO_DATASOURCE_CREDENTIAL_PROMPT } from "./disclosure/execution-guidance.js";
 /** Cordis plugin name used by loader diagnostics and lifecycle logs. */
 export const name = 'dsh-data-analysis';
 /** Services that must exist before the plugin binds and watches Agent scopes. */
-export const inject = ['agents', 'credentials', 'shellEnv', 'skills', 'systemPrompt', 'tools'];
-export const MARIVO_DATASOURCE_CREDENTIAL_PROMPT = [
-    'When marivo-semantic is active, every Marivo datasource *_env field must reference a valid POSIX environment name outside the reserved MARIVO_* and DSH_DATA_ANALYSIS_* namespaces and Host-owned DSH shell facts.',
-    'Never ask the user to provide credential values in chat, and never place credential values in commands or project files.',
-    'Immediately after md.register(...) or a manual datasource-file change, call marivo_datasource_test with that datasource name.',
-    'If marivo_datasource_test returns needs-credentials, wait for the user to save the Web credential form, then retry marivo_datasource_test before continuing.',
-    'Before datasource-backed analysis, call marivo_datasource_access once and reuse its exact bash_prelude or pwsh_prelude before each foreground analysis command until the bounded lease expires or is exhausted. The first # dsh-marivo-credential-lease: line is a required control marker; never remove or move it.',
-    'Do not call marivo_datasource_test before each analysis script. Renew access with marivo_datasource_access; run another connection test only after datasource changes, credential rotation, a connection failure, or an explicit user request.',
-    'Never use a lease with background or persistent Shell execution. Each admitted Shell consumes one use even if later credential resolution fails.',
-    'If a datasource credential environment variable is missing, reacquire access and retry with the exact prelude in a foreground Shell. Never inspect or read DSH credential files, credential backups, or ~/.marivo/secrets.toml.',
-].join(' ');
-export const MARIVO_EVIDENCE_SOURCES_PROMPT = [
-    'Call marivo_evidence_sources only when the user explicitly requests sources, citations, provenance, or audit details.',
-    'Request only exact persisted Findings by Marivo Session, Artifact, and Finding identity.',
-    'Treat source existence as identity and availability evidence, not as proof that the whole conclusion, calculation, or business judgment is entailed or correct.',
-    'If no exact Finding exists or its source cannot be recovered, say so instead of inventing or approximating a source.',
-].join(' ');
-export const MARIVO_REPORT_PROMPT = [
-    'Use dsh-data-analysis-report only when the user explicitly requests HTML/web or a durable report file, accepts an Agent proposal to create one, or asks to revise an existing Workspace report bundle.',
-    'Answer ordinary analysis in the conversation even when it is long or contains multiple charts or tables.',
-    'For existing analysis, recover and revalidate persisted Artifacts; never rerun observe only to create the report or fill DAG details.',
-].join(' ');
-const integrationSkillsRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'skills');
+export const inject = [
+    'agents',
+    'connection',
+    'typert',
+    'storageDomain',
+    'workspaceRegistry',
+    'credentials',
+    'shellEnv',
+    'skills',
+    'systemPrompt',
+    'tools',
+];
 /** Cordis loader schema. Runtime defaults are resolved in {@link apply}. */
 export const Config = z.object({
+    // Defer validation to authoring so loader errors cannot echo configured values.
+    datasourceDefaults: z.any(),
+    reportPublishing: z.any(),
+    pythonTimeoutMs: z.number().default(DEFAULT_PYTHON_TIMEOUT_MS),
+    pythonMaxTimeoutMs: z.number().default(DEFAULT_PYTHON_MAX_TIMEOUT_MS),
+    credentialInteraction: z.union(['web', 'none']).default('web'),
     projectRoot: z.string(),
     pythonExecutable: z.string(),
     runtimeRoot: z.string(),
-    uvExecutable: z.string(),
+    bootstrapPythonExecutable: z.string(),
     installTimeoutMs: z.number().default(DEFAULT_SHARED_RUNTIME_INSTALL_TIMEOUT_MS),
 });
 function configuredProjectRoot(config, agent) {
@@ -52,128 +62,157 @@ function configuredProjectRoot(config, agent) {
         process.env.DSH_CWD ??
         process.cwd());
 }
-/**
- * Install one already-bound environment into every live or subsequently published Agent scope.
- * Installation is transactional for existing Agents and is disposed with the Cordis plugin.
- */
-export function installMarivoPlugin(ctx, environmentOrResolver, options = {}) {
-    const installed = new Map();
-    const credentials = options.credentials ?? ctx.credentials;
-    if (credentials === undefined) {
-        throw new Error('dsh-data-analysis requires the DSH credentials service');
-    }
-    const shellCredentials = new MarivoShellCredentialLeases(ctx, credentials);
-    const bridgeSets = new WeakMap();
-    const install = (agent) => {
-        if (installed.has(agent))
-            return;
-        const source = environmentOrResolver instanceof MarivoEnvironment
-            ? environmentOrResolver
-            : () => Promise.resolve(environmentOrResolver(agent));
-        const resolveBridgeSet = async () => {
-            const environment = await resolveMarivoEnvironmentSource(source);
-            let bridges = bridgeSets.get(environment);
-            if (bridges === undefined) {
-                bridges = createMarivoBridgeSet(environment);
-                bridgeSets.set(environment, bridges);
-            }
-            return bridges;
-        };
-        const helpSource = options.helpBridgeSource ?? (async () => (await resolveBridgeSet()).help);
-        const datasourceSource = async () => (await resolveBridgeSet()).datasource;
-        const evidenceSource = async () => (await resolveBridgeSet()).evidence;
-        const controller = installMarivoDisclosure(ctx, agent, helpSource, options);
-        controller.addDisposer(shellCredentials.installAgent(agent, datasourceSource));
-        controller.addDisposer(registerMarivoDatasourceTestTool(agent.ctx, datasourceSource, credentials, {
-            revokeShellLease: (bridge, datasourceName) => shellCredentials.revokeLease(agent, bridge, datasourceName),
-        }));
-        controller.addDisposer(registerMarivoDatasourceAccessTool(agent.ctx, datasourceSource, credentials, {
-            revokeShellLease: (bridge, datasourceName) => shellCredentials.revokeLease(agent, bridge, datasourceName),
-            issueShellLease: (bridge, datasourceName, refs) => shellCredentials.issueLease(agent, bridge, datasourceName, refs),
-        }));
-        controller.addDisposer(registerMarivoEvidenceSourcesTool(agent.ctx, evidenceSource, agent.session));
-        controller.addDisposer(installMarivoEvidenceSourcesCodeDelivery(agent.ctx));
-        controller.addDisposer(agent.ctx.systemPrompt.section({
-            name: 'marivo:datasource-credentials',
-            order: 170,
-            text: () => controller.activeSkills.includes('marivo-semantic')
-                ? MARIVO_DATASOURCE_CREDENTIAL_PROMPT
-                : '',
-        }));
-        controller.addDisposer(agent.ctx.systemPrompt.section({
-            name: 'marivo:evidence-sources',
-            order: 180,
-            text: () => controller.activeSkills.includes('marivo-analysis') ? MARIVO_EVIDENCE_SOURCES_PROMPT : '',
-        }));
-        controller.addDisposer(agent.ctx.systemPrompt.section({
-            name: 'marivo:report',
-            order: 185,
-            text: () => controller.activeSkills.includes('marivo-analysis') ? MARIVO_REPORT_PROMPT : '',
-        }));
-        installed.set(agent, controller);
-    };
-    try {
-        for (const agent of ctx.agents.list())
-            install(agent);
-    }
-    catch (error) {
-        for (const controller of installed.values())
-            controller.dispose();
-        shellCredentials.dispose();
-        throw error;
-    }
-    const stopCreated = ctx.on('agent/created', ({ agent }) => {
-        install(agent);
-    });
-    const stopDisposed = ctx.on('agent/disposed', ({ agent }) => {
-        installed.get(agent)?.dispose();
-        installed.delete(agent);
-    });
-    let active = true;
-    return () => {
-        if (!active)
-            return;
-        active = false;
-        stopCreated();
-        stopDisposed();
-        for (const controller of installed.values())
-            controller.dispose();
-        installed.clear();
-        shellCredentials.dispose();
-    };
-}
 /** Ensure the shared Runtime once, mount its skills, then bind each Workspace lazily. */
 export async function apply(ctx, config = {}) {
+    const publishingConfig = resolvePublishingConfig(config.reportPublishing);
+    const pythonOptions = resolvePythonOptions(config);
     const pythonExecutable = config.pythonExecutable ?? process.env.DSH_DATA_ANALYSIS_PYTHON;
     const runtimeRoot = config.runtimeRoot ?? process.env.DSH_DATA_ANALYSIS_RUNTIME_ROOT;
-    const uvExecutable = config.uvExecutable ?? process.env.DSH_DATA_ANALYSIS_UV;
+    const bootstrapPythonExecutable = config.bootstrapPythonExecutable ?? process.env.DSH_DATA_ANALYSIS_BOOTSTRAP_PYTHON;
     const runtime = await ensureSharedMarivoRuntime({
         ...(pythonExecutable === undefined ? {} : { pythonExecutable }),
         ...(runtimeRoot === undefined ? {} : { runtimeRoot }),
-        ...(uvExecutable === undefined ? {} : { uvExecutable }),
+        ...(bootstrapPythonExecutable === undefined ? {} : { bootstrapPythonExecutable }),
         ...(config.installTimeoutMs === undefined ? {} : { installTimeoutMs: config.installTimeoutMs }),
     });
     const disposeRuntimeShellEnvironment = registerMarivoRuntimeShellEnvironment(ctx, runtime.pythonExecutable);
     const manager = new MarivoWorkspaceEnvironmentManager(runtime);
-    let disposePlugin;
+    const bindings = new WeakMap();
+    const resolveEnvironment = (agent) => {
+        const root = configuredProjectRoot(config, agent);
+        const existing = bindings.get(agent);
+        if (existing?.root === root)
+            return existing.environment;
+        const environment = manager.resolve(root);
+        bindings.set(agent, { root, environment });
+        return environment;
+    };
+    const credentialService = new MarivoCredentialService(ctx.credentials, config.credentialInteraction);
+    const credentialNotifications = new CredentialChangesService(ctx, credentialService);
+    let unregisterChanges;
+    const disposeChanges = async () => {
+        await credentialNotifications.close();
+        await unregisterChanges?.();
+    };
+    let disposePublishing;
+    let disposeCredentials;
+    let disposeReferences;
+    let disposePresentation;
+    let referenceService;
+    let agentInstallation;
+    let closing;
+    const browserService = new SemanticBrowserService({
+        getWorkspace: (id) => ctx.workspaceRegistry.get(WorkspaceId(id)),
+        projectRoot: (workspace) => config.projectRoot ?? process.env.DSH_DATA_ANALYSIS_PROJECT_ROOT ?? workspace.path,
+        resolve: (root) => manager.resolve(root),
+    });
+    const close = () => {
+        if (closing)
+            return closing;
+        closing = finishCleanup([
+            () => agentInstallation?.close(),
+            () => disposeCredentials?.(),
+            disposeChanges,
+            () => disposePublishing?.(),
+            () => disposePresentation?.(),
+            () => disposeReferences?.(),
+            () => browserService.close(),
+            () => credentialService.close(),
+            () => referenceService?.close(),
+        ]).then(() => finishCleanup([() => manager.close(), disposeRuntimeShellEnvironment]), async (error) => {
+            await finishCleanup([
+                () => manager.close(),
+                disposeRuntimeShellEnvironment,
+                () => {
+                    throw error;
+                },
+            ]);
+        });
+        void closing.catch(() => { });
+        return closing;
+    };
     try {
+        unregisterChanges = ctx.typert.register(credentialChangesHost);
         installSkillFilesystem(ctx, {
             providerName: 'dsh-data-analysis-marivo',
             includeDefaultRoots: false,
-            customSkillDirs: [runtime.skillsRoot, integrationSkillsRoot],
+            customSkillDirs: [runtime.skillsRoot],
+            watch: false,
+        });
+        installSkillFilesystem(ctx, {
+            providerName: 'dsh-data-analysis-presentation',
+            includeDefaultRoots: false,
+            customSkillDirs: [fileURLToPath(new URL('../skills/', import.meta.url))],
             watch: false,
         });
         const helpBridge = new MarivoHelpBridge(createSharedMarivoRuntimeRunner(runtime));
-        disposePlugin = installMarivoPlugin(ctx, (agent) => manager.resolve(configuredProjectRoot(config, agent)), { helpBridgeSource: helpBridge });
+        const presentationFiles = new MarivoPresentationFileService(async (sessionId) => resolvePresentationWorkspace(ctx, sessionId), async (id) => {
+            const workspace = ctx.workspaceRegistry.get(WorkspaceId(id));
+            return workspace ? { id: String(workspace.id), path: workspace.path } : undefined;
+        });
+        disposePresentation = registerMarivoPresentationRpc(ctx.connection, presentationFiles);
+        const reportPublishing = new ReportPublishingService(publishingConfig, ctx.credentials, presentationFiles, undefined, (id) => {
+            const workspace = ctx.workspaceRegistry.get(WorkspaceId(id));
+            if (!workspace)
+                throw new Error('workspace-unavailable');
+            return workspace.title;
+        });
+        disposePublishing = registerPublishingCredentials(ctx.connection, reportPublishing, (id) => Boolean(ctx.workspaceRegistry.get(WorkspaceId(id))));
+        agentInstallation = createMarivoAgentInstallation(ctx, resolveEnvironment, {
+            ...pythonOptions,
+            helpBridgeSource: helpBridge,
+            ...(publishingConfig ? { reportPublishing } : {}),
+            credentialService,
+        });
+        agentInstallation.install();
+        disposeCredentials = registerCredentialRpc(ctx.connection, credentialService, async (id) => {
+            const workspace = ctx.workspaceRegistry.get(WorkspaceId(id));
+            if (!workspace)
+                throw new Error('Workspace unavailable');
+            const root = config.projectRoot ?? process.env.DSH_DATA_ANALYSIS_PROJECT_ROOT ?? workspace.path;
+            const environment = await manager.resolve(root);
+            const current = ctx.workspaceRegistry.get(WorkspaceId(id));
+            if (!current ||
+                current.path !== workspace.path ||
+                (config.projectRoot ?? process.env.DSH_DATA_ANALYSIS_PROJECT_ROOT ?? current.path) !==
+                    root)
+                throw new Error('Workspace changed');
+            return new MarivoDatasourceBridge(environment);
+        }, config.datasourceDefaults);
+        let lastDiagnostic = -Infinity;
+        const usage = new SemanticReferenceUsage(ctx.storageDomain, Date.now, () => {
+            if (Date.now() - lastDiagnostic >= 30_000) {
+                lastDiagnostic = Date.now();
+                console.warn('dsh-data-analysis semantic-reference usage unavailable');
+            }
+        });
+        referenceService = new SemanticReferenceService(referenceEnvironmentResolver({
+            agent: (sessionId) => ctx.agents.list().find((item) => item.session.id === sessionId),
+            binding: (agent) => bindings.get(agent),
+            projectRoot: (agent) => configuredProjectRoot(config, agent),
+            resolve: resolveEnvironment,
+            workspace: (sessionId) => resolvePresentationWorkspace(ctx, sessionId),
+        }), usage);
+        disposeReferences = registerSemanticReferenceRpc(ctx.connection, referenceService, async (_endpoint, payload, signal) => {
+            try {
+                return { ok: true, value: await browserService.read(payload, signal) };
+            }
+            catch (error) {
+                return {
+                    ok: false,
+                    error: { code: 'internal', message: browserFailure(error), details: {} },
+                };
+            }
+        });
     }
     catch (error) {
-        manager.dispose();
-        disposeRuntimeShellEnvironment();
+        try {
+            await close();
+        }
+        catch (cleanupError) {
+            throw new AggregateError([error, cleanupError], 'Marivo installation and cleanup failed');
+        }
         throw error;
     }
-    return () => {
-        disposePlugin();
-        manager.dispose();
-        disposeRuntimeShellEnvironment();
-    };
+    return close;
 }

package/lib/presentation/asset.js

@@ -0,0 +1,34 @@
+import { buildPresentation } from "./build/index.js";
+import { parsePresentationDocument, } from "./contracts/index.js";
+import { presentationAssetPath, presentationSha256, readPresentationAsset } from "./files.js";
+/** Read a fixed, receipt-verified snapshot; never access analysis or current. */
+export async function readReceiptAsset(root, workspaceId, receipt, asset, signal) {
+    signal.throwIfAborted();
+    if (receipt.workspaceId !== workspaceId)
+        throw new Error('asset-owner-mismatch');
+    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 !== workspaceId ||
+        document.reportId !== receipt.reportId ||
+        document.buildId !== receipt.buildId ||
+        document.title !== receipt.title)
+        throw new Error('asset-owner-mismatch');
+    const bytes = asset === 'presentation.json'
+        ? documentBytes
+        : receipt.files.html
+            ? await readPresentationAsset(root, receipt.reportId, receipt.buildId, asset, signal)
+            : (await buildPresentation(document)).htmlBytes;
+    const file = asset === 'presentation.json'
+        ? receipt.files.document
+        : (receipt.files.html ?? { bytes: bytes.length, sha256: presentationSha256(bytes) });
+    if (bytes.length !== file.bytes || presentationSha256(bytes) !== file.sha256)
+        throw new Error('asset-digest-mismatch');
+    signal.throwIfAborted();
+    return { bytes, sha256: file.sha256 };
+}