@dsh-workbench/shared 0.1.0

package/dist/host/probe-libs.js

@@ -0,0 +1,61 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { libDir, libInstallCommand } from './opencli-runtime';
+import { isNewerVersion, latestVersion } from './release';
+import { resetReleaseCache } from './release';
+import { checkVersionRange } from './version-range';
+export function installedLibVersion(name) {
+    try {
+        const parsed = JSON.parse(readFileSync(join(libDir(name), 'package.json'), 'utf8'));
+        const version = parsed.version;
+        return typeof version === 'string' && version.trim() !== ''
+            ? version.trim()
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function probeLibs(options) {
+    const { needs, shell, force } = options;
+    const found = new Map();
+    for (const need of needs) {
+        if (found.has(need.name))
+            continue;
+        const base = { name: need.name, purpose: need.purpose };
+        const installed = installedLibVersion(need.name);
+        if (installed === undefined) {
+            found.set(need.name, {
+                ...base,
+                status: 'missing',
+                command: libInstallCommand({ need }),
+            });
+            continue;
+        }
+        if (checkVersionRange(need.version, installed) !== 'satisfied') {
+            found.set(need.name, {
+                ...base,
+                status: 'unsatisfied',
+                installed,
+                command: libInstallCommand({ need }),
+            });
+            continue;
+        }
+        const registry = process.env[need.registryEnv]?.trim() || need.registryDefault;
+        const latest = await latestVersion({ shell, name: need.name, registry, force });
+        const behind = latest !== undefined && isNewerVersion(latest, installed);
+        found.set(need.name, {
+            ...base,
+            status: behind ? 'outdated' : 'ok',
+            installed,
+            ...(latest === undefined ? {} : { latest }),
+            ...(behind
+                ? { command: libInstallCommand({ need, version: latest }) }
+                : {}),
+        });
+    }
+    return found;
+}
+export function resetLibCache() {
+    resetReleaseCache();
+}

package/dist/host/probe-units.d.ts

@@ -0,0 +1,17 @@
+import type { DshShell } from '@dsh-workbench/shared';
+import { type UnitCapability, type UnitCommands } from "./probe-libs";
+export type { UnitCapability, UnitCommands, UnitLibState, UnitPluginState } from "./probe-libs";
+export declare function parsePluginList(stdout: string): unknown[] | undefined;
+export declare function probeUnitCommands(options: {
+    shell: DshShell;
+    command?: string;
+    unit: UnitCommands;
+    force?: boolean;
+}): Promise<UnitCapability>;
+export declare function probeUnits(options: {
+    shell: DshShell;
+    command?: string;
+    units: readonly UnitCommands[];
+    force?: boolean;
+}): Promise<UnitCapability[]>;
+export declare const resetProbeCache: () => void;

package/dist/host/probe-units.js

@@ -0,0 +1,102 @@
+import { OPENCLI_TIMEOUT_MS, PROBE_TTL_MS } from '@dsh-workbench/shared';
+import { createTimedMemo } from "./probe-cache";
+import { parseJsonLoose } from '@dsh-workbench/shared';
+import { npmRegistryOf } from "./plugin-source";
+import { probeRelease } from "./release";
+import { probeLibs } from "./probe-libs";
+import { evaluateUnit } from "./probe-verdict";
+import { runShell } from "./shell";
+export function parsePluginList(stdout) {
+    const parsed = parseJsonLoose(stdout);
+    if (Array.isArray(parsed))
+        return parsed;
+    return /no plugins? installed/i.test(stdout) ? [] : undefined;
+}
+async function probeReleases(units, options) {
+    const needs = new Map();
+    for (const unit of units) {
+        for (const need of unit.plugins ?? []) {
+            const source = need.installSource;
+            if (source?.kind === "npm")
+                needs.set(need.name, source);
+        }
+    }
+    const found = new Map();
+    for (const [plugin, source] of needs) {
+        const registry = npmRegistryOf(source, process.env);
+        const signal = await probeRelease({
+            shell: options.shell,
+            package: source.package,
+            ...(registry.ok ? { registry: registry.value } : {}),
+            force: options.force,
+        });
+        if (signal !== undefined)
+            found.set(plugin, signal);
+    }
+    return found;
+}
+export async function probeUnitCommands(options) {
+    const all = await probeUnits({ ...options, units: [options.unit] });
+    return (all[0] ??
+        evaluateUnit(undefined, options.unit, "unchecked", options.command ?? "opencli"));
+}
+export async function probeUnits(options) {
+    const { shell, command = "opencli", units, force = false } = options;
+    const hits = units.map((unit) => unitCache.get(`${command}:${unit.unit}`));
+    if (!force && hits.every((hit) => hit !== undefined)) {
+        return hits;
+    }
+    const result = await runShell(shell, `${command} plugin list -f json`, {
+        timeoutMs: OPENCLI_TIMEOUT_MS,
+    }).then((value) => ({
+        kind: "ok",
+        stdout: value.exitCode === 0 ? value.stdout : "",
+        stderr: value.stderr,
+    }), (error) => ({
+        kind: "error",
+        stdout: "",
+        stderr: String(error),
+    }));
+    const list = result.kind === "ok" ? parsePluginList(result.stdout) : undefined;
+    const failure = result.kind === "error"
+        ? result.stderr
+        : list === undefined
+            ? "plugin list 的输出读不懂（不是 JSON 数组）"
+            : undefined;
+    if (failure !== undefined) {
+        return units.map((unit) => {
+            const capability = {
+                unit: unit.unit,
+                ...(unit.plugins?.[0] === undefined
+                    ? {}
+                    : { plugin: unit.plugins[0].name }),
+                status: "unchecked",
+                required: (unit.plugins ?? []).flatMap((need) => need.commands ?? []),
+                missing: [],
+                detail: failure,
+            };
+            unitCache.set(`${command}:${unit.unit}`, capability);
+            return capability;
+        });
+    }
+    const [releases, libs] = await Promise.all([
+        probeReleases(units, { shell, force }),
+        probeLibs({
+            needs: units.flatMap((unit) => unit.libs ?? []),
+            shell,
+            force,
+        }),
+    ]);
+    return units.map((unit) => {
+        const capability = evaluateUnit(list, unit, undefined, command, releases, libsOfUnit(unit, libs));
+        unitCache.set(`${command}:${unit.unit}`, capability);
+        return capability;
+    });
+}
+function libsOfUnit(unit, libs) {
+    return (unit.libs ?? [])
+        .map((need) => libs.get(need.name))
+        .filter((state) => state !== undefined);
+}
+const unitCache = createTimedMemo(PROBE_TTL_MS);
+export const resetProbeCache = () => void unitCache.clear();

package/dist/host/probe-verdict.d.ts

@@ -0,0 +1,7 @@
+import type { PluginRelease, UnitPluginNeed } from '@dsh-workbench/shared';
+import type { UnitCapability, UnitCommands, UnitLibState } from "./probe-libs";
+export declare function evaluateUnit(list: readonly unknown[] | undefined, unit: UnitCommands, failure: string | undefined, command?: string, releases?: ReadonlyMap<string, PluginRelease>, libs?: readonly UnitLibState[]): UnitCapability;
+export declare function gapsText(gaps: readonly string[]): string;
+export declare function pluginUpdateCommand(plugin: string | undefined): string | undefined;
+export declare function pluginInstallCommand(plugin: string | undefined): string;
+export declare function upgradeLine(need: UnitPluginNeed, command: string, latest: string): string | undefined;

package/dist/host/probe-verdict.js

@@ -0,0 +1,143 @@
+import { resolvePluginSource } from "./plugin-source";
+import { isNewerVersion } from "./release";
+export function evaluateUnit(list, unit, failure, command = "opencli", releases = new Map(), libs = []) {
+    const isPlugin = (item) => typeof item === "object" && item !== null;
+    const needs = unit.plugins ?? [];
+    const required = needs.flatMap((need) => need.commands ?? []);
+    const primary = needs[0]?.name;
+    if (failure !== undefined || list === undefined) {
+        return {
+            unit: unit.unit,
+            ...(primary === undefined ? {} : { plugin: primary }),
+            status: "unchecked",
+            required,
+            missing: [],
+            detail: failure ?? "探不动",
+            ...(libs.length === 0 ? {} : { libs }),
+        };
+    }
+    const plugins = list.filter(isPlugin);
+    const installed = new Map(plugins.map((item) => [String(item.name), item]));
+    const states = needs.map((need) => {
+        const hit = installed.get(need.name);
+        if (hit === undefined) {
+            const source = resolvePluginSource(need.installSource, process.env, {
+                command,
+                plugin: need.name,
+            });
+            return {
+                name: need.name,
+                status: "missing",
+                missing: [],
+                install: source.ok ? "ready" : source.problem,
+                command: source.ok ? source.line : pluginInstallCommand(need.name),
+            };
+        }
+        const available = new Set((Array.isArray(hit.commands) ? hit.commands : []).map(String));
+        const missing = (need.commands ?? []).filter((name) => !available.has(name));
+        const release = releases.get(need.name);
+        const behind = release?.latest !== undefined &&
+            isNewerVersion(release.latest, release.installed);
+        const commandsBehind = missing.length > 0;
+        const upgrade = behind && release?.latest !== undefined
+            ? upgradeLine(need, command, release.latest)
+            : undefined;
+        return {
+            name: need.name,
+            status: commandsBehind || behind ? "outdated" : "ok",
+            missing,
+            ...(release === undefined ? {} : { release }),
+            ...(commandsBehind || behind
+                ? {
+                    command: upgrade ??
+                        pluginUpdateCommand(need.name) ??
+                        pluginInstallCommand(need.name),
+                }
+                : {}),
+        };
+    });
+    const absent = states.filter((state) => state.status === "missing");
+    const outdated = states.filter((state) => state.status === "outdated");
+    const missing = states.flatMap((state) => state.missing);
+    const libMissing = libs.filter((state) => state.status === "missing");
+    const libMismatch = libs.filter((state) => state.status === "unsatisfied");
+    const libBehind = libs.filter((state) => state.status === "outdated");
+    const status = absent.length > 0 || libMissing.length > 0 || libMismatch.length > 0
+        ? "missing-plugin"
+        : missing.length > 0
+            ? "missing-commands"
+            : "ok";
+    const blocked = absent.find((state) => state.install !== "ready");
+    const install = absent.length === 0
+        ?
+            libMissing.length > 0 || libMismatch.length > 0
+                ? "ready"
+                : undefined
+        : blocked === undefined
+            ? "ready"
+            : blocked.install;
+    const fix = status === "missing-plugin"
+        ? install === "ready"
+            ? "install"
+            : undefined
+        : outdated.length > 0 || libBehind.length > 0
+            ? "update"
+            : undefined;
+    const first = absent[0] ?? outdated[0] ?? libMissing[0] ?? libMismatch[0] ?? libBehind[0];
+    const gaps = [...(missing.length === 0 ? [] : [`缺必需：${missing.join("、")}`])];
+    const newer = states.filter((state) => state.release?.latest !== undefined &&
+        isNewerVersion(state.release.latest, state.release.installed));
+    const versionText = newer.length === 0
+        ? ""
+        : `（源上有新版：${newer.map((state) => `${state.release?.installed ?? ""} → ${state.release?.latest ?? ""}`).join("、")}）`;
+    const absentNames = [
+        ...absent.map((state) => state.name),
+        ...libMissing.map((state) => state.name),
+    ];
+    const mismatchText = libMismatch.map((state) => {
+        const declared = unit.libs?.find((need) => need.name === state.name)?.version?.trim();
+        return `${state.name}（装的是 ${state.installed ?? "未知"}，声明要 ${declared === undefined || declared === "" ? "任意版本" : declared}）`;
+    });
+    return {
+        unit: unit.unit,
+        ...(primary === undefined ? {} : { plugin: primary }),
+        status,
+        required,
+        missing,
+        detail: absentNames.length > 0 || mismatchText.length > 0
+            ? [
+                ...(absentNames.length === 0
+                    ? []
+                    : [`${plugins.length} 个已装插件里没有 ${absentNames.join("、")}`]),
+                ...mismatchText,
+            ].join("；")
+            : `${needs.length} 份安装都在${gapsText(gaps)}${versionText}${libs.length === 0
+                ? ""
+                : `；交叉依赖：${libs.map((state) => `${state.name}${state.installed === undefined ? " 未装" : ` ${state.installed}`}`).join("、")}${libBehind.length === 0 ? "" : "（源上有新版）"}`}`,
+        ...(fix === undefined && first === undefined
+            ? {}
+            : { command: fix === "install" ? (absent[0] ?? first)?.command : first?.command }),
+        ...(fix === undefined ? {} : { fix }),
+        ...(install === undefined ? {} : { install }),
+        plugins: states,
+        ...(libs.length === 0 ? {} : { libs }),
+    };
+}
+export function gapsText(gaps) {
+    return gaps.length === 0 ? "" : `（${gaps.join("；")}）`;
+}
+export function pluginUpdateCommand(plugin) {
+    return plugin === undefined ? undefined : `opencli plugin update ${plugin}`;
+}
+export function pluginInstallCommand(plugin) {
+    return `opencli plugin install <${plugin ?? "插件"}源>`;
+}
+export function upgradeLine(need, command, latest) {
+    const source = resolvePluginSource(need.installSource, process.env, {
+        command,
+        plugin: need.name,
+        version: latest,
+        mode: "update",
+    });
+    return source.ok ? source.line : undefined;
+}

package/dist/host/provision.d.ts

@@ -0,0 +1,14 @@
+import type { ProvisionAction } from '../api/workbench-contract.js';
+export type { ProvisionAction };
+export declare const PROVISION_ACTIONS: readonly ["install", "update", "uninstall", "update-dependency"];
+export declare const DEPENDENCY_ACTIONS: readonly ["update-dependency"];
+export declare function isDependencyAction(action: ProvisionAction): action is (typeof DEPENDENCY_ACTIONS)[number];
+export interface ProvisionRequest {
+    readonly action: ProvisionAction;
+    readonly unit?: string;
+    readonly id?: string;
+}
+export interface ProvisionHandler {
+    handle(request: ProvisionRequest): Promise<unknown> | unknown;
+    affectedUnits?(request: ProvisionRequest): readonly string[];
+}

package/dist/host/provision.js

@@ -0,0 +1,12 @@
+export const PROVISION_ACTIONS = [
+    'install',
+    'update',
+    'uninstall',
+    'update-dependency',
+];
+export const DEPENDENCY_ACTIONS = ['update-dependency'];
+export function isDependencyAction(action) {
+    return DEPENDENCY_ACTIONS.includes(action);
+}
+const ALL_ACTIONS_COVERED = true;
+void ALL_ACTIONS_COVERED;

package/dist/host/shell.d.ts

@@ -0,0 +1,14 @@
+import type { DshShell } from '../api/dsh.js';
+export interface ShellResult {
+    readonly exitCode: number | null;
+    readonly timedOut: boolean;
+    readonly aborted: boolean;
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly truncated: boolean;
+}
+export declare function runShell(shell: DshShell, command: string, options?: {
+    workdir?: string;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}): Promise<ShellResult>;

package/dist/host/shell.js

@@ -0,0 +1,23 @@
+import { GIT_TIMEOUT_MS } from '../config/constants.js';
+const DEFAULT_MAX_BYTES = 8 * 1024 * 1024;
+export async function runShell(shell, command, options = {}) {
+    const { workdir, timeoutMs = GIT_TIMEOUT_MS, signal } = options;
+    const spec = shell.resolve({
+        command,
+        ...(workdir === undefined ? {} : { workdir }),
+        timeoutMs,
+        onExpiry: 'kill',
+        stdoutMaxBytes: DEFAULT_MAX_BYTES,
+        ...(signal === undefined ? {} : { signal }),
+    });
+    const execution = await shell.execute(spec);
+    const result = await execution.result();
+    return {
+        exitCode: result.exitCode,
+        timedOut: result.timedOut === true,
+        aborted: result.aborted === true,
+        stdout: result.stdout.text,
+        stderr: result.stderr.text,
+        truncated: result.stdout.truncated || result.stderr.truncated,
+    };
+}

package/dist/host/tool-approval.d.ts

@@ -0,0 +1,29 @@
+export type AskDecision = {
+    readonly kind: 'ask';
+    readonly reason: string;
+    readonly displayReason: {
+        readonly en: string;
+        readonly zh: string;
+    };
+} | {
+    readonly kind: 'deny';
+    readonly reason: string;
+};
+export interface ApprovalDetail {
+    readonly en: string;
+    readonly zh: string;
+}
+export type ApprovalFacts = ApprovalDetail | {
+    readonly blocked: string;
+};
+export interface ApprovalCall {
+    readonly name?: string | undefined;
+    readonly arguments?: unknown;
+    readonly workspace?: string | undefined;
+}
+export interface ApprovalContext {
+    readonly titleOf?: ((id: string) => string | undefined) | undefined;
+    readonly writes?: boolean | undefined;
+    readonly detailOf?: ((call: ApprovalCall) => ApprovalFacts | undefined | Promise<ApprovalFacts | undefined>) | undefined;
+}
+export declare function approvalFor(call: ApprovalCall, context?: ApprovalContext): Promise<AskDecision | undefined>;

package/dist/host/tool-approval.js

@@ -0,0 +1,190 @@
+function compose(detail, texts) {
+    if (detail === undefined || typeof detail.zh !== 'string' || detail.zh.trim() === '')
+        return texts.generic;
+    return { en: `${detail.en} — ${texts.question.en}`, zh: `${detail.zh} —— ${texts.question.zh}` };
+}
+function actionOf(call) {
+    const raw = call.arguments;
+    if (typeof raw !== 'object' || raw === null)
+        return {};
+    const value = raw;
+    return {
+        ...(typeof value.action === 'string' ? { action: value.action } : {}),
+        ...(typeof value.id === 'string' ? { id: value.id } : typeof value.unit === 'string' ? { id: value.unit } : {}),
+    };
+}
+const READ_ONLY_ACTIONS = new Set(['list', '']);
+const READ = { kind: 'read' };
+const UNKNOWN = { kind: 'unknown' };
+function ask(spec) {
+    return { kind: 'ask', spec };
+}
+function confirmed(call) {
+    const raw = call.arguments;
+    if (typeof raw !== 'object' || raw === null)
+        return undefined;
+    const value = raw.confirm;
+    return typeof value === 'boolean' ? value : undefined;
+}
+function effectOf(call, context) {
+    const name = call.name ?? '';
+    const { action, id } = actionOf(call);
+    const readAction = action !== undefined && action !== '' && READ_ONLY_ACTIONS.has(action);
+    const what = () => {
+        if (id === undefined || id === '')
+            return '一个模块';
+        return `「${context.titleOf?.(id) ?? id}」`;
+    };
+    if (name === 'workbench_cmdb_release') {
+        if (confirmed(call) !== true)
+            return READ;
+        return ask({
+            reason: 'confirm=true releases a version to a real environment',
+            generic: {
+                en: 'The agent wants to deploy a version for real (confirm: true) — it deploys on the platform (non-production). Allow?',
+                zh: 'agent 想在非生产环境上**真的部署一个版本**（confirm: true）—— 会在平台上部署。允许吗？',
+            },
+            question: {
+                en: 'it deploys on the platform for real (non-production). Allow?',
+                zh: '会在平台上真的部署一次（非生产环境）。允许吗？',
+            },
+        });
+    }
+    if (name === 'workbench_coding_issue_comment' || name === 'workbench_coding_issue_transfer') {
+        if (confirmed(call) !== true)
+            return READ;
+        const comment = name === 'workbench_coding_issue_comment';
+        return ask({
+            reason: comment
+                ? 'confirm=true posts a comment on the platform'
+                : 'confirm=true moves an issue to another status on the platform',
+            generic: comment
+                ? {
+                    en: 'The agent wants to post a comment on the platform for real (confirm: true) — it writes on the platform. Allow?',
+                    zh: 'agent 想**真的给一条缺陷加评论**（confirm: true）—— 会写平台数据。允许吗？',
+                }
+                : {
+                    en: 'The agent wants to move an issue to another status for real (confirm: true) — it writes on the platform. Allow?',
+                    zh: 'agent 想**真的把一条缺陷流转到别的状态**（confirm: true）—— 会写平台数据。允许吗？',
+                },
+            question: comment
+                ? {
+                    en: 'it posts that comment on the platform for real. Allow?',
+                    zh: '会在平台上真的发表这条评论。允许吗？',
+                }
+                : {
+                    en: 'it changes that issue status on the platform for real. Allow?',
+                    zh: '会在平台上真的改这条缺陷的状态。允许吗？',
+                },
+        });
+    }
+    if (name === 'workbench_modules') {
+        if (readAction)
+            return READ;
+        if (action === 'update-dependency') {
+            return ask({
+                reason: `workbench_modules update-dependency ${id ?? ''} upgrades a shared dependency on this machine`,
+                generic: {
+                    en: `The agent wants to upgrade the shared dependency ${what()} (it changes what is installed on this machine). Allow?`,
+                    zh: `agent 想升级共用依赖 ${what()}（会改这台机器上装的东西）。允许吗？`,
+                },
+                question: {
+                    en: 'it upgrades that shared dependency on this machine. Allow?',
+                    zh: `会升级共用依赖 ${what()}。允许吗？`,
+                },
+            });
+        }
+        const verb = action === 'install' ? '装' : action === 'uninstall' ? '卸载' : action === 'update' ? '更新' : '装 / 更新 / 卸载';
+        return ask({
+            reason: `workbench_modules ${action ?? '(unknown action)'} ${id ?? ''} changes plugins on this machine`.trim(),
+            generic: {
+                en: `The agent wants to ${verb === '装' ? 'install' : verb === '卸载' ? 'remove' : verb === '更新' ? 'update' : 'install/update/remove'} the module ${what()} (it changes plugins on this machine). Allow?`,
+                zh: `agent 想${verb}模块 ${what()}（会改这台机器上的插件）。允许吗？`,
+            },
+            question: {
+                en: 'it changes plugins on this machine. Allow?',
+                zh: '会改这台机器上的插件。允许吗？',
+            },
+        });
+    }
+    if (name !== 'workbench_panels')
+        return UNKNOWN;
+    if (readAction)
+        return READ;
+    if (action === 'hide') {
+        return ask({
+            reason: 'workbench_panels hide removes a module from the panel',
+            generic: {
+                en: `The agent wants to remove ${what()} from this project's panel (its agent tools go offline here too). Allow?`,
+                zh: `agent 想把 ${what()} 从这个项目的面板上收起来（这个项目里它的 agent 工具也一起下线）。允许吗？`,
+            },
+            question: {
+                en: 'it takes that module off this panel (its agent tools go offline here too). Allow?',
+                zh: `${what()}会从这个项目的面板上收起来（这个项目里它的 agent 工具也一起下线）。允许吗？`,
+            },
+        });
+    }
+    if (action === 'move') {
+        return ask({
+            reason: 'workbench_panels move reorders the panel',
+            generic: {
+                en: `The agent wants to reorder this project's panel (put ${what()} first). Allow?`,
+                zh: `agent 想调整这个项目面板的顺序（把 ${what()} 放前面）。允许吗？`,
+            },
+            question: {
+                en: `it reorders this panel (${what()} goes first). Allow?`,
+                zh: `会调整这个项目面板的顺序（${what()}放前面）。允许吗？`,
+            },
+        });
+    }
+    if (action === 'reset') {
+        return ask({
+            reason: 'workbench_panels reset clears the panel',
+            generic: {
+                en: "The agent wants to clear this project's panel (every module goes offline here). Allow?",
+                zh: 'agent 想清空这个项目的面板（所有模块在这个项目里都下线）。允许吗？',
+            },
+            question: {
+                en: 'it clears this panel (every module goes offline here). Allow?',
+                zh: '会清空这个项目的面板（所有模块在这个项目里都下线）。允许吗？',
+            },
+        });
+    }
+    return ask({
+        reason: `workbench_panels ${action ?? '(unknown action)'} changes the user's panel`,
+        generic: {
+            en: `The agent wants to add ${what()} to this project's panel. Allow?`,
+            zh: `agent 想把 ${what()} 加到**这个项目**的面板上。允许吗？`,
+        },
+        question: {
+            en: `it adds ${what()} to this project's panel. Allow?`,
+            zh: `会把 ${what()} 加到**这个项目**的面板上。允许吗？`,
+        },
+    });
+}
+export async function approvalFor(call, context = {}) {
+    const effect = effectOf(call, context);
+    if (effect.kind === 'read')
+        return undefined;
+    if (effect.kind === 'unknown') {
+        if (context.writes !== true)
+            return undefined;
+        return {
+            kind: 'deny',
+            reason: `${call.name ?? '这把工具'} 在清单里声明会写东西，但审批表没认领这次调用 —— 停下：` +
+                '给它在 tool-approval.ts 里补一条审批（含"这次会发生什么"），别让写静默过去',
+        };
+    }
+    const { spec } = effect;
+    let facts;
+    try {
+        facts = await context.detailOf?.(call);
+    }
+    catch (error) {
+        const why = error instanceof Error ? error.message : String(error);
+        return { kind: 'deny', reason: `拿不到"这次会发生什么"，已经停下：${why}` };
+    }
+    if (facts !== undefined && 'blocked' in facts)
+        return { kind: 'deny', reason: facts.blocked };
+    return { kind: 'ask', reason: spec.reason, displayReason: compose(facts, spec) };
+}

package/dist/host/tool-kit.d.ts

@@ -0,0 +1,19 @@
+import type { DshToolRunContext } from '../api/dsh.js';
+export declare function sessionWorkspace(exec: DshToolRunContext | undefined): string | null;
+export declare function textOutput(text: string): Array<Record<string, unknown>>;
+export declare function textRender(_args: unknown, value: unknown): Array<Record<string, unknown>>;
+export declare const TEXT_OUTPUT: {
+    schema: {
+        type: string;
+        properties: {};
+        additionalProperties: boolean;
+    };
+    render: typeof textRender;
+};
+export declare function jsonText(value: unknown): string;
+export interface CommandHintNames {
+    readonly plugin: string;
+    readonly suiteId: string;
+}
+export type CommandHint = <T>(command: string, run: () => Promise<T>) => Promise<T>;
+export declare function commandHintFor(names: CommandHintNames): CommandHint;