@chengxianglibra/dsh-data-analysis 0.1.1 → 0.1.2

package/lib/plugin.js

@@ -1,44 +1,54 @@
 /** 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 { WorkspaceId } from '@deepseek-ai/dsh-workspace';
 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 { MarivoDatasourceBridge } from "./datasource/bridge.js";
+import { registerMarivoDatasourceTestTool } from "./datasource/index.js";
+import { registerMarivoPythonTool } from "./datasource/python.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 { installMarivoEvidenceSourcesCodeDelivery, registerMarivoEvidenceSourcesTool, } from "./evidence/index.js";
+import { installMarivoPresentationCodeDelivery, MarivoPresentationFileService, registerMarivoPresentationRpc, registerMarivoPresentTool, } from "./presentation/index.js";
+import { browserFailure, SemanticBrowserService } from "./semantic-browser/service.js";
+import { registerSemanticReferenceRpc, SemanticReferenceService, SemanticReferenceUsage, } from "./semantic-reference/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 inject = [
+    'agents',
+    'connection',
+    'storageDomain',
+    'workspaceRegistry',
+    '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.',
+    '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(' ');
-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');
+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({
+    credentialInteraction: z.union(['web', 'none']).default('web'),
     projectRoot: z.string(),
     pythonExecutable: z.string(),
     runtimeRoot: z.string(),
@@ -62,7 +72,9 @@ export function installMarivoPlugin(ctx, environmentOrResolver, options = {}) {
     if (credentials === undefined) {
         throw new Error('dsh-data-analysis requires the DSH credentials service');
     }
-    const shellCredentials = new MarivoShellCredentialLeases(ctx, credentials);
+    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))
@@ -81,34 +93,40 @@ export function installMarivoPlugin(ctx, environmentOrResolver, options = {}) {
         };
         const helpSource = options.helpBridgeSource ?? (async () => (await resolveBridgeSet()).help);
         const datasourceSource = async () => (await resolveBridgeSet()).datasource;
-        const evidenceSource = async () => (await resolveBridgeSet()).evidence;
+        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(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(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(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')
+            text: () => controller.activeSkills.some((skill) => ['marivo-analysis', 'marivo-semantic'].includes(skill))
                 ? 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 : '',
+            name: 'marivo:analysis-closeout',
+            order: 175,
+            text: () => controller.activeSkills.includes('marivo-analysis')
+                ? MARIVO_ANALYSIS_CLOSEOUT_PROMPT
+                : '',
         }));
         installed.set(agent, controller);
     };
@@ -119,7 +137,8 @@ export function installMarivoPlugin(ctx, environmentOrResolver, options = {}) {
     catch (error) {
         for (const controller of installed.values())
             controller.dispose();
-        shellCredentials.dispose();
+        stopCredentialUpdates();
+        void credentialService.close();
         throw error;
     }
     const stopCreated = ctx.on('agent/created', ({ agent }) => {
@@ -136,12 +155,22 @@ export function installMarivoPlugin(ctx, environmentOrResolver, options = {}) {
         active = false;
         stopCreated();
         stopDisposed();
+        stopCredentialUpdates();
         for (const controller of installed.values())
             controller.dispose();
         installed.clear();
-        shellCredentials.dispose();
+        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 pythonExecutable = config.pythonExecutable ?? process.env.DSH_DATA_ANALYSIS_PYTHON;
@@ -155,24 +184,112 @@ export async function apply(ctx, config = {}) {
     });
     const disposeRuntimeShellEnvironment = registerMarivoRuntimeShellEnvironment(ctx, runtime.pythonExecutable);
     const manager = new MarivoWorkspaceEnvironmentManager(runtime);
+    const bindings = new WeakMap();
+    const resolveEnvironment = (agent) => {
+        const root = configuredProjectRoot(config, agent);
+        const existing = bindings.get(agent);
+        if (existing?.root === root)
+            return existing.environment;
+        const environment = manager.resolve(root);
+        bindings.set(agent, { root, environment });
+        return environment;
+    };
+    const credentialService = new MarivoCredentialService(ctx.credentials, config.credentialInteraction);
+    let disposeCredentials;
+    let disposeReferences;
+    let disposePresentation;
+    let referenceService;
     let disposePlugin;
+    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),
+    });
     try {
         installSkillFilesystem(ctx, {
             providerName: 'dsh-data-analysis-marivo',
             includeDefaultRoots: false,
-            customSkillDirs: [runtime.skillsRoot, integrationSkillsRoot],
+            customSkillDirs: [runtime.skillsRoot],
+            watch: false,
+        });
+        installSkillFilesystem(ctx, {
+            providerName: 'dsh-data-analysis-presentation',
+            includeDefaultRoots: false,
+            customSkillDirs: [fileURLToPath(new URL('../skills/', import.meta.url))],
             watch: false,
         });
         const helpBridge = new MarivoHelpBridge(createSharedMarivoRuntimeRunner(runtime));
-        disposePlugin = installMarivoPlugin(ctx, (agent) => manager.resolve(configuredProjectRoot(config, agent)), { helpBridgeSource: helpBridge });
+        disposePlugin = installMarivoPlugin(ctx, resolveEnvironment, {
+            helpBridgeSource: helpBridge,
+            credentialService,
+        });
+        disposeCredentials = registerCredentialRpc(ctx.connection, credentialService, async (id) => {
+            const workspace = ctx.workspaceRegistry.get(WorkspaceId(id));
+            if (!workspace)
+                throw new Error('Workspace unavailable');
+            const root = config.projectRoot ?? process.env.DSH_DATA_ANALYSIS_PROJECT_ROOT ?? workspace.path;
+            const environment = await manager.resolve(root);
+            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)
+                throw new Error('Workspace changed');
+            return new MarivoDatasourceBridge(environment);
+        });
+        disposePresentation = registerMarivoPresentationRpc(ctx.connection, new MarivoPresentationFileService(async (sessionId) => resolvePresentationWorkspace(ctx, sessionId)));
+        let lastDiagnostic = -Infinity;
+        const usage = new SemanticReferenceUsage(ctx.storageDomain, Date.now, () => {
+            if (Date.now() - lastDiagnostic >= 30_000) {
+                lastDiagnostic = Date.now();
+                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);
+        disposeReferences = registerSemanticReferenceRpc(ctx.connection, referenceService, async (_endpoint, payload, signal) => {
+            try {
+                return { ok: true, value: await browserService.read(payload, signal) };
+            }
+            catch (error) {
+                return {
+                    ok: false,
+                    error: { code: 'internal', message: browserFailure(error), details: {} },
+                };
+            }
+        });
     }
     catch (error) {
+        browserService.dispose();
+        await disposePresentation?.();
+        await disposeCredentials?.();
+        await credentialService.close();
+        await referenceService?.close();
+        disposePlugin?.();
         manager.dispose();
         disposeRuntimeShellEnvironment();
         throw error;
     }
-    return () => {
-        disposePlugin();
+    return async () => {
+        browserService.dispose();
+        await disposePresentation?.();
+        await disposeCredentials?.();
+        await credentialService.close();
+        await disposeReferences?.();
+        disposePlugin?.();
         manager.dispose();
         disposeRuntimeShellEnvironment();
     };