@chengxianglibra/dsh-data-analysis 0.1.1

package/lib/evidence/sources.js

@@ -0,0 +1,263 @@
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { resolveMarivoEvidenceBridge, } from "./bridge.js";
+export const MARIVO_EVIDENCE_SOURCES_TOOL_NAME = 'marivo_evidence_sources';
+export const MARIVO_EVIDENCE_SOURCES_META_KIND = 'marivo-evidence-sources';
+export const MARIVO_EVIDENCE_SOURCES_META_VERSION = 2;
+export const MARIVO_EVIDENCE_SOURCES_DURABLE_CONTENT_KIND = 'marivo-evidence-sources-card';
+export const MARIVO_EVIDENCE_SOURCES_MAX_PER_CALL = 20;
+const nullableStringSchema = { oneOf: [{ type: 'string' }, { type: 'null' }] };
+const evidenceSourceSchema = {
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+        status: {
+            oneOf: [
+                { type: 'string', const: 'available' },
+                { type: 'string', const: 'missing' },
+                { type: 'string', const: 'unsupported' },
+            ],
+            required: true,
+        },
+        title: { type: 'string', required: true },
+        locator: { type: 'string', required: true },
+        excerpt: { ...nullableStringSchema, required: true },
+        truncated: { type: 'boolean', required: true },
+        environmentFingerprint: { type: 'string', required: true },
+        sessionId: { type: 'string', required: true },
+        findingId: { type: 'string', required: true },
+        findingType: { ...nullableStringSchema, required: true },
+        epistemicKind: { ...nullableStringSchema, required: true },
+        artifactRef: { type: 'string', required: true },
+        canonicalItemKey: { ...nullableStringSchema, required: true },
+        committedAt: { ...nullableStringSchema, required: true },
+        sourceRefs: { type: 'array', items: { type: 'string' }, required: true },
+        revalidation: {
+            oneOf: [
+                { type: 'null' },
+                {
+                    type: 'object',
+                    additionalProperties: false,
+                    properties: {
+                        status: { type: 'string', required: true },
+                        semanticStatus: { ...nullableStringSchema, required: true },
+                        evidenceStatus: { ...nullableStringSchema, required: true },
+                        dependencyStatus: { ...nullableStringSchema, required: true },
+                    },
+                },
+            ],
+            required: true,
+        },
+    },
+};
+const evidenceSourcesOutputSchema = {
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+        status: { type: 'string', const: 'ok', required: true },
+        environment: {
+            type: 'object',
+            additionalProperties: false,
+            required: true,
+            properties: {
+                version: { type: 'string', required: true },
+                fingerprint: { type: 'string', required: true },
+            },
+        },
+        dshSessionId: { type: 'string', required: true },
+        sessionId: { type: 'string', required: true },
+        sources: { type: 'array', items: evidenceSourceSchema, required: true },
+    },
+};
+function nonEmptyString(value, field, maxLength = 2_048) {
+    if (typeof value !== 'string' || value.trim() === '' || value.length > maxLength) {
+        throw new TypeError(`${field} must be a non-empty string of at most ${maxLength} characters`);
+    }
+    return value;
+}
+function requestedSources(value) {
+    if (!Array.isArray(value) ||
+        value.length < 1 ||
+        value.length > MARIVO_EVIDENCE_SOURCES_MAX_PER_CALL) {
+        throw new TypeError(`marivo_evidence_sources sources must contain 1-${MARIVO_EVIDENCE_SOURCES_MAX_PER_CALL} items`);
+    }
+    const result = value.map((item, index) => {
+        if (typeof item !== 'object' || item === null || Array.isArray(item)) {
+            throw new TypeError(`marivo_evidence_sources sources[${index}] must be an object`);
+        }
+        const source = item;
+        if (Object.keys(source).length !== 2 ||
+            !Object.hasOwn(source, 'artifact_ref') ||
+            !Object.hasOwn(source, 'finding_id')) {
+            throw new TypeError(`marivo_evidence_sources sources[${index}] must contain exactly artifact_ref and finding_id`);
+        }
+        return {
+            artifactRef: nonEmptyString(source.artifact_ref, `marivo_evidence_sources sources[${index}].artifact_ref`, 512),
+            findingId: nonEmptyString(source.finding_id, `marivo_evidence_sources sources[${index}].finding_id`, 512),
+        };
+    });
+    if (new Set(result.map((item) => JSON.stringify(item))).size !== result.length) {
+        throw new TypeError('marivo_evidence_sources sources must be unique within one request');
+    }
+    return result;
+}
+function evidenceSource(environmentFingerprint, finding) {
+    return {
+        status: finding.status,
+        title: finding.title,
+        locator: finding.locator,
+        excerpt: finding.excerpt,
+        truncated: finding.truncated,
+        environmentFingerprint,
+        sessionId: finding.sessionId,
+        findingId: finding.findingId,
+        findingType: finding.findingType,
+        epistemicKind: finding.epistemicKind,
+        artifactRef: finding.artifactRef,
+        canonicalItemKey: finding.canonicalItemKey,
+        committedAt: finding.committedAt,
+        sourceRefs: [...finding.sourceRefs],
+        revalidation: finding.revalidation === null ? null : { ...finding.revalidation },
+    };
+}
+function renderSources(value) {
+    const lines = [
+        `Exact Marivo Evidence sources (${value.sources.length})`,
+        `Marivo Session: ${value.sessionId}`,
+    ];
+    value.sources.forEach((source, index) => {
+        lines.push('', `${index + 1}. ${source.title}`, `   status: ${source.status}`);
+        lines.push(`   locator: ${source.locator}`);
+        lines.push(`   excerpt: ${source.excerpt ?? 'unavailable'}`);
+        lines.push(`   excerpt_state: ${source.truncated ? 'truncated' : 'complete'}`);
+        const revalidation = source.revalidation;
+        lines.push(`   revalidation: ${revalidation === null ? 'unavailable' : revalidation.status}`);
+        if (revalidation !== null) {
+            lines.push(`   semantic_status: ${revalidation.semanticStatus ?? 'unavailable'}`, `   evidence_status: ${revalidation.evidenceStatus ?? 'unavailable'}`, `   dependency_status: ${revalidation.dependencyStatus ?? 'unavailable'}`);
+        }
+        lines.push(`   source_refs: ${source.sourceRefs.length === 0 ? 'none' : source.sourceRefs.join(', ')}`);
+    });
+    lines.push('', 'Boundary: source identity and availability do not prove that an entire conclusion, calculation, or business judgment is correct.');
+    return lines.join('\n');
+}
+export function evidenceSourcesMeta(value) {
+    return {
+        kind: MARIVO_EVIDENCE_SOURCES_META_KIND,
+        version: MARIVO_EVIDENCE_SOURCES_META_VERSION,
+        dshSessionId: value.dshSessionId,
+        sources: value.sources.map((source) => ({
+            ...source,
+            sourceRefs: [...source.sourceRefs],
+            revalidation: source.revalidation === null ? null : { ...source.revalidation },
+        })),
+    };
+}
+/** Build the exact-Finding source attachment Tool for one Agent and DSH Session. */
+export function createMarivoEvidenceSourcesTool(bridgeSource, session) {
+    return defineTool({
+        name: MARIVO_EVIDENCE_SOURCES_TOOL_NAME,
+        description: 'Attach exact persisted Marivo Evidence sources to the current turn only when the user explicitly requests sources, provenance, or audit details. This identifies sources; it does not validate the surrounding conclusion.',
+        parameters: {
+            session_id: {
+                type: 'string',
+                required: true,
+                description: 'Exact Marivo analysis Session ID containing the Findings.',
+            },
+            sources: {
+                type: 'array',
+                required: true,
+                description: `1-${MARIVO_EVIDENCE_SOURCES_MAX_PER_CALL} unique exact Artifact/Finding pairs to attach.`,
+                items: {
+                    type: 'object',
+                    additionalProperties: false,
+                    properties: {
+                        artifact_ref: { type: 'string', required: true },
+                        finding_id: { type: 'string', required: true },
+                    },
+                },
+            },
+        },
+        output: {
+            schema: evidenceSourcesOutputSchema,
+            render: (_args, value) => [
+                { type: 'text', text: renderSources(value) },
+            ],
+            presentationMeta: (_args, value) => evidenceSourcesMeta(value),
+        },
+        timeoutMs: 35_000,
+        async execute(args, exec) {
+            const sessionId = nonEmptyString(args.session_id, 'marivo_evidence_sources session_id', 512);
+            const selections = requestedSources(args.sources);
+            const bridge = await resolveMarivoEvidenceBridge(bridgeSource);
+            const findings = await bridge.findings(sessionId, selections, exec.signal);
+            return {
+                status: 'ok',
+                environment: {
+                    version: bridge.binding.marivoVersion,
+                    fingerprint: bridge.binding.fingerprint,
+                },
+                dshSessionId: String(session.id),
+                sessionId,
+                sources: findings.map((finding) => evidenceSource(bridge.binding.fingerprint, finding)),
+            };
+        },
+    });
+}
+export function registerMarivoEvidenceSourcesTool(ctx, bridgeSource, session) {
+    return ctx.tools.register(createMarivoEvidenceSourcesTool(bridgeSource, session));
+}
+function sourceTurnForRootCall(dispatch) {
+    const rootCallId = String(dispatch.exec.rootCallId ?? '');
+    if (rootCallId === '' || !Array.isArray(dispatch.agent?.session?.events))
+        return null;
+    for (let index = dispatch.agent.session.events.length - 1; index >= 0; index--) {
+        const candidate = dispatch.agent.session.events[index];
+        if (typeof candidate !== 'object' || candidate === null || Array.isArray(candidate))
+            continue;
+        const event = candidate;
+        if (event.type !== 'tool/call' || String(event.data?.callId ?? '') !== rootCallId)
+            continue;
+        const turn = event.data?.turn;
+        return Number.isSafeInteger(turn) && turn >= 0 ? turn : null;
+    }
+    return null;
+}
+/** Preserve nested Code Mode source metadata on the durable sub-dispatch event. */
+export function installMarivoEvidenceSourcesCodeDelivery(ctx) {
+    const pending = new Map();
+    const stopResult = ctx.on('tools/result', (exec, result) => {
+        if (exec.name !== MARIVO_EVIDENCE_SOURCES_TOOL_NAME ||
+            exec.parent === undefined ||
+            result.isError) {
+            return;
+        }
+        pending.set(String(exec.callId), evidenceSourcesMeta(result.value));
+    });
+    const stopDispatchLog = ctx.on('tools/code-dispatch-log', async (dispatch, next) => {
+        const content = await next();
+        if (dispatch.name !== MARIVO_EVIDENCE_SOURCES_TOOL_NAME)
+            return content;
+        const key = String(dispatch.subCallId);
+        const meta = pending.get(key);
+        pending.delete(key);
+        if (dispatch.isError || meta === undefined)
+            return content;
+        const turn = sourceTurnForRootCall(dispatch);
+        if (turn === null)
+            return content;
+        const card = {
+            type: MARIVO_EVIDENCE_SOURCES_DURABLE_CONTENT_KIND,
+            turn,
+            meta,
+        };
+        return [...content, card];
+    }, { prepend: true });
+    let active = true;
+    return () => {
+        if (!active)
+            return;
+        active = false;
+        stopDispatchLog();
+        stopResult();
+        pending.clear();
+    };
+}

package/lib/index.js

@@ -0,0 +1,7 @@
+export { createMarivoBridgeSet } from "./bridges.js";
+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";

package/lib/plugin.js

@@ -0,0 +1,179 @@
+/** 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 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 { 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";
+/** 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');
+/** Cordis loader schema. Runtime defaults are resolved in {@link apply}. */
+export const Config = z.object({
+    projectRoot: z.string(),
+    pythonExecutable: z.string(),
+    runtimeRoot: z.string(),
+    uvExecutable: z.string(),
+    installTimeoutMs: z.number().default(DEFAULT_SHARED_RUNTIME_INSTALL_TIMEOUT_MS),
+});
+function configuredProjectRoot(config, agent) {
+    return (config.projectRoot ??
+        process.env.DSH_DATA_ANALYSIS_PROJECT_ROOT ??
+        agent.session.header.cwd ??
+        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 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 runtime = await ensureSharedMarivoRuntime({
+        ...(pythonExecutable === undefined ? {} : { pythonExecutable }),
+        ...(runtimeRoot === undefined ? {} : { runtimeRoot }),
+        ...(uvExecutable === undefined ? {} : { uvExecutable }),
+        ...(config.installTimeoutMs === undefined ? {} : { installTimeoutMs: config.installTimeoutMs }),
+    });
+    const disposeRuntimeShellEnvironment = registerMarivoRuntimeShellEnvironment(ctx, runtime.pythonExecutable);
+    const manager = new MarivoWorkspaceEnvironmentManager(runtime);
+    let disposePlugin;
+    try {
+        installSkillFilesystem(ctx, {
+            providerName: 'dsh-data-analysis-marivo',
+            includeDefaultRoots: false,
+            customSkillDirs: [runtime.skillsRoot, integrationSkillsRoot],
+            watch: false,
+        });
+        const helpBridge = new MarivoHelpBridge(createSharedMarivoRuntimeRunner(runtime));
+        disposePlugin = installMarivoPlugin(ctx, (agent) => manager.resolve(configuredProjectRoot(config, agent)), { helpBridgeSource: helpBridge });
+    }
+    catch (error) {
+        manager.dispose();
+        disposeRuntimeShellEnvironment();
+        throw error;
+    }
+    return () => {
+        disposePlugin();
+        manager.dispose();
+        disposeRuntimeShellEnvironment();
+    };
+}

package/lib/types/bridges.d.ts

@@ -0,0 +1,11 @@
+import { MarivoDatasourceBridge } from './datasource/bridge.ts';
+import { MarivoHelpBridge } from './disclosure/bridge.ts';
+import type { MarivoEnvironment } from './environment/binding.ts';
+import { MarivoEvidenceBridge } from './evidence/bridge.ts';
+export interface MarivoBridgeSet {
+    readonly help: MarivoHelpBridge;
+    readonly datasource: MarivoDatasourceBridge;
+    readonly evidence: MarivoEvidenceBridge;
+}
+/** Compose domain adapters without adding domain methods back to the Environment. */
+export declare function createMarivoBridgeSet(environment: MarivoEnvironment): MarivoBridgeSet;

package/lib/types/client.d.ts

@@ -0,0 +1,125 @@
+import type { Context } from '@deepseek-ai/cordis';
+export declare const MARIVO_CREDENTIAL_STORAGE_PREFIX = "DSH_DATA_ANALYSIS_CREDENTIAL_";
+declare const EVIDENCE_SOURCES_META_KIND = "marivo-evidence-sources";
+declare const EVIDENCE_SOURCES_META_VERSION = 2;
+/** Browser-side copy of the Host mapping; contract tests keep both implementations identical. */
+export declare function marivoCredentialStorageRef(ref: string): string;
+export interface MarivoEvidenceSource {
+    status: 'available' | 'missing' | 'unsupported';
+    title: string;
+    locator: string;
+    excerpt: string | null;
+    truncated: boolean;
+    environmentFingerprint: string;
+    sessionId: string;
+    findingId: string;
+    findingType: string | null;
+    epistemicKind: string | null;
+    artifactRef: string;
+    canonicalItemKey: string | null;
+    committedAt: string | null;
+    sourceRefs: string[];
+    revalidation: {
+        status: string;
+        semanticStatus: string | null;
+        evidenceStatus: string | null;
+        dependencyStatus: string | null;
+    } | null;
+}
+export interface MarivoEvidenceSourcesMeta {
+    readonly kind: typeof EVIDENCE_SOURCES_META_KIND;
+    readonly version: typeof EVIDENCE_SOURCES_META_VERSION;
+    readonly dshSessionId: string;
+    readonly sources: readonly MarivoEvidenceSource[];
+}
+export interface MarivoEvidenceSourcesTurnDelivery {
+    readonly seq: number;
+    readonly sources: readonly MarivoEvidenceSource[];
+}
+export interface MarivoEvidenceSourcesTurnData {
+    readonly deliveries: readonly MarivoEvidenceSourcesTurnDelivery[];
+}
+interface MarivoEvidenceSourcesTurnState {
+    readonly turn: number;
+    readonly calls: ReadonlyMap<string, string>;
+    readonly deliveries: readonly MarivoEvidenceSourcesTurnDelivery[];
+}
+export interface MarivoEvidenceArtifactGroup {
+    readonly key: string;
+    readonly environmentFingerprint: string;
+    readonly sessionId: string;
+    readonly artifactRef: string;
+    readonly sources: readonly MarivoEvidenceSource[];
+}
+declare module '@deepseek-ai/dsh-client-runtime/client' {
+    interface ConversationTurnDataMap {
+        /** Explicitly requested Marivo Evidence sources collected from this exact Turn. */
+        'marivo-evidence-sources-delivery': MarivoEvidenceSourcesTurnData;
+    }
+}
+/** Parse the closed per-call source attachment persisted in Tool result metadata. */
+export declare function parseEvidenceSourcesMeta(value: unknown): MarivoEvidenceSourcesMeta | null;
+/** Decode the Code Mode-only source attachment from a durable sub-dispatch result. */
+export declare function parseEvidenceSourcesDurableContent(value: unknown): {
+    readonly turn: number;
+    readonly meta: MarivoEvidenceSourcesMeta;
+} | null;
+/** Recover one successful native or nested source attachment. */
+export declare function evidenceSourcesDeliveryFromEvent(event: any, calls?: ReadonlyMap<string, string>): MarivoEvidenceSourcesTurnDelivery | null;
+/** Aggregate explicit source attachments under one Harness-owned Turn key. */
+export declare const marivoEvidenceSourcesDeliveryDefinition: {
+    kind: string;
+    match(event: any): {
+        id: string;
+        role: string;
+    } | null;
+    start(_context: any, match: any): MarivoEvidenceSourcesTurnState;
+    update(context: any, match: any): MarivoEvidenceSourcesTurnState;
+    buildLocationData(context: any, scope: string): {
+        kind: string;
+        turn: any;
+        key: string;
+        value: {
+            deliveries: any;
+        };
+    } | null;
+};
+/** Successful sources completed before this exact closing Assistant message. */
+export declare function evidenceSourcesForClosing(owner: any): readonly MarivoEvidenceSource[];
+export declare function selectMarivoEvidenceSources(owner: any): readonly MarivoEvidenceSource[] | null;
+/** Group source presentation only; this does not infer Evidence equivalence or compatibility. */
+export declare function groupMarivoEvidenceSources(sources: readonly MarivoEvidenceSource[]): readonly MarivoEvidenceArtifactGroup[];
+export interface NeedsCredentialsResult {
+    status: 'needs-credentials';
+    name: string;
+    refs: string[];
+}
+export declare function parseNeedsCredentials(text: string): NeedsCredentialsResult | null;
+export declare function shouldAutoOpen(sessionId: string, callId: string, result: NeedsCredentialsResult | null): boolean;
+export declare function blankCredentialValues(refs: readonly string[]): Record<string, string>;
+export declare class CredentialDialogController {
+    readonly api: any;
+    constructor(api: any);
+    describe(refs: readonly string[]): Promise<Record<string, {
+        configured: boolean;
+    }>>;
+    inspect(refs: readonly string[]): Promise<{
+        configured: Record<string, boolean>;
+        missing: string[];
+        shouldOpen: boolean;
+    }>;
+    save(values: Readonly<Record<string, string>>): Promise<{
+        ok: boolean;
+        saved: string[];
+        errors: Record<string, string>;
+    }>;
+}
+export declare function MarivoDatasourceTestToolView(props: any): import("react").JSX.Element;
+export declare function MarivoDatasourceAccessToolView(props: any): import("react").JSX.Element;
+export declare function MarivoEvidenceSourcesPanel({ matched: sources, t, }: {
+    matched: readonly MarivoEvidenceSource[];
+    t: (key: string, values?: Record<string, string>) => string;
+}): import("react").JSX.Element;
+export declare const inject: string[];
+export declare function apply(ctx: Context): void;
+export {};

package/lib/types/compatibility.d.ts

@@ -0,0 +1,29 @@
+export declare const COMPATIBILITY_SCHEMA: "dsh-data-analysis-compatibility/v2";
+export interface DshDataAnalysisCompatibility {
+    readonly schema: typeof COMPATIBILITY_SCHEMA;
+    readonly dsh: {
+        readonly distribution: '@deepseek-ai/dsh';
+        readonly peerRange: string;
+    };
+    readonly marivo: {
+        readonly version: string;
+        readonly packageSpec: string;
+    };
+    readonly contracts: {
+        readonly runtimeInstallation: 'dsh-data-analysis-runtime/v2';
+        readonly subprocessPolicy: 'direct-argv-inherited-env-snapshot-overlay-v2';
+    };
+}
+/** The package semver and the compatibility contract shipped in this exact installation. */
+export declare const PLUGIN_VERSION: string;
+export declare const DSH_DATA_ANALYSIS_COMPATIBILITY: DshDataAnalysisCompatibility;
+/** Every DSH peer is required and must use this one verified release. */
+export declare const DSH_PEER_RANGE: string;
+export declare const DSH_DISTRIBUTION: "@deepseek-ai/dsh";
+export declare const DSH_PEER_DEPENDENCIES: Readonly<{
+    [k: string]: string;
+}>;
+export declare const MARIVO_VERSION: string;
+export declare const MARIVO_PACKAGE_SPEC: string;
+export declare const RUNTIME_INSTALLATION_VERSION: "dsh-data-analysis-runtime/v2";
+export declare const SUBPROCESS_POLICY_VERSION: "direct-argv-inherited-env-snapshot-overlay-v2";

package/lib/types/datasource/access.d.ts

@@ -0,0 +1,27 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { CredentialProvider } from '@deepseek-ai/dsh-credentials';
+import type { JsonValue } from '@deepseek-ai/dsh-session';
+import { type ToolDefinition } from '@deepseek-ai/dsh-tools';
+import { type MarivoDatasourceBridgePort, type MarivoDatasourceBridgeSource } from './bridge.ts';
+import type { MarivoShellLeaseReceipt } from './shell-env.ts';
+export declare const MARIVO_DATASOURCE_ACCESS_TOOL_NAME = "marivo_datasource_access";
+interface JsonObject {
+    [key: string]: JsonValue;
+}
+export type MarivoDatasourceAccessValue = ({
+    status: 'needs-credentials';
+    name: string;
+    refs: string[];
+} & JsonObject) | ({
+    status: 'ok';
+    name: string;
+    shell_lease: MarivoShellLeaseReceipt;
+} & JsonObject);
+export interface MarivoDatasourceAccessOptions {
+    revokeShellLease(bridge: MarivoDatasourceBridgePort, name: string): void;
+    issueShellLease(bridge: MarivoDatasourceBridgePort, name: string, refs: readonly string[]): MarivoShellLeaseReceipt;
+}
+/** Build the scoped datasource access Tool without performing a connection test. */
+export declare function createMarivoDatasourceAccessTool(bridgeSource: MarivoDatasourceBridgeSource, credentials: Pick<CredentialProvider, 'resolve'>, options: MarivoDatasourceAccessOptions): ToolDefinition;
+export declare function registerMarivoDatasourceAccessTool(ctx: Context, bridgeSource: MarivoDatasourceBridgeSource, credentials: Pick<CredentialProvider, 'resolve'>, options: MarivoDatasourceAccessOptions): () => void;
+export {};