@chengxianglibra/dsh-data-analysis 0.1.2 → 0.2.0

package/lib/plugin.js

@@ -1,28 +1,38 @@
+import { CredentialChangesService } from "./datasource/changes.js";
+import { credentialChangesHost } from "./datasource/changes-contract.js";
+import { finishCleanup } from "./lifecycle.js";
+import { createMarivoAgentInstallation } from "./plugin-agents.js";
+import { registerPublishingCredentials } from "./report-publishing/adapters.js";
+import { resolvePublishingConfig } from "./report-publishing/config.js";
+import { ReportPublishingService } from "./report-publishing/service.js";
+import { resolvePresentationWorkspace } from "./workspace-identity.js";
+export { installMarivoPlugin } from "./plugin-agents.js";
+export { resolvePresentationWorkspace } from "./workspace-identity.js";
+import { referenceEnvironmentResolver } from "./semantic-reference/environment.js";
 /** Cordis lifecycle adapter for the Web-profile shared Marivo Runtime. */
 import process from 'node:process';
 import { fileURLToPath } from 'node:url';
 import { apply as installSkillFilesystem } from '@deepseek-ai/dsh-skill-filesystem';
 import { WorkspaceId } from '@deepseek-ai/dsh-workspace';
 import z from '@deepseek-ai/schemastery';
-import { createMarivoBridgeSet } from "./bridges.js";
 import { MarivoDatasourceBridge } from "./datasource/bridge.js";
-import { registerMarivoDatasourceTestTool } from "./datasource/index.js";
-import { registerMarivoPythonTool } from "./datasource/python.js";
+import { DEFAULT_PYTHON_MAX_TIMEOUT_MS, DEFAULT_PYTHON_TIMEOUT_MS, resolvePythonOptions, } from "./datasource/python-options.js";
 import { registerCredentialRpc } from "./datasource/rpc.js";
 import { MarivoCredentialService } from "./datasource/service.js";
 import { registerMarivoRuntimeShellEnvironment } from "./datasource/shell-env.js";
 import { MarivoHelpBridge } from "./disclosure/bridge.js";
-import { installMarivoDisclosure, } from "./disclosure/index.js";
-import { createSharedMarivoRuntimeRunner, DEFAULT_SHARED_RUNTIME_INSTALL_TIMEOUT_MS, ensureSharedMarivoRuntime, MarivoEnvironment, MarivoWorkspaceEnvironmentManager, resolveMarivoEnvironmentSource, } from "./environment/index.js";
-import { installMarivoPresentationCodeDelivery, MarivoPresentationFileService, registerMarivoPresentationRpc, registerMarivoPresentTool, } from "./presentation/index.js";
+import { createSharedMarivoRuntimeRunner, DEFAULT_SHARED_RUNTIME_INSTALL_TIMEOUT_MS, ensureSharedMarivoRuntime, MarivoWorkspaceEnvironmentManager, } from "./environment/index.js";
+import { MarivoPresentationFileService, registerMarivoPresentationRpc, } from "./presentation/index.js";
 import { browserFailure, SemanticBrowserService } from "./semantic-browser/service.js";
 import { registerSemanticReferenceRpc, SemanticReferenceService, SemanticReferenceUsage, } from "./semantic-reference/index.js";
+export { MARIVO_DATASOURCE_CREDENTIAL_PROMPT } from "./disclosure/execution-guidance.js";
 /** Cordis plugin name used by loader diagnostics and lifecycle logs. */
 export const name = 'dsh-data-analysis';
 /** Services that must exist before the plugin binds and watches Agent scopes. */
 export const inject = [
     'agents',
     'connection',
+    'typert',
     'storageDomain',
     'workspaceRegistry',
     'credentials',
@@ -31,28 +41,18 @@ export const inject = [
     'systemPrompt',
     'tools',
 ];
-export const MARIVO_DATASOURCE_CREDENTIAL_PROMPT = [
-    '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 datasource names this execution may access, including datasources without passwords. Use datasources: [] only when no datasource will be 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. Create or resume Session/reader objects 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. Continue the same persistent 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');
-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(' ');
-const PRESENTATION_PROMPT = 'Answer ordinary factual questions in text. For charts, tables, reports, dashboards or a readable source presentation, load the dsh-data-analysis-presentation skill and deliver through marivo_present. Existing data needs no prior Marivo skill activation; load the Runtime skills and live Help when new analysis or semantic authoring is needed.';
 /** Cordis loader schema. Runtime defaults are resolved in {@link apply}. */
 export const Config = z.object({
+    // Defer validation to authoring so loader errors cannot echo configured values.
+    datasourceDefaults: z.any(),
+    reportPublishing: z.any(),
+    pythonTimeoutMs: z.number().default(DEFAULT_PYTHON_TIMEOUT_MS),
+    pythonMaxTimeoutMs: z.number().default(DEFAULT_PYTHON_MAX_TIMEOUT_MS),
     credentialInteraction: z.union(['web', 'none']).default('web'),
     projectRoot: z.string(),
     pythonExecutable: z.string(),
     runtimeRoot: z.string(),
-    uvExecutable: z.string(),
+    bootstrapPythonExecutable: z.string(),
     installTimeoutMs: z.number().default(DEFAULT_SHARED_RUNTIME_INSTALL_TIMEOUT_MS),
 });
 function configuredProjectRoot(config, agent) {
@@ -62,124 +62,17 @@ function configuredProjectRoot(config, agent) {
         process.env.DSH_CWD ??
         process.cwd());
 }
-/**
- * Install one already-bound environment into every live or subsequently published Agent scope.
- * Installation is transactional for existing Agents and is disposed with the Cordis plugin.
- */
-export function installMarivoPlugin(ctx, environmentOrResolver, options = {}) {
-    const installed = new Map();
-    const credentials = options.credentials ?? ctx.credentials;
-    if (credentials === undefined) {
-        throw new Error('dsh-data-analysis requires the DSH credentials service');
-    }
-    const credentialService = options.credentialService ??
-        new MarivoCredentialService(credentials, options.credentialInteraction);
-    const stopCredentialUpdates = ctx.on('credentials/reference-updated', (ref) => credentialService.invalidateStorageRef(ref));
-    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 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);
-        controller.addDisposer(registerMarivoDatasourceTestTool(agent.ctx, datasourceSource, credentialService));
-        controller.addDisposer(registerMarivoPythonTool(agent.ctx, datasourceSource, credentialService));
-        controller.addDisposer(() => credentialService.disposeAgent(agent));
-        controller.addDisposer(registerMarivoPresentTool(agent.ctx, presentationSource, agent.session));
-        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);
-    };
-    try {
-        for (const agent of ctx.agents.list())
-            install(agent);
-    }
-    catch (error) {
-        for (const controller of installed.values())
-            controller.dispose();
-        stopCredentialUpdates();
-        void credentialService.close();
-        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();
-        stopCredentialUpdates();
-        for (const controller of installed.values())
-            controller.dispose();
-        installed.clear();
-        void credentialService.close();
-    };
-}
-/** Resolve only Harness-owned, header-validated Workspace membership; never infer it from a path. */
-export function resolvePresentationWorkspace(ctx, sessionId) {
-    const matches = ctx.workspaceRegistry
-        .list()
-        .filter((workspace) => workspace.sessionIds.some((id) => String(id) === sessionId));
-    if (matches.length !== 1)
-        throw new Error('Presentation requires one current Session Workspace');
-    return { id: String(matches[0].id), path: matches[0].path };
-}
 /** Ensure the shared Runtime once, mount its skills, then bind each Workspace lazily. */
 export async function apply(ctx, config = {}) {
+    const publishingConfig = resolvePublishingConfig(config.reportPublishing);
+    const pythonOptions = resolvePythonOptions(config);
     const pythonExecutable = config.pythonExecutable ?? process.env.DSH_DATA_ANALYSIS_PYTHON;
     const runtimeRoot = config.runtimeRoot ?? process.env.DSH_DATA_ANALYSIS_RUNTIME_ROOT;
-    const uvExecutable = config.uvExecutable ?? process.env.DSH_DATA_ANALYSIS_UV;
+    const bootstrapPythonExecutable = config.bootstrapPythonExecutable ?? process.env.DSH_DATA_ANALYSIS_BOOTSTRAP_PYTHON;
     const runtime = await ensureSharedMarivoRuntime({
         ...(pythonExecutable === undefined ? {} : { pythonExecutable }),
         ...(runtimeRoot === undefined ? {} : { runtimeRoot }),
-        ...(uvExecutable === undefined ? {} : { uvExecutable }),
+        ...(bootstrapPythonExecutable === undefined ? {} : { bootstrapPythonExecutable }),
         ...(config.installTimeoutMs === undefined ? {} : { installTimeoutMs: config.installTimeoutMs }),
     });
     const disposeRuntimeShellEnvironment = registerMarivoRuntimeShellEnvironment(ctx, runtime.pythonExecutable);
@@ -195,17 +88,51 @@ export async function apply(ctx, config = {}) {
         return environment;
     };
     const credentialService = new MarivoCredentialService(ctx.credentials, config.credentialInteraction);
+    const credentialNotifications = new CredentialChangesService(ctx, credentialService);
+    let unregisterChanges;
+    const disposeChanges = async () => {
+        await credentialNotifications.close();
+        await unregisterChanges?.();
+    };
+    let disposePublishing;
     let disposeCredentials;
     let disposeReferences;
     let disposePresentation;
     let referenceService;
-    let disposePlugin;
+    let agentInstallation;
+    let closing;
     const browserService = new SemanticBrowserService({
         getWorkspace: (id) => ctx.workspaceRegistry.get(WorkspaceId(id)),
         projectRoot: (workspace) => config.projectRoot ?? process.env.DSH_DATA_ANALYSIS_PROJECT_ROOT ?? workspace.path,
         resolve: (root) => manager.resolve(root),
     });
+    const close = () => {
+        if (closing)
+            return closing;
+        closing = finishCleanup([
+            () => agentInstallation?.close(),
+            () => disposeCredentials?.(),
+            disposeChanges,
+            () => disposePublishing?.(),
+            () => disposePresentation?.(),
+            () => disposeReferences?.(),
+            () => browserService.close(),
+            () => credentialService.close(),
+            () => referenceService?.close(),
+        ]).then(() => finishCleanup([() => manager.close(), disposeRuntimeShellEnvironment]), async (error) => {
+            await finishCleanup([
+                () => manager.close(),
+                disposeRuntimeShellEnvironment,
+                () => {
+                    throw error;
+                },
+            ]);
+        });
+        void closing.catch(() => { });
+        return closing;
+    };
     try {
+        unregisterChanges = ctx.typert.register(credentialChangesHost);
         installSkillFilesystem(ctx, {
             providerName: 'dsh-data-analysis-marivo',
             includeDefaultRoots: false,
@@ -219,10 +146,25 @@ export async function apply(ctx, config = {}) {
             watch: false,
         });
         const helpBridge = new MarivoHelpBridge(createSharedMarivoRuntimeRunner(runtime));
-        disposePlugin = installMarivoPlugin(ctx, resolveEnvironment, {
+        const presentationFiles = new MarivoPresentationFileService(async (sessionId) => resolvePresentationWorkspace(ctx, sessionId), async (id) => {
+            const workspace = ctx.workspaceRegistry.get(WorkspaceId(id));
+            return workspace ? { id: String(workspace.id), path: workspace.path } : undefined;
+        });
+        disposePresentation = registerMarivoPresentationRpc(ctx.connection, presentationFiles);
+        const reportPublishing = new ReportPublishingService(publishingConfig, ctx.credentials, presentationFiles, undefined, (id) => {
+            const workspace = ctx.workspaceRegistry.get(WorkspaceId(id));
+            if (!workspace)
+                throw new Error('workspace-unavailable');
+            return workspace.title;
+        });
+        disposePublishing = registerPublishingCredentials(ctx.connection, reportPublishing, (id) => Boolean(ctx.workspaceRegistry.get(WorkspaceId(id))));
+        agentInstallation = createMarivoAgentInstallation(ctx, resolveEnvironment, {
+            ...pythonOptions,
             helpBridgeSource: helpBridge,
+            ...(publishingConfig ? { reportPublishing } : {}),
             credentialService,
         });
+        agentInstallation.install();
         disposeCredentials = registerCredentialRpc(ctx.connection, credentialService, async (id) => {
             const workspace = ctx.workspaceRegistry.get(WorkspaceId(id));
             if (!workspace)
@@ -232,11 +174,11 @@ export async function apply(ctx, config = {}) {
             const current = ctx.workspaceRegistry.get(WorkspaceId(id));
             if (!current ||
                 current.path !== workspace.path ||
-                (config.projectRoot ?? process.env.DSH_DATA_ANALYSIS_PROJECT_ROOT ?? current.path) !== root)
+                (config.projectRoot ?? process.env.DSH_DATA_ANALYSIS_PROJECT_ROOT ?? current.path) !==
+                    root)
                 throw new Error('Workspace changed');
             return new MarivoDatasourceBridge(environment);
-        });
-        disposePresentation = registerMarivoPresentationRpc(ctx.connection, new MarivoPresentationFileService(async (sessionId) => resolvePresentationWorkspace(ctx, sessionId)));
+        }, config.datasourceDefaults);
         let lastDiagnostic = -Infinity;
         const usage = new SemanticReferenceUsage(ctx.storageDomain, Date.now, () => {
             if (Date.now() - lastDiagnostic >= 30_000) {
@@ -244,22 +186,13 @@ export async function apply(ctx, config = {}) {
                 console.warn('dsh-data-analysis semantic-reference usage unavailable');
             }
         });
-        referenceService = new SemanticReferenceService(async (sessionId, purpose) => {
-            const agent = ctx.agents.list().find((item) => item.session.id === sessionId);
-            if (!agent)
-                throw new Error('unknown-session');
-            const bound = bindings.get(agent);
-            if (purpose === 'reference' &&
-                (!bound || bound.root !== configuredProjectRoot(config, agent)))
-                throw new Error('environment-unbound');
-            const environment = await (purpose === 'reference'
-                ? bound.environment
-                : resolveEnvironment(agent));
-            if (!ctx.agents.list().includes(agent) ||
-                bindings.get(agent)?.root !== configuredProjectRoot(config, agent))
-                throw new Error('environment-changed');
-            return environment;
-        }, usage);
+        referenceService = new SemanticReferenceService(referenceEnvironmentResolver({
+            agent: (sessionId) => ctx.agents.list().find((item) => item.session.id === sessionId),
+            binding: (agent) => bindings.get(agent),
+            projectRoot: (agent) => configuredProjectRoot(config, agent),
+            resolve: resolveEnvironment,
+            workspace: (sessionId) => resolvePresentationWorkspace(ctx, sessionId),
+        }), usage);
         disposeReferences = registerSemanticReferenceRpc(ctx.connection, referenceService, async (_endpoint, payload, signal) => {
             try {
                 return { ok: true, value: await browserService.read(payload, signal) };
@@ -273,24 +206,13 @@ export async function apply(ctx, config = {}) {
         });
     }
     catch (error) {
-        browserService.dispose();
-        await disposePresentation?.();
-        await disposeCredentials?.();
-        await credentialService.close();
-        await referenceService?.close();
-        disposePlugin?.();
-        manager.dispose();
-        disposeRuntimeShellEnvironment();
+        try {
+            await close();
+        }
+        catch (cleanupError) {
+            throw new AggregateError([error, cleanupError], 'Marivo installation and cleanup failed');
+        }
         throw error;
     }
-    return async () => {
-        browserService.dispose();
-        await disposePresentation?.();
-        await disposeCredentials?.();
-        await credentialService.close();
-        await disposeReferences?.();
-        disposePlugin?.();
-        manager.dispose();
-        disposeRuntimeShellEnvironment();
-    };
+    return close;
 }

package/lib/presentation/asset.js

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