@chengxianglibra/dsh-data-analysis 0.1.2 → 0.2.1

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: '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',
+                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,15 @@
+export const DEFAULT_PYTHON_TIMEOUT_MS = 120_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');
+    return { pythonTimeoutMs };
+}

package/lib/datasource/python.js

@@ -1,29 +1,58 @@
+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 readOptions = typeof options === 'function' ? options : () => options;
+    resolvePythonOptions(readOptions());
+    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. 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',
                 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 the current plugin pythonTimeoutMs setting. Credential waiting precedes this budget; Harness Shell limits, outer Code Mode deadlines and cancellation remain independent.',
             },
         },
         output: {
@@ -31,28 +60,62 @@ 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
+                        ? resolvePythonOptions(readOptions()).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: requestedTimeoutMs,
                     signal: prepared.signal,
                     stdin: JSON.stringify({
                         identity: binding,
@@ -66,19 +129,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 +161,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 +180,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();
             }
         },
     }));