@chengxianglibra/dsh-data-analysis 0.1.2 → 0.2.0

package/lib/compatibility.js

@@ -56,7 +56,7 @@ const packageManifest = parsePackageManifest(createRequire(import.meta.url)('../
 /** The package semver and the compatibility contract shipped in this exact installation. */
 export const PLUGIN_VERSION = packageManifest.version;
 export const DSH_DATA_ANALYSIS_COMPATIBILITY = packageManifest.dshDataAnalysisCompatibility;
-/** Every DSH peer is required and must use this one verified release. */
+/** Every DSH peer is required and must satisfy this declared compatibility range. */
 export const DSH_PEER_RANGE = DSH_DATA_ANALYSIS_COMPATIBILITY.dsh.peerRange;
 export const DSH_DISTRIBUTION = DSH_DATA_ANALYSIS_COMPATIBILITY.dsh.distribution;
 export const DSH_PEER_DEPENDENCIES = Object.freeze(Object.fromEntries(Object.entries(packageManifest.peerDependencies).filter(([name]) => name.startsWith('@deepseek-ai/dsh-'))));

package/lib/datasource/authoring.js

@@ -17,6 +17,7 @@ export const datasourceAuthoringSchema = z.object({
 export const DATASOURCE_AUTHORING_PROGRAM = String.raw `
 import contextlib
 import dataclasses
+import hashlib
 import json
 import sys
 import typing
@@ -43,28 +44,66 @@ def spec_fields(cls):
         result.append(item)
     return result
 
+def configuration(name, cls):
+    import marivo.semantic as ms
+    description = md.describe(name)
+    details = ms.load().datasources.get(name).details()
+    if details.backend_type != description.backend_type or dict(details.fields) != description.literal_fields or dict(details.env_refs) != description.env_refs:
+        raise ValueError("context-changed")
+    context = {"business_definition": details.context.business_definition,
+        "guardrails": list(details.context.guardrails)}
+    allowed = {field["name"] for field in spec_fields(cls)}
+    fields = {"name": name}
+    extra = {}
+    for key, value in description.literal_fields.items():
+        if key in allowed and key != "extra": fields[key] = value
+        else: extra[key] = value
+    if extra: fields["extra"] = extra
+    for key, value in description.env_refs.items():
+        if key.startswith("http_header:"):
+            fields.setdefault("http_headers_env", {})[key.removeprefix("http_header:")] = value
+        elif key + "_env" in allowed: fields[key + "_env"] = value
+        else: raise ValueError("datasource-definition-invalid")
+    version = hashlib.sha256(json.dumps([description.backend_type, fields, context], sort_keys=True).encode()).hexdigest()
+    return {"name": name, "backend": description.backend_type, "fields": fields, "version": version}, context
+
 try:
     payload = json.load(sys.stdin)
     with contextlib.redirect_stdout(Discard()), contextlib.redirect_stderr(Discard()):
         specs = {cls.backend_type: cls for cls in typing.get_args(md.DatasourceSpec)}
         if payload["action"] == "schema":
             result = {"backends": [{"name": key, "fields": spec_fields(cls)} for key, cls in specs.items()]}
+        elif payload["action"] == "read":
+            description = md.describe(payload["name"])
+            result, _ = configuration(payload["name"], specs[description.backend_type])
         else:
             cls = specs[payload["backend"]]
             fields = payload["fields"]
             allowed = {field["name"] for field in spec_fields(cls)}
+            context = None
+            if payload["action"] == "update":
+                current = md.describe(payload["name"])
+                if fields.get("name") != payload["name"] or current.backend_type != payload["backend"]:
+                    raise ValueError("datasource-identity-fixed")
+                original, context = configuration(payload["name"], cls)
+                if original["version"] != payload["version"]:
+                    raise ValueError("datasource-config-changed")
             if set(fields) - allowed:
                 raise ValueError("unknown-field")
             spec = cls(**fields)
-            if any(item.name == spec.name for item in md.list()):
+            if payload["action"] == "create" and any(item.name == spec.name for item in md.list()):
                 result = {"error": "datasource-already-exists"}
             else:
-                # Validate references before writing; the Host applies its own reserved-name check too.
                 if sorted(spec.env_refs.values()) != sorted(payload["refs"]):
                     raise ValueError("credential-reference-mismatch")
+                if context is not None:
+                    import marivo.semantic as ms
+                    spec = cls(**fields, ai_context=ms.ai_context(**context))
                 md.register(spec)
                 result = {"name": spec.name}
-except Exception:
-    result = {"error": "datasource-definition-invalid"}
+
+except Exception as exc:
+    code = str(exc)
+    result = {"error": code if code in ("datasource-config-changed", "datasource-identity-fixed", "context-changed") else "datasource-definition-invalid"}
 print(json.dumps(result))
 `.trim();

package/lib/datasource/bridge-programs.js

@@ -1,5 +1,5 @@
 import { RESOLVER_PROGRAM } from "./resolver-program.js";
-export const MARIVO_DATASOURCE_DESCRIBE_PROGRAM = String.raw `
+const DATASOURCE_DESCRIPTION_PROGRAM = String.raw `
 import json
 import os
 import sys
@@ -16,29 +16,32 @@ def project_description(description):
         "fields": description.env_refs,
         "definition": hashlib.sha256(json.dumps(payload, sort_keys=True, default=str).encode()).hexdigest()}
 
-print(json.dumps(project_description(md.describe(sys.argv[1])), sort_keys=True))
 `.trim();
-export const MARIVO_DATASOURCE_INVENTORY_PROGRAM = String.raw `
-import json
-import os
-import sys
-import marivo
-import marivo.datasource as md
-
-import hashlib
-
-def project_description(description):
-    payload = {"name": description.name, "backend": description.backend_type,
-        "fields": description.literal_fields, "refs": description.env_refs}
-    return {"name": description.name, "backend": description.backend_type,
-        "properties": description.literal_fields, "refs": list(description.env_refs.values()),
-        "fields": description.env_refs,
-        "definition": hashlib.sha256(json.dumps(payload, sort_keys=True, default=str).encode()).hexdigest()}
-
+export const MARIVO_DATASOURCE_DESCRIBE_PROGRAM = `${DATASOURCE_DESCRIPTION_PROGRAM}
+print(json.dumps(project_description(md.describe(sys.argv[1])), sort_keys=True))`;
+export const MARIVO_DATASOURCE_REMOVE_PROGRAM = `${DATASOURCE_DESCRIPTION_PROGRAM}
+import contextlib
+class Discard:
+    def write(self, value): return len(value)
+    def flush(self): pass
+try:
+    payload = json.load(sys.stdin)
+    with contextlib.redirect_stdout(Discard()), contextlib.redirect_stderr(Discard()):
+        current = project_description(md.describe(payload["name"]))
+        if current["definition"] != payload["definition"]:
+            result = {"error": "context-changed"}
+        elif md.remove(payload["name"]):
+            result = {"name": payload["name"]}
+        else:
+            result = {"error": "datasource-not-removable"}
+except Exception:
+    result = {"error": "datasource-remove-failed"}
+print(json.dumps(result))`;
+export const MARIVO_DATASOURCE_INVENTORY_PROGRAM = `${DATASOURCE_DESCRIPTION_PROGRAM}
 print(json.dumps({
     "datasources": [project_description(md.describe(item.name)) for item in md.list()],
 }, sort_keys=True))
-`.trim();
+`;
 export const MARIVO_DATASOURCE_TEST_PROGRAM = `${RESOLVER_PROGRAM}\n${String.raw `
 import contextlib
 import io

package/lib/datasource/bridge.js

@@ -2,7 +2,7 @@ import { isCredentialRefName } from '@deepseek-ai/dsh-credentials';
 import { MarivoEnvironmentError } from "../environment/errors.js";
 import { resolveMarivoBridgeSource } from "../environment/source.js";
 import { DATASOURCE_AUTHORING_PROGRAM, datasourceAuthoringSchema, } from "./authoring.js";
-import { MARIVO_DATASOURCE_DESCRIBE_PROGRAM, MARIVO_DATASOURCE_INVENTORY_PROGRAM, MARIVO_DATASOURCE_TEST_PROGRAM, } from "./bridge-programs.js";
+import { MARIVO_DATASOURCE_DESCRIBE_PROGRAM, MARIVO_DATASOURCE_INVENTORY_PROGRAM, MARIVO_DATASOURCE_REMOVE_PROGRAM, MARIVO_DATASOURCE_TEST_PROGRAM, } from "./bridge-programs.js";
 import { marivoCredentialStorageRef } from "./shell-env.js";
 const DATASOURCE_LIMITS = Object.freeze({
     timeoutMs: 30_000,
@@ -210,7 +210,30 @@ export class MarivoDatasourceBridge {
             fingerprint: this.binding.fingerprint,
         });
     }
+    async configuration(name, signal) {
+        const result = await this.#runner.runChecked({
+            program: DATASOURCE_AUTHORING_PROGRAM,
+            stdin: JSON.stringify({ action: 'read', name }),
+            limits: DATASOURCE_LIMITS,
+            signal,
+        });
+        this.#assertSuccess(result, 'inventory');
+        const value = parseJsonObject(result.stdout, 'inventory');
+        if (value.name !== name ||
+            typeof value.backend !== 'string' ||
+            typeof value.version !== 'string' ||
+            !object(value.fields) ||
+            !jsonValue(value.fields))
+            throw new Error('Datasource configuration cannot be read completely');
+        return value;
+    }
+    async update(input, signal) {
+        return this.#write(input, 'update', signal);
+    }
     async create(input, signal) {
+        return this.#write(input, 'create', signal);
+    }
+    async #write(input, action, signal) {
         const refs = Object.entries(input.fields)
             .filter(([key]) => key.endsWith('_env'))
             .flatMap(([, value]) => typeof value === 'string'
@@ -233,14 +256,17 @@ export class MarivoDatasourceBridge {
         }
         const result = await this.#runner.runChecked({
             program: DATASOURCE_AUTHORING_PROGRAM,
-            stdin: JSON.stringify({ action: 'create', ...input, refs }),
+            stdin: JSON.stringify({ action, ...input, refs }),
             limits: DATASOURCE_LIMITS,
             signal,
         });
         this.#assertSuccess(result, 'inventory');
         const value = parseJsonObject(result.stdout, 'inventory');
         if (value.error === 'datasource-already-exists' ||
-            value.error === 'datasource-definition-invalid')
+            value.error === 'datasource-definition-invalid' ||
+            value.error === 'datasource-config-changed' ||
+            value.error === 'datasource-identity-fixed' ||
+            value.error === 'context-changed')
             return { error: value.error };
         if (typeof value.name !== 'string')
             throw new Error('Invalid datasource creation result');
@@ -256,6 +282,23 @@ export class MarivoDatasourceBridge {
         this.#assertSuccess(result, 'describe');
         return parseDescription(parseJsonObject(result.stdout, 'describe'), 'describe');
     }
+    async remove(description, signal) {
+        const result = await this.#runner.runChecked({
+            program: MARIVO_DATASOURCE_REMOVE_PROGRAM,
+            stdin: JSON.stringify({ name: description.name, definition: description.definition }),
+            limits: DATASOURCE_LIMITS,
+            signal,
+        });
+        this.#assertSuccess(result, 'inventory');
+        const value = parseJsonObject(result.stdout, 'inventory');
+        if (value.error === 'context-changed' ||
+            value.error === 'datasource-not-removable' ||
+            value.error === 'datasource-remove-failed')
+            return { error: value.error };
+        if (value.name !== description.name)
+            throw new Error('Invalid datasource removal result');
+        return { name: description.name };
+    }
     async inventory(signal) {
         const result = await this.#runner.runChecked({
             program: MARIVO_DATASOURCE_INVENTORY_PROGRAM,

package/lib/datasource/changes-contract.js

@@ -0,0 +1,41 @@
+import { z } from 'zod';
+export const CREDENTIAL_CHANGES_SERVICE = 'dshDataAnalysisCredentials';
+const owner = '@chengxianglibra/dsh-data-analysis';
+const sessionId = z.string().min(1).max(256);
+export const credentialRevisionSchema = z
+    .object({ generation: z.string().uuid(), cursor: z.string().min(1).max(256) })
+    .strict();
+/** Plugin-owned strict boundary shared by both faces; no Host registry is duplicated. */
+const descriptor = {
+    id: `${owner}#${CREDENTIAL_CHANGES_SERVICE}/changes`,
+    service: CREDENTIAL_CHANGES_SERVICE,
+    namespace: CREDENTIAL_CHANGES_SERVICE,
+    method: 'changes',
+    mode: 'stream',
+    invocation: { kind: 'direct' },
+    parameters: [
+        {
+            name: 'sessionId',
+            wire: 'sessionId',
+            source: 'json',
+            codec: { mode: 'strict', typeSymbol: `${owner}#CredentialSessionId`, schema: sessionId },
+        },
+    ],
+    cancellation: { parameter: 'signal' },
+    result: {
+        mode: 'strict',
+        typeSymbol: `${owner}#CredentialRevision`,
+        schema: credentialRevisionSchema,
+    },
+};
+export const credentialChangesHost = {
+    package: owner,
+    face: 'host',
+    schemas: [],
+    model: { services: [], events: [], objects: [] },
+    invocations: [descriptor],
+};
+export const credentialChangesRemote = {
+    package: owner,
+    descriptors: [descriptor],
+};

package/lib/datasource/changes.js

@@ -0,0 +1,49 @@
+import { setTimeout as delay } from 'node:timers/promises';
+import { TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
+import { PendingTasks } from "../lifecycle.js";
+import { CREDENTIAL_CHANGES_SERVICE } from "./changes-contract.js";
+import { CredentialServiceError } from "./service.js";
+/** Reuses the Host's logical stream carrier; credentials and waiting calls keep their owner. */
+export class CredentialChangesService extends TypertRemoteService {
+    credentials;
+    lifetime = new AbortController();
+    tasks = new PendingTasks();
+    closing;
+    constructor(ctx, credentials) {
+        super(ctx, CREDENTIAL_CHANGES_SERVICE);
+        this.credentials = credentials;
+    }
+    async *changes(sessionId, caller) {
+        const signal = AbortSignal.any([caller, this.lifetime.signal]);
+        let cursor;
+        while (!signal.aborted) {
+            const snapshot = await this.tasks.track(this.snapshot(sessionId, cursor, signal));
+            signal.throwIfAborted();
+            if (snapshot.cursor !== cursor) {
+                cursor = snapshot.cursor;
+                yield { generation: snapshot.generation, cursor };
+            }
+        }
+    }
+    async snapshot(sessionId, cursor, signal) {
+        let attempt = 0;
+        for (;;) {
+            signal.throwIfAborted();
+            try {
+                return await this.credentials.waitWatch(sessionId, cursor, signal);
+            }
+            catch (error) {
+                signal.throwIfAborted();
+                if (!(error instanceof CredentialServiceError) ||
+                    error.code !== 'credential-state-unavailable')
+                    throw new Error('credential-notification-unavailable');
+                await delay([1000, 2000, 5000][Math.min(attempt++, 2)], undefined, { signal });
+            }
+        }
+    }
+    close() {
+        this.lifetime.abort();
+        this.closing ??= this.tasks.drain();
+        return this.closing;
+    }
+}

package/lib/datasource/configure.js

@@ -0,0 +1,39 @@
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { registerMarivoTool } from "../tool-lifecycle.js";
+import { resolveMarivoDatasourceBridge } from "./bridge.js";
+export const MARIVO_DATASOURCE_CONFIGURE_TOOL_NAME = 'marivo_datasource_configure';
+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.',
+        parameters: {
+            mode: {
+                type: 'string',
+                required: true,
+                description: 'create (also permits choosing an existing datasource) or edit (fixed name and engine).',
+            },
+            name: { type: 'string', description: 'Existing datasource name, required only for edit.' },
+            reason: {
+                type: 'string',
+                required: true,
+                description: 'Brief reason for configuration, at most 1000 characters. No secrets.',
+            },
+        },
+        output: {
+            schema: { type: 'json' },
+            render: (_args, value) => [{ type: 'text', text: JSON.stringify(value) }],
+        },
+        async execute(args, exec) {
+            if (args.mode !== 'create' && args.mode !== 'edit')
+                throw new Error('Invalid configuration mode');
+            return JSON.parse(JSON.stringify(await service.track(service.configure(exec, () => resolveMarivoDatasourceBridge(source), {
+                mode: args.mode,
+                name: args.name,
+                reason: args.reason,
+            }))));
+        },
+    });
+}
+export function registerMarivoDatasourceConfigureTool(ctx, source, service) {
+    return registerMarivoTool(ctx, createMarivoDatasourceConfigureTool(source, service));
+}

package/lib/datasource/defaults.js

@@ -0,0 +1,25 @@
+import { z } from 'zod';
+import { CredentialServiceError } from "./service.js";
+/** Validate against this Workspace's live Runtime; never include config values in errors. */
+export function withDatasourceDefaults(schema, configured) {
+    if (configured === undefined)
+        return schema;
+    const parsed = z.record(z.string(), z.record(z.string(), z.json())).safeParse(configured);
+    if (!parsed.success)
+        throw new CredentialServiceError('datasource-defaults-invalid');
+    for (const [backend, values] of Object.entries(parsed.data)) {
+        const definition = schema.backends.find((item) => item.name === backend);
+        if (!definition)
+            throw new CredentialServiceError('datasource-defaults-backend-invalid');
+        for (const [name, value] of Object.entries(values)) {
+            const field = definition.fields.find((item) => item.name === name);
+            if (name.endsWith('_env'))
+                throw new CredentialServiceError('datasource-defaults-credential-forbidden');
+            if (!field)
+                throw new CredentialServiceError('datasource-defaults-field-invalid');
+            if (field.type !== 'json' && typeof value !== field.type)
+                throw new CredentialServiceError('datasource-defaults-type-invalid');
+        }
+    }
+    return { ...schema, creationDefaults: parsed.data };
+}

package/lib/datasource/index.js

@@ -1,5 +1,6 @@
 export { MarivoDatasourceBridge, resolveMarivoDatasourceBridge, resolveMarivoDatasourceInventoryBridge, } from "./bridge.js";
-export { registerMarivoPythonTool } from "./python.js";
+export { createMarivoDatasourceConfigureTool, MARIVO_DATASOURCE_CONFIGURE_TOOL_NAME, registerMarivoDatasourceConfigureTool, } from "./configure.js";
+export { MarivoPythonExecutionError, registerMarivoPythonTool } from "./python.js";
 export { MarivoCredentialService } from "./service.js";
 export { assertMarivoCredentialReferences, MARIVO_CREDENTIAL_STORAGE_PREFIX, marivoCredentialStorageRef, } from "./shell-env.js";
 export { createMarivoDatasourceTestTool, MARIVO_DATASOURCE_TEST_TOOL_NAME, registerMarivoDatasourceTestTool, } from "./test.js";

package/lib/datasource/python-options.js

@@ -0,0 +1,21 @@
+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) {
+    if (typeof value !== 'number' ||
+        !Number.isInteger(value) ||
+        value <= 0 ||
+        value > MAX_TIMER_DELAY_MS)
+        throw new Error(`${name} must be a positive integer no greater than ${MAX_TIMER_DELAY_MS}`);
+    return value;
+}
+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 };
+}

package/lib/datasource/python.js

@@ -1,29 +1,57 @@
+import { performance } from 'node:perf_hooks';
 import process from 'node:process';
 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 { PYTHON_LAUNCHER, PYTHON_WORKER } from "./resolver-program.js";
+import { CredentialServiceError, } from "./service.js";
 import { datasourceToolValue } from "./test.js";
+/** The message survives Harness error normalization; it contains only safe adapter facts. */
+export class MarivoPythonExecutionError extends Error {
+    execution;
+    constructor(message, execution) {
+        super(`${message}; execution=${JSON.stringify(execution)}`);
+        this.name = 'MarivoPythonExecutionError';
+        this.execution = execution;
+    }
+}
+const CHECK_EFFECTS = 'Inspect existing effects and the intended Session through current Runtime Help before retrying; do not automatically replay. Saved results and remote query cancellation are not confirmed.';
+const PREPARATION_CODES = new Set([
+    'agent-required',
+    'invalid-datasources',
+    'call-ended',
+    'context-changed',
+    'credentials-changed',
+    'execution-ended',
+    'disposed',
+]);
 function quote(value) {
     return process.platform === 'win32'
         ? `'${value.replaceAll("'", "''")}'`
         : `'${value.replaceAll("'", "'\\''")}'`;
 }
-export function registerMarivoPythonTool(ctx, source, service) {
-    return ctx.tools.register(defineTool({
+export function registerMarivoPythonTool(ctx, source, service, options = {}) {
+    const limits = resolvePythonOptions(options);
+    return registerMarivoTool(ctx, defineTool({
         name: 'marivo_python',
-        description: 'Execute foreground Python in the bound Marivo Workspace using Host-injected credentials. This call waits for missing credentials for every listed datasource before starting Python once; configured credentials do not trigger a connection test. Create/resume Sessions and readers inside this execution; 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.',
+        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.',
         parameters: {
             code: {
                 type: 'string',
                 required: true,
-                description: 'Python code, never credential values. Use try/finally for per-call Session resource cleanup; consult current Runtime Help for Session APIs.',
+                description: 'Python code, never credential values. Close resources within this call. When using Marivo Session APIs, consult current Runtime Help and close Sessions in finally.',
             },
             datasources: {
                 type: 'array',
                 required: true,
                 items: { type: 'string' },
-                description: 'All exact datasource names this execution may access through data or metadata connections, including inspection and datasources without passwords; pass [] only when no datasource will be accessed. Catalog-only definition reads need no datasource connection.',
+                description: 'All exact Marivo datasource names this execution may access through data or metadata connections, including inspection and datasources without passwords. Pass [] for local pandas or native DuckDB file analysis without Marivo datasource access. Catalog-only definition reads need no datasource connection.',
+            },
+            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.`,
             },
         },
         output: {
@@ -31,28 +59,60 @@ export function registerMarivoPythonTool(ctx, source, service) {
             render: (_args, value) => [{ type: 'text', text: JSON.stringify(value) }],
         },
         async execute(args, exec) {
-            const code = args.code;
-            if (!code.trim() || Buffer.byteLength(code) > 131072)
-                throw new Error('Invalid Python code size');
-            const shell = ctx.get('shell');
-            if (!shell)
-                throw new Error('DSH Shell execution service is required');
-            const shellEnv = ctx.get('shellEnv');
-            if (!shellEnv)
-                throw new Error('DSH Shell environment service is required');
-            const policyService = ctx.get('sandboxPolicy');
-            if (shell.sandboxMode !== undefined && !policyService)
-                throw new Error('DSH sandbox policy is required');
-            const prepared = await service.track(service.prepareExecution(exec, () => resolveMarivoDatasourceBridge(source), args.datasources));
-            if (!('status' in prepared) || prepared.status !== 'ready')
-                return datasourceToolValue(prepared);
+            const calledAt = performance.now();
+            let phase = 'preparing';
+            let requestedTimeoutMs = null;
+            let effectiveTimeoutMs = null;
+            let shellStartedAt = null;
+            let executionElapsedMs = null;
+            let prepared;
+            const summary = (reason, nextAction) => {
+                const now = performance.now();
+                return {
+                    phase,
+                    reason,
+                    requestedTimeoutMs,
+                    effectiveTimeoutMs,
+                    elapsedMs: now - calledAt,
+                    executionElapsedMs: executionElapsedMs ?? (shellStartedAt === null ? null : now - shellStartedAt),
+                    nextAction,
+                };
+            };
+            const rejectInput = (message) => {
+                throw new MarivoPythonExecutionError(message, summary('not-started', 'Correct the input or Host configuration before retrying.'));
+            };
             try {
+                try {
+                    requestedTimeoutMs = pythonTimeout(args.timeoutMs === undefined ? limits.pythonTimeoutMs : args.timeoutMs, 'timeoutMs');
+                }
+                catch {
+                    rejectInput('timeoutMs must be a positive integer no greater than 2147483647');
+                }
+                const code = args.code;
+                if (typeof code !== 'string' || !code.trim() || Buffer.byteLength(code) > 131072)
+                    rejectInput('Invalid Python code size');
+                const shell = ctx.get('shell');
+                if (!shell)
+                    rejectInput('DSH Shell execution service is required');
+                const shellEnv = ctx.get('shellEnv');
+                if (!shellEnv)
+                    rejectInput('DSH Shell environment service is required');
+                const policyService = ctx.get('sandboxPolicy');
+                if (shell.sandboxMode !== undefined && !policyService)
+                    rejectInput('DSH sandbox policy is required');
+                const admission = await service.track(service.prepareExecution(exec, () => resolveMarivoDatasourceBridge(source), args.datasources));
+                if (!('status' in admission) || admission.status !== 'ready')
+                    return {
+                        ...datasourceToolValue(admission),
+                        execution: summary('not-started', 'Resolve the datasource credential requirement or reported connection failure before retrying.'),
+                    };
+                prepared = admission;
                 const { binding } = prepared.bridge;
                 const policy = policyService?.resolve(exec.agent ? { session: exec.agent.session } : {});
                 const spec = shell.resolve({
                     command: `${process.platform === 'win32' ? '& ' : ''}${quote(binding.pythonExecutable)} -c ${quote(PYTHON_LAUNCHER)}`,
                     workdir: binding.projectRoot,
-                    timeoutMs: 120_000,
+                    timeoutMs: Math.min(requestedTimeoutMs, limits.pythonMaxTimeoutMs),
                     signal: prepared.signal,
                     stdin: JSON.stringify({
                         identity: binding,
@@ -66,19 +126,25 @@ export function registerMarivoPythonTool(ctx, source, service) {
                     dshEnv: shellEnv.collect(exec),
                     ...(policy ? { sandboxPolicy: policy } : {}),
                 });
+                effectiveTimeoutMs = spec.timeoutMs;
                 // Keep this guard adjacent to the only launch, after synchronous Host hooks.
                 prepared.assertCurrent();
                 const startedAt = new Date().toISOString();
+                phase = 'executing';
+                shellStartedAt = performance.now();
                 const result = await service.track(shell.run(spec));
+                executionElapsedMs = performance.now() - shellStartedAt;
                 const finishedAt = new Date().toISOString();
+                const credentialValues = prepared.values;
                 // Defense at the result seam as well as before Harness collection/spill.
-                const redact = (text) => Object.values(prepared.values)
+                const redact = (text) => Object.values(credentialValues)
                     .filter(Boolean)
                     .sort((a, b) => b.length - a.length)
                     .reduce((out, value) => out.split(value).join('[REDACTED]'), text);
                 let codeRef;
                 let codeCaptureError;
                 if (result.exitCode === 0 && !result.timedOut && !result.aborted) {
+                    phase = 'capturing-code';
                     try {
                         prepared.assertCurrent();
                         if (Object.values(prepared.values).some((value) => value && code.includes(value)))
@@ -92,6 +158,15 @@ export function registerMarivoPythonTool(ctx, source, service) {
                             'Python completed successfully, but its source code could not be saved. Do not rerun the code to recover this snapshot; inspect its existing effects.';
                     }
                 }
+                const reason = result.timedOut
+                    ? 'timed-out'
+                    : result.aborted
+                        ? 'cancelled'
+                        : result.exitCode === 0
+                            ? 'succeeded'
+                            : result.exitCode === null
+                                ? 'unknown'
+                                : 'nonzero-exit';
                 return JSON.parse(JSON.stringify({
                     exitCode: result.exitCode,
                     timedOut: result.timedOut,
@@ -102,13 +177,29 @@ export function registerMarivoPythonTool(ctx, source, service) {
                     sandbox: result.sandbox ?? null,
                     ...(codeRef ? { codeRef } : {}),
                     ...(codeCaptureError ? { codeCaptureError } : {}),
+                    execution: summary(reason, codeCaptureError ?? (reason === 'succeeded' ? null : CHECK_EFFECTS)),
                 }));
             }
-            catch {
-                throw new Error('Marivo Python execution failed or was cancelled; inspect the execution policy and retry only after checking effects');
+            catch (error) {
+                if (error instanceof MarivoPythonExecutionError)
+                    throw error;
+                const cancelled = (prepared?.signal ?? exec.signal).aborted;
+                const reason = cancelled
+                    ? 'cancelled'
+                    : shellStartedAt === null
+                        ? 'not-started'
+                        : 'unknown';
+                const code = error instanceof CredentialServiceError && PREPARATION_CODES.has(error.code)
+                    ? ` (${error.code})`
+                    : '';
+                throw new MarivoPythonExecutionError(shellStartedAt === null
+                    ? `Marivo Python preparation failed or was cancelled; Python was not started${code}`
+                    : 'Marivo Python execution outcome is unknown after an execution service failure or cancellation', summary(reason, shellStartedAt === null
+                    ? 'Check credentials, Workspace binding and Host execution policy before retrying.'
+                    : CHECK_EFFECTS));
             }
             finally {
-                prepared.release();
+                prepared?.release();
             }
         },
     }));