@chengxianglibra/dsh-data-analysis 0.1.1 → 0.2.0

package/lib/datasource/shell-env.js

@@ -1,13 +1,6 @@
-import { randomBytes } from 'node:crypto';
-import { credentialRef, isCredentialRefName, } from '@deepseek-ai/dsh-credentials';
+import { isCredentialRefName } from '@deepseek-ai/dsh-credentials';
 import { MarivoEnvironmentError } from "../environment/index.js";
-import { resolveMarivoDatasourceBridge, } from "./bridge.js";
 export const MARIVO_CREDENTIAL_STORAGE_PREFIX = 'DSH_DATA_ANALYSIS_CREDENTIAL_';
-export const MARIVO_CREDENTIAL_LEASE_PREFIX = '# dsh-marivo-credential-lease:';
-export const DEFAULT_MARIVO_CREDENTIAL_LEASE_TTL_MS = 30 * 60_000;
-export const DEFAULT_MARIVO_CREDENTIAL_LEASE_MAX_USES = 64;
-const TOKEN_PATTERN = /^[A-Za-z0-9_-]{43}$/;
-const SHELL_TOOL_NAMES = new Set(['bash', 'pwsh']);
 const HOST_SHELL_ENVIRONMENT_NAMES = new Set([
     'DSH_HOME',
     'DSH_SESSION_ID',
@@ -56,331 +49,7 @@ export function marivoCredentialStorageRef(ref) {
         .join('');
     return `${MARIVO_CREDENTIAL_STORAGE_PREFIX}${encoded}`;
 }
-function credentialBindings(refs) {
-    return Object.freeze([...new Set(refs)].map((environmentRef) => ({
-        environmentRef,
-        storageRef: marivoCredentialStorageRef(environmentRef),
-    })));
-}
-function bashPrelude(token, bindings) {
-    return [
-        `${MARIVO_CREDENTIAL_LEASE_PREFIX}${token}`,
-        ...bindings.flatMap(({ environmentRef, storageRef }) => [
-            `export ${environmentRef}="\${${storageRef}}"`,
-            `unset ${storageRef}`,
-        ]),
-        'export MARIVO_PERSIST_CREDENTIALS=0',
-    ].join('\n');
-}
-function pwshPrelude(token, bindings) {
-    return [
-        `${MARIVO_CREDENTIAL_LEASE_PREFIX}${token}`,
-        ...bindings.flatMap(({ environmentRef, storageRef }) => [
-            `$env:${environmentRef} = $env:${storageRef}`,
-            `Remove-Item Env:${storageRef}`,
-        ]),
-        "$env:MARIVO_PERSIST_CREDENTIALS = '0'",
-    ].join('\n');
-}
-function leaseFailure(code, message, details = {}) {
-    return new MarivoEnvironmentError(code, message, details);
-}
-function commandArguments(execution) {
-    return typeof execution.arguments === 'object' &&
-        execution.arguments !== null &&
-        !Array.isArray(execution.arguments)
-        ? execution.arguments
-        : undefined;
-}
-function hasCredentialStorageRefAt(command, offset, caseInsensitive) {
-    const candidate = caseInsensitive ? command.slice(offset).toUpperCase() : command.slice(offset);
-    if (!candidate.startsWith(MARIVO_CREDENTIAL_STORAGE_PREFIX))
-        return false;
-    let cursor = MARIVO_CREDENTIAL_STORAGE_PREFIX.length;
-    const firstHex = cursor;
-    while (cursor < candidate.length && /[A-F0-9]/.test(candidate[cursor] ?? ''))
-        cursor++;
-    return (cursor > firstHex &&
-        (cursor === candidate.length || !/[A-Z0-9_]/i.test(candidate[cursor] ?? '')));
-}
-function isBashCommentStart(command, offset) {
-    if (offset === 0)
-        return true;
-    return /[\s;&|()]/.test(command[offset - 1] ?? '');
-}
-function containsCredentialDereference(execution) {
-    const command = commandArguments(execution)?.command;
-    if (typeof command !== 'string')
-        return false;
-    const pwsh = execution.name === 'pwsh';
-    let quote;
-    let comment = false;
-    for (let index = 0; index < command.length; index++) {
-        const character = command[index];
-        if (comment) {
-            if (character === '\n' || character === '\r')
-                comment = false;
-            continue;
-        }
-        if (quote === "'") {
-            if (character === "'") {
-                if (pwsh && command[index + 1] === "'")
-                    index++;
-                else
-                    quote = undefined;
-            }
-            continue;
-        }
-        if (character === (pwsh ? '`' : '\\')) {
-            index++;
-            continue;
-        }
-        if (character === '#' && quote === undefined && (pwsh || isBashCommentStart(command, index))) {
-            comment = true;
-            continue;
-        }
-        if (character === "'" && quote === undefined) {
-            quote = "'";
-            continue;
-        }
-        if (character === '"') {
-            quote = quote === '"' ? undefined : '"';
-            continue;
-        }
-        if (character !== '$')
-            continue;
-        if (pwsh) {
-            if (command.slice(index + 1, index + 5).toLowerCase() === 'env:' &&
-                hasCredentialStorageRefAt(command, index + 5, true)) {
-                return true;
-            }
-            if (command.slice(index + 1, index + 6).toLowerCase() === '{env:' &&
-                hasCredentialStorageRefAt(command, index + 6, true)) {
-                return true;
-            }
-            continue;
-        }
-        const refOffset = command[index + 1] === '{' ? index + 2 : index + 1;
-        if (hasCredentialStorageRefAt(command, refOffset, false))
-            return true;
-    }
-    return false;
-}
-function leaseToken(execution) {
-    const command = commandArguments(execution)?.command;
-    if (typeof command !== 'string')
-        return undefined;
-    const firstLine = command.split(/\r?\n/, 1)[0] ?? '';
-    const candidate = firstLine.startsWith(MARIVO_CREDENTIAL_LEASE_PREFIX)
-        ? firstLine.slice(MARIVO_CREDENTIAL_LEASE_PREFIX.length)
-        : undefined;
-    if (candidate !== undefined && TOKEN_PATTERN.test(candidate))
-        return candidate;
-    if (firstLine.includes('dsh-marivo-credential-')) {
-        throw leaseFailure('shell-credential-lease-invalid', 'Marivo shell credential lease marker is malformed or unsupported');
-    }
-    return undefined;
-}
-function isHarnessPersistentShell(agent, name) {
-    const definition = agent.ctx.tools.get(name, agent);
-    return definition?.output.schema.type === 'string';
-}
 export function assertMarivoCredentialReferences(refs) {
-    for (const ref of refs) {
+    for (const ref of refs)
         marivoCredentialStorageRef(ref);
-    }
-}
-/** Own bounded leases and expose credential values only to each admitted Shell execution. */
-export class MarivoShellCredentialLeases {
-    #ctx;
-    #credentials;
-    #ttlMs;
-    #maxUses;
-    #leases = new Map();
-    #executionValues = new Map();
-    #contributors = new Map();
-    #disposed = false;
-    constructor(ctx, credentials, options = {}) {
-        const ttlMs = options.ttlMs ?? DEFAULT_MARIVO_CREDENTIAL_LEASE_TTL_MS;
-        const maxUses = options.maxUses ?? DEFAULT_MARIVO_CREDENTIAL_LEASE_MAX_USES;
-        if (!Number.isSafeInteger(ttlMs) ||
-            ttlMs < 1 ||
-            ttlMs > DEFAULT_MARIVO_CREDENTIAL_LEASE_TTL_MS) {
-            throw new TypeError(`Marivo shell credential lease ttlMs must be an integer from 1 to ${DEFAULT_MARIVO_CREDENTIAL_LEASE_TTL_MS}`);
-        }
-        if (!Number.isSafeInteger(maxUses) ||
-            maxUses < 1 ||
-            maxUses > DEFAULT_MARIVO_CREDENTIAL_LEASE_MAX_USES) {
-            throw new TypeError(`Marivo shell credential lease maxUses must be an integer from 1 to ${DEFAULT_MARIVO_CREDENTIAL_LEASE_MAX_USES}`);
-        }
-        this.#ctx = ctx;
-        this.#credentials = credentials;
-        this.#ttlMs = ttlMs;
-        this.#maxUses = maxUses;
-    }
-    #ensureContributor(ref) {
-        if (this.#disposed)
-            throw new Error('Marivo shell credential leases are disposed');
-        if (this.#contributors.has(ref))
-            return;
-        const dispose = shellEnvironmentRegistry(this.#ctx).register({
-            name: `dsh-data-analysis:credential:${ref}`,
-            variables: {
-                [ref]: {
-                    description: 'Marivo datasource credential authorized for this Shell execution.',
-                },
-            },
-            resolve: (execution) => {
-                const value = this.#executionValues.get(execution)?.values.get(ref);
-                return value === undefined ? {} : { [ref]: value };
-            },
-        });
-        this.#contributors.set(ref, dispose);
-    }
-    #purgeExpired(now) {
-        for (const [token, lease] of this.#leases) {
-            if (lease.expiresAt <= now)
-                this.#leases.delete(token);
-        }
-    }
-    revokeLease(agent, bridge, datasourceName) {
-        for (const [token, lease] of this.#leases) {
-            if (lease.agent === agent &&
-                lease.workspaceFingerprint === bridge.binding.fingerprint &&
-                lease.datasourceName === datasourceName) {
-                this.#leases.delete(token);
-            }
-        }
-    }
-    issueLease(agent, bridge, datasourceName, refs) {
-        if (this.#disposed)
-            throw new Error('Marivo shell credential leases are disposed');
-        const now = Date.now();
-        this.#purgeExpired(now);
-        this.revokeLease(agent, bridge, datasourceName);
-        assertMarivoCredentialReferences(refs);
-        const bindings = credentialBindings(refs);
-        for (const binding of bindings)
-            this.#ensureContributor(binding.storageRef);
-        const token = randomBytes(32).toString('base64url');
-        this.#leases.set(token, {
-            agent,
-            workspaceFingerprint: bridge.binding.fingerprint,
-            datasourceName,
-            bindings,
-            expiresAt: now + this.#ttlMs,
-            remainingUses: this.#maxUses,
-        });
-        return {
-            token,
-            expires_in_ms: this.#ttlMs,
-            max_uses: this.#maxUses,
-            usage: 'bounded-foreground-shell-lease',
-            bash_prelude: bashPrelude(token, bindings),
-            pwsh_prelude: pwshPrelude(token, bindings),
-        };
-    }
-    async #claim(agent, bridgeSource, execution, token) {
-        const lease = this.#leases.get(token);
-        if (lease === undefined) {
-            throw leaseFailure('shell-credential-lease-invalid', 'Marivo shell credential lease is unknown; call marivo_datasource_access again');
-        }
-        if (lease.expiresAt <= Date.now()) {
-            this.#leases.delete(token);
-            throw leaseFailure('shell-credential-lease-expired', 'Marivo shell credential lease has expired; call marivo_datasource_access again', { datasourceName: lease.datasourceName });
-        }
-        if (execution.agent !== agent || lease.agent !== agent) {
-            throw leaseFailure('shell-credential-lease-scope-mismatch', 'Marivo shell credential lease belongs to another Agent');
-        }
-        const bridge = await resolveMarivoDatasourceBridge(bridgeSource);
-        if (this.#leases.get(token) !== lease) {
-            throw leaseFailure('shell-credential-lease-invalid', 'Marivo shell credential lease was revoked; call marivo_datasource_access again');
-        }
-        if (lease.workspaceFingerprint !== bridge.binding.fingerprint) {
-            throw leaseFailure('shell-credential-lease-scope-mismatch', 'Marivo shell credential lease belongs to another Workspace binding');
-        }
-        if (lease.expiresAt <= Date.now()) {
-            this.#leases.delete(token);
-            throw leaseFailure('shell-credential-lease-expired', 'Marivo shell credential lease has expired; call marivo_datasource_access again', { datasourceName: lease.datasourceName });
-        }
-        const args = commandArguments(execution);
-        if (args?.run_in_background === true) {
-            throw leaseFailure('shell-credential-injection-unsupported', 'Marivo shell credential leases cannot be used by background Shell executions', { tool: execution.name });
-        }
-        if (isHarnessPersistentShell(agent, execution.name)) {
-            throw leaseFailure('shell-credential-injection-unsupported', `Marivo shell credential leases cannot be used by persistent ${execution.name}`, { tool: execution.name });
-        }
-        if (lease.remainingUses < 1) {
-            this.#leases.delete(token);
-            throw leaseFailure('shell-credential-lease-exhausted', 'Marivo shell credential lease is exhausted; call marivo_datasource_access again', { datasourceName: lease.datasourceName });
-        }
-        lease.remainingUses--;
-        const values = new Map();
-        for (const binding of lease.bindings) {
-            execution.signal.throwIfAborted();
-            let resolved;
-            try {
-                resolved = await this.#credentials.resolve(credentialRef(binding.storageRef));
-            }
-            catch {
-                throw leaseFailure('shell-credential-lease-resolve-failed', 'A credential authorized by the Marivo shell lease could not be resolved', { datasourceName: lease.datasourceName, ref: binding.environmentRef });
-            }
-            if (resolved === undefined) {
-                throw leaseFailure('shell-credential-lease-resolve-failed', 'A credential authorized by the Marivo shell lease is no longer configured', { datasourceName: lease.datasourceName, ref: binding.environmentRef });
-            }
-            values.set(binding.storageRef, resolved.value);
-        }
-        this.#executionValues.set(execution, { agent, values });
-    }
-    async prepareExecution(agent, bridgeSource, execution) {
-        if (this.#disposed)
-            throw new Error('Marivo shell credential leases are disposed');
-        const token = leaseToken(execution);
-        if (token === undefined) {
-            if (containsCredentialDereference(execution)) {
-                throw leaseFailure('shell-credential-lease-invalid', 'Marivo shell credential reference is not authorized because the exact prelude lease marker is missing. Call marivo_datasource_access again, copy the exact prelude, and use a foreground Shell execution', { tool: execution.name });
-            }
-            return false;
-        }
-        await this.#claim(agent, bridgeSource, execution, token);
-        return true;
-    }
-    installAgent(agent, bridgeSource) {
-        const stopPreExecute = agent.ctx.on('tools/pre-execute', async (execution, next) => {
-            if (execution.agent === agent && SHELL_TOOL_NAMES.has(execution.name)) {
-                await this.prepareExecution(agent, bridgeSource, execution);
-            }
-            return next();
-        });
-        const stopResult = agent.ctx.on('tools/result', (execution) => {
-            if (execution.agent === agent)
-                this.#executionValues.delete(execution);
-        });
-        let active = true;
-        return () => {
-            if (!active)
-                return;
-            active = false;
-            stopPreExecute();
-            stopResult();
-            for (const [token, lease] of this.#leases) {
-                if (lease.agent === agent)
-                    this.#leases.delete(token);
-            }
-            for (const [execution, snapshot] of this.#executionValues) {
-                if (snapshot.agent === agent)
-                    this.#executionValues.delete(execution);
-            }
-        };
-    }
-    dispose() {
-        if (this.#disposed)
-            return;
-        this.#disposed = true;
-        this.#leases.clear();
-        this.#executionValues.clear();
-        for (const dispose of this.#contributors.values())
-            dispose();
-        this.#contributors.clear();
-    }
 }

package/lib/datasource/test.js

@@ -1,65 +1,39 @@
 import { defineTool } from '@deepseek-ai/dsh-tools';
-import { resolveMarivoDatasourceBridge, } from "./bridge.js";
-import { inspectMarivoDatasourceCredentials } from "./credentials.js";
+import { registerMarivoTool } from "../tool-lifecycle.js";
+import { resolveMarivoDatasourceBridge } from "./bridge.js";
 export const MARIVO_DATASOURCE_TEST_TOOL_NAME = 'marivo_datasource_test';
-function datasourceName(value) {
-    if (typeof value !== 'string' || value.trim() === '' || value.length > 256) {
-        throw new TypeError('marivo_datasource_test name must be a non-empty string of at most 256 characters');
-    }
-    return value;
-}
-function renderValue(value) {
-    if (value.status === 'needs-credentials')
-        return JSON.stringify(value);
-    if (value.status === 'ok') {
-        return `Marivo datasource ${value.name} connection test succeeded${value.latency_ms === null ? '' : ` in ${value.latency_ms} ms`}.`;
-    }
-    return JSON.stringify(value);
-}
-/** Build the scoped datasource connection-test Tool. */
-export function createMarivoDatasourceTestTool(bridgeSource, credentials, options) {
+export function createMarivoDatasourceTestTool(source, service) {
     return defineTool({
         name: MARIVO_DATASOURCE_TEST_TOOL_NAME,
-        description: 'Test one configured Marivo datasource connection. Missing datasource environment references are requested through the DSH credential service.',
+        description: 'Test a Marivo datasource through Host credentials. Missing credentials wait for the Web form while this call remains alive; configured connection failures return directly.',
         parameters: {
-            name: {
-                type: 'string',
-                required: true,
-                description: 'Configured Marivo datasource name.',
-            },
+            name: { type: 'string', required: true, description: 'Configured datasource name.' },
         },
         output: {
             schema: { type: 'json' },
-            render: (_args, value) => [
-                { type: 'text', text: renderValue(value) },
-            ],
+            render: (_args, value) => [{ type: 'text', text: JSON.stringify(value) }],
         },
-        timeoutMs: 65_000,
         async execute(args, exec) {
-            const name = datasourceName(args.name);
-            const bridge = await resolveMarivoDatasourceBridge(bridgeSource);
-            options.revokeShellLease(bridge, name);
-            const described = await bridge.describe(name, exec.signal);
-            const overlay = {};
-            const missing = await inspectMarivoDatasourceCredentials(described.refs, credentials, exec.signal, (ref, value) => {
-                overlay[ref] = value;
-            });
-            if (missing.length > 0)
-                return { status: 'needs-credentials', name: described.name, refs: missing };
-            const tested = await bridge.test(name, overlay, exec.signal);
-            if (tested.ok) {
-                return { status: 'ok', name: tested.name, latency_ms: tested.latency_ms };
-            }
-            return {
-                status: 'failed',
-                name: tested.name,
-                latency_ms: tested.latency_ms,
-                failure: tested.failure,
-                repair: tested.repair,
-            };
+            if (!args.name.trim() || args.name.length > 256)
+                throw new Error('Invalid datasource name');
+            return datasourceToolValue(await service.track(service.prepare('test', exec, () => resolveMarivoDatasourceBridge(source), args.name)));
         },
     });
 }
-export function registerMarivoDatasourceTestTool(ctx, bridgeSource, credentials, options) {
-    return ctx.tools.register(createMarivoDatasourceTestTool(bridgeSource, credentials, options));
+export function registerMarivoDatasourceTestTool(ctx, source, service) {
+    return registerMarivoTool(ctx, createMarivoDatasourceTestTool(source, service));
+}
+/** Preserve the datasource tools' public status family; raw Marivo results stay inside the service. */
+export function datasourceToolValue(result) {
+    if (!('ok' in result))
+        return JSON.parse(JSON.stringify(result));
+    return JSON.parse(JSON.stringify(result.ok
+        ? { status: 'ok', name: result.name, latency_ms: result.latency_ms }
+        : {
+            status: 'failed',
+            name: result.name,
+            latency_ms: result.latency_ms,
+            failure: result.failure,
+            repair: result.repair,
+        }));
 }

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