@chengxianglibra/dsh-data-analysis 0.2.0 → 0.2.2

package/lib/datasource/changes-contract.js

@@ -18,14 +18,18 @@ const descriptor = {
             name: 'sessionId',
             wire: 'sessionId',
             source: 'json',
-            codec: { mode: 'strict', typeSymbol: `${owner}#CredentialSessionId`, schema: sessionId },
+            codec: {
+                mode: 'strict',
+                typeSymbol: `${owner}#CredentialSessionId`,
+                create: () => sessionId,
+            },
         },
     ],
     cancellation: { parameter: 'signal' },
     result: {
         mode: 'strict',
         typeSymbol: `${owner}#CredentialRevision`,
-        schema: credentialRevisionSchema,
+        create: () => credentialRevisionSchema,
     },
 };
 export const credentialChangesHost = {

package/lib/datasource/configure.js

@@ -5,7 +5,7 @@ export const MARIVO_DATASOURCE_CONFIGURE_TOOL_NAME = 'marivo_datasource_configur
 export function createMarivoDatasourceConfigureTool(source, service) {
     return defineTool({
         name: MARIVO_DATASOURCE_CONFIGURE_TOOL_NAME,
-        description: 'Ask the user to create/select or edit a datasource in the owning Web session right tab. Waits until the user saves and tests successfully, cancels, or hands off a failure. Never pass credentials or configuration values. After success, rediscover the datasource and verify the requested table before analysis.',
+        description: 'When a requested remote table has no usable configured datasource, use mode=create to let the user create/select one; repair connection configuration with mode=edit and its exact name. The user configures it in the owning Web session right tab; never write connection configuration on their behalf or pass credentials or configuration values. Waits for successful save and connection test, cancellation or failure. Only status=ok permits continuation: rediscover the datasource and verify the requested table and read access before analysis. Success already includes a connection test; do not repeat it unless configuration or credentials change, a connection fails, or the user requests one. Local files need no remote datasource setup.',
         parameters: {
             mode: {
                 type: 'string',

package/lib/datasource/python-options.js

@@ -1,5 +1,4 @@
 export const DEFAULT_PYTHON_TIMEOUT_MS = 120_000;
-export const DEFAULT_PYTHON_MAX_TIMEOUT_MS = 600_000;
 const MAX_TIMER_DELAY_MS = 2_147_483_647;
 /** Do not echo rejected inputs: tool arguments and configuration are not trusted diagnostics. */
 export function pythonTimeout(value, name) {
@@ -12,10 +11,5 @@ export function pythonTimeout(value, name) {
 }
 export function resolvePythonOptions(options) {
     const pythonTimeoutMs = pythonTimeout(options.pythonTimeoutMs === undefined ? DEFAULT_PYTHON_TIMEOUT_MS : options.pythonTimeoutMs, 'pythonTimeoutMs');
-    const pythonMaxTimeoutMs = pythonTimeout(options.pythonMaxTimeoutMs === undefined
-        ? DEFAULT_PYTHON_MAX_TIMEOUT_MS
-        : options.pythonMaxTimeoutMs, 'pythonMaxTimeoutMs');
-    if (pythonTimeoutMs > pythonMaxTimeoutMs)
-        throw new Error('pythonTimeoutMs must not exceed pythonMaxTimeoutMs');
-    return { pythonTimeoutMs, pythonMaxTimeoutMs };
+    return { pythonTimeoutMs };
 }

package/lib/datasource/python.js

@@ -4,7 +4,7 @@ import { defineTool } from '@deepseek-ai/dsh-tools';
 import { savePythonExecution } from "../python-execution.js";
 import { registerMarivoTool } from "../tool-lifecycle.js";
 import { resolveMarivoDatasourceBridge } from "./bridge.js";
-import { pythonTimeout, resolvePythonOptions } from "./python-options.js";
+import { pythonTimeout, resolvePythonOptions, } from "./python-options.js";
 import { PYTHON_LAUNCHER, PYTHON_WORKER } from "./resolver-program.js";
 import { CredentialServiceError, } from "./service.js";
 import { datasourceToolValue } from "./test.js";
@@ -33,10 +33,11 @@ function quote(value) {
         : `'${value.replaceAll("'", "'\\''")}'`;
 }
 export function registerMarivoPythonTool(ctx, source, service, options = {}) {
-    const limits = resolvePythonOptions(options);
+    const readOptions = typeof options === 'function' ? options : () => options;
+    resolvePythonOptions(readOptions());
     return registerMarivoTool(ctx, defineTool({
         name: 'marivo_python',
-        description: 'Execute foreground Python in the bound Runtime and Workspace, including local pandas and native DuckDB file analysis. This call waits for missing credentials for every listed Marivo datasource before starting Python once; configured credentials do not trigger a connection test. When using Marivo Sessions or readers, create/resume them inside this execution and close Sessions in finally. No background execution or secret environment variables. Nonzero exits are reported without replay. Successful execution saves the exact submitted code and returns codeRef; explicitly associate it with presentation datasets through draft codeRefs. A codeCaptureError does not change the execution outcome and must not trigger replay. The execution summary reports adapter phase, outcome and effective Shell budget, not query progress or saved Artifacts. Credential waiting precedes the Shell budget; outer Code Mode deadlines and cancellation still apply. Timeout does not confirm remote query cancellation or absence of saved results.',
+        description: 'Execute foreground Python in the bound Runtime and Workspace, including local pandas and native DuckDB file analysis. Waits for missing credentials for every declared datasource before starting code once; no automatic connection test or execution replay. No background execution or secret environment variables. Success returns codeRef for the submitted code; associate it with presentation datasets through draft codeRefs when needed. codeCaptureError leaves the execution outcome unchanged; do not rerun to recover the code record. Inspect execution phase, outcome and nextAction after failure; timeout does not prove remote query cancellation or absence of saved results.',
         parameters: {
             code: {
                 type: 'string',
@@ -51,7 +52,7 @@ export function registerMarivoPythonTool(ctx, source, service, options = {}) {
             },
             timeoutMs: {
                 type: 'number',
-                description: `Optional foreground Shell timeout in milliseconds, a positive integer at most 2147483647. Defaults to ${limits.pythonTimeoutMs}; capped at ${limits.pythonMaxTimeoutMs} and then by Harness Shell. Outer Code Mode deadlines remain independent.`,
+                description: 'Optional foreground Shell timeout in milliseconds, a positive integer at most 2147483647. Defaults to the current plugin pythonTimeoutMs setting. Credential waiting precedes this budget; Harness Shell limits, outer Code Mode deadlines and cancellation remain independent.',
             },
         },
         output: {
@@ -83,7 +84,9 @@ export function registerMarivoPythonTool(ctx, source, service, options = {}) {
             };
             try {
                 try {
-                    requestedTimeoutMs = pythonTimeout(args.timeoutMs === undefined ? limits.pythonTimeoutMs : args.timeoutMs, 'timeoutMs');
+                    requestedTimeoutMs = pythonTimeout(args.timeoutMs === undefined
+                        ? resolvePythonOptions(readOptions()).pythonTimeoutMs
+                        : args.timeoutMs, 'timeoutMs');
                 }
                 catch {
                     rejectInput('timeoutMs must be a positive integer no greater than 2147483647');
@@ -112,7 +115,8 @@ export function registerMarivoPythonTool(ctx, source, service, options = {}) {
                 const spec = shell.resolve({
                     command: `${process.platform === 'win32' ? '& ' : ''}${quote(binding.pythonExecutable)} -c ${quote(PYTHON_LAUNCHER)}`,
                     workdir: binding.projectRoot,
-                    timeoutMs: Math.min(requestedTimeoutMs, limits.pythonMaxTimeoutMs),
+                    timeoutMs: requestedTimeoutMs,
+                    onExpiry: 'kill',
                     signal: prepared.signal,
                     stdin: JSON.stringify({
                         identity: binding,
@@ -132,7 +136,8 @@ export function registerMarivoPythonTool(ctx, source, service, options = {}) {
                 const startedAt = new Date().toISOString();
                 phase = 'executing';
                 shellStartedAt = performance.now();
-                const result = await service.track(shell.run(spec));
+                const execution = await service.track(shell.execute(spec));
+                const result = await service.track(execution.result());
                 executionElapsedMs = performance.now() - shellStartedAt;
                 const finishedAt = new Date().toISOString();
                 const credentialValues = prepared.values;

package/lib/datasource/test.js

@@ -5,7 +5,7 @@ export const MARIVO_DATASOURCE_TEST_TOOL_NAME = 'marivo_datasource_test';
 export function createMarivoDatasourceTestTool(source, service) {
     return defineTool({
         name: MARIVO_DATASOURCE_TEST_TOOL_NAME,
-        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.',
+        description: 'Test a Marivo datasource through Host credentials after datasource changes, credential rotation, connection failures, or explicit user requests. Normal analysis with configured credentials needs no preliminary test; successful marivo_datasource_configure already tested that configuration. Missing credentials wait for the Web form only while this call remains alive; configured connection failures return directly. Only status=ok proves this connection test succeeded; verify the requested table and read access separately.',
         parameters: {
             name: { type: 'string', required: true, description: 'Configured datasource name.' },
         },

package/lib/disclosure/execution-guidance.js

@@ -1,14 +1,11 @@
 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.',
+    'These are Host execution and credential rules; Marivo API and semantic contracts come from the bound Runtime Skill and live Help.',
     'DSH Credentials owns Marivo datasource secrets. Never request values in chat, read credential files or ~/.marivo/secrets.toml, or write secrets to scripts, arguments, environment variables, reports or logs.',
-    'Use marivo_datasource_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()',
+    'Use marivo_datasource_configure for missing datasource setup or connection configuration repair; the user owns configuration in the Web form. Use marivo_datasource_test for connection checks under its tool contract. Configured credentials alone do not prove connection or read access.',
+    'Execute analysis, metadata inspection and semantic data reads through marivo_python in the bound Runtime and Workspace. Declare all exact Marivo datasource names this execution may access, including datasources without passwords; use datasources: [] for local pandas or native DuckDB without Marivo datasource access.',
+    'Each marivo_python call is a separate process. Create/resume Marivo Sessions inside the call, close them in finally, and retain the persisted Session identity when continuing the same analysis. Closing process resources does not delete durable Artifacts. Do not replace the credential resolver, read SecretValue contents, or bypass Host scope with environment/cache configuration.',
+    'Preserve real failures. After uncertain execution, inspect existing effects before retrying; never automatically replay a script with possible side effects.',
 ].join('\n');
 export const MARIVO_ANALYSIS_CLOSEOUT_PROMPT = [
     'Analysis semantics and execution contracts come from the activated Runtime Skill and current Help.',

package/lib/plugin-agents.js

@@ -12,7 +12,7 @@ import { registerMarivoExportHtmlTool } from "./presentation/export-html.js";
 import { installMarivoPresentationCodeDelivery, registerMarivoPresentTool, } from "./presentation/index.js";
 import { registerReportPublishTool } from "./report-publishing/adapters.js";
 import { resolvePresentationWorkspace } from "./workspace-identity.js";
-const PRESENTATION_PROMPT = 'Answer ordinary factual questions in text. For analysis of provided data files, load dsh-data-analysis-files; local pandas or native DuckDB work needs no Marivo semantic setup. For charts, tables, reports, dashboards or a readable source presentation, load dsh-data-analysis-presentation and deliver through marivo_present. When the user requests an offline HTML file, export the saved report with marivo_export_html, then call native present with the returned path before the final response. Use the Runtime skills and live Help when the task needs Marivo analysis or semantic authoring; existing data can be presented directly.';
+const PRESENTATION_PROMPT = 'Match delivery to the user request. Ordinary answers and simple comparison tables can stay in chat. For analysis of attachments or Workspace data files, including short chat comparisons, first load dsh-data-analysis-files; requested CSV, JSON or PNG files use native present. For interactive charts or tables, saved reports, dashboards, report updates or visual source panels, load dsh-data-analysis-presentation and use marivo_present; that Skill also covers report export and publication when requested. Existing results can be presented directly. Use the Runtime skills and live Help for Marivo analysis or semantic authoring; local pandas or native DuckDB file analysis needs no Marivo semantic setup. When analysis reveals a reusable business definition or semantic gap, follow the relevant Skill to assess reuse or handoff to marivo-semantic, limited to what the current task needs or the user has authorized; stop when that scope is answered or its blockers are explicit.';
 /**
  * Install one already-bound environment into every live or subsequently published Agent scope.
  * Installation is transactional for existing Agents and is disposed with the Cordis plugin.
@@ -87,7 +87,7 @@ export function createMarivoAgentInstallation(ctx, environmentOrResolver, option
             controller.addDisposer(installMarivoExecutionGuidance(agent, controller));
             controller.addDisposer(registerMarivoDatasourceTestTool(agent.ctx, datasourceSource, credentialService));
             controller.addDisposer(registerMarivoDatasourceConfigureTool(agent.ctx, datasourceSource, credentialService));
-            controller.addDisposer(registerMarivoPythonTool(agent.ctx, datasourceSource, credentialService, pythonOptions));
+            controller.addDisposer(registerMarivoPythonTool(agent.ctx, datasourceSource, credentialService, options.pythonOptionsSource ?? pythonOptions));
             controller.addDisposer(() => credentialService.disposeAgent(agent));
             controller.addDisposer(registerMarivoPresentTool(agent.ctx, presentationSource, agent.session));
             controller.addDisposer(registerMarivoExportHtmlTool(agent.ctx, () => resolvePresentationWorkspace(ctx, String(agent.session.id)), agent.session));

package/lib/plugin.js

@@ -5,6 +5,7 @@ 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 { currentPythonOptions, installPythonSettings, } from "./settings.js";
 import { resolvePresentationWorkspace } from "./workspace-identity.js";
 export { installMarivoPlugin } from "./plugin-agents.js";
 export { resolvePresentationWorkspace } from "./workspace-identity.js";
@@ -16,7 +17,7 @@ import { apply as installSkillFilesystem } from '@deepseek-ai/dsh-skill-filesyst
 import { WorkspaceId } from '@deepseek-ai/dsh-workspace';
 import z from '@deepseek-ai/schemastery';
 import { MarivoDatasourceBridge } from "./datasource/bridge.js";
-import { DEFAULT_PYTHON_MAX_TIMEOUT_MS, DEFAULT_PYTHON_TIMEOUT_MS, resolvePythonOptions, } from "./datasource/python-options.js";
+import { DEFAULT_PYTHON_TIMEOUT_MS } from "./datasource/python-options.js";
 import { registerCredentialRpc } from "./datasource/rpc.js";
 import { MarivoCredentialService } from "./datasource/service.js";
 import { registerMarivoRuntimeShellEnvironment } from "./datasource/shell-env.js";
@@ -46,8 +47,13 @@ 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),
+    pythonTimeoutMs: z
+        .number()
+        .min(1)
+        .max(2_147_483_647)
+        .step(1)
+        .default(DEFAULT_PYTHON_TIMEOUT_MS)
+        .volatile(),
     credentialInteraction: z.union(['web', 'none']).default('web'),
     projectRoot: z.string(),
     pythonExecutable: z.string(),
@@ -65,7 +71,7 @@ function configuredProjectRoot(config, agent) {
 /** 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 pythonOptions = currentPythonOptions(config);
     const pythonExecutable = config.pythonExecutable ?? process.env.DSH_DATA_ANALYSIS_PYTHON;
     const runtimeRoot = config.runtimeRoot ?? process.env.DSH_DATA_ANALYSIS_RUNTIME_ROOT;
     const bootstrapPythonExecutable = config.bootstrapPythonExecutable ?? process.env.DSH_DATA_ANALYSIS_BOOTSTRAP_PYTHON;
@@ -100,6 +106,7 @@ export async function apply(ctx, config = {}) {
     let disposePresentation;
     let referenceService;
     let agentInstallation;
+    let pythonSettings;
     let closing;
     const browserService = new SemanticBrowserService({
         getWorkspace: (id) => ctx.workspaceRegistry.get(WorkspaceId(id)),
@@ -111,6 +118,7 @@ export async function apply(ctx, config = {}) {
             return closing;
         closing = finishCleanup([
             () => agentInstallation?.close(),
+            () => pythonSettings?.dispose(),
             () => disposeCredentials?.(),
             disposeChanges,
             () => disposePublishing?.(),
@@ -132,6 +140,7 @@ export async function apply(ctx, config = {}) {
         return closing;
     };
     try {
+        pythonSettings = installPythonSettings(ctx, config);
         unregisterChanges = ctx.typert.register(credentialChangesHost);
         installSkillFilesystem(ctx, {
             providerName: 'dsh-data-analysis-marivo',
@@ -160,6 +169,7 @@ export async function apply(ctx, config = {}) {
         disposePublishing = registerPublishingCredentials(ctx.connection, reportPublishing, (id) => Boolean(ctx.workspaceRegistry.get(WorkspaceId(id))));
         agentInstallation = createMarivoAgentInstallation(ctx, resolveEnvironment, {
             ...pythonOptions,
+            pythonOptionsSource: pythonSettings.get,
             helpBridgeSource: helpBridge,
             ...(publishingConfig ? { reportPublishing } : {}),
             credentialService,