@chengxianglibra/dsh-data-analysis 0.1.1

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

@@ -0,0 +1,53 @@
+import type { JsonValue } from '@deepseek-ai/dsh-session';
+import type { MarivoBridgeSource } from '../environment/source.ts';
+import type { MarivoCheckedRunner, MarivoEnvironmentBinding } from '../environment/types.ts';
+interface JsonObject {
+    [key: string]: JsonValue;
+}
+export interface MarivoDatasourceFailure extends JsonObject {
+    code: string;
+    exception_type: string;
+    backend_code: string | null;
+    backend_name: string | null;
+    message: string;
+}
+export interface MarivoDatasourceRepair extends JsonObject {
+    kind: string;
+    help_target: string;
+    action: string;
+    snippet: string | null;
+    candidates: string[];
+    preserves_evidence: boolean | null;
+}
+export interface MarivoDatasourceDescription {
+    name: string;
+    refs: string[];
+}
+export interface MarivoDatasourceTestResult {
+    name: string;
+    ok: boolean;
+    latency_ms: number | null;
+    failure: MarivoDatasourceFailure | null;
+    repair: MarivoDatasourceRepair | null;
+}
+export interface MarivoDatasourceBridgePort {
+    readonly binding: Readonly<MarivoEnvironmentBinding>;
+    describe(name: string, signal?: AbortSignal): Promise<MarivoDatasourceDescription>;
+    inventory(signal?: AbortSignal): Promise<MarivoDatasourceDescription[]>;
+    test(name: string, environmentOverlay: Readonly<NodeJS.ProcessEnv>, signal?: AbortSignal): Promise<MarivoDatasourceTestResult>;
+}
+export type MarivoDatasourceBridgeSource = MarivoBridgeSource<MarivoDatasourceBridgePort>;
+export type MarivoDatasourceInventoryBridge = Pick<MarivoDatasourceBridgePort, 'inventory'>;
+export type MarivoDatasourceInventoryBridgeSource = MarivoBridgeSource<MarivoDatasourceInventoryBridge>;
+/** Identity-checked adapter for Marivo datasource metadata and connection tests. */
+export declare class MarivoDatasourceBridge {
+    #private;
+    readonly binding: Readonly<MarivoEnvironmentBinding>;
+    constructor(runner: MarivoCheckedRunner);
+    describe(name: string, signal?: AbortSignal): Promise<MarivoDatasourceDescription>;
+    inventory(signal?: AbortSignal): Promise<MarivoDatasourceDescription[]>;
+    test(name: string, environmentOverlay: Readonly<NodeJS.ProcessEnv>, signal?: AbortSignal): Promise<MarivoDatasourceTestResult>;
+}
+export declare function resolveMarivoDatasourceBridge(source: MarivoDatasourceBridgeSource): Promise<MarivoDatasourceBridgePort>;
+export declare function resolveMarivoDatasourceInventoryBridge(source: MarivoDatasourceInventoryBridgeSource): Promise<MarivoDatasourceInventoryBridge>;
+export {};

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

@@ -0,0 +1,8 @@
+export type { MarivoDatasourceAccessOptions, MarivoDatasourceAccessValue, } from './access.ts';
+export { createMarivoDatasourceAccessTool, MARIVO_DATASOURCE_ACCESS_TOOL_NAME, registerMarivoDatasourceAccessTool, } from './access.ts';
+export type { MarivoDatasourceBridgePort, MarivoDatasourceBridgeSource, MarivoDatasourceDescription, MarivoDatasourceFailure, MarivoDatasourceInventoryBridge, MarivoDatasourceInventoryBridgeSource, MarivoDatasourceRepair, MarivoDatasourceTestResult, } from './bridge.ts';
+export { MarivoDatasourceBridge, resolveMarivoDatasourceBridge, resolveMarivoDatasourceInventoryBridge, } from './bridge.ts';
+export type { MarivoShellLeaseReceipt } from './shell-env.ts';
+export { assertMarivoCredentialReferences, DEFAULT_MARIVO_CREDENTIAL_LEASE_MAX_USES, DEFAULT_MARIVO_CREDENTIAL_LEASE_TTL_MS, MARIVO_CREDENTIAL_LEASE_PREFIX, MARIVO_CREDENTIAL_STORAGE_PREFIX, MarivoShellCredentialLeases, marivoCredentialStorageRef, } from './shell-env.ts';
+export type { MarivoDatasourceTestOptions, MarivoDatasourceTestValue, } from './test.ts';
+export { createMarivoDatasourceTestTool, MARIVO_DATASOURCE_TEST_TOOL_NAME, registerMarivoDatasourceTestTool, } from './test.ts';

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

@@ -0,0 +1,38 @@
+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

@@ -0,0 +1,32 @@
+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';
+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 {};

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

@@ -0,0 +1,73 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { Agent } from '@deepseek-ai/dsh-agent';
+import type { UserMessage } from '@deepseek-ai/dsh-session';
+import type { ToolExecution, ToolExecutionResult } from '@deepseek-ai/dsh-tools';
+import { type MarivoHelpBridgeSource, type MarivoHelpDelivery, type MarivoHelpDeliveryQuery, type MarivoHelpLimits } from './help.ts';
+export declare const MARIVO_ROOT_HELP_TARGETS: Readonly<{
+    readonly 'marivo-analysis': "analysis";
+    readonly 'marivo-semantic': "authoring";
+}>;
+export type MarivoSkillName = keyof typeof MARIVO_ROOT_HELP_TARGETS;
+export type MarivoRootHelpTarget = (typeof MARIVO_ROOT_HELP_TARGETS)[MarivoSkillName];
+export interface MarivoDisclosureOptions {
+    helpLimits?: Partial<MarivoHelpLimits>;
+}
+export interface MarivoSkillActivationRecord {
+    skill: MarivoSkillName;
+    source: 'model' | 'user';
+}
+export interface MarivoRootHelpDisclosureRecord {
+    skill: MarivoSkillName;
+    target: MarivoRootHelpTarget;
+    environmentFingerprint: string;
+    bodyDigest: string;
+    delivery: MarivoHelpDelivery;
+    reason: 'activation' | 'recovery';
+    helpTextBytes: number;
+    latencyMs: number;
+}
+export interface MarivoDisclosureFailureRecord {
+    skills: MarivoSkillName[];
+    message: string;
+}
+export interface MarivoDisclosureTelemetry {
+    activations: MarivoSkillActivationRecord[];
+    rootHelp: MarivoRootHelpDisclosureRecord[];
+    failures: MarivoDisclosureFailureRecord[];
+}
+export interface MarivoDisclosureSource {
+    readonly kind: 'marivo-disclosure';
+    readonly form: 'root-help';
+    readonly skill: MarivoSkillName;
+    readonly target: MarivoRootHelpTarget;
+    readonly environmentFingerprint: string;
+    readonly bodyDigest: string;
+    readonly update?: true;
+}
+declare module '@deepseek-ai/dsh-llm' {
+    interface MessageSourceMap {
+        'marivo-disclosure': MarivoDisclosureSource;
+    }
+}
+export declare class MarivoDisclosureError extends Error {
+    readonly code = "root-help-failed";
+    readonly skills: readonly MarivoSkillName[];
+    constructor(skills: readonly MarivoSkillName[], cause: unknown);
+}
+/** Per-Agent controller for skill-triggered, prompt-visible Marivo help disclosure. */
+export declare class MarivoDisclosureController {
+    #private;
+    readonly agent: Agent;
+    readonly bridgeSource: MarivoHelpBridgeSource;
+    readonly options: Readonly<MarivoDisclosureOptions>;
+    constructor(agent: Agent, bridgeSource: MarivoHelpBridgeSource, options?: MarivoDisclosureOptions);
+    get activeSkills(): readonly MarivoSkillName[];
+    telemetry(): MarivoDisclosureTelemetry;
+    addDisposer(disposer: () => void): void;
+    observeToolResult(exec: Readonly<ToolExecution>, result: Readonly<ToolExecutionResult>): void;
+    resolveDelivery(query: Readonly<MarivoHelpDeliveryQuery>): MarivoHelpDelivery;
+    prepareStep(messages: readonly UserMessage[], signal: AbortSignal): Promise<UserMessage[]>;
+    dispose(): 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/bridge.d.ts

@@ -0,0 +1,28 @@
+import type { MarivoBridgeSource } from '../environment/source.ts';
+import type { MarivoCheckedRunner, MarivoEnvironmentBinding } from '../environment/types.ts';
+export interface MarivoHelpBridgeLimits {
+    timeoutMs: number;
+    stdoutMaxBytes: number;
+    stderrMaxBytes: number;
+}
+export interface MarivoHelpBridgePort {
+    readonly binding: Readonly<MarivoEnvironmentBinding>;
+    inventory(limits: Readonly<MarivoHelpBridgeLimits>, signal?: AbortSignal): Promise<Buffer>;
+    runTarget(target: string, limits: Readonly<MarivoHelpBridgeLimits>, signal?: AbortSignal): Promise<Buffer>;
+}
+export type MarivoHelpBridgeSource = MarivoBridgeSource<MarivoHelpBridgePort>;
+export type MarivoHelpFailureCode = 'invalid-request' | 'target-failed' | 'empty-help' | 'combined-output-limit';
+export declare class MarivoHelpError extends Error {
+    readonly code: MarivoHelpFailureCode;
+    readonly details: Readonly<Record<string, unknown>>;
+    constructor(code: MarivoHelpFailureCode, message: string, details?: Readonly<Record<string, unknown>>, options?: ErrorOptions);
+}
+/** Identity-checked adapter for the live Marivo Help surface. */
+export declare class MarivoHelpBridge {
+    #private;
+    readonly binding: Readonly<MarivoEnvironmentBinding>;
+    constructor(runner: MarivoCheckedRunner);
+    runTarget(target: string, limits: Readonly<MarivoHelpBridgeLimits>, signal?: AbortSignal): Promise<Buffer>;
+    inventory(limits: Readonly<MarivoHelpBridgeLimits>, signal?: AbortSignal): Promise<Buffer>;
+}
+export declare function resolveMarivoHelpBridge(source: MarivoHelpBridgeSource): Promise<MarivoHelpBridgePort>;

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

@@ -0,0 +1,64 @@
+import type { Context } from '@deepseek-ai/cordis';
+import { type ToolDefinition } from '@deepseek-ai/dsh-tools';
+import { type MarivoHelpBridgePort, type MarivoHelpBridgeSource } from './bridge.ts';
+export type { MarivoHelpBridgePort, MarivoHelpBridgeSource, MarivoHelpFailureCode, } from './bridge.ts';
+export { MarivoHelpError, resolveMarivoHelpBridge } from './bridge.ts';
+export declare const MARIVO_HELP_TOOL_NAME = "marivo_help";
+export interface MarivoHelpLimits {
+    maxTargets: number;
+    maxTargetChars: number;
+    maxTotalTargetChars: number;
+    targetTimeoutMs: number;
+    focusedStdoutMaxBytes: number;
+    inventoryStdoutMaxBytes: number;
+    stderrMaxBytes: number;
+    combinedStdoutMaxBytes: number;
+    toolTimeoutMs: number;
+}
+export declare const DEFAULT_MARIVO_HELP_LIMITS: Readonly<MarivoHelpLimits>;
+export interface MarivoHelpTargetResult {
+    target: string;
+    body: string;
+    bodyDigest: string;
+    delivery: MarivoHelpDelivery;
+}
+export type MarivoHelpDelivery = 'delivered' | 'already-visible' | 'replacement';
+export interface MarivoHelpDeliveryQuery {
+    environmentFingerprint: string;
+    target: string;
+    bodyDigest: string;
+}
+export type MarivoHelpDeliveryResolver = (query: Readonly<MarivoHelpDeliveryQuery>) => MarivoHelpDelivery;
+export interface MarivoHelpValue {
+    environment: {
+        version: string;
+        fingerprint: string;
+    };
+    targets: MarivoHelpTargetResult[];
+}
+export interface MarivoHelpToolValue {
+    environment: {
+        version: string;
+    };
+    targets: MarivoHelpTargetResult[];
+}
+export declare function resolveMarivoHelpLimits(overrides?: Partial<MarivoHelpLimits>): Readonly<MarivoHelpLimits>;
+/** Validate only mechanical resource boundaries and deduplicate in first-seen order. */
+export declare function normalizeHelpTargets(input: unknown, limits: Readonly<MarivoHelpLimits>): string[];
+/** Read the current raw canonical inventory without parsing or caching it. */
+export declare function loadTargetInventory(bridge: MarivoHelpBridgePort, options?: {
+    limits?: Partial<MarivoHelpLimits>;
+    signal?: AbortSignal;
+}): Promise<string>;
+export declare function marivoHelpBodyDigest(body: string): string;
+export declare function renderMarivoHelpValue(value: MarivoHelpToolValue): string;
+/** Read one all-or-nothing batch from the bound live Marivo help surface. */
+export declare function readMarivoHelpTargets(bridge: MarivoHelpBridgePort, rawTargets: unknown, options?: {
+    limits?: Partial<MarivoHelpLimits>;
+    signal?: AbortSignal;
+    resolveDelivery?: MarivoHelpDeliveryResolver;
+}): Promise<MarivoHelpValue>;
+/** 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;

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

@@ -0,0 +1,5 @@
+export type { MarivoDisclosureFailureRecord, MarivoDisclosureOptions, MarivoDisclosureSource, MarivoDisclosureTelemetry, MarivoRootHelpDisclosureRecord, MarivoRootHelpTarget, MarivoSkillActivationRecord, MarivoSkillName, } from './activation.ts';
+export { installMarivoDisclosure, MARIVO_ROOT_HELP_TARGETS, MarivoDisclosureController, MarivoDisclosureError, } from './activation.ts';
+export { MarivoHelpBridge } from './bridge.ts';
+export type { MarivoHelpBridgePort, MarivoHelpBridgeSource, MarivoHelpDelivery, MarivoHelpDeliveryQuery, MarivoHelpDeliveryResolver, MarivoHelpFailureCode, MarivoHelpLimits, MarivoHelpTargetResult, MarivoHelpValue, } from './help.ts';
+export { createMarivoHelpTool, DEFAULT_MARIVO_HELP_LIMITS, loadTargetInventory, MARIVO_HELP_TOOL_NAME, MarivoHelpError, marivoHelpBodyDigest, normalizeHelpTargets, readMarivoHelpTargets, registerMarivoHelpTool, renderMarivoHelpValue, resolveMarivoHelpBridge, resolveMarivoHelpLimits, } from './help.ts';

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

@@ -0,0 +1,26 @@
+import { FixedSubprocessPolicy } from './subprocess.ts';
+import type { ImportIdentity, MarivoCheckedRunRequest, MarivoEnvironmentBinding, MarivoEnvironmentConfig, SharedMarivoRuntime } from './types.ts';
+/** A ready binding and the single frozen subprocess policy that established it. */
+export declare class MarivoEnvironment {
+    #private;
+    readonly binding: Readonly<MarivoEnvironmentBinding>;
+    readonly subprocessPolicy: FixedSubprocessPolicy;
+    constructor(binding: MarivoEnvironmentBinding, subprocessPolicy: FixedSubprocessPolicy);
+    get status(): 'ready' | 'failed';
+    /**
+     * Execute one Python program after checking the bound import identity in the same process.
+     * Identity mismatch permanently fails this binding; ordinary program failures do not.
+     */
+    runChecked(request: MarivoCheckedRunRequest): Promise<import("./types.ts").SubprocessResult>;
+    /** Recheck and return the exact bound import identity. */
+    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?: {
+    environment?: NodeJS.ProcessEnv;
+}): MarivoEnvironment;
+/** Resolve, probe, and establish one Marivo Environment Binding. */
+export declare function bindMarivoEnvironment(config: MarivoEnvironmentConfig, options?: {
+    environment?: NodeJS.ProcessEnv;
+    signal?: AbortSignal;
+}): Promise<MarivoEnvironment>;

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

@@ -0,0 +1,8 @@
+import type { DoctorReport } from './types.ts';
+/** Parse the complete doctor stdout. Non-zero process exit is deliberately handled elsewhere. */
+export declare function parseDoctorReport(stdout: Buffer): DoctorReport;
+/**
+ * Validate disclosure-specific admission checks without treating the top-level doctor status as
+ * an admission decision.
+ */
+export declare function admitDoctorReport(report: DoctorReport, expectedProjectRoot: string, expectedPythonExecutable: string): void;

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

@@ -0,0 +1,7 @@
+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';
+/** Stable failure envelope for config, subprocess, doctor, and identity errors. */
+export declare class MarivoEnvironmentError extends Error {
+    readonly code: EnvironmentFailureCode;
+    readonly details: Readonly<Record<string, unknown>>;
+    constructor(code: EnvironmentFailureCode, message: string, details?: Readonly<Record<string, unknown>>, options?: ErrorOptions);
+}

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

@@ -0,0 +1,9 @@
+export { bindMarivoEnvironment, createSharedMarivoRuntimeRunner, MarivoEnvironment, } from './binding.ts';
+export { admitDoctorReport, parseDoctorReport } from './doctor.ts';
+export { MarivoEnvironmentError } from './errors.ts';
+export { DEFAULT_SHARED_RUNTIME_INSTALL_TIMEOUT_MS, ensureSharedMarivoRuntime, SHARED_MARIVO_PACKAGE_SPEC, SHARED_PYTHON_SPEC, } from './runtime.ts';
+export type { MarivoBridgeSource, MarivoEnvironmentSource } from './source.ts';
+export { resolveMarivoBridgeSource, resolveMarivoEnvironmentSource, } from './source.ts';
+export { DEFAULT_SUBPROCESS_LIMITS, FixedSubprocessPolicy, MARIVO_PERSIST_CREDENTIALS_DISABLED, MARIVO_PERSIST_CREDENTIALS_ENV, SUBPROCESS_POLICY_ID, } from './subprocess.ts';
+export type { DoctorCheck, DoctorOverallStatus, DoctorReport, DoctorSection, DoctorStatus, ImportIdentity, MarivoCheckedRunner, MarivoCheckedRunRequest, MarivoEnvironmentBinding, MarivoEnvironmentConfig, SharedMarivoRuntime, SharedMarivoRuntimeConfig, SubprocessLimits, SubprocessRequest, SubprocessResult, } from './types.ts';
+export { MarivoWorkspaceEnvironmentManager } from './workspace.ts';

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

@@ -0,0 +1,17 @@
+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 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;
+}
+/** Ensure and validate the one DSH-home-owned Marivo installation. */
+export declare function ensureSharedMarivoRuntime(config?: SharedMarivoRuntimeConfig, options?: RuntimeInstallOptions): Promise<SharedMarivoRuntime>;
+export {};

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

@@ -0,0 +1,7 @@
+import type { MarivoEnvironment } from './binding.ts';
+/** A fixed binding or a lazy per-Agent/per-Workspace binding. */
+export type MarivoEnvironmentSource = MarivoEnvironment | (() => Promise<MarivoEnvironment>);
+/** A fixed domain adapter or a lazy adapter backed by a Workspace Environment. */
+export type MarivoBridgeSource<T> = T | (() => Promise<T>);
+export declare function resolveMarivoEnvironmentSource(source: MarivoEnvironmentSource): Promise<MarivoEnvironment>;
+export declare function resolveMarivoBridgeSource<T>(source: MarivoBridgeSource<T>): Promise<T>;

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

@@ -0,0 +1,19 @@
+import type { SubprocessLimits, SubprocessRequest, SubprocessResult } from './types.ts';
+export declare const SUBPROCESS_POLICY_ID: "direct-argv-inherited-env-snapshot-overlay-v2";
+export declare const MARIVO_PERSIST_CREDENTIALS_ENV = "MARIVO_PERSIST_CREDENTIALS";
+export declare const MARIVO_PERSIST_CREDENTIALS_DISABLED = "0";
+export declare const DEFAULT_SUBPROCESS_LIMITS: Readonly<SubprocessLimits>;
+/**
+ * Direct-argv subprocess runner shared by doctor, inventory, and focused help.
+ *
+ * The policy captures cwd and the environment projection once. Calls never use a shell. On
+ * POSIX, detached children form a process group so timeout, cancellation, and output overflow
+ * terminate the whole group.
+ */
+export declare class FixedSubprocessPolicy {
+    #private;
+    readonly id: "direct-argv-inherited-env-snapshot-overlay-v2";
+    readonly cwd: string;
+    constructor(cwd: string, environment?: NodeJS.ProcessEnv);
+    run(request: SubprocessRequest): Promise<SubprocessResult>;
+}

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

@@ -0,0 +1,96 @@
+/** Configuration accepted by the MVP environment resolver. */
+export interface MarivoEnvironmentConfig {
+    projectRoot: string;
+    pythonExecutable?: string;
+}
+/** Configuration for the one DSH-home-owned Marivo runtime shared by every Workspace. */
+export interface SharedMarivoRuntimeConfig {
+    runtimeRoot?: string;
+    pythonExecutable?: string;
+    uvExecutable?: string;
+    installTimeoutMs?: number;
+}
+/** Validated identity and stable skill root of the shared Marivo installation. */
+export interface SharedMarivoRuntime {
+    runtimeRoot: string;
+    pythonExecutable: string;
+    marivoVersion: string;
+    packagePath: string;
+    reportKitVersion: string;
+    reportKitPackagePath: string;
+    skillsRoot: string;
+    installationPath: string;
+}
+export type DoctorStatus = 'ok' | 'info' | 'warning' | 'fail' | 'skipped';
+export type DoctorOverallStatus = 'ok' | 'warning' | 'fail';
+export interface DoctorCheck {
+    id: string;
+    status: DoctorStatus;
+    summary: string;
+    details?: Record<string, unknown>;
+}
+export interface DoctorSection {
+    id: string;
+    status: DoctorStatus;
+    checks: DoctorCheck[];
+}
+export interface DoctorReport {
+    status: DoctorOverallStatus;
+    project_root: string;
+    python_executable: string;
+    marivo: {
+        version: string;
+        package_path: string;
+    };
+    sections: DoctorSection[];
+}
+/** Stable, non-secret identity retained by a successful binding. */
+export interface MarivoEnvironmentBinding {
+    projectRoot: string;
+    pythonExecutable: string;
+    marivoVersion: string;
+    packagePath: string;
+    subprocessPolicyId: string;
+    fingerprint: string;
+}
+export interface SubprocessLimits {
+    timeoutMs: number;
+    stdoutMaxBytes: number;
+    stderrMaxBytes: number;
+    terminateGraceMs: number;
+}
+export interface SubprocessRequest {
+    executable: string;
+    args: readonly string[];
+    /** Per-call environment values layered over the frozen binding snapshot. */
+    environmentOverlay?: Readonly<NodeJS.ProcessEnv>;
+    limits?: Partial<SubprocessLimits>;
+    signal?: AbortSignal;
+}
+/** One identity-checked Python operation executed by a bound Environment. */
+export interface MarivoCheckedRunRequest {
+    program: string;
+    args?: readonly string[];
+    /** Per-operation values; every non-empty value is redacted from captured output. */
+    environmentOverlay?: Readonly<NodeJS.ProcessEnv>;
+    limits?: Partial<SubprocessLimits>;
+    signal?: AbortSignal;
+}
+export interface SubprocessResult {
+    exitCode: number | null;
+    signal: NodeJS.Signals | null;
+    stdout: Buffer;
+    stderr: Buffer;
+    durationMs: number;
+}
+export interface ImportIdentity {
+    pythonExecutable: string;
+    marivoVersion: string;
+    packagePath: string;
+}
+/** Narrow execution contract consumed by domain bridge adapters. */
+export interface MarivoCheckedRunner {
+    readonly binding: Readonly<MarivoEnvironmentBinding>;
+    readonly status: 'ready' | 'failed';
+    runChecked(request: MarivoCheckedRunRequest): Promise<SubprocessResult>;
+}

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

@@ -0,0 +1,10 @@
+import { type MarivoEnvironment } from './binding.ts';
+import type { SharedMarivoRuntime } from './types.ts';
+/** Cache one zero-init Workspace binding while retaining project-specific doctor state. */
+export declare class MarivoWorkspaceEnvironmentManager {
+    #private;
+    readonly runtime: SharedMarivoRuntime;
+    constructor(runtime: SharedMarivoRuntime);
+    resolve(projectRoot: string): Promise<MarivoEnvironment>;
+    dispose(): void;
+}

package/lib/types/evidence/bridge.d.ts

@@ -0,0 +1,40 @@
+import type { MarivoBridgeSource } from '../environment/source.ts';
+import type { MarivoCheckedRunner, MarivoEnvironmentBinding } from '../environment/types.ts';
+export interface MarivoFindingProjection {
+    status: 'available' | 'missing' | 'unsupported';
+    title: string;
+    locator: string;
+    excerpt: string | null;
+    truncated: boolean;
+    findingId: string;
+    findingType: string | null;
+    epistemicKind: string | null;
+    artifactRef: string;
+    sessionId: string;
+    canonicalItemKey: string | null;
+    committedAt: string | null;
+    sourceRefs: string[];
+    revalidation: {
+        status: string;
+        semanticStatus: string | null;
+        evidenceStatus: string | null;
+        dependencyStatus: string | null;
+    } | null;
+}
+export interface MarivoFindingSelection {
+    artifactRef: string;
+    findingId: string;
+}
+export interface MarivoEvidenceBridgePort {
+    readonly binding: Readonly<Pick<MarivoEnvironmentBinding, 'fingerprint' | 'marivoVersion'>>;
+    findings(sessionId: string, selections: readonly MarivoFindingSelection[], signal?: AbortSignal): Promise<MarivoFindingProjection[]>;
+}
+export type MarivoEvidenceBridgeSource = MarivoBridgeSource<MarivoEvidenceBridgePort>;
+/** Identity-checked adapter for exact persisted Marivo Findings. */
+export declare class MarivoEvidenceBridge {
+    #private;
+    readonly binding: Readonly<MarivoEnvironmentBinding>;
+    constructor(runner: MarivoCheckedRunner);
+    findings(sessionId: string, selections: readonly MarivoFindingSelection[], signal?: AbortSignal): Promise<MarivoFindingProjection[]>;
+}
+export declare function resolveMarivoEvidenceBridge(source: MarivoEvidenceBridgeSource): Promise<MarivoEvidenceBridgePort>;

package/lib/types/evidence/index.d.ts

@@ -0,0 +1,4 @@
+export type { MarivoEvidenceBridgePort, MarivoEvidenceBridgeSource, MarivoFindingProjection, MarivoFindingSelection, } from './bridge.ts';
+export { MarivoEvidenceBridge, resolveMarivoEvidenceBridge, } from './bridge.ts';
+export type { MarivoEvidenceSource, MarivoEvidenceSourcesMeta, MarivoEvidenceSourcesValue, } from './sources.ts';
+export { createMarivoEvidenceSourcesTool, evidenceSourcesMeta, installMarivoEvidenceSourcesCodeDelivery, MARIVO_EVIDENCE_SOURCES_DURABLE_CONTENT_KIND, MARIVO_EVIDENCE_SOURCES_MAX_PER_CALL, MARIVO_EVIDENCE_SOURCES_META_KIND, MARIVO_EVIDENCE_SOURCES_META_VERSION, MARIVO_EVIDENCE_SOURCES_TOOL_NAME, registerMarivoEvidenceSourcesTool, } from './sources.ts';

package/lib/types/evidence/sources.d.ts

@@ -0,0 +1,57 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { JsonValue, Session } from '@deepseek-ai/dsh-session';
+import { type ToolDefinition } from '@deepseek-ai/dsh-tools';
+import { type MarivoEvidenceBridgeSource } from './bridge.ts';
+export declare const MARIVO_EVIDENCE_SOURCES_TOOL_NAME = "marivo_evidence_sources";
+export declare const MARIVO_EVIDENCE_SOURCES_META_KIND = "marivo-evidence-sources";
+export declare const MARIVO_EVIDENCE_SOURCES_META_VERSION = 2;
+export declare const MARIVO_EVIDENCE_SOURCES_DURABLE_CONTENT_KIND = "marivo-evidence-sources-card";
+export declare const MARIVO_EVIDENCE_SOURCES_MAX_PER_CALL = 20;
+export interface MarivoEvidenceSource {
+    [key: string]: JsonValue;
+    status: 'available' | 'missing' | 'unsupported';
+    title: string;
+    locator: string;
+    excerpt: string | null;
+    truncated: boolean;
+    environmentFingerprint: string;
+    sessionId: string;
+    findingId: string;
+    findingType: string | null;
+    epistemicKind: string | null;
+    artifactRef: string;
+    canonicalItemKey: string | null;
+    committedAt: string | null;
+    sourceRefs: string[];
+    revalidation: {
+        [key: string]: JsonValue;
+        status: string;
+        semanticStatus: string | null;
+        evidenceStatus: string | null;
+        dependencyStatus: string | null;
+    } | null;
+}
+export interface MarivoEvidenceSourcesValue {
+    [key: string]: JsonValue;
+    status: 'ok';
+    environment: {
+        version: string;
+        fingerprint: string;
+    };
+    dshSessionId: string;
+    sessionId: string;
+    sources: MarivoEvidenceSource[];
+}
+export interface MarivoEvidenceSourcesMeta {
+    [key: string]: JsonValue;
+    kind: typeof MARIVO_EVIDENCE_SOURCES_META_KIND;
+    version: typeof MARIVO_EVIDENCE_SOURCES_META_VERSION;
+    dshSessionId: string;
+    sources: MarivoEvidenceSource[];
+}
+export declare function evidenceSourcesMeta(value: MarivoEvidenceSourcesValue): MarivoEvidenceSourcesMeta;
+/** Build the exact-Finding source attachment Tool for one Agent and DSH Session. */
+export declare function createMarivoEvidenceSourcesTool(bridgeSource: MarivoEvidenceBridgeSource, session: Session): ToolDefinition;
+export declare function registerMarivoEvidenceSourcesTool(ctx: Context, bridgeSource: MarivoEvidenceBridgeSource, session: Session): () => void;
+/** Preserve nested Code Mode source metadata on the durable sub-dispatch event. */
+export declare function installMarivoEvidenceSourcesCodeDelivery(ctx: Context): () => void;

package/lib/types/index.d.ts

@@ -0,0 +1,9 @@
+export type { MarivoBridgeSet } from './bridges.ts';
+export { createMarivoBridgeSet } from './bridges.ts';
+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';