@chengxianglibra/dsh-data-analysis 0.1.2 → 0.2.0

package/lib/disclosure/activation.js

@@ -1,5 +1,6 @@
 import { createUserMessage } from '@deepseek-ai/dsh-llm';
 import { scopeParentOf } from '@deepseek-ai/dsh-scope';
+import { finishCleanup, PendingTasks } from "../lifecycle.js";
 import { MARIVO_HELP_TOOL_NAME, readMarivoHelpTargets, registerMarivoHelpTool, renderMarivoHelpValue, resolveMarivoHelpBridge, } from "./help.js";
 const SKILL_TOOL_NAME = 'skill';
 export const MARIVO_ROOT_HELP_TARGETS = Object.freeze({
@@ -119,6 +120,8 @@ export class MarivoDisclosureController {
     #visibleHelp = new Map();
     #lifecycleAbort = new AbortController();
     #disposers = [];
+    #tasks = new PendingTasks();
+    #closing;
     #disposed = false;
     #telemetry = { activations: [], rootHelp: [], failures: [] };
     constructor(agent, bridgeSource, options = {}) {
@@ -181,7 +184,10 @@ export class MarivoDisclosureController {
             return 'already-visible';
         return visible === undefined ? 'delivered' : 'replacement';
     }
-    async prepareStep(messages, signal) {
+    prepareStep(messages, signal) {
+        return this.#tasks.track(this.#prepareStep(messages, signal));
+    }
+    async #prepareStep(messages, signal) {
         if (this.#disposed)
             throw this.#lifecycleAbort.signal.reason;
         this.#observeExplicitInvocations(messages);
@@ -273,13 +279,16 @@ export class MarivoDisclosureController {
             return;
         this.#disposed = true;
         this.#lifecycleAbort.abort(new Error('Marivo disclosure controller disposed'));
-        for (const disposer of this.#disposers.reverse())
-            disposer();
+        this.#closing = finishCleanup([...this.#disposers.reverse(), () => this.#tasks.drain()]);
         this.#disposers = [];
         this.#activeSkills.clear();
         this.#pendingSkills.clear();
         this.#visibleHelp.clear();
     }
+    close() {
+        this.dispose();
+        return this.#closing;
+    }
     #inheritedSkillToolVisible() {
         const inheritedSkillTool = this.agent.ctx.tools.get(SKILL_TOOL_NAME, scopeParentOf(this.agent));
         return (inheritedSkillTool !== undefined &&
@@ -294,7 +303,7 @@ export class MarivoDisclosureController {
         }
     }
     #restoreActiveSkills() {
-        for (const event of this.agent.session.events) {
+        for (const event of this.agent.session.snapshotEvents()) {
             if (event.type !== 'user/message')
                 continue;
             const disclosure = rootHelpSource(event.data.source);
@@ -309,7 +318,7 @@ export class MarivoDisclosureController {
     #refreshVisibleHelp(messages) {
         this.#visibleHelp.clear();
         const visible = new Set(this.agent.session.surface.nodes);
-        for (const event of this.agent.session.events) {
+        for (const event of this.agent.session.snapshotEvents()) {
             if (!visible.has(event.seq))
                 continue;
             if (event.type === 'user/message') {
@@ -340,7 +349,9 @@ export class MarivoDisclosureController {
         }
     }
     #hasHistoricalDisclosure(skill) {
-        return this.agent.session.events.some((event) => event.type === 'user/message' && rootHelpSource(event.data.source)?.skill === skill);
+        return this.agent.session
+            .snapshotEvents()
+            .some((event) => event.type === 'user/message' && rootHelpSource(event.data.source)?.skill === skill);
     }
 }
 /** Install skill-triggered Marivo live-help disclosure for one Agent scope. */
@@ -356,9 +367,10 @@ export function installMarivoDisclosure(_ctx, agent, bridgeSource, options = {})
             if (decision.kind === 'reject')
                 return decision;
             const injections = await controller.prepareStep(decision.messages, signal);
+            signal.throwIfAborted();
             return injections.length === 0
                 ? decision
-                : { kind: 'enter', messages: [...decision.messages, ...injections] };
+                : { ...decision, messages: [...decision.messages, ...injections] };
         }, true));
         return controller;
     }

package/lib/disclosure/execution-guidance.js

@@ -0,0 +1,52 @@
+import { createUserMessage } from '@deepseek-ai/dsh-llm';
+export const MARIVO_DATASOURCE_CREDENTIAL_PROMPT = [
+    'When a requested table has no usable configured datasource, call marivo_datasource_configure with mode=create and a brief reason. For a datasource needing connection configuration repair, use mode=edit and its exact name. The user configures it in the owning Web right tab; do not request secrets in chat or write connection configuration on the user behalf. Only status=ok allows continuing: rediscover the datasource and verify the requested table and read access before analysis. Other statuses are not connection success. A provided local file may be analyzed directly when appropriate; do not invent a remote datasource requirement.',
+    'DSH Credentials owns Marivo datasource secrets. Never request values in chat, read credential files or ~/.marivo/secrets.toml, or write secrets to scripts, arguments, environment variables, reports or logs.',
+    'Use marivo_datasource_test after datasource changes, credential rotation, connection failures, or explicit user requests. Missing credentials wait for the Web form only while the original call remains alive.',
+    'Execute analysis, metadata inspection and semantic data reads through marivo_python. Declare all exact Marivo datasource names this execution may access, including datasources without passwords. Local file analysis with pandas or native DuckDB uses datasources: [] when no Marivo datasource is accessed.',
+    'marivo_python waits for all missing credentials and validates the bound Workspace and datasource identities before taking one fresh snapshot and starting user code once. Configured credentials need no extra connection test. Ordinary Shell receives no datasource secret.',
+    'marivo_python installs credential_scope before user code. When using Marivo Session/reader objects, create or resume them inside that execution, and close Sessions in finally. Do not replace the resolver, read SecretValue contents, or bypass Host scope with environment/cache configuration.',
+    "Each marivo_python call uses a separate process. Closing releases that process's Session resources; it does not end the analytical question or delete durable Artifacts. When continuing a persisted Marivo analysis, reuse its Session identity across calls.",
+    'Configured credentials do not imply a valid connection or query permissions. Preserve real failures; never automatically replay a script with possible side effects.',
+    'Session lifetime pattern inside one marivo_python call (create/resume using current Runtime Help):\nsession = ...\ntry:\n    ...  # analysis using this Session\nfinally:\n    session.close()',
+].join('\n');
+export const MARIVO_ANALYSIS_CLOSEOUT_PROMPT = [
+    'Analysis semantics and execution contracts come from the activated Runtime Skill and current Help.',
+    'Before completing any analysis, including a text-only answer, check each user question and each requested comparison scope against its evidence. Keep incomplete branches explicit; preserve comparison sides, direction and denominator. Match conclusion strength to evidence, and reflect limitations in the claims themselves.',
+].join(' ');
+/** Bridge rules activated after system prompt assembly, without changing their wording. */
+function executionGuidanceSupplement(before, after) {
+    const rules = [];
+    if (before.length === 0 && after.length > 0)
+        rules.push(MARIVO_DATASOURCE_CREDENTIAL_PROMPT);
+    if (!before.includes('marivo-analysis') && after.includes('marivo-analysis'))
+        rules.push(MARIVO_ANALYSIS_CLOSEOUT_PROMPT);
+    if (rules.length === 0)
+        return [];
+    return [
+        createUserMessage({
+            content: [
+                {
+                    type: 'text',
+                    text: ['<marivo_execution_guidance>', ...rules, '</marivo_execution_guidance>'].join('\n\n'),
+                },
+            ],
+            source: { kind: 'plugin', plugin: 'dsh-data-analysis' },
+        }),
+    ];
+}
+/** Full-plugin seam: requires its execution tools, credentials service and system sections. */
+export function installMarivoExecutionGuidance(agent, controller) {
+    return agent.ctx.on('agent/pre-step', async ({ signal }, next) => {
+        // Prepend after Help installation to wrap its successful disclosure decision.
+        const previouslyActive = controller.activeSkills;
+        const decision = await next();
+        if (decision.kind === 'reject')
+            return decision;
+        signal.throwIfAborted();
+        const guidance = executionGuidanceSupplement(previouslyActive, controller.activeSkills);
+        return guidance.length === 0
+            ? decision
+            : { ...decision, messages: [...decision.messages, ...guidance] };
+    }, true);
+}

package/lib/disclosure/help.js

@@ -1,5 +1,6 @@
 import { createHash } from 'node:crypto';
 import { defineTool } from '@deepseek-ai/dsh-tools';
+import { registerMarivoTool } from "../tool-lifecycle.js";
 import { MarivoHelpError, resolveMarivoHelpBridge, } from "./bridge.js";
 export { MarivoHelpError, resolveMarivoHelpBridge } from "./bridge.js";
 export const MARIVO_HELP_TOOL_NAME = 'marivo_help';
@@ -203,12 +204,14 @@ export function createMarivoHelpTool(bridgeSource, limitOverrides = {}, resolveD
         },
         timeoutMs: limits.toolTimeoutMs,
         async execute(args, exec) {
+            exec.signal.throwIfAborted();
             const bridge = await resolveMarivoHelpBridge(bridgeSource);
             const internal = await readMarivoHelpTargets(bridge, args.targets, {
                 limits,
                 signal: exec.signal,
                 resolveDelivery,
             });
+            exec.signal.throwIfAborted();
             const value = {
                 environment: { version: internal.environment.version },
                 targets: internal.targets,
@@ -223,5 +226,5 @@ export function createMarivoHelpTool(bridgeSource, limitOverrides = {}, resolveD
 }
 /** Register the focused Help Tool; skill-triggered root disclosure is composed separately. */
 export function registerMarivoHelpTool(ctx, bridgeSource, limits = {}, resolveDelivery) {
-    return ctx.tools.register(createMarivoHelpTool(bridgeSource, limits, resolveDelivery));
+    return registerMarivoTool(ctx, createMarivoHelpTool(bridgeSource, limits, resolveDelivery));
 }

package/lib/environment/runtime.js

@@ -25,6 +25,7 @@ import os
 import sys
 from importlib.metadata import distribution
 import marivo
+import ibis.backends.duckdb
 from marivo.semantic.definition import SemanticDefinition
 import pandas
 import dsh_data_analysis_presentation
@@ -166,7 +167,7 @@ async function probeRuntime(runtimeRoot, executable, environment, timeoutMs, pre
     });
     const repair = administrator ? administratorRepair(canonical, presentationKitWheel) : undefined;
     if (administrator && result.exitCode !== 0) {
-        throw new MarivoEnvironmentError('shared-runtime-package-unavailable', `Administrator Python must provide Marivo ${PINNED_MARIVO_VERSION}, pandas ${PRESENTATION_KIT_PANDAS_RANGE}, and ${PRESENTATION_KIT_DISTRIBUTION} ${PRESENTATION_KIT_VERSION}. ${repair.message}`, {
+        throw new MarivoEnvironmentError('shared-runtime-package-unavailable', `Administrator Python must provide Marivo ${PINNED_MARIVO_VERSION} with the duckdb extra, pandas ${PRESENTATION_KIT_PANDAS_RANGE}, and ${PRESENTATION_KIT_DISTRIBUTION} ${PRESENTATION_KIT_VERSION}. ${repair.message}`, {
             pythonExecutable: canonical,
             marivoVersion: PINNED_MARIVO_VERSION,
             pandasRange: PRESENTATION_KIT_PANDAS_RANGE,
@@ -462,50 +463,48 @@ async function backupInvalidRuntime(runtimeRoot) {
     }
     await rename(runtimeRoot, `${runtimeRoot}.invalid-${Date.now()}-${randomUUID()}`);
 }
-async function installManagedRuntime(runtimeRoot, uvExecutable, presentationKitWheel, environment, timeoutMs) {
+async function installManagedRuntime(runtimeRoot, bootstrapPythonExecutable, presentationKitWheel, environment, timeoutMs) {
     const policy = new FixedSubprocessPolicy(runtimeRoot, environment);
     const limits = { timeoutMs, stdoutMaxBytes: 1_048_576, stderrMaxBytes: 1_048_576 };
-    requireSuccess('install managed Python', await policy.run({
-        executable: uvExecutable,
-        args: ['python', 'install', SHARED_PYTHON_SPEC],
-        limits,
-    }));
-    const found = requireSuccess('resolve managed Python', await policy.run({
-        executable: uvExecutable,
-        args: ['python', 'find', '--managed-python', SHARED_PYTHON_SPEC],
-        limits,
-    }));
-    const managedPython = found.stdout.toString('utf8').trim();
-    if (!path.isAbsolute(managedPython)) {
-        throw new MarivoEnvironmentError('shared-runtime-install-failed', 'uv returned a non-absolute managed Python path', { managedPython });
-    }
-    const canonicalManagedPython = await assertExecutable(managedPython);
-    const version = parseJsonObject('validate managed Python', await policy.run({
-        executable: canonicalManagedPython,
-        args: ['-c', PYTHON_VERSION_SCRIPT],
-        limits,
-    }));
+    let version;
+    try {
+        version = parseJsonObject('validate local Python', await policy.run({
+            executable: bootstrapPythonExecutable,
+            args: ['-c', PYTHON_VERSION_SCRIPT],
+            limits,
+        }));
+    }
+    catch (error) {
+        if (!(error instanceof MarivoEnvironmentError))
+            throw error;
+        throw new MarivoEnvironmentError('shared-runtime-install-failed', 'Could not validate local Python. Install Python 3.10+ with venv/ensurepip, or set bootstrapPythonExecutable to its absolute path.', { pythonExecutable: bootstrapPythonExecutable, causeCode: error.code });
+    }
     if (!Array.isArray(version.version) ||
         typeof version.version[0] !== 'number' ||
         typeof version.version[1] !== 'number' ||
         version.version[0] < 3 ||
         (version.version[0] === 3 && version.version[1] < 10)) {
-        throw new MarivoEnvironmentError('shared-runtime-install-failed', 'uv managed Python does not satisfy Marivo >=3.10', { version: version.version, pythonExecutable: canonicalManagedPython });
+        throw new MarivoEnvironmentError('shared-runtime-install-failed', `Local Python does not satisfy Marivo >=${SHARED_PYTHON_SPEC}; detected ${Array.isArray(version.version) ? version.version.join('.') : 'unknown'}`, { version: version.version, pythonExecutable: bootstrapPythonExecutable });
+    }
+    if (typeof version.python_executable !== 'string' ||
+        !path.isAbsolute(version.python_executable)) {
+        throw new MarivoEnvironmentError('shared-runtime-install-failed', 'Local Python returned a non-absolute interpreter path');
     }
-    requireSuccess('create shared virtual environment', await policy.run({
-        executable: uvExecutable,
-        args: ['venv', '--python', canonicalManagedPython, '--seed', path.join(runtimeRoot, '.venv')],
+    const canonicalPython = await assertExecutable(version.python_executable);
+    requireSuccess('create shared virtual environment (requires Python venv/ensurepip; install python3-venv on Debian/Ubuntu)', await policy.run({
+        executable: canonicalPython,
+        args: ['-m', 'venv', path.join(runtimeRoot, '.venv')],
         limits,
     }));
     const executable = venvPython(runtimeRoot);
     requireSuccess(`install Marivo ${PINNED_MARIVO_VERSION}`, await policy.run({
-        executable: uvExecutable,
-        args: ['pip', 'install', '--python', executable, '--upgrade', SHARED_MARIVO_PACKAGE_SPEC],
+        executable,
+        args: ['-m', 'pip', 'install', '--upgrade', SHARED_MARIVO_PACKAGE_SPEC],
         limits,
     }));
     requireSuccess(`install presentation kit ${PRESENTATION_KIT_VERSION}`, await policy.run({
-        executable: uvExecutable,
-        args: ['pip', 'install', '--python', executable, '--no-deps', presentationKitWheel],
+        executable,
+        args: ['-m', 'pip', 'install', '--no-deps', presentationKitWheel],
         limits,
     }));
     return probeRuntime(runtimeRoot, executable, environment, timeoutMs, presentationKitWheel, false, PINNED_MARIVO_VERSION);
@@ -518,9 +517,11 @@ export async function ensureSharedMarivoRuntime(config = {}, options = {}) {
     const configuredPython = config.pythonExecutable === undefined
         ? undefined
         : normalizeAbsolute('pythonExecutable', config.pythonExecutable);
-    const uvExecutable = config.uvExecutable === undefined
-        ? 'uv'
-        : normalizeAbsolute('uvExecutable', config.uvExecutable);
+    const bootstrapPythonExecutable = config.bootstrapPythonExecutable === undefined
+        ? process.platform === 'win32'
+            ? 'python'
+            : 'python3'
+        : normalizeAbsolute('bootstrapPythonExecutable', config.bootstrapPythonExecutable);
     const timeoutMs = positiveTimeout(config.installTimeoutMs);
     const presentationKitWheel = path.normalize(path.resolve(options.presentationKitWheelPath ?? bundledPresentationKitWheel()));
     const existing = await validatedExisting(runtimeRoot, configuredPython, options.environment, timeoutMs, presentationKitWheel);
@@ -538,7 +539,7 @@ export async function ensureSharedMarivoRuntime(config = {}, options = {}) {
         await backupInvalidRuntime(runtimeRoot);
         await mkdir(runtimeRoot, { recursive: true });
         const probe = configuredPython === undefined
-            ? await installManagedRuntime(runtimeRoot, uvExecutable, presentationKitWheel, options.environment, timeoutMs)
+            ? await installManagedRuntime(runtimeRoot, bootstrapPythonExecutable, presentationKitWheel, options.environment, timeoutMs)
             : await probeRuntime(runtimeRoot, configuredPython, options.environment, timeoutMs, presentationKitWheel, true, PINNED_MARIVO_VERSION);
         const skillsRoot = await syncSkills(runtimeRoot, probe.package_path);
         const record = {

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,13 +27,23 @@ 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({
@@ -48,7 +59,13 @@ export class MarivoWorkspaceEnvironmentManager {
         }
         return binding;
     }
+    close() {
+        this.dispose();
+        this.#closing ??= finishCleanup([() => this.#tasks.drain()]);
+        return this.#closing;
+    }
     dispose() {
+        this.#disposed = true;
         this.#bindings.clear();
     }
 }

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