@dsh-edge/dsh-edge-agent 0.0.0-stage → 0.1.1

package/lib/dsh-adapter/effective-model.d.ts

@@ -0,0 +1,85 @@
+/**
+ * §7.179 (2026-11-11): 内部阶段（guard 检测 / 意图分类）**真正会跑**的模型。
+ *
+ * 背景（主人实测 2026-11-11 12:56，桌面 App）：
+ *
+ *   guard / intent 两个阶段的 provider 钉在 `local-llm` 上，但模型名此前只跟
+ *   `llm.local.model` 走（prompt-guard / intent-router 各自在 apply() 里算一次）。
+ *   **DELEGATE 模式下 `llm.local.baseUrl` 与 `llm.local.model` 都是空的**
+ *   （shipped 模板如此，§7.171）⇒ 模型名停在 Schema 默认 `qwen3-4b`，而 wire
+ *   上真正跑的是委托解析出来的**宿主当前模型**（实测
+ *   `qwen-token-plan-cn/deepseek-v4.1-flash`）。
+ *
+ *   ⇒ 面板写「模型 local-llm/qwen3-4b」而实际跑的是另一个模型 = **与实际行为
+ *   相反的陈述**（主人的规矩）。§7.176 已经定过同一口径（「DELEGATE 模式下写
+ *   宿主当前模型 id —— wire 上真正跑的就是它，不写一个跟实际不符的名字」），
+ *   这里把它落到 guard / intent 两个阶段上。
+ *
+ * 口径（与 local-llm-adapter 的 wire 行为逐条对齐，不是另写一套）：
+ *
+ *   - 直连池（`llm.local.baseUrl` 非空）：wire body 的 model = `llm.local.model`
+ *     （adapter 的 `defaultModel`，`options.model` 只是路由键 `route=`）⇒ 取它；
+ *   - DELEGATE 池（baseUrl 空）：wire body 的 model = 委托目标的解析结果
+ *     （`env` 显式 → `selection` 宿主当前选择 → `probe` 活拓扑探针；探针步
+ *     没定 model 时 adapter 在 stream 时取该 provider 的第一个 model id）
+ *     ⇒ **复用 adapter 的同一份解析链**（`probeCloudTarget`）；
+ *   - 都拿不到 ⇒ 退回调用方给的请求值，并如实标注来处（`requested`）。
+ *
+ * 单一事实源：`probeCloudTarget`（cloud-llm-adapter 导出）—— local-llm-adapter
+ * 的 DELEGATE 分支用的就是它，本模块只复用、不复制解析逻辑。
+ */
+/** 内部阶段真正会跑的模型。 */
+export interface EffectiveLocalModel {
+    /** 实际会跑（wire body）的模型 id。 */
+    model: string;
+    /**
+     * 实际落点的 provider。
+     *
+     * 直连池 = 本地路由自己（`local-llm`）；DELEGATE = **宿主 provider**
+     * （`qwen-token-plan-cn` 之类）—— 这一项才是「数据往哪儿去」的事实。
+     */
+    provider?: string;
+    /** 这个 id 的来处（审计与面板的事实标注）。 */
+    source: 'local-pool' | 'host-delegate' | 'requested';
+    /** 委托解析链的哪一步（与 delegate 审计的 `source` 同名，便于对账）。 */
+    via?: 'env' | 'selection' | 'probe';
+}
+/** 本地池里本模块用到的几个字段（测试可直接构造）。 */
+export interface LocalPoolShape {
+    baseUrl?: string;
+    model?: string;
+    /** `llm.local.delegate=false` = kill switch（路由不注册）。 */
+    delegate?: boolean;
+    delegateProvider?: string;
+    delegateModel?: string;
+}
+/**
+ * §7.180: **同步**解析（不触网）。
+ *
+ * 供 input-guard 在 `agent/created` 里**同步**补钉会话选择：宿主的第一轮
+ * pre-step 紧跟 agent 创建之后，异步补钉会来不及（§7.179 的 fail-closed
+ * 闸门会把第一轮直接拒掉）。
+ *
+ * 返回 `undefined` = 这一轮解析还需要一次异步的 `firstModelId` 查询（委托
+ * 解析链的**探针步**没定 model）⇒ 调用方要么异步补钉，要么明确跳过 ——
+ * **不许**拿一个「看起来对」的 id 糊弄过去（§7.176）。
+ */
+export declare function resolveEffectiveLocalModelSync(ctx: unknown, pool: LocalPoolShape, requested: string, ownProvider?: string): EffectiveLocalModel | undefined;
+/**
+ * 解析「这个内部阶段这一轮真正会跑哪个模型」（池形态由调用方给 ⇒ 可测）。
+ *
+ * @param ctx        宿主 ctx（读 `llm` / `agentDefaultModel` 两个软依赖）
+ * @param pool       本地池现状（直连 / DELEGATE）
+ * @param requested  调用方请求的模型 id（拿不到真相时的退路）
+ * @param ownProvider 调用方自己那条路由（`local-llm`），用于递归护栏
+ */
+export declare function resolveEffectiveLocalModelWith(ctx: unknown, pool: LocalPoolShape, requested: string, ownProvider?: string): Promise<EffectiveLocalModel>;
+/**
+ * 解析「这个内部阶段这一轮真正会跑哪个模型」（池形态取自 config/edge.json）。
+ *
+ * @param ctx        宿主 ctx（读 `llm` / `agentDefaultModel` 两个软依赖）
+ * @param requested  调用方请求的模型 id（拿不到真相时的退路）
+ * @param ownProvider 调用方自己那条路由（`local-llm`），用于递归护栏
+ */
+export declare function resolveEffectiveLocalModel(ctx: unknown, requested: string, ownProvider?: string): Promise<EffectiveLocalModel>;
+//# sourceMappingURL=effective-model.d.ts.map

package/lib/dsh-adapter/effective-model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"effective-model.d.ts","sourceRoot":"","sources":["../../src/dsh-adapter/effective-model.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAaH,mBAAmB;AACnB,MAAM,WAAW,mBAAmB;IAClC,6BAA6B;IAC7B,KAAK,EAAE,MAAM,CAAA;IACb;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,6BAA6B;IAC7B,MAAM,EAAE,YAAY,GAAG,eAAe,GAAG,WAAW,CAAA;IACpD,kDAAkD;IAClD,GAAG,CAAC,EAAE,KAAK,GAAG,WAAW,GAAG,OAAO,CAAA;CACpC;AAED,+BAA+B;AAC/B,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,uDAAuD;IACvD,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB;AA8DD;;;;;;;;;;GAUG;AACH,wBAAgB,8BAA8B,CAC5C,GAAG,EAAE,OAAO,EACZ,IAAI,EAAE,cAAc,EACpB,SAAS,EAAE,MAAM,EACjB,WAAW,SAAc,GACxB,mBAAmB,GAAG,SAAS,CAoBjC;AAED;;;;;;;GAOG;AACH,wBAAsB,8BAA8B,CAClD,GAAG,EAAE,OAAO,EACZ,IAAI,EAAE,cAAc,EACpB,SAAS,EAAE,MAAM,EACjB,WAAW,SAAc,GACxB,OAAO,CAAC,mBAAmB,CAAC,CAoB9B;AAED;;;;;;GAMG;AACH,wBAAsB,0BAA0B,CAC9C,GAAG,EAAE,OAAO,EACZ,SAAS,EAAE,MAAM,EACjB,WAAW,SAAc,GACxB,OAAO,CAAC,mBAAmB,CAAC,CAQ9B"}

package/lib/dsh-adapter/effective-model.js

@@ -0,0 +1,171 @@
+/**
+ * §7.179 (2026-11-11): 内部阶段（guard 检测 / 意图分类）**真正会跑**的模型。
+ *
+ * 背景（主人实测 2026-11-11 12:56，桌面 App）：
+ *
+ *   guard / intent 两个阶段的 provider 钉在 `local-llm` 上，但模型名此前只跟
+ *   `llm.local.model` 走（prompt-guard / intent-router 各自在 apply() 里算一次）。
+ *   **DELEGATE 模式下 `llm.local.baseUrl` 与 `llm.local.model` 都是空的**
+ *   （shipped 模板如此，§7.171）⇒ 模型名停在 Schema 默认 `qwen3-4b`，而 wire
+ *   上真正跑的是委托解析出来的**宿主当前模型**（实测
+ *   `qwen-token-plan-cn/deepseek-v4.1-flash`）。
+ *
+ *   ⇒ 面板写「模型 local-llm/qwen3-4b」而实际跑的是另一个模型 = **与实际行为
+ *   相反的陈述**（主人的规矩）。§7.176 已经定过同一口径（「DELEGATE 模式下写
+ *   宿主当前模型 id —— wire 上真正跑的就是它，不写一个跟实际不符的名字」），
+ *   这里把它落到 guard / intent 两个阶段上。
+ *
+ * 口径（与 local-llm-adapter 的 wire 行为逐条对齐，不是另写一套）：
+ *
+ *   - 直连池（`llm.local.baseUrl` 非空）：wire body 的 model = `llm.local.model`
+ *     （adapter 的 `defaultModel`，`options.model` 只是路由键 `route=`）⇒ 取它；
+ *   - DELEGATE 池（baseUrl 空）：wire body 的 model = 委托目标的解析结果
+ *     （`env` 显式 → `selection` 宿主当前选择 → `probe` 活拓扑探针；探针步
+ *     没定 model 时 adapter 在 stream 时取该 provider 的第一个 model id）
+ *     ⇒ **复用 adapter 的同一份解析链**（`probeCloudTarget`）；
+ *   - 都拿不到 ⇒ 退回调用方给的请求值，并如实标注来处（`requested`）。
+ *
+ * 单一事实源：`probeCloudTarget`（cloud-llm-adapter 导出）—— local-llm-adapter
+ * 的 DELEGATE 分支用的就是它，本模块只复用、不复制解析逻辑。
+ */
+import { probeCloudTarget, localPoolTargetCache, } from './cloud-llm-adapter.js';
+import { localPool } from './edge-config.js';
+/** ctx 上取宿主服务的软读法（读不到就是 undefined，不抛）。 */
+function softService(ctx, name) {
+    try {
+        return ctx?.get?.(name);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * 用 adapter 的同一份解析链探一次委托目标。
+ *
+ * `ownProvider` = 调用方自己那条路由（`local-llm`）—— 递归护栏要排除它自己。
+ *
+ * §7.180: 结果进**共享**缓存（`localPoolTargetCache`）—— 与 wire
+ * （local-llm-adapter 的 DELEGATE 分支）、模型目录（`listModels()`）读的是
+ * 同一个目标对象 ⇒ 三处说的必然是同一个模型。
+ */
+function probeTarget(ctx, ownProvider, pool) {
+    const llm = softService(ctx, 'llm');
+    if (!llm || typeof llm.listProviders !== 'function')
+        return null;
+    const accessors = {
+        llm,
+        getAgentDefaultModel: () => softService(ctx, 'agentDefaultModel'),
+    };
+    const cfg = {
+        providers: [ownProvider],
+        delegateProvider: pool.delegateProvider,
+        delegateModel: pool.delegateModel,
+        // `llm.local.delegate=false` = kill switch ⇒ 路由根本没注册 ⇒ 没有委托目标。
+        delegateEnabled: pool.delegate,
+    };
+    try {
+        const cached = localPoolTargetCache.get(llm, cfg);
+        if (cached !== undefined)
+            return cached;
+        const target = probeCloudTarget(accessors, cfg);
+        localPoolTargetCache.set(llm, cfg, target);
+        return target;
+    }
+    catch {
+        return null;
+    }
+}
+/** 探针步没定 model 时，adapter 取该 provider 的第一个 model id（同一口径）。 */
+async function firstModelId(ctx, provider) {
+    const llm = softService(ctx, 'llm');
+    if (!llm || typeof llm.listModels !== 'function')
+        return '';
+    try {
+        const models = await llm.listModels(provider);
+        const id = models?.[0]?.id;
+        return typeof id === 'string' ? id.trim() : '';
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * §7.180: **同步**解析（不触网）。
+ *
+ * 供 input-guard 在 `agent/created` 里**同步**补钉会话选择：宿主的第一轮
+ * pre-step 紧跟 agent 创建之后，异步补钉会来不及（§7.179 的 fail-closed
+ * 闸门会把第一轮直接拒掉）。
+ *
+ * 返回 `undefined` = 这一轮解析还需要一次异步的 `firstModelId` 查询（委托
+ * 解析链的**探针步**没定 model）⇒ 调用方要么异步补钉，要么明确跳过 ——
+ * **不许**拿一个「看起来对」的 id 糊弄过去（§7.176）。
+ */
+export function resolveEffectiveLocalModelSync(ctx, pool, requested, ownProvider = 'local-llm') {
+    // 直连池：wire body 的 model 就是池自己的 model（同步可知）。
+    if (pool.baseUrl) {
+        const model = (pool.model ?? '').trim();
+        return {
+            model: model.length > 0 ? model : requested,
+            provider: ownProvider,
+            source: 'local-pool',
+        };
+    }
+    // DELEGATE：与 adapter 同一条解析链（同步部分）。
+    const target = probeTarget(ctx, ownProvider, pool);
+    if (!target) {
+        // 解析不到任何落点 ⇒ 池跑不起来；退回请求值并如实标注来处。
+        return { model: requested, source: 'requested' };
+    }
+    const model = (target.model ?? '').trim();
+    if (model.length === 0)
+        return undefined;
+    return { model, provider: target.provider, source: 'host-delegate', via: target.source };
+}
+/**
+ * 解析「这个内部阶段这一轮真正会跑哪个模型」（池形态由调用方给 ⇒ 可测）。
+ *
+ * @param ctx        宿主 ctx（读 `llm` / `agentDefaultModel` 两个软依赖）
+ * @param pool       本地池现状（直连 / DELEGATE）
+ * @param requested  调用方请求的模型 id（拿不到真相时的退路）
+ * @param ownProvider 调用方自己那条路由（`local-llm`），用于递归护栏
+ */
+export async function resolveEffectiveLocalModelWith(ctx, pool, requested, ownProvider = 'local-llm') {
+    // 直连池 / 解析不到落点：同步就能定。
+    const sync = resolveEffectiveLocalModelSync(ctx, pool, requested, ownProvider);
+    if (sync !== undefined && sync.source !== 'host-delegate')
+        return sync;
+    // DELEGATE 且探针步没定 model：需要一次 firstModelId 查询（异步）。
+    const target = probeTarget(ctx, ownProvider, pool);
+    if (!target)
+        return { model: requested, source: 'requested' };
+    let model = (target.model ?? '').trim();
+    if (model.length === 0) {
+        model = await firstModelId(ctx, target.provider);
+        // §7.180: 回填进缓存的目标对象 ⇒ 目录（listModels）、会话补钉与 wire
+        // 三处共享同一个 id（缓存里放的就是这个对象本身）。
+        if (model.length > 0)
+            target.model = model;
+    }
+    if (model.length === 0) {
+        // 落点解析到了、model id 拿不到 ⇒ 如实记下落点，模型名退回请求值。
+        return { model: requested, provider: target.provider, source: 'host-delegate', via: target.source };
+    }
+    return { model, provider: target.provider, source: 'host-delegate', via: target.source };
+}
+/**
+ * 解析「这个内部阶段这一轮真正会跑哪个模型」（池形态取自 config/edge.json）。
+ *
+ * @param ctx        宿主 ctx（读 `llm` / `agentDefaultModel` 两个软依赖）
+ * @param requested  调用方请求的模型 id（拿不到真相时的退路）
+ * @param ownProvider 调用方自己那条路由（`local-llm`），用于递归护栏
+ */
+export async function resolveEffectiveLocalModel(ctx, requested, ownProvider = 'local-llm') {
+    let pool;
+    try {
+        pool = localPool();
+    }
+    catch {
+        pool = {};
+    }
+    return resolveEffectiveLocalModelWith(ctx, pool, requested, ownProvider);
+}

package/lib/dsh-adapter/etscli-shell-guard.d.ts

@@ -0,0 +1,244 @@
+/**
+ * etscli-shell-guard — §7.120：封堵「bash 里直接调 etscli 写子命令」这条逃逸口
+ *
+ * ## 为什么需要这个模块
+ *
+ * §7.98 的安全边界是**注册表白名单**：只把 14 个**只读** etscli 子命令注册进
+ * `ctx.tools`，写类（`file upload` / `file delete` / `fs rm` / `chat send` /
+ * `auth logout` / `migrate *` / `sharing create` / `meeting summary` /
+ * `file download` …）一个都不注册 ⇒ 模型在**工具清单**里选不到它们。
+ *
+ * 但 §7.118 那次实测把这条边界捅穿了：agent 直接
+ * `bash: etscli file upload ...`，把本地文件传到了 MEOS 设备的
+ * `/备忘/联系方式.txt`。原因（§7.120 查清）：
+ *
+ * 1. 宿主的 **Auto review 闸门只在 `auto` preset 下安装**，本仓 edge preset 用
+ *    `workspace-write` ⇒ 没有风险分类器；
+ * 2. 剩下的**沙箱越界升级是纯文件系统视角** —— `etscli file upload` 改的是
+ *    **远端 MEOS 设备**（走 etscli 自己的协议），对文件系统沙箱完全不可见 ⇒
+ *    不越界 ⇒ 不升级 ⇒ **不触发审批**；
+ * 3. 于是 `bash` 这个通用逃逸口成了唯一的真身在侧：白名单管的是「工具清单」，
+ *    管不住「模型自己在 shell 里敲什么」。
+ *
+ * ## 主人裁决（2026-10-31）与机制落点
+ *
+ * > 用**插件侧守卫**封堵 —— 拦 bash 里 etscli 的写子命令。
+ *
+ * 裁决的实质是「**插件侧**封堵，不碰宿主启动环境（不改 PATH / 不改启动脚本），
+ * 桌面与无头两个 profile 都生效」。机制落点从 `ctx.tools.guard()` 换成
+ * `tools/pre-execute` waterfall，理由是三条**可查证**的事实：
+ *
+ * 1. **`ctx.tools.guard()` 不接受调用方的 scope。**
+ *    宿主实现是 `guard(guard) { return this.layers.effect(this.ctx, …) }`
+ *    （`@deepseek-ai/dsh-tools` `lib/index.js:3017-3022`）—— 注册进的是
+ *    **ToolRuntime 服务自己那个 ctx** 所在的层。插件侧拿到 `ctx.tools` 时，
+ *    拿不到、也改不了那个 ctx ⇒ **无法把守卫绑到边缘 preset 的 scope 上**；
+ *    服务在宿主根上下文提供时，那一层就是**全局层** ⇒ 标准模式会话也会被拦，
+ *    而标准模式会话的审计链必须**零本项目事件**（§7.140 不变式）。
+ * 2. **宿主的插件沙箱 façade 刻意不暴露 `guard`。**
+ *    `dsh-cordis-host-runner/lib/types/guard.js:581-588` 给插件的 `ctx.tools`
+ *    只留 `register` / `schemas` / `get`（注释里点名 `guard` 属于
+ *    「identity protection, pre-policy, **monotonic guards**, …」这一串
+ *    不许旁路的机制）。桌面 profile 现在给的是真服务（`ctx.tools.view()`
+ *    能用 ⇒ boot scan 数出 28 个工具），但这属于**沙箱边界之外的当前状态**，
+ *    不是稳定契约。
+ * 3. **`tools/pre-execute` 既是宿主点名的扩展点，又是 scope 感知的。**
+ *    宿主注释原话（`lib/index.js:3008`）：「Register a monotonic guard **after
+ *    the extensible `tools/pre-execute` waterfall**」。派发时
+ *    `carrier = scopeTarget(this, exec.agent)`（`lib/index.js:3320-3321`）——
+ *    监听器按 scope 链派发，**边缘 preset 的监听器只收到边缘会话的事件**，
+ *    标准模式会话的 scope 链上没有本插件的 scope ⇒ 收不到。
+ *
+ * 而 §7.136 已经把这条路在本仓跑通了：`realm-skill-bridge` 的 Layer 3 realm
+ * 闸门就是同一个 waterfall（`realm-skill-bridge.ts:1182`），审计链里有 6 条
+ * `tool.realm.denied`（`level: security`）作实证。
+ *
+ * 拒绝语义与 `guard()` 等价且同样**单调**：waterfall 判 `deny` 时
+ * `decision.reason` 直接成为拒绝理由（`lib/index.js:3337-3343`），工具**不派发**，
+ * 后续监听器与守卫都放不回来。
+ *
+ * ## 这条守卫堵的是「逃逸口」，不是「能力」
+ *
+ * 技能（`ets-file` / `ets-chat` / `ets-auth` …）走的是**宿主 skill 工具**
+ * （`exec.name === 'skill'`，参数 `skillName`），**不经过 bash**，因此**不受影响**
+ * —— 主人装的那些技能照常可用。本守卫只拦「模型自己在 shell 里敲 etscli」这条路。
+ *
+ * 诚实记录它的边界：**命令文本匹配可以被绝对路径调用、复制二进制、别名或拼接
+ * 绕过** ⇒ 它不是能力层的等价物。真正封死「模型按名字够到那个二进制」仍要靠
+ * 摘 PATH（主人本轮裁决不做）。两条是**纵深防御**关系。
+ *
+ * ## 依赖方向
+ *
+ * 本模块 import `etscli-tools.ts` 的 `ETSCLI_READONLY_ARGV`（白名单的**单一
+ * 事实源** = 从只读工具注册表派生的那份）—— **单向**依赖：`etscli-tools.ts`
+ * 不 import 本模块（否则成环：环在这里恰好不炸，那是求值顺序的运气）。
+ *
+ * ## 为什么是**独立插件行**，而不是写在 etscli-tools 里
+ *
+ * §7.118 那次 MEOS 写入事故发生在**headless HTTP profile**里，而那个 profile
+ * （以及 desktop-safe preset）**本来就没挂** `etscli-tools` ⇒ 守卫写在它里面
+ * 就等于**哪个部署都没上膛**（「代码写了、测试过了、闸门没装」是本仓最怕的
+ * 那种状态）。独立成行后可以**按需挂载**：
+ *
+ * - `profiles/dsh-edge-agent/cordis.patch.yml`（headless HTTP profile ——
+ *   事故发生的那个）；
+ * - `presets/edge.desktop-safe.patch.yml`（桌面 preset）；
+ * - `presets/edge.patch.yml`（完整 edge preset）。
+ *
+ * 独立行只**加一道闸**，**不**把那 14 个只读 etscli 工具带进那些 profile ——
+ * 带进去是能力扩张，超出「封堵逃逸口」这件事本身。
+ *
+ * @module dsh-edge-agent/etscli-shell-guard
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import Schema from '@deepseek-ai/schemastery';
+/** 插件名（cordis patch 行的 id 与本名一致）。 */
+export declare const name = "etscli-shell-guard";
+/**
+ * 没有服务依赖（§7.169）：只用 `ctx.on`（cordis 的框架动词）。
+ *
+ * **刻意不声明 `auditLog`**：声明成硬依赖后，本行要等 auditLog 服务就绪
+ * 才 apply —— 那条服务一旦缺席，**闸门整个不装上**（逃逸口静默敞开）。
+ * 闸门必须先于任何证据通道就位。审计服务改为**延迟注入**捕获
+ * （见 apply() 内注释）：审计是证据通道，不是闸门的依赖。
+ */
+export declare const inject: readonly [];
+/** 能执行任意命令的工具名（小写比较）。 */
+export declare const SHELL_TOOL_NAMES: readonly string[];
+/**
+ * 只读子命令白名单：每项是一段 argv 前缀（`['fs','ls']` 匹配
+ * `fs ls --path /tmp`）。
+ *
+ * **由调用方传入**（单一事实源 = `etscli-tools.ts` 从注册表派生的那份），
+ * 本模块**不 import** 它 —— 否则 `etscli-tools → etscli-shell-guard →
+ * etscli-tools` 会成环：模块求值顺序一变就是 TDZ 崩，而崩点还是「运行期
+> 才炸」的那种。
+ */
+export type EtscliReadonlyAllowlist = readonly (readonly string[])[];
+/** 守卫的选项（白名单必填 —— 少传就是「白名单为空 ⇒ 全拒」的 fail-closed）。 */
+export interface EtscliGuardOptions {
+    /** 只读子命令白名单（argv 前缀）。 */
+    allowlist: EtscliReadonlyAllowlist;
+    /** etscli 二进制路径（用于识别绝对路径调用）。 */
+    bin?: string;
+    /** 拒绝时的回调（证据要落盘）。 */
+    onDeny?: (denial: EtscliGuardDenial) => void;
+}
+/** 守卫的判定结果。 */
+export interface EtscliShellVerdict {
+    /** 是否拒绝这次执行。 */
+    denied: boolean;
+    /** 被拦下的子命令（`file upload` 这种），用于审计与给模型的提示。 */
+    subcommand?: string;
+    /** 拒绝理由（返回给宿主，会变成工具结果里的 `Error: <reason>`）。 */
+    reason?: string;
+}
+/**
+ * 极简 shell 分词。
+ *
+ * 够用就好：这里的目的是**找出命令文本里有没有 etscli 调用**，不是做一个
+ * 完整的 shell 解析器。处理引号、转义、以及 `;` `|` `&` `>` `<` 这些分隔符，
+ * 好让 `etscli` 后面只取到属于它自己的那几个 token。
+ */
+export declare function tokenizeShell(command: string): string[];
+/**
+ * 这串 argv 是不是白名单里的只读子命令？
+ *
+ * 判据用**前缀匹配**：白名单项 `['fs','ls']` 匹配 `fs ls --path /tmp`。
+ * 精确到 token，不会把 `fs lsx` 误判成 `fs ls`。
+ */
+export declare function isReadOnlyEtscliArgv(argv: readonly string[], allowlist: EtscliReadonlyAllowlist): boolean;
+/**
+ * 判定一条 shell 命令里有没有「不该出现的 etscli 调用」。
+ *
+ * 规则：**只放行白名单里那 14 个只读子命令**，其余一律拒绝。
+ *
+ * 为什么用白名单而不是黑名单（把 `file upload` / `fs rm` 这些逐个列出来禁）：
+ * 黑名单只能挡住**已经想到的**写子命令 —— etscli 加一个新写命令，黑名单就漏一个。
+ * 白名单的漏法是**多挡**（新加的只读命令也会被挡），而白名单那份清单就在
+ * `etscli-tools.ts` 里（注册什么就放行什么），两者天然同步。
+ *
+ * @param command - shell 命令文本
+ * @param options.allowlist - 只读子命令白名单（argv 前缀）
+ * @param options.bin - 配置里的 etscli 二进制路径（用于识别绝对路径调用）
+ */
+export declare function evaluateEtscliShellCommand(command: string, options: {
+    allowlist: EtscliReadonlyAllowlist;
+    bin?: string;
+}): EtscliShellVerdict;
+/**
+ * 宿主执行信封（`dsh-tools` 的 exec 形状）的结构化描述。
+ *
+ * 参数字段名在宿主版本间会变（`arguments` / `args` / `input`），所以三个都读。
+ */
+export interface ToolExecLike {
+    name?: unknown;
+    arguments?: unknown;
+    args?: unknown;
+    input?: unknown;
+}
+/**
+ * 判定一次工具执行里有没有「不该出现的 etscli 调用」。
+ *
+ * 只看 **shell 类工具**（`bash` / `pwsh`）—— 技能走的是 `skill` 工具（参数
+ * `skillName`），不受影响；`etscli_*` 白名单工具走绝对路径直接调二进制，
+ * 也不经过 shell 工具。
+ *
+ * 参数值**不按参数名取**：把 exec 的参数对象里所有字符串值都过一遍。这样
+ * 不用依赖宿主 bash 工具的参数名（`command` / `cmd` / …），也不会因为参数名
+ * 变了就漏检。
+ */
+export declare function evaluateEtscliToolCall(exec: unknown, options: {
+    allowlist: EtscliReadonlyAllowlist;
+    bin?: string;
+}): EtscliShellVerdict;
+/** 守卫被拒绝时的回调载荷。 */
+export interface EtscliGuardDenial {
+    /** 触发拒绝的工具名。 */
+    tool: string;
+    /** 被拦下的子命令。 */
+    subcommand: string;
+    /** 拒绝理由。 */
+    reason: string;
+}
+/**
+ * 把守卫注册到宿主的 `tools/pre-execute` waterfall。
+ *
+ * 契约（`@deepseek-ai/dsh-tools` `lib/index.js:3319-3343`）：
+ *
+ * - 监听器返回 `{kind:'deny', reason}` ⇒ 这次执行**不派发**，`reason` 成为
+ *   拒绝理由（工具结果里的 `Error: <reason>`），后续监听器/守卫放不回来；
+ * - 放行时必须 `return next()` —— 直接 `allow` 会把后面的链条截断。
+ *
+ * 本监听器从**本插件自己的 ctx** 注册，而本插件挂在边缘 preset 的 scope 里
+ * ⇒ 宿主按 scope 链派发（`scopeTarget(this, exec.agent)`）⇒ 标准模式会话
+ * 收不到本事件 ⇒ 守卫不会伸到标准模式（§7.140 的零事件不变式不受影响）。
+ *
+ * @returns 宿主返回的**精确 disposer**（用于有序拆卸 / HMR 清理）
+ */
+export declare function registerEtscliShellGuard(ctx: Context, options: EtscliGuardOptions): () => void;
+export interface Config {
+    /**
+     * etscli 二进制绝对路径 —— 只用来**识别**绝对路径调用
+     * （`/Users/me/.local/bin/etscli file upload …`）。
+     *
+     * 缺省顺序：本项 → `config/edge.json` 的 `etscli.bin` → `~/.local/bin/etscli`
+     * （§7.102「one config file」：运行期配置只有一个读点）。
+     */
+    etscliBin?: string;
+}
+export declare const Config: Schema<Config>;
+/**
+ * 装上这道闸。
+ *
+ * 装的顺序与两件记录：
+ *
+ * 1. **启动行**（`armed`）：只记拒绝行的话，"守卫没装上" 和 "守卫装上了但这次
+ *    没人触发" 在日志里长得一模一样 ⇒ 启动时把**白名单规模**与**机制落点**
+ *    写出来。不记放行行（每次 bash 调用都记会淹掉真正的拒绝行；realm 闸门那层
+ *    已经在逐次记 tool allow/deny）。
+ * 2. **拒绝行**：ops log `warn` + 审计行 `etscli.shell.denied`
+ *    （`level: security`；载荷**不含命令原文** —— 里面可能有本地路径与文件名）。
+ */
+export declare function apply(ctx: Context, config: Config): Promise<() => void>;
+//# sourceMappingURL=etscli-shell-guard.d.ts.map

package/lib/dsh-adapter/etscli-shell-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"etscli-shell-guard.d.ts","sourceRoot":"","sources":["../../src/dsh-adapter/etscli-shell-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2FG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAClD,OAAO,MAAM,MAAM,0BAA0B,CAAA;AAK7C,qCAAqC;AACrC,eAAO,MAAM,IAAI,uBAAuB,CAAA;AAExC;;;;;;;GAOG;AACH,eAAO,MAAM,MAAM,aAAc,CAAA;AAEjC,yBAAyB;AACzB,eAAO,MAAM,gBAAgB,EAAE,SAAS,MAAM,EAAqB,CAAA;AAEnE;;;;;;;;GAQG;AACH,MAAM,MAAM,uBAAuB,GAAG,SAAS,CAAC,SAAS,MAAM,EAAE,CAAC,EAAE,CAAA;AAEpE,qDAAqD;AACrD,MAAM,WAAW,kBAAkB;IACjC,yBAAyB;IACzB,SAAS,EAAE,uBAAuB,CAAA;IAClC,gCAAgC;IAChC,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,qBAAqB;IACrB,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,iBAAiB,KAAK,IAAI,CAAA;CAC7C;AAKD,eAAe;AACf,MAAM,WAAW,kBAAkB;IACjC,gBAAgB;IAChB,MAAM,EAAE,OAAO,CAAA;IACf,6CAA6C;IAC7C,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,+CAA+C;IAC/C,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAKD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAuDvD;AAQD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,SAAS,EAAE,uBAAuB,GACjC,OAAO,CAIT;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE;IAAE,SAAS,EAAE,uBAAuB,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GAC5D,kBAAkB,CAiDpB;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,KAAK,CAAC,EAAE,OAAO,CAAA;CAChB;AAoBD;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,OAAO,EACb,OAAO,EAAE;IAAE,SAAS,EAAE,uBAAuB,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GAC5D,kBAAkB,CAiBpB;AAED,mBAAmB;AACnB,MAAM,WAAW,iBAAiB;IAChC,gBAAgB;IAChB,IAAI,EAAE,MAAM,CAAA;IACZ,eAAe;IACf,UAAU,EAAE,MAAM,CAAA;IAClB,YAAY;IACZ,MAAM,EAAE,MAAM,CAAA;CACf;AAcD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,wBAAwB,CACtC,GAAG,EAAE,OAAO,EACZ,OAAO,EAAE,kBAAkB,GAC1B,MAAM,IAAI,CA2BZ;AAID,MAAM,WAAW,MAAM;IACrB;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,eAAO,MAAM,MAAM,EAAE,MAAM,CAAC,MAAM,CAEhC,CAAA;AAEF;;;;;;;;;;;GAWG;AACH,wBAAsB,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,CAAC,CAoE7E"}