@chengxianglibra/dsh-data-analysis 0.2.1 → 0.2.3

package/lib/compatibility.js

@@ -48,6 +48,7 @@ function parsePackageManifest(value) {
             contracts: Object.freeze({
                 runtimeInstallation: requiredLiteral(contracts.runtimeInstallation, 'dsh-data-analysis-runtime/v3', 'package compatibility contracts.runtimeInstallation'),
                 subprocessPolicy: requiredLiteral(contracts.subprocessPolicy, 'direct-argv-inherited-env-snapshot-overlay-v2', 'package compatibility contracts.subprocessPolicy'),
+                integration: requiredLiteral(contracts.integration, 'dsh-data-analysis-integration/v1', 'package compatibility contracts.integration'),
             }),
         }),
     });

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/defaults.js

@@ -1,10 +1,13 @@
 import { z } from 'zod';
 import { CredentialServiceError } from "./service.js";
+import { marivoCredentialStorageRef } from "./shell-env.js";
 /** Validate against this Workspace's live Runtime; never include config values in errors. */
-export function withDatasourceDefaults(schema, configured) {
-    if (configured === undefined)
+export function withDatasourceDefaults(schema, configured, managed) {
+    if (configured === undefined && managed === undefined)
         return schema;
-    const parsed = z.record(z.string(), z.record(z.string(), z.json())).safeParse(configured);
+    const parsed = z
+        .record(z.string(), z.record(z.string(), z.json()))
+        .safeParse(configured === undefined ? {} : configured);
     if (!parsed.success)
         throw new CredentialServiceError('datasource-defaults-invalid');
     for (const [backend, values] of Object.entries(parsed.data)) {
@@ -21,5 +24,24 @@ export function withDatasourceDefaults(schema, configured) {
                 throw new CredentialServiceError('datasource-defaults-type-invalid');
         }
     }
-    return { ...schema, creationDefaults: parsed.data };
+    const combined = Object.fromEntries(Object.entries(parsed.data).map(([backend, values]) => [backend, { ...values }]));
+    if (managed !== undefined) {
+        const references = z.record(z.string(), z.record(z.string(), z.string())).safeParse(managed);
+        if (!references.success)
+            throw new CredentialServiceError('datasource-defaults-invalid');
+        for (const [backend, fields] of Object.entries(references.data)) {
+            const definition = schema.backends.find((item) => item.name === backend);
+            if (!definition)
+                throw new CredentialServiceError('datasource-defaults-backend-invalid');
+            for (const [name, reference] of Object.entries(fields)) {
+                if (!name.endsWith('_env') || !definition.fields.some((field) => field.name === name))
+                    throw new CredentialServiceError('datasource-defaults-field-invalid');
+                marivoCredentialStorageRef(reference);
+                if (Object.hasOwn(combined[backend] ?? {}, name))
+                    throw new CredentialServiceError('datasource-defaults-credential-forbidden');
+            }
+            combined[backend] = { ...combined[backend], ...fields };
+        }
+    }
+    return { ...schema, creationDefaults: combined };
 }

package/lib/datasource/python.js

@@ -116,6 +116,7 @@ export function registerMarivoPythonTool(ctx, source, service, options = {}) {
                     command: `${process.platform === 'win32' ? '& ' : ''}${quote(binding.pythonExecutable)} -c ${quote(PYTHON_LAUNCHER)}`,
                     workdir: binding.projectRoot,
                     timeoutMs: requestedTimeoutMs,
+                    onExpiry: 'kill',
                     signal: prepared.signal,
                     stdin: JSON.stringify({
                         identity: binding,
@@ -135,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/rpc.js

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 import { registerPluginRpc } from "../rpc.js";
-import { withDatasourceDefaults } from "./defaults.js";
+import { withDatasourceDefaults, } from "./defaults.js";
 import { CREDENTIAL_CHANNEL, credentialError } from "./service.js";
 const text = z.string().min(1).max(256);
 const handle = { generation: z.string().uuid(), id: z.string().uuid(), scope: z.string().uuid() };
@@ -15,7 +15,7 @@ const mutation = z
     changes: z.record(text, z.string().min(1).max(65536)).optional(),
 })
     .strict();
-export function registerCredentialRpc(connection, service, workspace, datasourceDefaults) {
+export function registerCredentialRpc(connection, service, workspace, datasourceDefaults, managedCredentialDefaults) {
     const unregister = registerPluginRpc(connection, CREDENTIAL_CHANNEL, [
         'overview',
         'authoring',
@@ -53,7 +53,7 @@ export function registerCredentialRpc(connection, service, workspace, datasource
                     generation: service.generation,
                     ...(input.mode === 'edit'
                         ? schema
-                        : withDatasourceDefaults(schema, datasourceDefaults)),
+                        : withDatasourceDefaults(schema, datasourceDefaults, managedCredentialDefaults)),
                 };
             }
             else if (endpoint === 'configuration') {

package/lib/environment/runtime.js

@@ -527,6 +527,8 @@ export async function ensureSharedMarivoRuntime(config = {}, options = {}) {
     const existing = await validatedExisting(runtimeRoot, configuredPython, options.environment, timeoutMs, presentationKitWheel);
     if (existing !== undefined)
         return existing;
+    if (options.existingOnly)
+        throw new MarivoEnvironmentError('shared-runtime-installation-required', 'A valid shared Marivo Runtime installation is required');
     await mkdir(path.dirname(runtimeRoot), { recursive: true });
     const lockPath = `${runtimeRoot}.install-lock`;
     const release = await acquireLock(lockPath, timeoutMs, options.waitIntervalMs ?? 100);

package/lib/environment/workspace.js

@@ -31,9 +31,11 @@ export class MarivoWorkspaceEnvironmentManager {
     #disposed = false;
     #closing;
     runtime;
+    onBound;
     #bindings = new Map();
-    constructor(runtime) {
+    constructor(runtime, onBound) {
         this.runtime = runtime;
+        this.onBound = onBound;
     }
     resolve(projectRoot) {
         return this.#tasks.track(this.#resolve(projectRoot));
@@ -54,6 +56,16 @@ export class MarivoWorkspaceEnvironmentManager {
                     version: this.runtime.presentationKitVersion,
                     packagePath: this.runtime.presentationKitPackagePath,
                 },
+            })
+                .then(async (environment) => {
+                if (this.#disposed)
+                    throw new Error('Marivo Workspace manager disposed');
+                await this.onBound?.(environment);
+                return environment;
+            })
+                .catch((error) => {
+                this.#bindings.delete(canonicalRoot);
+                throw error;
             });
             this.#bindings.set(canonicalRoot, binding);
         }

package/lib/integration.js

@@ -0,0 +1,5 @@
+/** Public extension seam. The version denotes this shape, not a specific consumer. */
+export const INTEGRATION_CONTRACT_VERSION = 'dsh-data-analysis-integration/v1';
+export { withDatasourceDefaults } from "./datasource/defaults.js";
+export { applyWithIntegration } from "./plugin.js";
+export { registerPluginRpc } from "./rpc.js";

package/lib/plugin.js

@@ -5,7 +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 { installPythonSettings } from "./settings.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";
@@ -17,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_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";
@@ -47,7 +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),
+    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(),
@@ -64,8 +70,12 @@ function configuredProjectRoot(config, agent) {
 }
 /** Ensure the shared Runtime once, mount its skills, then bind each Workspace lazily. */
 export async function apply(ctx, config = {}) {
+    return applyWithIntegration(ctx, config);
+}
+/** Compose an extension at the public seam while retaining the ordinary plugin behavior. */
+export async function applyWithIntegration(ctx, config = {}, integration = {}) {
     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;
@@ -76,7 +86,7 @@ export async function apply(ctx, config = {}) {
         ...(config.installTimeoutMs === undefined ? {} : { installTimeoutMs: config.installTimeoutMs }),
     });
     const disposeRuntimeShellEnvironment = registerMarivoRuntimeShellEnvironment(ctx, runtime.pythonExecutable);
-    const manager = new MarivoWorkspaceEnvironmentManager(runtime);
+    const manager = new MarivoWorkspaceEnvironmentManager(runtime, integration.onWorkspaceBound);
     const bindings = new WeakMap();
     const resolveEnvironment = (agent) => {
         const root = configuredProjectRoot(config, agent);
@@ -87,7 +97,7 @@ export async function apply(ctx, config = {}) {
         bindings.set(agent, { root, environment });
         return environment;
     };
-    const credentialService = new MarivoCredentialService(ctx.credentials, config.credentialInteraction);
+    const credentialService = new MarivoCredentialService(integration.datasourceCredentials ?? ctx.credentials, config.credentialInteraction);
     const credentialNotifications = new CredentialChangesService(ctx, credentialService);
     let unregisterChanges;
     const disposeChanges = async () => {
@@ -134,7 +144,7 @@ export async function apply(ctx, config = {}) {
         return closing;
     };
     try {
-        pythonSettings = installPythonSettings(ctx, pythonOptions);
+        pythonSettings = installPythonSettings(ctx, config);
         unregisterChanges = ctx.typert.register(credentialChangesHost);
         installSkillFilesystem(ctx, {
             providerName: 'dsh-data-analysis-marivo',
@@ -182,7 +192,7 @@ export async function apply(ctx, config = {}) {
                     root)
                 throw new Error('Workspace changed');
             return new MarivoDatasourceBridge(environment);
-        }, config.datasourceDefaults);
+        }, config.datasourceDefaults, integration.managedCredentialDefaults);
         let lastDiagnostic = -Infinity;
         const usage = new SemanticReferenceUsage(ctx.storageDomain, Date.now, () => {
             if (Date.now() - lastDiagnostic >= 30_000) {

package/lib/presentation/execution-policy.js

@@ -0,0 +1,5 @@
+/** Report-specific wall-clock budgets; leave time after source reads for publication. */
+export const PRESENTATION_EXECUTION_BUDGETS = Object.freeze({
+    sourceReadTimeoutMs: 120_000,
+    toolTimeoutMs: 180_000,
+});

package/lib/presentation/projection/index.js

@@ -1,6 +1,7 @@
 import { MarivoEnvironmentError } from "../../environment/errors.js";
 import { readPythonExecution } from "../../python-execution.js";
 import { PRESENTATION_BUDGETS, PresentationContractError, parsePresentationDocument, parsePresentationDraft, parseTypedDataset, } from "../contracts/index.js";
+import { PRESENTATION_EXECUTION_BUDGETS } from "../execution-policy.js";
 import { readWorkspaceJson } from "./files.js";
 import { MARIVO_PRESENTATION_READ_PROGRAM } from "./program.js";
 export { readWorkspaceJson } from "./files.js";
@@ -60,16 +61,32 @@ export class MarivoPresentationProjection {
         let diagnostics = [];
         const artifactData = new Map();
         if (draft.sources.length > 0) {
-            const result = await this.#runner.runChecked({
-                program: MARIVO_PRESENTATION_READ_PROGRAM,
-                args: [JSON.stringify({ sources: draft.sources, datasets: artifactSelections })],
-                limits: {
-                    timeoutMs: 30_000,
-                    stdoutMaxBytes: PRESENTATION_BUDGETS.documentBytes,
-                    stderrMaxBytes: 65_536,
-                },
-                signal: options.signal,
-            });
+            const startedAt = performance.now();
+            let result;
+            try {
+                result = await this.#runner.runChecked({
+                    program: MARIVO_PRESENTATION_READ_PROGRAM,
+                    args: [JSON.stringify({ sources: draft.sources, datasets: artifactSelections })],
+                    limits: {
+                        timeoutMs: PRESENTATION_EXECUTION_BUDGETS.sourceReadTimeoutMs,
+                        stdoutMaxBytes: PRESENTATION_BUDGETS.documentBytes,
+                        stderrMaxBytes: 65_536,
+                    },
+                    signal: options.signal,
+                });
+            }
+            catch (error) {
+                if (!(error instanceof MarivoEnvironmentError) || error.code !== 'subprocess-timeout')
+                    throw error;
+                // Construct only safe operation metadata; upstream messages/details may contain secrets.
+                throw new MarivoEnvironmentError('subprocess-timeout', 'Presentation source reading timed out. Source projection did not complete; report submission has not started. Keep the draft and source declarations for retry; do not remove sources or rerun analysis to repair presentation.', {
+                    phase: 'presentation-source-read',
+                    timeoutMs: PRESENTATION_EXECUTION_BUDGETS.sourceReadTimeoutMs,
+                    durationMs: Math.max(0, Math.round(performance.now() - startedAt)),
+                    sourceCount: draft.sources.length,
+                    sessionCount: new Set(draft.sources.map((source) => source.ref.sessionId)).size,
+                });
+            }
             this.#assertReady(options.signal);
             if (result.exitCode !== 0)
                 throw new MarivoEnvironmentError('subprocess-failed', 'The bound Marivo presentation read failed.', { exitCode: result.exitCode });

package/lib/presentation/tool.js

@@ -2,6 +2,7 @@ import { randomUUID } from 'node:crypto';
 import { defineTool } from '@deepseek-ai/dsh-tools';
 import { registerMarivoTool } from "../tool-lifecycle.js";
 import { parsePresentationBuildId } from "./contracts/index.js";
+import { PRESENTATION_EXECUTION_BUDGETS } from "./execution-policy.js";
 import { MARIVO_PRESENT_TOOL_NAME, MARIVO_PRESENTATION_DELIVERY_KIND, parsePresentationDelivery, presentationReceiptText, } from "./receipt.js";
 import { publishPresentation, resolvePresentation } from "./reports.js";
 /** One call projects a draft, builds the document, commits them, then emits the receipt. */
@@ -38,7 +39,7 @@ export function createMarivoPresentTool(source, session, lifecycleSignal) {
             ],
             presentationMeta: (_args, value) => JSON.parse(value.deliveryJson),
         },
-        timeoutMs: 120_000,
+        timeoutMs: PRESENTATION_EXECUTION_BUDGETS.toolTimeoutMs,
         async execute(args, exec) {
             const signal = lifecycleSignal ? AbortSignal.any([exec.signal, lifecycleSignal]) : exec.signal;
             if (typeof args.draft_path !== 'string' ||

package/lib/settings.js

@@ -1,21 +1,17 @@
-import z from '@deepseek-ai/schemastery';
 import { resolvePythonOptions } from "./datasource/python-options.js";
 export const PYTHON_SETTINGS_NAMESPACE = 'dsh-data-analysis';
-export const PythonSettings = z.object({
-    pythonTimeoutMs: z.number().min(1).max(2_147_483_647).step(1).required(),
-});
-/** Follow the Host settings provider; headless compositions retain their entry configuration. */
+export function currentPythonOptions(options) {
+    const value = options.pythonTimeoutMs;
+    return resolvePythonOptions({
+        pythonTimeoutMs: value !== null && typeof value === 'object' && typeof value.get === 'function'
+            ? value.get()
+            : value,
+    });
+}
+/** Config is projected by the Host settings service; a headless composition reads its live entry. */
 export function installPythonSettings(ctx, options) {
-    const entry = resolvePythonOptions(options);
-    let source = () => entry;
     const dispose = ctx.inject(['settings'], (settingsCtx) => {
-        settingsCtx.settings.installSection(ctx, PYTHON_SETTINGS_NAMESPACE, PythonSettings, entry, {
-            validate: resolvePythonOptions,
-            setSource: (current) => {
-                source = current;
-            },
-            onChange: () => { },
-        });
+        settingsCtx.effect(() => settingsCtx.settings.configure({ auto: false }, ctx.fiber));
     });
-    return { get: () => source(), dispose: () => dispose.dispose() };
+    return { get: () => currentPythonOptions(options), dispose: () => dispose.dispose() };
 }

package/lib/types/client/settings/card.d.ts

@@ -1,9 +1,9 @@
-import type { SettingsScope } from '@deepseek-ai/dsh-client-ui-settings/client';
+import type { ConfigForm } from '@deepseek-ai/dsh-client-ui-settings/client';
 export interface PythonSettingsValue {
     pythonTimeoutMs: number;
 }
 /** Seconds in the form, exact integer milliseconds at the Host boundary. */
 export declare function timeoutMilliseconds(text: string): number | undefined;
 export declare function PythonSettingsCard({ scope }: {
-    scope: SettingsScope<PythonSettingsValue>;
+    scope: ConfigForm<PythonSettingsValue>;
 }): import("react").JSX.Element | null;

package/lib/types/client.d.ts

@@ -3,6 +3,7 @@ import { installRightTabs } from './client/right-tabs/install.tsx';
 export { marivoPresentationDeliveryDefinition, parsePresentationDurableContent, presentationDeliveryFromEvent, presentationsForNode, } from './client/presentation/delivery.ts';
 export { PresentationDeliveryModel } from './client/presentation/delivery-model.ts';
 export { HostPresentationReader } from './client/presentation/host-entry.tsx';
+export { createPluginRpc } from './client/rpc.ts';
 export declare const inject: string[];
 export declare function apply(ctx: Context, options?: {
     diagnostics?: boolean;

package/lib/types/compatibility.d.ts

@@ -12,6 +12,7 @@ export interface DshDataAnalysisCompatibility {
     readonly contracts: {
         readonly runtimeInstallation: 'dsh-data-analysis-runtime/v3';
         readonly subprocessPolicy: 'direct-argv-inherited-env-snapshot-overlay-v2';
+        readonly integration: 'dsh-data-analysis-integration/v1';
     };
 }
 /** The package semver and the compatibility contract shipped in this exact installation. */

package/lib/types/datasource/defaults.d.ts

@@ -1,7 +1,8 @@
 import type { DatasourceAuthoring } from './authoring.ts';
 export type DatasourceDefaults = Record<string, Record<string, unknown>>;
+export type ManagedCredentialDefaults = Record<string, Record<string, string>>;
 export type DatasourceAuthoringView = DatasourceAuthoring & {
     creationDefaults?: DatasourceDefaults;
 };
 /** Validate against this Workspace's live Runtime; never include config values in errors. */
-export declare function withDatasourceDefaults(schema: DatasourceAuthoring, configured: unknown): DatasourceAuthoringView;
+export declare function withDatasourceDefaults(schema: DatasourceAuthoring, configured: unknown, managed?: ManagedCredentialDefaults): DatasourceAuthoringView;

package/lib/types/datasource/rpc.d.ts

@@ -1,5 +1,5 @@
 import type { HostConnectionHandle } from '@deepseek-ai/dsh-client-connection';
 import type { MarivoDatasourceBridgePort } from './bridge.ts';
-import { type DatasourceDefaults } from './defaults.ts';
+import { type DatasourceDefaults, type ManagedCredentialDefaults } from './defaults.ts';
 import { type MarivoCredentialService } from './service.ts';
-export declare function registerCredentialRpc(connection: HostConnectionHandle, service: MarivoCredentialService, workspace: (id: string) => Promise<MarivoDatasourceBridgePort>, datasourceDefaults?: DatasourceDefaults): () => Promise<void>;
+export declare function registerCredentialRpc(connection: HostConnectionHandle, service: MarivoCredentialService, workspace: (id: string) => Promise<MarivoDatasourceBridgePort>, datasourceDefaults?: DatasourceDefaults, managedCredentialDefaults?: ManagedCredentialDefaults): () => Promise<void>;

package/lib/types/disclosure/execution-guidance.d.ts

@@ -1,5 +1,13 @@
 import type { Agent } from '@deepseek-ai/dsh-agent';
 import type { MarivoDisclosureController } from './activation.ts';
+declare module '@deepseek-ai/dsh-llm' {
+    interface MessageSourceMap {
+        plugin: {
+            kind: 'plugin';
+            plugin: string;
+        };
+    }
+}
 export declare const MARIVO_DATASOURCE_CREDENTIAL_PROMPT: string;
 export declare const MARIVO_ANALYSIS_CLOSEOUT_PROMPT: string;
 /** Full-plugin seam: requires its execution tools, credentials service and system sections. */

package/lib/types/environment/errors.d.ts

@@ -1,4 +1,4 @@
-export type EnvironmentFailureCode = 'project-root-invalid' | 'python-path-relative' | 'python-unavailable' | 'shared-runtime-config-invalid' | 'shared-runtime-lock-timeout' | 'shared-runtime-install-failed' | 'shared-runtime-identity-mismatch' | 'shared-runtime-version-unsupported' | 'shared-runtime-pandas-unsupported' | 'shared-runtime-presentation-kit-unsupported' | 'shared-runtime-presentation-kit-wheel-invalid' | 'shared-runtime-presentation-kit-wheel-unavailable' | 'shared-runtime-package-unavailable' | 'shared-runtime-skills-invalid' | 'subprocess-start-failed' | 'subprocess-timeout' | 'subprocess-cancelled' | 'subprocess-output-limit' | 'subprocess-output-invalid' | 'subprocess-failed' | 'datasource-credential-ref-invalid' | 'datasource-credential-resolve-failed' | 'shell-credential-lease-invalid' | 'shell-credential-lease-expired' | 'shell-credential-lease-exhausted' | 'shell-credential-lease-scope-mismatch' | 'shell-credential-lease-resolve-failed' | 'shell-credential-injection-unsupported' | 'doctor-json-invalid' | 'doctor-admission-failed' | 'binding-identity-mismatch' | 'binding-failed';
+export type EnvironmentFailureCode = 'project-root-invalid' | 'python-path-relative' | 'python-unavailable' | 'shared-runtime-config-invalid' | 'shared-runtime-installation-required' | 'shared-runtime-lock-timeout' | 'shared-runtime-install-failed' | 'shared-runtime-identity-mismatch' | 'shared-runtime-version-unsupported' | 'shared-runtime-pandas-unsupported' | 'shared-runtime-presentation-kit-unsupported' | 'shared-runtime-presentation-kit-wheel-invalid' | 'shared-runtime-presentation-kit-wheel-unavailable' | 'shared-runtime-package-unavailable' | 'shared-runtime-skills-invalid' | 'subprocess-start-failed' | 'subprocess-timeout' | 'subprocess-cancelled' | 'subprocess-output-limit' | 'subprocess-output-invalid' | 'subprocess-failed' | 'datasource-credential-ref-invalid' | 'datasource-credential-resolve-failed' | 'shell-credential-lease-invalid' | 'shell-credential-lease-expired' | 'shell-credential-lease-exhausted' | 'shell-credential-lease-scope-mismatch' | 'shell-credential-lease-resolve-failed' | 'shell-credential-injection-unsupported' | 'doctor-json-invalid' | 'doctor-admission-failed' | 'binding-identity-mismatch' | 'binding-failed';
 /** Stable failure envelope for config, subprocess, doctor, and identity errors. */
 export declare class MarivoEnvironmentError extends Error {
     readonly code: EnvironmentFailureCode;

package/lib/types/environment/runtime.d.ts

@@ -7,6 +7,8 @@ export declare const PRESENTATION_KIT_PANDAS_RANGE = ">=2.2.0,<3.0.0";
 export declare const PRESENTATION_KIT_WHEEL_FILENAME = "dsh_data_analysis_presentation_kit-1.1.0-py3-none-any.whl";
 export declare const DEFAULT_SHARED_RUNTIME_INSTALL_TIMEOUT_MS = 600000;
 interface RuntimeInstallOptions {
+    /** Validate an existing installation without creating directories or acquiring an install lock. */
+    existingOnly?: boolean;
     environment?: NodeJS.ProcessEnv;
     waitIntervalMs?: number;
     /** Test/build seam; production always resolves the wheel distributed beside the plugin. */

package/lib/types/environment/workspace.d.ts

@@ -4,7 +4,8 @@ import type { SharedMarivoRuntime } from './types.ts';
 export declare class MarivoWorkspaceEnvironmentManager {
     #private;
     readonly runtime: SharedMarivoRuntime;
-    constructor(runtime: SharedMarivoRuntime);
+    readonly onBound?: (environment: MarivoEnvironment) => Promise<void>;
+    constructor(runtime: SharedMarivoRuntime, onBound?: (environment: MarivoEnvironment) => Promise<void>);
     resolve(projectRoot: string): Promise<MarivoEnvironment>;
     close(): Promise<void>;
     dispose(): void;

package/lib/types/integration.d.ts

@@ -0,0 +1,16 @@
+import type { ManagedCredentialDefaults } from './datasource/defaults.ts';
+import type { CredentialStore } from './datasource/service.ts';
+import type { MarivoEnvironment } from './environment/index.ts';
+/** Public extension seam. The version denotes this shape, not a specific consumer. */
+export declare const INTEGRATION_CONTRACT_VERSION: "dsh-data-analysis-integration/v1";
+export interface MarivoIntegrationV1 {
+    /** Runs once after a Workspace binds, before its environment is returned. */
+    readonly onWorkspaceBound?: (environment: MarivoEnvironment) => Promise<void>;
+    /** Harness-managed store used only by datasource operations. */
+    readonly datasourceCredentials?: CredentialStore;
+    /** Credential reference names, validated against the live Workspace Runtime schema. */
+    readonly managedCredentialDefaults?: ManagedCredentialDefaults;
+}
+export { withDatasourceDefaults } from './datasource/defaults.ts';
+export { applyWithIntegration } from './plugin.ts';
+export { registerPluginRpc } from './rpc.ts';

package/lib/types/plugin.d.ts

@@ -1,17 +1,18 @@
 import { type ReportPublishingConfig } from './report-publishing/config.ts';
+import { type PythonTimeoutConfig } from './settings.ts';
 export { installMarivoPlugin, type MarivoPluginEnvironmentResolver } from './plugin-agents.ts';
 export { resolvePresentationWorkspace } from './workspace-identity.ts';
 import type { Context } from '@deepseek-ai/cordis';
 import z from '@deepseek-ai/schemastery';
 import type { DatasourceDefaults } from './datasource/defaults.ts';
-import { type MarivoPythonOptions } from './datasource/python-options.ts';
+import type { MarivoIntegrationV1 } from './integration.ts';
 export { MARIVO_DATASOURCE_CREDENTIAL_PROMPT } from './disclosure/execution-guidance.ts';
 /** Cordis plugin name used by loader diagnostics and lifecycle logs. */
 export declare const name = "dsh-data-analysis";
 /** Services that must exist before the plugin binds and watches Agent scopes. */
 export declare const inject: string[];
 /** Loader-safe configuration for the shared Runtime and per-Workspace bindings. */
-export interface Config extends MarivoPythonOptions {
+export interface Config extends PythonTimeoutConfig {
     readonly reportPublishing?: ReportPublishingConfig;
     /** Non-secret creation defaults by backend; checked against each live Runtime schema. */
     readonly datasourceDefaults?: DatasourceDefaults;
@@ -28,6 +29,28 @@ export interface Config extends MarivoPythonOptions {
     readonly installTimeoutMs?: number;
 }
 /** Cordis loader schema. Runtime defaults are resolved in {@link apply}. */
-export declare const Config: z<Config>;
+export declare const Config: z<Schemastery.ObjectS<NoInfer<{
+    datasourceDefaults: z<any, any, "plain">;
+    reportPublishing: z<any, any, "plain">;
+    pythonTimeoutMs: z<number, number, "volatile-defined">;
+    credentialInteraction: z<"none" | "web", "none" | "web", "defined">;
+    projectRoot: z<string, string, "plain">;
+    pythonExecutable: z<string, string, "plain">;
+    runtimeRoot: z<string, string, "plain">;
+    bootstrapPythonExecutable: z<string, string, "plain">;
+    installTimeoutMs: z<number, number, "defined">;
+}>>, Schemastery.ObjectT<NoInfer<{
+    datasourceDefaults: z<any, any, "plain">;
+    reportPublishing: z<any, any, "plain">;
+    pythonTimeoutMs: z<number, number, "volatile-defined">;
+    credentialInteraction: z<"none" | "web", "none" | "web", "defined">;
+    projectRoot: z<string, string, "plain">;
+    pythonExecutable: z<string, string, "plain">;
+    runtimeRoot: z<string, string, "plain">;
+    bootstrapPythonExecutable: z<string, string, "plain">;
+    installTimeoutMs: z<number, number, "defined">;
+}>>, "plain">;
 /** Ensure the shared Runtime once, mount its skills, then bind each Workspace lazily. */
 export declare function apply(ctx: Context, config?: Config): Promise<() => Promise<void>>;
+/** Compose an extension at the public seam while retaining the ordinary plugin behavior. */
+export declare function applyWithIntegration(ctx: Context, config?: Config, integration?: MarivoIntegrationV1): Promise<() => Promise<void>>;

package/lib/types/presentation/execution-policy.d.ts

@@ -0,0 +1,5 @@
+/** Report-specific wall-clock budgets; leave time after source reads for publication. */
+export declare const PRESENTATION_EXECUTION_BUDGETS: Readonly<{
+    sourceReadTimeoutMs: 120000;
+    toolTimeoutMs: 180000;
+}>;

package/lib/types/rpc.d.ts

@@ -1,3 +1,3 @@
 /** Dedicated plugin RPC envelopes over Harness-owned authenticated exact Fetch routes. */
-import { type ConnectionRpcHandler, type HostConnectionHandle } from '@deepseek-ai/dsh-client-connection';
-export declare function registerPluginRpc(connection: Pick<HostConnectionHandle, 'fetch'>, channel: string, endpoints: readonly string[], handler: ConnectionRpcHandler): () => Promise<void>;
+import { type ConnectionRpcHandlerResult, type HostConnectionHandle } from '@deepseek-ai/dsh-client-connection';
+export declare function registerPluginRpc(connection: Pick<HostConnectionHandle, 'fetch'>, channel: string, endpoints: readonly string[], handler: (endpoint: string, payload: unknown, signal: AbortSignal) => Promise<ConnectionRpcHandlerResult>): () => Promise<void>;

package/lib/types/semantic-reference/rpc.d.ts

@@ -1,4 +1,4 @@
-import type { ConnectionRpcHandler, HostConnectionHandle } from '@deepseek-ai/dsh-client-connection';
+import type { ConnectionRpcHandlerResult, HostConnectionHandle } from '@deepseek-ai/dsh-client-connection';
 import type { MarivoCheckedRunner } from '../environment/types.ts';
 import { SemanticReferenceBridge } from './bridge.ts';
 import { type SemanticReferenceUsage } from './usage.ts';
@@ -12,4 +12,4 @@ export declare class SemanticReferenceService {
     stop(): void;
     close(): Promise<void>;
 }
-export declare function registerSemanticReferenceRpc(connection: HostConnectionHandle, service: SemanticReferenceService, browser?: ConnectionRpcHandler): () => Promise<void>;
+export declare function registerSemanticReferenceRpc(connection: HostConnectionHandle, service: SemanticReferenceService, browser?: (endpoint: string, payload: unknown, signal: AbortSignal) => Promise<ConnectionRpcHandlerResult>): () => Promise<void>;

package/lib/types/settings.d.ts

@@ -1,14 +1,14 @@
 import type { Context } from '@deepseek-ai/cordis';
-import z from '@deepseek-ai/schemastery';
 import { type MarivoPythonOptions } from './datasource/python-options.ts';
 export declare const PYTHON_SETTINGS_NAMESPACE = "dsh-data-analysis";
-export declare const PythonSettings: z<Schemastery.ObjectS<{
-    pythonTimeoutMs: z<number, number>;
-}>, Schemastery.ObjectT<{
-    pythonTimeoutMs: z<number, number>;
-}>>;
-/** Follow the Host settings provider; headless compositions retain their entry configuration. */
-export declare function installPythonSettings(ctx: Context, options: MarivoPythonOptions): {
+export interface PythonTimeoutConfig {
+    pythonTimeoutMs?: number | {
+        get(): number;
+    };
+}
+export declare function currentPythonOptions(options: PythonTimeoutConfig): Required<MarivoPythonOptions>;
+/** Config is projected by the Host settings service; a headless composition reads its live entry. */
+export declare function installPythonSettings(ctx: Context, options: PythonTimeoutConfig): {
     get: () => Required<MarivoPythonOptions>;
     dispose: () => Promise<void>;
 };