@chengxianglibra/dsh-data-analysis 0.1.2 → 0.2.1

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,49 @@
+import { createUserMessage } from '@deepseek-ai/dsh-llm';
+export const MARIVO_DATASOURCE_CREDENTIAL_PROMPT = [
+    'These are Host execution and credential rules; Marivo API and semantic contracts come from the bound Runtime Skill and live Help.',
+    '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_configure for missing datasource setup or connection configuration repair; the user owns configuration in the Web form. Use marivo_datasource_test for connection checks under its tool contract. Configured credentials alone do not prove connection or read access.',
+    'Execute analysis, metadata inspection and semantic data reads through marivo_python in the bound Runtime and Workspace. Declare all exact Marivo datasource names this execution may access, including datasources without passwords; use datasources: [] for local pandas or native DuckDB without Marivo datasource access.',
+    'Each marivo_python call is a separate process. Create/resume Marivo Sessions inside the call, close them in finally, and retain the persisted Session identity when continuing the same analysis. Closing process resources does not delete durable Artifacts. Do not replace the credential resolver, read SecretValue contents, or bypass Host scope with environment/cache configuration.',
+    'Preserve real failures. After uncertain execution, inspect existing effects before retrying; never automatically replay a script with possible side effects.',
+].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 = 'Match delivery to the user request. Ordinary answers and simple comparison tables can stay in chat. For analysis of attachments or Workspace data files, including short chat comparisons, first load dsh-data-analysis-files; requested CSV, JSON or PNG files use native present. For interactive charts or tables, saved reports, dashboards, report updates or visual source panels, load dsh-data-analysis-presentation and use marivo_present; that Skill also covers report export and publication when requested. Existing results can be presented directly. Use the Runtime skills and live Help for Marivo analysis or semantic authoring; local pandas or native DuckDB file analysis needs no Marivo semantic setup. When analysis reveals a reusable business definition or semantic gap, follow the relevant Skill to assess reuse or handoff to marivo-semantic, limited to what the current task needs or the user has authorized; stop when that scope is answered or its blockers are explicit.';
+/**
+ * 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, options.pythonOptionsSource ?? 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;
+}