@chengxianglibra/dsh-data-analysis 0.1.1

package/lib/datasource/shell-env.js

@@ -0,0 +1,386 @@
+import { randomBytes } from 'node:crypto';
+import { credentialRef, isCredentialRefName, } from '@deepseek-ai/dsh-credentials';
+import { MarivoEnvironmentError } from "../environment/index.js";
+import { resolveMarivoDatasourceBridge, } from "./bridge.js";
+export const MARIVO_CREDENTIAL_STORAGE_PREFIX = 'DSH_DATA_ANALYSIS_CREDENTIAL_';
+export const MARIVO_CREDENTIAL_LEASE_PREFIX = '# dsh-marivo-credential-lease:';
+export const DEFAULT_MARIVO_CREDENTIAL_LEASE_TTL_MS = 30 * 60_000;
+export const DEFAULT_MARIVO_CREDENTIAL_LEASE_MAX_USES = 64;
+const TOKEN_PATTERN = /^[A-Za-z0-9_-]{43}$/;
+const SHELL_TOOL_NAMES = new Set(['bash', 'pwsh']);
+const HOST_SHELL_ENVIRONMENT_NAMES = new Set([
+    'DSH_HOME',
+    'DSH_SESSION_ID',
+    'DSH_SESSION_JSONL',
+    'DSH_SHELL',
+]);
+function shellEnvironmentRegistry(ctx) {
+    return ctx.shellEnv;
+}
+/** Publish the exact shared interpreter as a non-secret, per-execution DSH fact. */
+export function registerMarivoRuntimeShellEnvironment(ctx, pythonExecutable) {
+    return shellEnvironmentRegistry(ctx).register({
+        name: 'dsh-data-analysis:runtime',
+        variables: {
+            DSH_DATA_ANALYSIS_PYTHON: {
+                description: 'Exact Python interpreter admitted by the shared Marivo Runtime.',
+            },
+        },
+        resolve: () => ({ DSH_DATA_ANALYSIS_PYTHON: pythonExecutable }),
+    });
+}
+function invalidReference(ref) {
+    const valid = isCredentialRefName(ref);
+    return new MarivoEnvironmentError('datasource-credential-ref-invalid', valid
+        ? `Marivo datasource credential reference uses a reserved runtime namespace or Host name: ${ref}`
+        : `Marivo datasource credential reference must be a POSIX environment name: ${ref}`, {
+        ref,
+        expected: valid
+            ? 'a POSIX environment name outside MARIVO_*, DSH_DATA_ANALYSIS_*, and Host-owned DSH shell facts'
+            : '[A-Za-z_][A-Za-z0-9_]*',
+    });
+}
+function isReservedDatasourceCredentialReference(ref) {
+    const upper = ref.toUpperCase();
+    return (upper.startsWith('MARIVO_') ||
+        upper.startsWith('DSH_DATA_ANALYSIS_') ||
+        HOST_SHELL_ENVIRONMENT_NAMES.has(upper));
+}
+/** Map one user-authored datasource environment reference to plugin-owned DSH storage. */
+export function marivoCredentialStorageRef(ref) {
+    if (!isCredentialRefName(ref) || isReservedDatasourceCredentialReference(ref)) {
+        throw invalidReference(ref);
+    }
+    const encoded = [...ref]
+        .map((character) => character.charCodeAt(0).toString(16).padStart(2, '0').toUpperCase())
+        .join('');
+    return `${MARIVO_CREDENTIAL_STORAGE_PREFIX}${encoded}`;
+}
+function credentialBindings(refs) {
+    return Object.freeze([...new Set(refs)].map((environmentRef) => ({
+        environmentRef,
+        storageRef: marivoCredentialStorageRef(environmentRef),
+    })));
+}
+function bashPrelude(token, bindings) {
+    return [
+        `${MARIVO_CREDENTIAL_LEASE_PREFIX}${token}`,
+        ...bindings.flatMap(({ environmentRef, storageRef }) => [
+            `export ${environmentRef}="\${${storageRef}}"`,
+            `unset ${storageRef}`,
+        ]),
+        'export MARIVO_PERSIST_CREDENTIALS=0',
+    ].join('\n');
+}
+function pwshPrelude(token, bindings) {
+    return [
+        `${MARIVO_CREDENTIAL_LEASE_PREFIX}${token}`,
+        ...bindings.flatMap(({ environmentRef, storageRef }) => [
+            `$env:${environmentRef} = $env:${storageRef}`,
+            `Remove-Item Env:${storageRef}`,
+        ]),
+        "$env:MARIVO_PERSIST_CREDENTIALS = '0'",
+    ].join('\n');
+}
+function leaseFailure(code, message, details = {}) {
+    return new MarivoEnvironmentError(code, message, details);
+}
+function commandArguments(execution) {
+    return typeof execution.arguments === 'object' &&
+        execution.arguments !== null &&
+        !Array.isArray(execution.arguments)
+        ? execution.arguments
+        : undefined;
+}
+function hasCredentialStorageRefAt(command, offset, caseInsensitive) {
+    const candidate = caseInsensitive ? command.slice(offset).toUpperCase() : command.slice(offset);
+    if (!candidate.startsWith(MARIVO_CREDENTIAL_STORAGE_PREFIX))
+        return false;
+    let cursor = MARIVO_CREDENTIAL_STORAGE_PREFIX.length;
+    const firstHex = cursor;
+    while (cursor < candidate.length && /[A-F0-9]/.test(candidate[cursor] ?? ''))
+        cursor++;
+    return (cursor > firstHex &&
+        (cursor === candidate.length || !/[A-Z0-9_]/i.test(candidate[cursor] ?? '')));
+}
+function isBashCommentStart(command, offset) {
+    if (offset === 0)
+        return true;
+    return /[\s;&|()]/.test(command[offset - 1] ?? '');
+}
+function containsCredentialDereference(execution) {
+    const command = commandArguments(execution)?.command;
+    if (typeof command !== 'string')
+        return false;
+    const pwsh = execution.name === 'pwsh';
+    let quote;
+    let comment = false;
+    for (let index = 0; index < command.length; index++) {
+        const character = command[index];
+        if (comment) {
+            if (character === '\n' || character === '\r')
+                comment = false;
+            continue;
+        }
+        if (quote === "'") {
+            if (character === "'") {
+                if (pwsh && command[index + 1] === "'")
+                    index++;
+                else
+                    quote = undefined;
+            }
+            continue;
+        }
+        if (character === (pwsh ? '`' : '\\')) {
+            index++;
+            continue;
+        }
+        if (character === '#' && quote === undefined && (pwsh || isBashCommentStart(command, index))) {
+            comment = true;
+            continue;
+        }
+        if (character === "'" && quote === undefined) {
+            quote = "'";
+            continue;
+        }
+        if (character === '"') {
+            quote = quote === '"' ? undefined : '"';
+            continue;
+        }
+        if (character !== '$')
+            continue;
+        if (pwsh) {
+            if (command.slice(index + 1, index + 5).toLowerCase() === 'env:' &&
+                hasCredentialStorageRefAt(command, index + 5, true)) {
+                return true;
+            }
+            if (command.slice(index + 1, index + 6).toLowerCase() === '{env:' &&
+                hasCredentialStorageRefAt(command, index + 6, true)) {
+                return true;
+            }
+            continue;
+        }
+        const refOffset = command[index + 1] === '{' ? index + 2 : index + 1;
+        if (hasCredentialStorageRefAt(command, refOffset, false))
+            return true;
+    }
+    return false;
+}
+function leaseToken(execution) {
+    const command = commandArguments(execution)?.command;
+    if (typeof command !== 'string')
+        return undefined;
+    const firstLine = command.split(/\r?\n/, 1)[0] ?? '';
+    const candidate = firstLine.startsWith(MARIVO_CREDENTIAL_LEASE_PREFIX)
+        ? firstLine.slice(MARIVO_CREDENTIAL_LEASE_PREFIX.length)
+        : undefined;
+    if (candidate !== undefined && TOKEN_PATTERN.test(candidate))
+        return candidate;
+    if (firstLine.includes('dsh-marivo-credential-')) {
+        throw leaseFailure('shell-credential-lease-invalid', 'Marivo shell credential lease marker is malformed or unsupported');
+    }
+    return undefined;
+}
+function isHarnessPersistentShell(agent, name) {
+    const definition = agent.ctx.tools.get(name, agent);
+    return definition?.output.schema.type === 'string';
+}
+export function assertMarivoCredentialReferences(refs) {
+    for (const ref of refs) {
+        marivoCredentialStorageRef(ref);
+    }
+}
+/** Own bounded leases and expose credential values only to each admitted Shell execution. */
+export class MarivoShellCredentialLeases {
+    #ctx;
+    #credentials;
+    #ttlMs;
+    #maxUses;
+    #leases = new Map();
+    #executionValues = new Map();
+    #contributors = new Map();
+    #disposed = false;
+    constructor(ctx, credentials, options = {}) {
+        const ttlMs = options.ttlMs ?? DEFAULT_MARIVO_CREDENTIAL_LEASE_TTL_MS;
+        const maxUses = options.maxUses ?? DEFAULT_MARIVO_CREDENTIAL_LEASE_MAX_USES;
+        if (!Number.isSafeInteger(ttlMs) ||
+            ttlMs < 1 ||
+            ttlMs > DEFAULT_MARIVO_CREDENTIAL_LEASE_TTL_MS) {
+            throw new TypeError(`Marivo shell credential lease ttlMs must be an integer from 1 to ${DEFAULT_MARIVO_CREDENTIAL_LEASE_TTL_MS}`);
+        }
+        if (!Number.isSafeInteger(maxUses) ||
+            maxUses < 1 ||
+            maxUses > DEFAULT_MARIVO_CREDENTIAL_LEASE_MAX_USES) {
+            throw new TypeError(`Marivo shell credential lease maxUses must be an integer from 1 to ${DEFAULT_MARIVO_CREDENTIAL_LEASE_MAX_USES}`);
+        }
+        this.#ctx = ctx;
+        this.#credentials = credentials;
+        this.#ttlMs = ttlMs;
+        this.#maxUses = maxUses;
+    }
+    #ensureContributor(ref) {
+        if (this.#disposed)
+            throw new Error('Marivo shell credential leases are disposed');
+        if (this.#contributors.has(ref))
+            return;
+        const dispose = shellEnvironmentRegistry(this.#ctx).register({
+            name: `dsh-data-analysis:credential:${ref}`,
+            variables: {
+                [ref]: {
+                    description: 'Marivo datasource credential authorized for this Shell execution.',
+                },
+            },
+            resolve: (execution) => {
+                const value = this.#executionValues.get(execution)?.values.get(ref);
+                return value === undefined ? {} : { [ref]: value };
+            },
+        });
+        this.#contributors.set(ref, dispose);
+    }
+    #purgeExpired(now) {
+        for (const [token, lease] of this.#leases) {
+            if (lease.expiresAt <= now)
+                this.#leases.delete(token);
+        }
+    }
+    revokeLease(agent, bridge, datasourceName) {
+        for (const [token, lease] of this.#leases) {
+            if (lease.agent === agent &&
+                lease.workspaceFingerprint === bridge.binding.fingerprint &&
+                lease.datasourceName === datasourceName) {
+                this.#leases.delete(token);
+            }
+        }
+    }
+    issueLease(agent, bridge, datasourceName, refs) {
+        if (this.#disposed)
+            throw new Error('Marivo shell credential leases are disposed');
+        const now = Date.now();
+        this.#purgeExpired(now);
+        this.revokeLease(agent, bridge, datasourceName);
+        assertMarivoCredentialReferences(refs);
+        const bindings = credentialBindings(refs);
+        for (const binding of bindings)
+            this.#ensureContributor(binding.storageRef);
+        const token = randomBytes(32).toString('base64url');
+        this.#leases.set(token, {
+            agent,
+            workspaceFingerprint: bridge.binding.fingerprint,
+            datasourceName,
+            bindings,
+            expiresAt: now + this.#ttlMs,
+            remainingUses: this.#maxUses,
+        });
+        return {
+            token,
+            expires_in_ms: this.#ttlMs,
+            max_uses: this.#maxUses,
+            usage: 'bounded-foreground-shell-lease',
+            bash_prelude: bashPrelude(token, bindings),
+            pwsh_prelude: pwshPrelude(token, bindings),
+        };
+    }
+    async #claim(agent, bridgeSource, execution, token) {
+        const lease = this.#leases.get(token);
+        if (lease === undefined) {
+            throw leaseFailure('shell-credential-lease-invalid', 'Marivo shell credential lease is unknown; call marivo_datasource_access again');
+        }
+        if (lease.expiresAt <= Date.now()) {
+            this.#leases.delete(token);
+            throw leaseFailure('shell-credential-lease-expired', 'Marivo shell credential lease has expired; call marivo_datasource_access again', { datasourceName: lease.datasourceName });
+        }
+        if (execution.agent !== agent || lease.agent !== agent) {
+            throw leaseFailure('shell-credential-lease-scope-mismatch', 'Marivo shell credential lease belongs to another Agent');
+        }
+        const bridge = await resolveMarivoDatasourceBridge(bridgeSource);
+        if (this.#leases.get(token) !== lease) {
+            throw leaseFailure('shell-credential-lease-invalid', 'Marivo shell credential lease was revoked; call marivo_datasource_access again');
+        }
+        if (lease.workspaceFingerprint !== bridge.binding.fingerprint) {
+            throw leaseFailure('shell-credential-lease-scope-mismatch', 'Marivo shell credential lease belongs to another Workspace binding');
+        }
+        if (lease.expiresAt <= Date.now()) {
+            this.#leases.delete(token);
+            throw leaseFailure('shell-credential-lease-expired', 'Marivo shell credential lease has expired; call marivo_datasource_access again', { datasourceName: lease.datasourceName });
+        }
+        const args = commandArguments(execution);
+        if (args?.run_in_background === true) {
+            throw leaseFailure('shell-credential-injection-unsupported', 'Marivo shell credential leases cannot be used by background Shell executions', { tool: execution.name });
+        }
+        if (isHarnessPersistentShell(agent, execution.name)) {
+            throw leaseFailure('shell-credential-injection-unsupported', `Marivo shell credential leases cannot be used by persistent ${execution.name}`, { tool: execution.name });
+        }
+        if (lease.remainingUses < 1) {
+            this.#leases.delete(token);
+            throw leaseFailure('shell-credential-lease-exhausted', 'Marivo shell credential lease is exhausted; call marivo_datasource_access again', { datasourceName: lease.datasourceName });
+        }
+        lease.remainingUses--;
+        const values = new Map();
+        for (const binding of lease.bindings) {
+            execution.signal.throwIfAborted();
+            let resolved;
+            try {
+                resolved = await this.#credentials.resolve(credentialRef(binding.storageRef));
+            }
+            catch {
+                throw leaseFailure('shell-credential-lease-resolve-failed', 'A credential authorized by the Marivo shell lease could not be resolved', { datasourceName: lease.datasourceName, ref: binding.environmentRef });
+            }
+            if (resolved === undefined) {
+                throw leaseFailure('shell-credential-lease-resolve-failed', 'A credential authorized by the Marivo shell lease is no longer configured', { datasourceName: lease.datasourceName, ref: binding.environmentRef });
+            }
+            values.set(binding.storageRef, resolved.value);
+        }
+        this.#executionValues.set(execution, { agent, values });
+    }
+    async prepareExecution(agent, bridgeSource, execution) {
+        if (this.#disposed)
+            throw new Error('Marivo shell credential leases are disposed');
+        const token = leaseToken(execution);
+        if (token === undefined) {
+            if (containsCredentialDereference(execution)) {
+                throw leaseFailure('shell-credential-lease-invalid', 'Marivo shell credential reference is not authorized because the exact prelude lease marker is missing. Call marivo_datasource_access again, copy the exact prelude, and use a foreground Shell execution', { tool: execution.name });
+            }
+            return false;
+        }
+        await this.#claim(agent, bridgeSource, execution, token);
+        return true;
+    }
+    installAgent(agent, bridgeSource) {
+        const stopPreExecute = agent.ctx.on('tools/pre-execute', async (execution, next) => {
+            if (execution.agent === agent && SHELL_TOOL_NAMES.has(execution.name)) {
+                await this.prepareExecution(agent, bridgeSource, execution);
+            }
+            return next();
+        });
+        const stopResult = agent.ctx.on('tools/result', (execution) => {
+            if (execution.agent === agent)
+                this.#executionValues.delete(execution);
+        });
+        let active = true;
+        return () => {
+            if (!active)
+                return;
+            active = false;
+            stopPreExecute();
+            stopResult();
+            for (const [token, lease] of this.#leases) {
+                if (lease.agent === agent)
+                    this.#leases.delete(token);
+            }
+            for (const [execution, snapshot] of this.#executionValues) {
+                if (snapshot.agent === agent)
+                    this.#executionValues.delete(execution);
+            }
+        };
+    }
+    dispose() {
+        if (this.#disposed)
+            return;
+        this.#disposed = true;
+        this.#leases.clear();
+        this.#executionValues.clear();
+        for (const dispose of this.#contributors.values())
+            dispose();
+        this.#contributors.clear();
+    }
+}

package/lib/datasource/test.js

@@ -0,0 +1,65 @@
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { resolveMarivoDatasourceBridge, } from "./bridge.js";
+import { inspectMarivoDatasourceCredentials } from "./credentials.js";
+export const MARIVO_DATASOURCE_TEST_TOOL_NAME = 'marivo_datasource_test';
+function datasourceName(value) {
+    if (typeof value !== 'string' || value.trim() === '' || value.length > 256) {
+        throw new TypeError('marivo_datasource_test name must be a non-empty string of at most 256 characters');
+    }
+    return value;
+}
+function renderValue(value) {
+    if (value.status === 'needs-credentials')
+        return JSON.stringify(value);
+    if (value.status === 'ok') {
+        return `Marivo datasource ${value.name} connection test succeeded${value.latency_ms === null ? '' : ` in ${value.latency_ms} ms`}.`;
+    }
+    return JSON.stringify(value);
+}
+/** Build the scoped datasource connection-test Tool. */
+export function createMarivoDatasourceTestTool(bridgeSource, credentials, options) {
+    return defineTool({
+        name: MARIVO_DATASOURCE_TEST_TOOL_NAME,
+        description: 'Test one configured Marivo datasource connection. Missing datasource environment references are requested through the DSH credential service.',
+        parameters: {
+            name: {
+                type: 'string',
+                required: true,
+                description: 'Configured Marivo datasource name.',
+            },
+        },
+        output: {
+            schema: { type: 'json' },
+            render: (_args, value) => [
+                { type: 'text', text: renderValue(value) },
+            ],
+        },
+        timeoutMs: 65_000,
+        async execute(args, exec) {
+            const name = datasourceName(args.name);
+            const bridge = await resolveMarivoDatasourceBridge(bridgeSource);
+            options.revokeShellLease(bridge, name);
+            const described = await bridge.describe(name, exec.signal);
+            const overlay = {};
+            const missing = await inspectMarivoDatasourceCredentials(described.refs, credentials, exec.signal, (ref, value) => {
+                overlay[ref] = value;
+            });
+            if (missing.length > 0)
+                return { status: 'needs-credentials', name: described.name, refs: missing };
+            const tested = await bridge.test(name, overlay, exec.signal);
+            if (tested.ok) {
+                return { status: 'ok', name: tested.name, latency_ms: tested.latency_ms };
+            }
+            return {
+                status: 'failed',
+                name: tested.name,
+                latency_ms: tested.latency_ms,
+                failure: tested.failure,
+                repair: tested.repair,
+            };
+        },
+    });
+}
+export function registerMarivoDatasourceTestTool(ctx, bridgeSource, credentials, options) {
+    return ctx.tools.register(createMarivoDatasourceTestTool(bridgeSource, credentials, options));
+}