@chengxianglibra/dsh-data-analysis 0.1.1

package/lib/disclosure/activation.js

@@ -0,0 +1,369 @@
+import { createUserMessage } from '@deepseek-ai/dsh-llm';
+import { scopeParentOf } from '@deepseek-ai/dsh-scope';
+import { MARIVO_HELP_TOOL_NAME, readMarivoHelpTargets, registerMarivoHelpTool, renderMarivoHelpValue, resolveMarivoHelpBridge, } from "./help.js";
+const SKILL_TOOL_NAME = 'skill';
+export const MARIVO_ROOT_HELP_TARGETS = Object.freeze({
+    'marivo-analysis': 'analysis',
+    'marivo-semantic': 'authoring',
+});
+const MARIVO_SKILL_ORDER = ['marivo-analysis', 'marivo-semantic'];
+export class MarivoDisclosureError extends Error {
+    code = 'root-help-failed';
+    skills;
+    constructor(skills, cause) {
+        const detail = cause instanceof Error ? cause.message : String(cause);
+        super(`Marivo root help disclosure failed for ${skills.join(', ')}: ${detail}`, { cause });
+        this.name = 'MarivoDisclosureError';
+        this.skills = [...skills];
+    }
+}
+function isMarivoSkillName(value) {
+    return typeof value === 'string' && Object.hasOwn(MARIVO_ROOT_HELP_TARGETS, value);
+}
+function rootHelpSource(value) {
+    if (typeof value !== 'object' || value === null)
+        return undefined;
+    const source = value;
+    if (source.kind !== 'marivo-disclosure' ||
+        source.form !== 'root-help' ||
+        !isMarivoSkillName(source.skill) ||
+        source.target !== MARIVO_ROOT_HELP_TARGETS[source.skill] ||
+        typeof source.environmentFingerprint !== 'string' ||
+        typeof source.bodyDigest !== 'string')
+        return undefined;
+    return source;
+}
+function focusedHelpMeta(value) {
+    if (typeof value !== 'object' || value === null)
+        return [];
+    const meta = value;
+    if (meta.kind !== 'marivo-help-disclosure' ||
+        typeof meta.environmentFingerprint !== 'string' ||
+        !Array.isArray(meta.targets))
+        return [];
+    return meta.targets.flatMap((item) => {
+        if (typeof item !== 'object' || item === null)
+            return [];
+        const target = item.target;
+        const bodyDigest = item.bodyDigest;
+        const delivery = item.delivery;
+        if (typeof target !== 'string' ||
+            typeof bodyDigest !== 'string' ||
+            (delivery !== 'delivered' && delivery !== 'replacement'))
+            return [];
+        return [
+            {
+                environmentFingerprint: meta.environmentFingerprint,
+                target,
+                bodyDigest,
+            },
+        ];
+    });
+}
+function successfulSkillName(result) {
+    if (result.isError || typeof result.value !== 'object' || result.value === null)
+        return undefined;
+    const name = result.value.name;
+    return isMarivoSkillName(name) ? name : undefined;
+}
+function successfulHelpValue(result) {
+    if (result.isError || typeof result.value !== 'object' || result.value === null)
+        return undefined;
+    const value = result.value;
+    if (typeof value.environment !== 'object' ||
+        value.environment === null ||
+        typeof value.environment.fingerprint !== 'string' ||
+        !Array.isArray(value.targets))
+        return undefined;
+    return value;
+}
+function renderRootHelpMessage(skill, value, update) {
+    const target = MARIVO_ROOT_HELP_TARGETS[skill];
+    const item = value.targets[0];
+    if (item === undefined || item.target !== target) {
+        throw new Error(`Marivo root help ${target} did not return its requested target`);
+    }
+    return createUserMessage({
+        content: [
+            {
+                type: 'text',
+                text: [
+                    `<marivo_help_context skill="${skill}" target="${target}">`,
+                    update
+                        ? 'This live root help replaces the earlier disclosure for this skill.'
+                        : 'This live root help accompanies the loaded Marivo skill.',
+                    '',
+                    renderMarivoHelpValue(value),
+                    '</marivo_help_context>',
+                ].join('\n'),
+            },
+        ],
+        source: {
+            kind: 'marivo-disclosure',
+            form: 'root-help',
+            skill,
+            target,
+            environmentFingerprint: value.environment.fingerprint,
+            bodyDigest: item.bodyDigest,
+            ...(update ? { update: true } : {}),
+        },
+    });
+}
+/** Per-Agent controller for skill-triggered, prompt-visible Marivo help disclosure. */
+export class MarivoDisclosureController {
+    agent;
+    bridgeSource;
+    options;
+    #activeSkills = new Set();
+    #pendingSkills = new Set();
+    #visibleHelp = new Map();
+    #lifecycleAbort = new AbortController();
+    #disposers = [];
+    #disposed = false;
+    #telemetry = { activations: [], rootHelp: [], failures: [] };
+    constructor(agent, bridgeSource, options = {}) {
+        this.agent = agent;
+        this.bridgeSource = bridgeSource;
+        this.options = Object.freeze({
+            ...(options.helpLimits === undefined ? {} : { helpLimits: { ...options.helpLimits } }),
+        });
+        this.#restoreActiveSkills();
+    }
+    get activeSkills() {
+        return MARIVO_SKILL_ORDER.filter((skill) => this.#activeSkills.has(skill));
+    }
+    telemetry() {
+        return {
+            activations: this.#telemetry.activations.map((record) => ({ ...record })),
+            rootHelp: this.#telemetry.rootHelp.map((record) => ({ ...record })),
+            failures: this.#telemetry.failures.map((record) => ({
+                ...record,
+                skills: [...record.skills],
+            })),
+        };
+    }
+    addDisposer(disposer) {
+        this.#disposers.push(disposer);
+    }
+    #activate(skill, source) {
+        this.#activeSkills.add(skill);
+        this.#pendingSkills.add(skill);
+        this.#telemetry.activations.push({ skill, source });
+    }
+    observeToolResult(exec, result) {
+        if (exec.agent !== this.agent)
+            return;
+        if (exec.name === SKILL_TOOL_NAME && this.#inheritedSkillToolVisible()) {
+            const skill = successfulSkillName(result);
+            if (skill !== undefined)
+                this.#activate(skill, 'model');
+            return;
+        }
+        if (exec.name !== MARIVO_HELP_TOOL_NAME)
+            return;
+        const value = successfulHelpValue(result);
+        if (value === undefined)
+            return;
+        for (const item of value.targets) {
+            if (item.delivery === 'already-visible')
+                continue;
+            this.#visibleHelp.set(item.target, {
+                environmentFingerprint: value.environment.fingerprint,
+                target: item.target,
+                bodyDigest: item.bodyDigest,
+            });
+        }
+    }
+    resolveDelivery(query) {
+        const visible = this.#visibleHelp.get(query.target);
+        if (visible?.environmentFingerprint === query.environmentFingerprint &&
+            visible.bodyDigest === query.bodyDigest)
+            return 'already-visible';
+        return visible === undefined ? 'delivered' : 'replacement';
+    }
+    async prepareStep(messages, signal) {
+        if (this.#disposed)
+            throw this.#lifecycleAbort.signal.reason;
+        this.#observeExplicitInvocations(messages);
+        this.#refreshVisibleHelp(messages);
+        if (this.#activeSkills.size === 0)
+            return [];
+        const bridge = await resolveMarivoHelpBridge(this.bridgeSource);
+        if (this.#disposed)
+            throw this.#lifecycleAbort.signal.reason;
+        const requested = MARIVO_SKILL_ORDER.filter((skill) => {
+            if (!this.#activeSkills.has(skill))
+                return false;
+            const target = MARIVO_ROOT_HELP_TARGETS[skill];
+            const visible = this.#visibleHelp.get(target);
+            return (this.#pendingSkills.has(skill) ||
+                visible?.environmentFingerprint !== bridge.binding.fingerprint);
+        });
+        if (requested.length === 0)
+            return [];
+        const batchAbort = new AbortController();
+        const readSignal = AbortSignal.any([signal, this.#lifecycleAbort.signal, batchAbort.signal]);
+        let primaryCause;
+        const settled = await Promise.allSettled(requested.map(async (skill) => {
+            try {
+                const target = MARIVO_ROOT_HELP_TARGETS[skill];
+                const reason = this.#pendingSkills.has(skill) ? 'activation' : 'recovery';
+                const startedAt = performance.now();
+                const value = await readMarivoHelpTargets(bridge, [target], {
+                    limits: this.options.helpLimits,
+                    signal: readSignal,
+                    resolveDelivery: (query) => this.resolveDelivery(query),
+                });
+                return { skill, target, reason, startedAt, value };
+            }
+            catch (cause) {
+                primaryCause ??= cause;
+                batchAbort.abort(cause);
+                throw cause;
+            }
+        }));
+        if (this.#disposed)
+            throw this.#lifecycleAbort.signal.reason;
+        const rejected = settled.find((result) => result.status === 'rejected');
+        if (rejected !== undefined) {
+            const error = new MarivoDisclosureError(requested, primaryCause ?? rejected.reason);
+            this.#telemetry.failures.push({ skills: [...requested], message: error.message });
+            throw error;
+        }
+        readSignal.throwIfAborted();
+        const reads = settled.map((result) => {
+            if (result.status !== 'fulfilled')
+                throw new Error('unreachable rejected root Help read');
+            return result.value;
+        });
+        const injections = [];
+        for (const read of reads) {
+            const item = read.value.targets[0];
+            if (item === undefined || item.target !== read.target) {
+                const error = new MarivoDisclosureError([read.skill], new Error('root target missing'));
+                this.#telemetry.failures.push({ skills: [read.skill], message: error.message });
+                throw error;
+            }
+            const update = this.#visibleHelp.has(read.target) || this.#hasHistoricalDisclosure(read.skill);
+            this.#telemetry.rootHelp.push({
+                skill: read.skill,
+                target: read.target,
+                environmentFingerprint: read.value.environment.fingerprint,
+                bodyDigest: item.bodyDigest,
+                delivery: item.delivery,
+                reason: read.reason,
+                helpTextBytes: Buffer.byteLength(item.body),
+                latencyMs: Math.max(0, Math.round(performance.now() - read.startedAt)),
+            });
+            this.#pendingSkills.delete(read.skill);
+            if (item.delivery === 'already-visible')
+                continue;
+            const message = renderRootHelpMessage(read.skill, read.value, update);
+            injections.push(message);
+            this.#visibleHelp.set(read.target, {
+                environmentFingerprint: read.value.environment.fingerprint,
+                target: read.target,
+                bodyDigest: item.bodyDigest,
+            });
+        }
+        return injections;
+    }
+    dispose() {
+        if (this.#disposed)
+            return;
+        this.#disposed = true;
+        this.#lifecycleAbort.abort(new Error('Marivo disclosure controller disposed'));
+        for (const disposer of this.#disposers.reverse())
+            disposer();
+        this.#disposers = [];
+        this.#activeSkills.clear();
+        this.#pendingSkills.clear();
+        this.#visibleHelp.clear();
+    }
+    #inheritedSkillToolVisible() {
+        const inheritedSkillTool = this.agent.ctx.tools.get(SKILL_TOOL_NAME, scopeParentOf(this.agent));
+        return (inheritedSkillTool !== undefined &&
+            this.agent.ctx.tools.get(SKILL_TOOL_NAME, this.agent) === inheritedSkillTool);
+    }
+    #observeExplicitInvocations(messages) {
+        for (const message of messages) {
+            const source = message.source;
+            if (source.kind === 'skill-invocation' && isMarivoSkillName(source.name)) {
+                this.#activate(source.name, 'user');
+            }
+        }
+    }
+    #restoreActiveSkills() {
+        for (const event of this.agent.session.events) {
+            if (event.type !== 'user/message')
+                continue;
+            const disclosure = rootHelpSource(event.data.source);
+            if (disclosure !== undefined)
+                this.#activeSkills.add(disclosure.skill);
+            const source = event.data.source;
+            if (source.kind === 'skill-invocation' && isMarivoSkillName(source.name)) {
+                this.#activeSkills.add(source.name);
+            }
+        }
+    }
+    #refreshVisibleHelp(messages) {
+        this.#visibleHelp.clear();
+        const visible = new Set(this.agent.session.surface.nodes);
+        for (const event of this.agent.session.events) {
+            if (!visible.has(event.seq))
+                continue;
+            if (event.type === 'user/message') {
+                const source = rootHelpSource(event.data.source);
+                if (source !== undefined) {
+                    this.#visibleHelp.set(source.target, {
+                        environmentFingerprint: source.environmentFingerprint,
+                        target: source.target,
+                        bodyDigest: source.bodyDigest,
+                    });
+                }
+            }
+            else if (event.type === 'tool/result') {
+                for (const item of focusedHelpMeta(event.data.meta)) {
+                    this.#visibleHelp.set(item.target, item);
+                }
+            }
+        }
+        for (const message of messages) {
+            const source = rootHelpSource(message.source);
+            if (source === undefined)
+                continue;
+            this.#visibleHelp.set(source.target, {
+                environmentFingerprint: source.environmentFingerprint,
+                target: source.target,
+                bodyDigest: source.bodyDigest,
+            });
+        }
+    }
+    #hasHistoricalDisclosure(skill) {
+        return this.agent.session.events.some((event) => event.type === 'user/message' && rootHelpSource(event.data.source)?.skill === skill);
+    }
+}
+/** Install skill-triggered Marivo live-help disclosure for one Agent scope. */
+export function installMarivoDisclosure(_ctx, agent, bridgeSource, options = {}) {
+    const controller = new MarivoDisclosureController(agent, bridgeSource, options);
+    try {
+        controller.addDisposer(registerMarivoHelpTool(agent.ctx, bridgeSource, options.helpLimits, (query) => controller.resolveDelivery(query)));
+        controller.addDisposer(agent.ctx.on('tools/result', (exec, result) => {
+            controller.observeToolResult(exec, result);
+        }));
+        controller.addDisposer(agent.ctx.on('agent/pre-step', async ({ signal }, next) => {
+            const decision = await next();
+            if (decision.kind === 'reject')
+                return decision;
+            const injections = await controller.prepareStep(decision.messages, signal);
+            return injections.length === 0
+                ? decision
+                : { kind: 'enter', messages: [...decision.messages, ...injections] };
+        }, true));
+        return controller;
+    }
+    catch (cause) {
+        controller.dispose();
+        throw cause;
+    }
+}

package/lib/disclosure/bridge-program.js

@@ -0,0 +1,11 @@
+export const MARIVO_HELP_PROGRAM = String.raw `
+import sys
+import marivo
+
+marivo.help(sys.argv[1])
+`.trim();
+export const MARIVO_HELP_INVENTORY_PROGRAM = String.raw `
+import marivo
+
+marivo.help()
+`.trim();

package/lib/disclosure/bridge.js

@@ -0,0 +1,65 @@
+import { MarivoEnvironmentError } from "../environment/errors.js";
+import { resolveMarivoBridgeSource } from "../environment/source.js";
+import { MARIVO_HELP_INVENTORY_PROGRAM, MARIVO_HELP_PROGRAM } from "./bridge-program.js";
+export class MarivoHelpError extends Error {
+    code;
+    details;
+    constructor(code, message, details = {}, options) {
+        super(message, options);
+        this.name = 'MarivoHelpError';
+        this.code = code;
+        this.details = details;
+    }
+}
+function boundedStderr(stderr) {
+    const text = stderr.toString('utf8').trim();
+    return text.length === 0 ? 'no stderr was returned' : text.slice(0, 4_000);
+}
+/** Identity-checked adapter for the live Marivo Help surface. */
+export class MarivoHelpBridge {
+    binding;
+    #runner;
+    constructor(runner) {
+        this.#runner = runner;
+        this.binding = runner.binding;
+    }
+    async runTarget(target, limits, signal) {
+        return this.#run(MARIVO_HELP_PROGRAM, [target], limits, signal, `target ${JSON.stringify(target)}`);
+    }
+    async inventory(limits, signal) {
+        return this.#run(MARIVO_HELP_INVENTORY_PROGRAM, [], limits, signal, 'inventory');
+    }
+    async #run(program, args, limits, signal, subject) {
+        try {
+            const result = await this.#runner.runChecked({
+                program,
+                args,
+                limits,
+                signal,
+            });
+            if (result.exitCode !== 0) {
+                throw new MarivoHelpError('target-failed', `marivo_help ${subject} failed with exit code ${String(result.exitCode)}: ${boundedStderr(result.stderr)}`, { subject, exitCode: result.exitCode });
+            }
+            if (result.stdout.byteLength === 0) {
+                throw new MarivoHelpError('empty-help', `marivo_help ${subject} returned empty stdout`, {
+                    subject,
+                });
+            }
+            return result.stdout;
+        }
+        catch (cause) {
+            if (cause instanceof MarivoHelpError)
+                throw cause;
+            if (cause instanceof MarivoEnvironmentError &&
+                (cause.code === 'binding-identity-mismatch' || cause.code === 'binding-failed'))
+                throw cause;
+            if (cause instanceof MarivoEnvironmentError) {
+                throw new MarivoHelpError('target-failed', `marivo_help ${subject} failed: ${cause.message}`, { subject, environmentFailureCode: cause.code }, { cause });
+            }
+            throw new MarivoHelpError('target-failed', `marivo_help ${subject} failed`, { subject }, { cause });
+        }
+    }
+}
+export function resolveMarivoHelpBridge(source) {
+    return resolveMarivoBridgeSource(source);
+}

package/lib/disclosure/help.js

@@ -0,0 +1,227 @@
+import { createHash } from 'node:crypto';
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { MarivoHelpError, resolveMarivoHelpBridge, } from "./bridge.js";
+export { MarivoHelpError, resolveMarivoHelpBridge } from "./bridge.js";
+export const MARIVO_HELP_TOOL_NAME = 'marivo_help';
+export const DEFAULT_MARIVO_HELP_LIMITS = Object.freeze({
+    maxTargets: 8,
+    maxTargetChars: 256,
+    maxTotalTargetChars: 2_048,
+    targetTimeoutMs: 30_000,
+    focusedStdoutMaxBytes: 262_144,
+    inventoryStdoutMaxBytes: 1_048_576,
+    stderrMaxBytes: 65_536,
+    combinedStdoutMaxBytes: 1_048_576,
+    toolTimeoutMs: 245_000,
+});
+function positiveInteger(name, value) {
+    if (!Number.isSafeInteger(value) || value < 1) {
+        throw new TypeError(`marivo_help ${name} must be a positive safe integer`);
+    }
+    return value;
+}
+export function resolveMarivoHelpLimits(overrides = {}) {
+    const merged = { ...DEFAULT_MARIVO_HELP_LIMITS, ...overrides };
+    return Object.freeze({
+        maxTargets: positiveInteger('maxTargets', merged.maxTargets),
+        maxTargetChars: positiveInteger('maxTargetChars', merged.maxTargetChars),
+        maxTotalTargetChars: positiveInteger('maxTotalTargetChars', merged.maxTotalTargetChars),
+        targetTimeoutMs: positiveInteger('targetTimeoutMs', merged.targetTimeoutMs),
+        focusedStdoutMaxBytes: positiveInteger('focusedStdoutMaxBytes', merged.focusedStdoutMaxBytes),
+        inventoryStdoutMaxBytes: positiveInteger('inventoryStdoutMaxBytes', merged.inventoryStdoutMaxBytes),
+        stderrMaxBytes: positiveInteger('stderrMaxBytes', merged.stderrMaxBytes),
+        combinedStdoutMaxBytes: positiveInteger('combinedStdoutMaxBytes', merged.combinedStdoutMaxBytes),
+        toolTimeoutMs: positiveInteger('toolTimeoutMs', merged.toolTimeoutMs),
+    });
+}
+/** Validate only mechanical resource boundaries and deduplicate in first-seen order. */
+export function normalizeHelpTargets(input, limits) {
+    if (!Array.isArray(input)) {
+        throw new MarivoHelpError('invalid-request', 'marivo_help targets must be an array');
+    }
+    if (input.length === 0) {
+        throw new MarivoHelpError('invalid-request', 'marivo_help targets must contain at least one target');
+    }
+    if (input.length > limits.maxTargets) {
+        throw new MarivoHelpError('invalid-request', `marivo_help accepts at most ${limits.maxTargets} targets per call`, { maxTargets: limits.maxTargets, received: input.length });
+    }
+    const targets = [];
+    const seen = new Set();
+    let totalChars = 0;
+    for (const [index, target] of input.entries()) {
+        if (typeof target !== 'string' || target.length === 0) {
+            throw new MarivoHelpError('invalid-request', `marivo_help target at index ${index} must be a non-empty string`, { index });
+        }
+        if (target.length > limits.maxTargetChars) {
+            throw new MarivoHelpError('invalid-request', `marivo_help target at index ${index} exceeds ${limits.maxTargetChars} characters`, { index, maxTargetChars: limits.maxTargetChars, received: target.length });
+        }
+        totalChars += target.length;
+        if (totalChars > limits.maxTotalTargetChars) {
+            throw new MarivoHelpError('invalid-request', `marivo_help targets exceed ${limits.maxTotalTargetChars} total characters`, { maxTotalTargetChars: limits.maxTotalTargetChars, received: totalChars });
+        }
+        if (!seen.has(target)) {
+            seen.add(target);
+            targets.push(target);
+        }
+    }
+    return targets;
+}
+/** Read the current raw canonical inventory without parsing or caching it. */
+export async function loadTargetInventory(bridge, options = {}) {
+    const limits = resolveMarivoHelpLimits(options.limits);
+    const stdout = await bridge.inventory({
+        timeoutMs: limits.targetTimeoutMs,
+        stdoutMaxBytes: limits.inventoryStdoutMaxBytes,
+        stderrMaxBytes: limits.stderrMaxBytes,
+    }, options.signal);
+    return stdout.toString('utf8');
+}
+export function marivoHelpBodyDigest(body) {
+    return createHash('sha256').update(body).digest('hex');
+}
+export function renderMarivoHelpValue(value) {
+    const header = `Marivo version: ${value.environment.version}`;
+    return [
+        header,
+        ...value.targets.map((item) => {
+            if (item.delivery === 'already-visible') {
+                return `Target: ${item.target}\nCurrent help is already visible in this prompt.`;
+            }
+            return `Target: ${item.target}\n${item.body}`;
+        }),
+    ].join('\n\n');
+}
+function helpPresentationKey(value) {
+    return JSON.stringify([
+        value.environment.version,
+        value.targets.map((item) => [item.target, item.bodyDigest, item.delivery]),
+    ]);
+}
+/** Read one all-or-nothing batch from the bound live Marivo help surface. */
+export async function readMarivoHelpTargets(bridge, rawTargets, options = {}) {
+    const limits = resolveMarivoHelpLimits(options.limits);
+    const targets = normalizeHelpTargets(rawTargets, limits);
+    const environmentIdentity = {
+        version: bridge.binding.marivoVersion,
+        fingerprint: bridge.binding.fingerprint,
+    };
+    const results = [];
+    let combinedBytes = 0;
+    for (const target of targets) {
+        const stdout = await bridge.runTarget(target, {
+            timeoutMs: limits.targetTimeoutMs,
+            stdoutMaxBytes: limits.focusedStdoutMaxBytes,
+            stderrMaxBytes: limits.stderrMaxBytes,
+        }, options.signal);
+        combinedBytes += stdout.byteLength;
+        if (combinedBytes > limits.combinedStdoutMaxBytes) {
+            throw new MarivoHelpError('combined-output-limit', `marivo_help combined stdout exceeds ${limits.combinedStdoutMaxBytes} bytes`, { maxBytes: limits.combinedStdoutMaxBytes, observedBytes: combinedBytes, target });
+        }
+        const body = stdout.toString('utf8');
+        const bodyDigest = marivoHelpBodyDigest(body);
+        results.push({
+            target,
+            body,
+            bodyDigest,
+            delivery: options.resolveDelivery?.({
+                environmentFingerprint: environmentIdentity.fingerprint,
+                target,
+                bodyDigest,
+            }) ?? 'delivered',
+        });
+    }
+    return { environment: environmentIdentity, targets: results };
+}
+/** Build the native Harness ToolDefinition without registering Agent activation behavior. */
+export function createMarivoHelpTool(bridgeSource, limitOverrides = {}, resolveDelivery) {
+    const limits = resolveMarivoHelpLimits(limitOverrides);
+    const presentations = new Map();
+    return defineTool({
+        name: MARIVO_HELP_TOOL_NAME,
+        description: 'Request current live Marivo API help for one or more canonical string targets from the exact shared Runtime.',
+        parameters: {
+            targets: {
+                type: 'array',
+                required: true,
+                description: 'One or more canonical Marivo help targets.',
+                items: { type: 'string' },
+            },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    environment: {
+                        type: 'object',
+                        required: true,
+                        additionalProperties: false,
+                        properties: {
+                            version: { type: 'string', required: true },
+                        },
+                    },
+                    targets: {
+                        type: 'array',
+                        required: true,
+                        items: {
+                            type: 'object',
+                            additionalProperties: false,
+                            properties: {
+                                target: { type: 'string', required: true },
+                                body: { type: 'string', required: true },
+                                bodyDigest: { type: 'string', required: true },
+                                delivery: {
+                                    type: 'string',
+                                    required: true,
+                                    enum: ['delivered', 'already-visible', 'replacement'],
+                                },
+                            },
+                        },
+                    },
+                },
+            },
+            render: (_args, value) => [{ type: 'text', text: renderMarivoHelpValue(value) }],
+            presentationMeta: (_args, value) => {
+                const key = helpPresentationKey(value);
+                const pending = presentations.get(key);
+                const environmentFingerprint = pending?.shift();
+                if (pending?.length === 0)
+                    presentations.delete(key);
+                if (environmentFingerprint === undefined) {
+                    throw new Error('marivo_help presentation identity is unavailable');
+                }
+                return {
+                    kind: 'marivo-help-disclosure',
+                    environmentFingerprint,
+                    targets: value.targets.map((item) => ({
+                        target: item.target,
+                        bodyDigest: item.bodyDigest,
+                        delivery: item.delivery,
+                    })),
+                };
+            },
+        },
+        timeoutMs: limits.toolTimeoutMs,
+        async execute(args, exec) {
+            const bridge = await resolveMarivoHelpBridge(bridgeSource);
+            const internal = await readMarivoHelpTargets(bridge, args.targets, {
+                limits,
+                signal: exec.signal,
+                resolveDelivery,
+            });
+            const value = {
+                environment: { version: internal.environment.version },
+                targets: internal.targets,
+            };
+            const key = helpPresentationKey(value);
+            const pending = presentations.get(key) ?? [];
+            pending.push(internal.environment.fingerprint);
+            presentations.set(key, pending);
+            return value;
+        },
+    });
+}
+/** Register the focused Help Tool; skill-triggered root disclosure is composed separately. */
+export function registerMarivoHelpTool(ctx, bridgeSource, limits = {}, resolveDelivery) {
+    return ctx.tools.register(createMarivoHelpTool(bridgeSource, limits, resolveDelivery));
+}

package/lib/disclosure/index.js

@@ -0,0 +1,3 @@
+export { installMarivoDisclosure, MARIVO_ROOT_HELP_TARGETS, MarivoDisclosureController, MarivoDisclosureError, } from "./activation.js";
+export { MarivoHelpBridge } from "./bridge.js";
+export { createMarivoHelpTool, DEFAULT_MARIVO_HELP_LIMITS, loadTargetInventory, MARIVO_HELP_TOOL_NAME, MarivoHelpError, marivoHelpBodyDigest, normalizeHelpTargets, readMarivoHelpTargets, registerMarivoHelpTool, renderMarivoHelpValue, resolveMarivoHelpBridge, resolveMarivoHelpLimits, } from "./help.js";