@chengxianglibra/dsh-data-analysis 0.1.1 → 0.2.0

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

@@ -0,0 +1,155 @@
+import type { Agent } from '@deepseek-ai/dsh-agent';
+import { type CredentialProvider } from '@deepseek-ai/dsh-credentials';
+import type { ToolExecution } from '@deepseek-ai/dsh-tools';
+import type { JsonValue } from '@deepseek-ai/dsh-util-values';
+import type { DatasourceCreateInput, DatasourceUpdateInput } from './authoring.ts';
+import type { MarivoDatasourceBridgePort, MarivoDatasourceDescription, MarivoDatasourceTestResult } from './bridge.ts';
+export declare const CREDENTIAL_CHANNEL = "/dsh-data-analysis-credentials";
+export type CredentialStore = Pick<CredentialProvider, 'describe' | 'resolve' | 'set' | 'unset'>;
+export type CredentialAction = 'save' | 'update' | 'delete' | 'delete-datasource' | 'test' | 'submit' | 'diagnose';
+export interface CredentialContextView {
+    token: string;
+    workspaceId: string;
+    name: string;
+    backend: string;
+    properties: Record<string, JsonValue>;
+    refs: string[];
+    fields: Record<string, string>;
+    version: string;
+    credentials: Record<string, {
+        configured: boolean;
+        source?: string;
+        writable: boolean;
+    }>;
+    lastTest?: {
+        at: number;
+        result: MarivoDatasourceTestResult;
+        stale: boolean;
+    };
+}
+export interface CredentialRequestView {
+    id: string;
+    sessionId: string;
+    context: CredentialContextView;
+    status: 'awaiting-input' | 'executing' | 'awaiting-decision' | 'succeeded' | 'handed-off' | 'call-ended' | 'cancelled' | 'context-changed';
+    failure?: MarivoDatasourceTestResult;
+    endedAt?: number;
+}
+export interface DatasourceConfigureInput {
+    mode: 'create' | 'edit';
+    name?: string;
+    reason: string;
+}
+export interface ConfigurationRequestView extends Omit<CredentialRequestView, 'context'> {
+    configuration: DatasourceConfigureInput;
+    workspaceId: string;
+    context?: CredentialContextView;
+}
+interface PendingConfiguration {
+    view: ConfigurationRequestView;
+    settled: boolean;
+    controller: AbortController;
+    exec: ToolExecution;
+    resolve: () => Promise<MarivoDatasourceBridgePort>;
+    fingerprint: string;
+    sessionIdentity: string;
+    signal: AbortSignal;
+    finish: (value: ConfigurationResult) => void;
+    stop: () => void;
+}
+export interface ConfigurationResult {
+    status: 'ok' | 'failed' | 'cancelled' | 'call-ended' | 'context-changed' | 'needs-configuration';
+    name?: string;
+    latency_ms?: number | null;
+    failure?: MarivoDatasourceTestResult['failure'];
+    repair?: MarivoDatasourceTestResult['repair'];
+}
+export interface CredentialOperationView {
+    id: string;
+    scope: string;
+    action: CredentialAction;
+    status: 'running' | 'succeeded' | 'failed' | 'cancelled';
+    phase: 'saving' | 'removing' | 'validating' | 'settled';
+    deleteCredentials?: boolean;
+    datasourceRemoved?: boolean;
+    deletedCredentials?: string[];
+    credentialDeleteFailures?: string[];
+    saved: string[];
+    errors: string[];
+    result?: MarivoDatasourceTestResult;
+    endedAt?: number;
+}
+export interface CredentialNeedsInput {
+    status: 'needs-credentials';
+    name: string;
+    refs: string[];
+}
+export interface PreparedCredentialExecution {
+    status: 'ready';
+    values: Record<string, string>;
+    grants: Record<string, MarivoDatasourceDescription>;
+    bridge: MarivoDatasourceBridgePort;
+    signal: AbortSignal;
+    /** Call synchronously immediately before starting the resolved Shell request. */
+    assertCurrent: () => void;
+    /** Forget values and stop operation-scoped credential tracking. */
+    release: () => void;
+}
+export declare class CredentialServiceError extends Error {
+    readonly code: string;
+    constructor(code: string);
+}
+export declare function credentialError(error: unknown): string;
+/** Owns only plugin operations and execution-scoped waits. No value cache or datasource registry. */
+export declare class MarivoCredentialService {
+    #private;
+    readonly generation: `${string}-${string}-${string}-${string}-${string}`;
+    readonly interaction: 'web' | 'none';
+    readonly now: () => number;
+    constructor(store: CredentialStore, interaction?: 'web' | 'none', now?: () => number);
+    executionSignal(caller: AbortSignal, agent?: Agent): AbortSignal;
+    invalidateStorageRef(storageRef: string): void;
+    invalidate(refs: readonly string[]): void;
+    overview(workspaceId: string, resolve: () => Promise<MarivoDatasourceBridgePort>, caller: AbortSignal): Promise<CredentialContextView[]>;
+    createDatasource(generation: string, fingerprint: string, input: DatasourceCreateInput, resolve: () => Promise<MarivoDatasourceBridgePort>, caller: AbortSignal): Promise<{
+        name: string;
+    }>;
+    updateDatasource(generation: string, fingerprint: string, input: DatasourceUpdateInput, resolve: () => Promise<MarivoDatasourceBridgePort>, caller: AbortSignal): Promise<{
+        name: string;
+    }>;
+    configure(exec: ToolExecution, resolve: () => Promise<MarivoDatasourceBridgePort>, input: DatasourceConfigureInput): Promise<ConfigurationResult>;
+    configurationRequest(id: string, workspaceId: string, resolve: () => Promise<MarivoDatasourceBridgePort>, caller: AbortSignal): Promise<PendingConfiguration>;
+    selectConfiguration(id: string, workspaceId: string, name: string, resolve: () => Promise<MarivoDatasourceBridgePort>, caller: AbortSignal): Promise<ConfigurationRequestView>;
+    prepare(_kind: 'test', exec: ToolExecution, resolve: () => Promise<MarivoDatasourceBridgePort>, name: string): Promise<MarivoDatasourceTestResult | CredentialNeedsInput>;
+    prepareExecution(exec: ToolExecution, resolve: () => Promise<MarivoDatasourceBridgePort>, names: string[]): Promise<PreparedCredentialExecution | CredentialNeedsInput | MarivoDatasourceTestResult>;
+    watch(sessionId: string, cursor?: string): {
+        generation: string;
+        cursor: string;
+        requests: CredentialRequestView[];
+        configurationRequests: ConfigurationRequestView[];
+    };
+    waitWatch(sessionId: string, cursor: string | undefined, signal: AbortSignal): Promise<{
+        generation: string;
+        cursor: string;
+        requests: CredentialRequestView[];
+        configurationRequests: ConfigurationRequestView[];
+    }>;
+    operation(generation: string, id: string, scope: string): CredentialOperationView | undefined;
+    start(input: {
+        generation: string;
+        id: string;
+        scope: string;
+        action: CredentialAction;
+        version: string;
+        requestId?: string;
+        changes?: Record<string, string>;
+        reference?: string;
+        deleteCredentials?: boolean;
+    }): CredentialOperationView;
+    cancelOperation(generation: string, id: string, scope: string): void;
+    cancelRequest(id: string): void;
+    disposeAgent(agent: Agent): void;
+    track<T>(task: Promise<T>): Promise<T>;
+    close(): Promise<void>;
+}
+export {};

package/lib/types/datasource/shell-env.d.ts

@@ -1,38 +1,9 @@
 import type { Context } from '@deepseek-ai/cordis';
-import type { Agent } from '@deepseek-ai/dsh-agent';
-import { type CredentialProvider } from '@deepseek-ai/dsh-credentials';
-import type { ToolExecution } from '@deepseek-ai/dsh-tools';
-import { type MarivoDatasourceBridgePort, type MarivoDatasourceBridgeSource } from './bridge.ts';
 export declare const MARIVO_CREDENTIAL_STORAGE_PREFIX = "DSH_DATA_ANALYSIS_CREDENTIAL_";
-export declare const MARIVO_CREDENTIAL_LEASE_PREFIX = "# dsh-marivo-credential-lease:";
-export declare const DEFAULT_MARIVO_CREDENTIAL_LEASE_TTL_MS: number;
-export declare const DEFAULT_MARIVO_CREDENTIAL_LEASE_MAX_USES = 64;
 type MarivoCredentialStorageRefName = `DSH_DATA_ANALYSIS_CREDENTIAL_${string}`;
-export interface MarivoShellLeaseReceipt {
-    [key: string]: string | number;
-    token: string;
-    expires_in_ms: number;
-    max_uses: number;
-    usage: 'bounded-foreground-shell-lease';
-    bash_prelude: string;
-    pwsh_prelude: string;
-}
 /** Publish the exact shared interpreter as a non-secret, per-execution DSH fact. */
 export declare function registerMarivoRuntimeShellEnvironment(ctx: Context, pythonExecutable: string): () => void;
 /** Map one user-authored datasource environment reference to plugin-owned DSH storage. */
 export declare function marivoCredentialStorageRef(ref: string): MarivoCredentialStorageRefName;
 export declare function assertMarivoCredentialReferences(refs: readonly string[]): void;
-/** Own bounded leases and expose credential values only to each admitted Shell execution. */
-export declare class MarivoShellCredentialLeases {
-    #private;
-    constructor(ctx: Context, credentials: Pick<CredentialProvider, 'resolve'>, options?: {
-        ttlMs?: number;
-        maxUses?: number;
-    });
-    revokeLease(agent: Agent, bridge: MarivoDatasourceBridgePort, datasourceName: string): void;
-    issueLease(agent: Agent, bridge: MarivoDatasourceBridgePort, datasourceName: string, refs: readonly string[]): MarivoShellLeaseReceipt;
-    prepareExecution(agent: Agent, bridgeSource: MarivoDatasourceBridgeSource, execution: ToolExecution): Promise<boolean>;
-    installAgent(agent: Agent, bridgeSource: MarivoDatasourceBridgeSource): () => void;
-    dispose(): void;
-}
 export {};

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

@@ -1,32 +1,9 @@
 import type { Context } from '@deepseek-ai/cordis';
-import type { CredentialProvider } from '@deepseek-ai/dsh-credentials';
-import type { JsonValue } from '@deepseek-ai/dsh-session';
 import { type ToolDefinition } from '@deepseek-ai/dsh-tools';
-import { type MarivoDatasourceBridgePort, type MarivoDatasourceBridgeSource, type MarivoDatasourceFailure, type MarivoDatasourceRepair } from './bridge.ts';
+import { type MarivoDatasourceBridgeSource } from './bridge.ts';
+import type { MarivoCredentialService } from './service.ts';
 export declare const MARIVO_DATASOURCE_TEST_TOOL_NAME = "marivo_datasource_test";
-interface JsonObject {
-    [key: string]: JsonValue;
-}
-export type MarivoDatasourceTestValue = ({
-    status: 'needs-credentials';
-    name: string;
-    refs: string[];
-} & JsonObject) | ({
-    status: 'ok';
-    name: string;
-    latency_ms: number | null;
-} & JsonObject) | ({
-    status: 'failed';
-    name: string;
-    latency_ms: number | null;
-    failure: MarivoDatasourceFailure;
-    repair: MarivoDatasourceRepair;
-} & JsonObject);
-export interface MarivoDatasourceTestOptions {
-    /** Explicit validation invalidates prior access for this Agent and datasource. */
-    revokeShellLease(bridge: MarivoDatasourceBridgePort, name: string): void;
-}
-/** Build the scoped datasource connection-test Tool. */
-export declare function createMarivoDatasourceTestTool(bridgeSource: MarivoDatasourceBridgeSource, credentials: Pick<CredentialProvider, 'resolve'>, options: MarivoDatasourceTestOptions): ToolDefinition;
-export declare function registerMarivoDatasourceTestTool(ctx: Context, bridgeSource: MarivoDatasourceBridgeSource, credentials: Pick<CredentialProvider, 'resolve'>, options: MarivoDatasourceTestOptions): () => void;
-export {};
+export declare function createMarivoDatasourceTestTool(source: MarivoDatasourceBridgeSource, service: MarivoCredentialService): ToolDefinition;
+export declare function registerMarivoDatasourceTestTool(ctx: Context, source: MarivoDatasourceBridgeSource, service: MarivoCredentialService): () => Promise<void>;
+/** Preserve the datasource tools' public status family; raw Marivo results stay inside the service. */
+export declare function datasourceToolValue(result: Awaited<ReturnType<MarivoCredentialService['prepare']>>): any;

package/lib/types/disclosure/activation.d.ts

@@ -63,11 +63,12 @@ export declare class MarivoDisclosureController {
     constructor(agent: Agent, bridgeSource: MarivoHelpBridgeSource, options?: MarivoDisclosureOptions);
     get activeSkills(): readonly MarivoSkillName[];
     telemetry(): MarivoDisclosureTelemetry;
-    addDisposer(disposer: () => void): void;
+    addDisposer(disposer: () => unknown): void;
     observeToolResult(exec: Readonly<ToolExecution>, result: Readonly<ToolExecutionResult>): void;
     resolveDelivery(query: Readonly<MarivoHelpDeliveryQuery>): MarivoHelpDelivery;
     prepareStep(messages: readonly UserMessage[], signal: AbortSignal): Promise<UserMessage[]>;
     dispose(): void;
+    close(): Promise<void>;
 }
 /** Install skill-triggered Marivo live-help disclosure for one Agent scope. */
 export declare function installMarivoDisclosure(_ctx: Context, agent: Agent, bridgeSource: MarivoHelpBridgeSource, options?: MarivoDisclosureOptions): MarivoDisclosureController;

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

@@ -0,0 +1,6 @@
+import type { Agent } from '@deepseek-ai/dsh-agent';
+import type { MarivoDisclosureController } from './activation.ts';
+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. */
+export declare function installMarivoExecutionGuidance(agent: Agent, controller: MarivoDisclosureController): () => void;

package/lib/types/disclosure/help.d.ts

@@ -61,4 +61,4 @@ export declare function readMarivoHelpTargets(bridge: MarivoHelpBridgePort, rawT
 /** Build the native Harness ToolDefinition without registering Agent activation behavior. */
 export declare function createMarivoHelpTool(bridgeSource: MarivoHelpBridgeSource, limitOverrides?: Partial<MarivoHelpLimits>, resolveDelivery?: MarivoHelpDeliveryResolver): ToolDefinition;
 /** Register the focused Help Tool; skill-triggered root disclosure is composed separately. */
-export declare function registerMarivoHelpTool(ctx: Context, bridgeSource: MarivoHelpBridgeSource, limits?: Partial<MarivoHelpLimits>, resolveDelivery?: MarivoHelpDeliveryResolver): () => void;
+export declare function registerMarivoHelpTool(ctx: Context, bridgeSource: MarivoHelpBridgeSource, limits?: Partial<MarivoHelpLimits>, resolveDelivery?: MarivoHelpDeliveryResolver): () => Promise<void>;

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

@@ -16,11 +16,15 @@ export declare class MarivoEnvironment {
     assertImportIdentity(signal?: AbortSignal): Promise<ImportIdentity>;
 }
 /** Build an identity-checked Help runner directly from an admitted shared Runtime. */
-export declare function createSharedMarivoRuntimeRunner(runtime: Pick<SharedMarivoRuntime, 'runtimeRoot' | 'pythonExecutable' | 'marivoVersion' | 'packagePath'>, options?: {
+export declare function createSharedMarivoRuntimeRunner(runtime: Pick<SharedMarivoRuntime, 'runtimeRoot' | 'pythonExecutable' | 'marivoVersion' | 'packagePath' | 'presentationKitVersion' | 'presentationKitPackagePath'>, options?: {
     environment?: NodeJS.ProcessEnv;
 }): MarivoEnvironment;
 /** Resolve, probe, and establish one Marivo Environment Binding. */
 export declare function bindMarivoEnvironment(config: MarivoEnvironmentConfig, options?: {
     environment?: NodeJS.ProcessEnv;
     signal?: AbortSignal;
+    presentationKit?: Readonly<{
+        version: string;
+        packagePath: string;
+    }>;
 }): Promise<MarivoEnvironment>;

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-report-kit-unsupported' | 'shared-runtime-report-kit-wheel-invalid' | 'shared-runtime-report-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-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

@@ -1,16 +1,16 @@
 import type { SharedMarivoRuntime, SharedMarivoRuntimeConfig } from './types.ts';
 export declare const SHARED_PYTHON_SPEC = "3.10";
 export declare const SHARED_MARIVO_PACKAGE_SPEC: string;
-export declare const REPORT_KIT_DISTRIBUTION = "dsh-data-analysis-report-kit";
-export declare const REPORT_KIT_VERSION = "3.0.0";
-export declare const REPORT_KIT_PANDAS_RANGE = ">=2.2.0,<3.0.0";
-export declare const REPORT_KIT_WHEEL_FILENAME = "dsh_data_analysis_report_kit-3.0.0-py3-none-any.whl";
+export declare const PRESENTATION_KIT_DISTRIBUTION = "dsh-data-analysis-presentation-kit";
+export declare const PRESENTATION_KIT_VERSION = "1.1.0";
+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 {
     environment?: NodeJS.ProcessEnv;
     waitIntervalMs?: number;
     /** Test/build seam; production always resolves the wheel distributed beside the plugin. */
-    reportKitWheelPath?: string;
+    presentationKitWheelPath?: string;
 }
 /** Ensure and validate the one DSH-home-owned Marivo installation. */
 export declare function ensureSharedMarivoRuntime(config?: SharedMarivoRuntimeConfig, options?: RuntimeInstallOptions): Promise<SharedMarivoRuntime>;

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

@@ -7,7 +7,8 @@ export interface MarivoEnvironmentConfig {
 export interface SharedMarivoRuntimeConfig {
     runtimeRoot?: string;
     pythonExecutable?: string;
-    uvExecutable?: string;
+    /** Absolute local Python for venv creation; defaults to python3 (Windows: python). */
+    bootstrapPythonExecutable?: string;
     installTimeoutMs?: number;
 }
 /** Validated identity and stable skill root of the shared Marivo installation. */
@@ -16,8 +17,8 @@ export interface SharedMarivoRuntime {
     pythonExecutable: string;
     marivoVersion: string;
     packagePath: string;
-    reportKitVersion: string;
-    reportKitPackagePath: string;
+    presentationKitVersion: string;
+    presentationKitPackagePath: string;
     skillsRoot: string;
     installationPath: string;
 }
@@ -50,6 +51,11 @@ export interface MarivoEnvironmentBinding {
     pythonExecutable: string;
     marivoVersion: string;
     packagePath: string;
+    /** Present only for bindings admitted through the shared presentation Runtime. */
+    presentationKit?: Readonly<{
+        version: string;
+        packagePath: string;
+    }>;
     subprocessPolicyId: string;
     fingerprint: string;
 }
@@ -60,6 +66,8 @@ export interface SubprocessLimits {
     terminateGraceMs: number;
 }
 export interface SubprocessRequest {
+    /** Host-only pipe input. Never part of argv or the environment. */
+    stdin?: string;
     executable: string;
     args: readonly string[];
     /** Per-call environment values layered over the frozen binding snapshot. */
@@ -69,6 +77,10 @@ export interface SubprocessRequest {
 }
 /** One identity-checked Python operation executed by a bound Environment. */
 export interface MarivoCheckedRunRequest {
+    /** Host-only pipe input; callers own its short operation lifetime. */
+    stdin?: string;
+    /** Values to redact from captured output, never passed through the environment. */
+    secretValues?: readonly string[];
     program: string;
     args?: readonly string[];
     /** Per-operation values; every non-empty value is redacted from captured output. */

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

@@ -6,5 +6,6 @@ export declare class MarivoWorkspaceEnvironmentManager {
     readonly runtime: SharedMarivoRuntime;
     constructor(runtime: SharedMarivoRuntime);
     resolve(projectRoot: string): Promise<MarivoEnvironment>;
+    close(): Promise<void>;
     dispose(): void;
 }

package/lib/types/index.d.ts

@@ -4,6 +4,6 @@ export * from './compatibility.ts';
 export * from './datasource/index.ts';
 export * from './disclosure/index.ts';
 export * from './environment/index.ts';
-export * from './evidence/index.ts';
 export type { Config as PluginConfig } from './plugin.ts';
 export { apply, Config, inject, installMarivoPlugin, name } from './plugin.ts';
+export * from './presentation/index.ts';

package/lib/types/lifecycle.d.ts

@@ -0,0 +1,8 @@
+/** Tracks owned work, including work whose caller stopped waiting after cancellation. */
+export declare class PendingTasks {
+    #private;
+    track<T>(task: Promise<T>): Promise<T>;
+    drain(): Promise<void>;
+}
+/** Start every stop synchronously, then await every cleanup even if another one fails. */
+export declare function finishCleanup(actions: readonly (() => unknown)[]): Promise<void>;

package/lib/types/plugin-agents.d.ts

@@ -0,0 +1,27 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { Agent } from '@deepseek-ai/dsh-agent';
+import { type MarivoPythonOptions } from './datasource/python-options.ts';
+import { type CredentialStore, MarivoCredentialService } from './datasource/service.ts';
+import type { MarivoHelpBridgeSource } from './disclosure/bridge.ts';
+import { type MarivoDisclosureOptions } from './disclosure/index.ts';
+import { MarivoEnvironment } from './environment/index.ts';
+import type { ReportPublishingService } from './report-publishing/service.ts';
+export type MarivoPluginEnvironmentResolver = (agent: Agent) => MarivoEnvironment | Promise<MarivoEnvironment>;
+/**
+ * Install one already-bound environment into every live or subsequently published Agent scope.
+ * Installation is transactional for existing Agents and is disposed with the Cordis plugin.
+ */
+export declare function createMarivoAgentInstallation(ctx: Context, environmentOrResolver: MarivoEnvironment | MarivoPluginEnvironmentResolver, options?: MarivoDisclosureOptions & MarivoPythonOptions & {
+    /** Override used by focused tests; normal plugin installation uses ctx.credentials. */
+    reportPublishing?: ReportPublishingService;
+    credentials?: CredentialStore;
+    credentialService?: MarivoCredentialService;
+    credentialInteraction?: 'web' | 'none';
+    /** Runtime-scoped Help source; normal plugin installation never binds Help to a Workspace. */
+    helpBridgeSource?: MarivoHelpBridgeSource;
+}): {
+    install(): void;
+    close: () => Promise<void>;
+};
+/** Stops synchronously; the returned Promise also waits for all owned work. */
+export declare function installMarivoPlugin(...args: Parameters<typeof createMarivoAgentInstallation>): () => Promise<void>;

package/lib/types/plugin.d.ts

@@ -1,43 +1,33 @@
-/** Cordis lifecycle adapter for the Web-profile shared Marivo Runtime. */
+import { type ReportPublishingConfig } from './report-publishing/config.ts';
+export { installMarivoPlugin, type MarivoPluginEnvironmentResolver } from './plugin-agents.ts';
+export { resolvePresentationWorkspace } from './workspace-identity.ts';
 import type { Context } from '@deepseek-ai/cordis';
-import type { Agent } from '@deepseek-ai/dsh-agent';
-import type { CredentialProvider } from '@deepseek-ai/dsh-credentials';
 import z from '@deepseek-ai/schemastery';
-import { type MarivoHelpBridgeSource } from './disclosure/bridge.ts';
-import { type MarivoDisclosureOptions } from './disclosure/index.ts';
-import { MarivoEnvironment } from './environment/index.ts';
+import type { DatasourceDefaults } from './datasource/defaults.ts';
+import { type MarivoPythonOptions } from './datasource/python-options.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[];
-export declare const MARIVO_DATASOURCE_CREDENTIAL_PROMPT: string;
-export declare const MARIVO_EVIDENCE_SOURCES_PROMPT: string;
-export declare const MARIVO_REPORT_PROMPT: string;
 /** Loader-safe configuration for the shared Runtime and per-Workspace bindings. */
-export interface Config {
+export interface Config extends MarivoPythonOptions {
+    readonly reportPublishing?: ReportPublishingConfig;
+    /** Non-secret creation defaults by backend; checked against each live Runtime schema. */
+    readonly datasourceDefaults?: DatasourceDefaults;
+    readonly credentialInteraction?: 'web' | 'none';
     /** Explicit project root override; otherwise each Agent uses session.header.cwd. */
     readonly projectRoot?: string;
     /** Administrator-provided shared interpreter; must already contain an importable Marivo. */
     readonly pythonExecutable?: string;
     /** Shared Runtime root; defaults below $DSH_HOME. */
     readonly runtimeRoot?: string;
-    /** Local uv executable; an explicit value must be absolute. */
-    readonly uvExecutable?: string;
+    /** Local Python used to create the managed venv; an explicit value must be absolute. */
+    readonly bootstrapPythonExecutable?: string;
     /** Maximum time for installation and lock acquisition. */
     readonly installTimeoutMs?: number;
 }
 /** Cordis loader schema. Runtime defaults are resolved in {@link apply}. */
 export declare const Config: z<Config>;
-export type MarivoPluginEnvironmentResolver = (agent: Agent) => MarivoEnvironment | Promise<MarivoEnvironment>;
-/**
- * Install one already-bound environment into every live or subsequently published Agent scope.
- * Installation is transactional for existing Agents and is disposed with the Cordis plugin.
- */
-export declare function installMarivoPlugin(ctx: Context, environmentOrResolver: MarivoEnvironment | MarivoPluginEnvironmentResolver, options?: MarivoDisclosureOptions & {
-    /** Override used by focused tests; normal plugin installation uses ctx.credentials. */
-    credentials?: Pick<CredentialProvider, 'resolve'>;
-    /** Runtime-scoped Help source; normal plugin installation never binds Help to a Workspace. */
-    helpBridgeSource?: MarivoHelpBridgeSource;
-}): () => void;
 /** Ensure the shared Runtime once, mount its skills, then bind each Workspace lazily. */
-export declare function apply(ctx: Context, config?: Config): Promise<() => void>;
+export declare function apply(ctx: Context, config?: Config): Promise<() => Promise<void>>;

package/lib/types/presentation/asset.d.ts

@@ -0,0 +1,6 @@
+import { type PresentationAsset, type PresentationReceipt } from './contracts/index.ts';
+/** Read a fixed, receipt-verified snapshot; never access analysis or current. */
+export declare function readReceiptAsset(root: string, workspaceId: string, receipt: PresentationReceipt, asset: PresentationAsset, signal: AbortSignal): Promise<{
+    bytes: Buffer<ArrayBufferLike>;
+    sha256: string;
+}>;

package/lib/types/presentation/build/index.d.ts

@@ -0,0 +1,16 @@
+import { type PresentationDocument } from '../contracts/index.ts';
+export interface BuiltPresentation {
+    document: PresentationDocument;
+    documentBytes: Buffer;
+    htmlBytes?: Buffer;
+}
+/**
+ * Render an S2 snapshot without reading source data, generating identity, or writing files.
+ * Both renderers are built into the installed package; execution needs no build tooling.
+ */
+export declare function buildPresentation(value: PresentationDocument): Promise<BuiltPresentation & {
+    htmlBytes: Buffer;
+}>;
+export declare function buildPresentation(value: PresentationDocument, options: {
+    html?: boolean;
+}): Promise<BuiltPresentation>;

package/lib/types/presentation/commit.d.ts

@@ -0,0 +1,4 @@
+import type { BuiltPresentation } from './build/index.ts';
+import { type PresentationReceipt } from './contracts/index.ts';
+/** Owns only one newly-created build. A single directory rename publishes all requested complete files. */
+export declare function commitPresentation(workspaceRoot: string, input: BuiltPresentation, assertOwner: () => Promise<void>, signal?: AbortSignal): Promise<PresentationReceipt>;

package/lib/types/presentation/contracts/asset-path.d.ts

@@ -0,0 +1,2 @@
+import type { PresentationAsset } from './types.ts';
+export declare function presentationAssetRelativePath(reportId: string, buildId: string, asset: PresentationAsset): string;

package/lib/types/presentation/contracts/catalog.d.ts

@@ -0,0 +1,27 @@
+import { type PresentationReceipt } from './index.ts';
+export interface PublicationSource {
+    kind: 'agent' | 'reader';
+    sessionId: string | null;
+}
+export interface ReportVersion {
+    receipt: PresentationReceipt;
+    publishedAt: string | null;
+    source: PublicationSource | null;
+}
+export interface ReportHistory {
+    workspaceId: string;
+    reportId: string;
+    currentBuildId: string;
+    legacyHistoryUnavailable: boolean;
+    versions: ReportVersion[];
+}
+export interface ReportCatalog {
+    workspaceId: string;
+    reports: ReportVersion[];
+    unavailable: number;
+}
+export declare const REPORT_HISTORY_BYTES: number;
+export declare const REPORT_HISTORY_LIMIT = 4096;
+export declare function parseReportVersion(value: unknown): ReportVersion;
+export declare function parseReportHistory(value: unknown): ReportHistory;
+export declare function parseReportCatalog(value: unknown): ReportCatalog;

package/lib/types/presentation/contracts/charts.d.ts

@@ -0,0 +1,11 @@
+import { type ChartType, type ChartView, type TypedDataset } from './types.ts';
+export type { ChartBindings, ChartOptions, ChartType, ChartView } from './types.ts';
+export declare const CHART_TYPES: readonly ["line", "area", "stackedArea", "sparkline", "bar", "horizontalBar", "stackedBar", "stackedBar100", "horizontalStackedBar", "horizontalStackedBar100", "histogram", "boxPlot", "scatter", "heatmap", "pie", "leaderboard", "funnel", "waterfall"];
+/** Strictly validates one binding. A containing block handles id/kind/preparedViews. */
+export declare function parseChartViewShape(value: unknown, path?: string): asserts value is ChartView;
+/** Exact source columns, including every auxiliary field used by geometry or tooltip. */
+export declare function chartColumns(view: ChartView): string[];
+/** Verifies supplied values only: never bins, ranks, accumulates, normalizes or sorts. */
+export declare function validateChartView(view: ChartView, dataset: TypedDataset, path?: string, dataPath?: string, rowIndices?: readonly number[]): void;
+/** Changes geometry only. Statistical views must be declared with prepared bindings. */
+export declare function chartTransition(view: ChartView, chart: ChartType, dataset: TypedDataset): ChartView | undefined;

package/lib/types/presentation/contracts/editing.d.ts

@@ -0,0 +1,8 @@
+import type { PresentationBlock, PresentationDocument } from './types.ts';
+export interface PresentationEdits {
+    title: string;
+    blocks: PresentationBlock[];
+}
+export declare function presentationEdits(document: PresentationDocument): PresentationEdits;
+/** Only presentation fields are accepted. Saved data, sources and captured code stay server-owned. */
+export declare function applyPresentationEdits(base: PresentationDocument, value: unknown): PresentationDocument;

package/lib/types/presentation/contracts/index.d.ts

@@ -0,0 +1,11 @@
+import { type Cell, type DatasetColumn, type PresentationDocument, type PresentationDraft, type PresentationReceipt, type TypedDataset } from './types.ts';
+export * from './charts.ts';
+export * from './types.ts';
+export * from './values.ts';
+export declare function parsePresentationBuildId(value: unknown, path?: string): string;
+export declare function parseTypedDataset(value: unknown, path?: string): TypedDataset;
+/** Tables retain the original decimal/int64 spelling, including trailing decimal zeroes. */
+export declare function formatCell(value: Cell, _column: DatasetColumn): string;
+export declare function parsePresentationDraft(value: unknown): PresentationDraft;
+export declare function parsePresentationDocument(value: unknown): PresentationDocument;
+export declare function parsePresentationReceipt(value: unknown): PresentationReceipt;

package/lib/types/presentation/contracts/interaction.d.ts

@@ -0,0 +1,8 @@
+import type { PresentationBlock, PresentationDocument, PresentationInteraction } from './types.ts';
+export declare function defaultSelection(interaction: PresentationInteraction): Record<string, string>;
+export declare function selectedSlice(interaction: PresentationInteraction, selection: Record<string, string>): import("./types.ts").PresentationSlice;
+export declare function interactionRows(interaction: PresentationInteraction | undefined, selection: Record<string, string>, block: PresentationBlock): number[] | undefined;
+export declare function filterSummary(interaction: PresentationInteraction, selection: Record<string, string>): string;
+/** Preserve the authored before / interactive / after boundary during host edits. */
+export declare function blockRegion(document: PresentationDocument, id: string): number;
+export declare function editedInteraction(document: PresentationDocument, blocks: PresentationBlock[]): PresentationInteraction | undefined;