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

package/lib/dsh-adapter/input-guard.d.ts

@@ -0,0 +1,508 @@
+/**
+ * input-guard — 端侧隐私安全管线的编排器。
+ *
+ * 把安全/隐私/脱敏逻辑从 transport 层（http-api）上移到 Agent Loop 的
+ * 事件链上，让所有入口（http-api / Web UI / CLI / SDK / 未来的 WebSocket
+ * 或 gRPC）自动统一走同一套管线。谁也无法绕过。
+ *
+ * 正向（agent/pre-step）：fail-closed 路由闸门 → 攻击检测 → 策略判定 →
+ *   意图分类 → 脱敏
+ * 反向（llm/stream）：对 text-delta chunk 流式反脱敏
+ *
+ * §7.175 (2026-11-11): 路由改写退役。input-guard 不在 agent/request 里改写
+ * provider/model（宿主的 prepareRequest() 会对改写直接抛错）。
+ *
+ * §7.184 (2026-11-11，主人裁决「选择器完全不动，实际请求改道到本地池」）：
+ *   - **会话选型不再被改写**（§7.176 的钉选 / §7.179 的补钉 / §7.183 的回钉全部
+ *     退役）⇒ 宿主模型选择器保持主人选的那个，不跳。
+ *   - 「本轮必须留在设备上」这条不变式改由**出网那一跳**保证：LOCAL 轮次的请求
+ *     在 `llm/stream` 被换成 provider = 本地池（见 handleLlmStream）。
+ *   - 旧口径（§7.175：判定 LOCAL 而选型不是本地 ⇒ 拒绝这一轮）随之退役 ——
+ *     能改道就不必拒；改不动时仍然 fail-closed（抛错，绝不放行到云端）。
+ *
+ * 设计详见：docs/input-guard-design.md
+ *
+ * §7.123 (2026-10-27): the pure message-array helpers (find / replace user
+ * turns) moved to `./input-guard-messages.ts` — they encode the
+ * payload.messages vs decision.messages contract, which is the part of this
+ * module that upstream keeps changing. This file keeps the hook LOGIC.
+ *
+ * @module dsh-edge-agent/input-guard
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { Service } from '@deepseek-ai/cordis';
+import Schema from '@deepseek-ai/schemastery';
+import { type LocalPoolShape } from './effective-model.js';
+export declare const name = "input-guard";
+export declare const inject: readonly ["promptGuard", "privacyPolicy", "intentRouter", "sanitizer", "auditLog", "realmSkillBridge"];
+export interface Config {
+    /** 总开关。false 时所有 hook 都直接 pass-through（debug / 紧急回退用）。*/
+    enableInputGuard: boolean;
+    /** LOCAL 路径是否也走脱敏（默认 false：LOCAL LLM 看到原文，不上云无需脱敏）。*/
+    sanitizeLocalTraffic: boolean;
+    /** 攻击检测 / privacy-policy REJECT → 阻断 step（user 行为不端）。
+     *  false = 仅审计 + 放行（fail-open on policy；不推荐）。*/
+    rejectOnPolicyViolation: boolean;
+    /** Sanitize 失败 → 是否阻断本轮（系统故障而非 user 错）。
+     *
+     *  §7.175 (2026-11-11): 曾经这个开关表示「降级到 LOCAL 路由」——
+     *  input-guard 在 agent/request 里改写 provider/model。**改写已经退役**
+     *  （宿主的 prepareRequest() 会因为改写直接抛错），路由恒由宿主的
+     *  modelSelection 决定。现在它只表示「脱敏失败要不要拦下这一轮」：
+     *  false = REJECT step（user 看到空 result）；true = 放行。
+     *  默认 true — 边缘模式恒走本地模型，原始 PII 不出境。*/
+    downgradeOnSanitizeFailure: boolean;
+    /** 本地 provider 名。必须与本地 LLM adapter 注册名一致，也是 §7.175
+     *  fail-closed 闸门认定的「本地」：宿主 modelSelection.provider 必须等于
+     *  它，否则本轮被拒（绝不放行到可能上云的 provider）。*/
+    localProvider: string;
+    localModel: string;
+    /** 2026-09-03 §7.35: Cloud adapter 读 key 的 env slot 名。
+     *  与 cloud-llm-adapter.Config.apiKeyEnv 默认一致（'DEEPSEEK_API_KEY'），
+     *  也尊重 cordis.patch.yml:41 的 DSH_EDGE_CLOUD_KEY_ENV 覆盖。
+     *
+     *  §7.175 (2026-11-11): **input-guard 不再消费本项**。边缘模式恒用本地
+     *  模型（主人裁决），云池不参与任何路由判定；「云端不可用 → 降级 LOCAL」
+     *  那条路径随路由改写一起退役。本项保留在 schema 里只是为了不破坏既有
+     *  配置文件（cloud-llm-adapter 仍按自己的同名项读它）。*/
+    cloudApiKeyEnv: string;
+    /** 2026-09-07 §7.43 fix: TUI / dsh-web-app chat 入口不会写 agent._edgeRoute
+     *  （只有 http-api 写），所以 handlePreStep 拿不到"如果没降级本来会路由到
+     *  哪个 provider"。曾用作「降级前原路由」的 fallback。
+     *
+     *  §7.175 (2026-11-11): 降级机制退役后本项**不再被 input-guard 读取**
+     *  （路由恒由宿主的 modelSelection 决定）。保留在 schema 里只是为了不
+     *  破坏既有配置文件。*/
+    defaultCloudProvider: string;
+    defaultCloudModel: string;
+    /** §7.179 (2026-11-11): 本插件所在 preset 的 id。
+     *
+     *  用途：`agent-preset/selected` 事件是**全局**事件（宿主 registry 直接
+     *  `ctx.emit('agent-preset/selected', session.id, presetId)`，不带 scope 载体）
+     *  ⇒ 所有工作方式的监听器都收到 ⇒ 必须自己按 presetId 过滤，否则会给
+     *  标准模式的会话也钉上 local-llm（那会改掉宿主的选择，违反 §7.140
+     *  「标准模式零 edge 事件」）。
+     *
+     *  这个值必须与 preset yml 里的 `config.id` 一致 —— scripts/verify-preset-isolate.ts
+     *  复核这一点（不一致即门禁失败），所以它不是「两份各写各的」，而是**被门禁
+     *  锁住的一致量**。*/
+    presetId: string;
+}
+export declare const Config: Schema<Config>;
+/** Minimal prompt-guard 接口（只暴露 input-guard 用到的方法）。*/
+interface PromptGuardLike {
+    checkInput(text: string, sessionId: string): Promise<{
+        safe: boolean;
+        reason?: string;
+        riskLevel?: 'low' | 'medium' | 'high';
+    }>;
+    checkOutput?(text: string, context?: {
+        sanitized?: boolean;
+    }): Promise<{
+        filtered: string;
+        redacted: Array<{
+            type: string;
+            masked: string;
+        }>;
+    }>;
+}
+/** Minimal privacy-policy 接口。*/
+interface PrivacyPolicyLike {
+    matchRouting(text: string): {
+        realm?: string;
+        confidence?: number;
+        rationale?: string;
+    } | null | undefined;
+}
+/** Minimal intent-router 接口。*/
+interface IntentRouterLike {
+    classify(text: string, context?: {
+        recentMessages?: unknown[];
+        sessionId?: string;
+    }): Promise<{
+        category: 'LOCAL' | 'CLOUD' | 'SANITIZED' | 'REJECT';
+        confidence: number;
+        rationale?: string;
+    }>;
+}
+/** Minimal sanitizer 接口。
+ *  §7.123 (2026-10-27): the replacement shape was STALE here — it declared
+ *  `{ type, original, token }` while sanitizer-pipeline's real `Replacement`
+ *  is `{ original, placeholder, piiType, dataClass, keptPrefix? }`. The
+ *  mismatch was invisible while input-guard only read `.length`; now that
+ *  the audit records which PII types were hit, the interface must match
+ *  the real contract. */
+interface SanitizerLike {
+    sanitize(text: string, context?: {
+        sessionId?: string;
+    }): Promise<{
+        sanitizedText: string;
+        sessionId: string;
+        replacements: Array<{
+            original: string;
+            placeholder: string;
+            piiType: string;
+            dataClass: string;
+            keptPrefix?: string;
+        }>;
+    }>;
+    desanitize(text: string, sessionId: string): Promise<string>;
+}
+/** Minimal audit-log 接口。*/
+interface AuditLogLike {
+    log(entry: {
+        level: 'debug' | 'info' | 'warn' | 'error' | 'security';
+        kind: string;
+        source: string;
+        payload: Record<string, unknown>;
+    }): Promise<unknown>;
+}
+/** StreamChunk 形状（来自 @deepseek-ai/dsh-llm，避免深层依赖）。*/
+interface StreamChunkLike {
+    type: string;
+    text?: string;
+    [k: string]: unknown;
+}
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        inputGuard: InputGuardServiceImpl;
+    }
+}
+/** Per-session 的"这一步做了脱敏"状态。按 sessionId 存在普通 Map 里
+ *  （pre-step 的 session 引用与 llm/stream 的 sessionId 字符串不是同一
+ *  对象，WeakMap 回收不了），靠 SESSION_STATE_CAP 的 LRU 淘汰兜住。*/
+export interface StepSanitizationState {
+    /** 当前 turn/step 是否做了脱敏。每次 agent/pre-step 入口重置。*/
+    sanitized: boolean;
+    /** 替换次数（0 = 没替换，无需 desanitize）。*/
+    replacements: number;
+    /** 触发脱敏时的 session id（冗余但便于审计）。*/
+    sessionId: string;
+    /** 时间戳，便于陈旧检查。*/
+    timestamp: number;
+    /** 入口路径（'http-api' = _edgeRoute 已设；'webui' = 未设）。
+     *  §7.175 起它只描述「这一轮的路由决策从哪来」，不再用于改写路由。*/
+    routeSource?: 'http-api' | 'webui';
+}
+/** 上一路由决策：被 input-guard 在 agent/pre-step 读取，避免重复 classify()。*/
+interface AgentEdgeRoute {
+    realm: 'LOCAL' | 'CLOUD' | 'SANITIZED';
+    category: 'LOCAL' | 'CLOUD' | 'SANITIZED' | 'REJECT';
+    provider: string;
+    model: string;
+    confidence: number;
+    rationale?: string;
+}
+/** agent/request waterfall 返回的 config 形状（DSH agent-loop 的 contract）。*/
+interface AgentRequestConfig {
+    provider: string;
+    model: string;
+    reasoningEffort?: number;
+    maxTokens?: number;
+}
+/**
+ * input-guard 服务。
+ *
+ * 三个全局 hook：
+ *   - `agent/pre-step`（正向）：**fail-closed 路由闸门** → 攻击 → 策略 →
+ *     分类 → 脱敏
+ *   - `agent/request`（只读放行）：§7.175 起**不再改写** provider/model
+ *   - `llm/stream`（反向）：§7.184 起把 LOCAL 轮次的请求**改道**到本地池；
+ *     并对 text-delta chunk 流式反脱敏
+ *
+ * 跨 hook 状态用 Map<sessionId, StepSanitizationState> 维护。
+ */
+export declare class InputGuardServiceImpl extends Service {
+    private readonly config;
+    private readonly promptGuard;
+    private readonly privacyPolicy;
+    private readonly intentRouter;
+    private readonly sanitizer;
+    private readonly auditLog;
+    /** sessionId → 当前 step 的脱敏状态。用 Map<string, state> 而不是 WeakMap<session>
+     *  是因为 pre-step 的 session 引用和 llm/stream options 上的 sessionId
+     *  对应的不是同一个对象（pre-step 拿到的是 agent 实例的 session，
+     *  llm/stream 拿到的是 LLM request envelope 上的 sessionId 字符串）。*/
+    private readonly stepState;
+    /**
+     * §7.106 (2026-10-23): last routed category per session. The attack-block
+     * gate consults it: a LOCAL turn cannot egress anything, so credential-flavored
+     * "leak" detections are the user operating their own device (密盒登录类),
+     * which the operator ruled must pass — warn instead of block. Injection-class
+     * reasons stay blocked even under LOCAL (injection can drive local tools).
+     * The egress risk of the same credentials later riding session history into a
+     * CLOUD turn is closed by the sanitizer's new `credential` PII class, not by
+     * this exemption.
+     */
+    private readonly turnCategory;
+    /**
+     * §7.144: LLM trace 的行为配置（`audit.llmTrace` 段）。
+     *
+     * 构造时读一次 —— 这是**观测**配置，不是路由配置，读一次足够；每次
+     * 读盘会在每个 LLM 往返上多一次 IO。
+     */
+    private readonly traceConfig;
+    /**
+     * §7.151: 出网守卫（宿主原生 provider 路径的 §7.131 裁剪）。
+     *
+     * 必须在**请求派发之前**裁 —— 而宿主把 LOOP 构建的请求 deep-frozen
+     * 送来（监听器只读不改），所以裁完要**换掉请求体重新派发**。守卫自己
+     * 持有「已裁过」的标记集合，避免重新派发时无限递归。
+     */
+    private readonly hostEgressGuard;
+    /**
+     * §7.175 (2026-11-11): 「云池现在到底可用吗」的探针（§7.35 / §7.100）随
+     * 路由改写一起退役 —— 边缘模式恒用本地模型（主人裁决），云池不参与任何
+     * 路由判定。留着它只会把「云端不可用」报成「路由缺失」。*/
+    /**
+     * §7.171 (2026-11-10): "本地路由现在到底可用吗" —— local-llm 有两种上线方式：
+     * 配置了 `llm.local.baseUrl` → 直连自有池；没配置 → DELEGATE 模式（转发宿主
+     * 提供商，见 local-llm-adapter.apply）。**两种情况下路由都是注册了的** ⇒
+     * `modelRouter.isAvailable('local-llm')` 即可判据，与直连时完全一致。
+     *
+     * 只有 `llm.local.delegate=false`（kill switch）才会让路由不存在 —— 那时
+     * intent=LOCAL 按隐私裁决必须走本地模型，在改写 provider 之前必须确认目标
+     * 路由真的存在，否则会把「本地」意图发给一条不存在的路由。
+     *
+     * 旧上游 / fake ctx 没有 listProviders 时无法证伪 → 保持旧行为（照常改写），
+     * 不让老环境因这次收紧而回归。
+     */
+    private localAvailable;
+    /**
+     * §7.180: 本地池现状 —— 直连（配了 `llm.local.baseUrl`）还是 DELEGATE
+     * （没配端点，转发宿主提供商，§7.171），连同 model / delegate 旋钮。
+     *
+     * 补钉用的 model id 由这份现状**推导**（而不是另读一份宿主选择）⇒ 与
+     * wire、模型目录同源（见 §7.180）。
+     *
+     * protected 而不是 private：单测子类化覆写它，不必依赖机器上那份
+     * `~/.dsh-edge-agent/edge.json` 的真实内容。
+     */
+    protected localPoolShape(): LocalPoolShape;
+    /**
+     * §7.184 (2026-11-11): 本轮判定 LOCAL 时，把实际请求**改道**到本地池。
+     *
+     * 背景（主人裁决 2026-11-11）：「选择器完全不动，实际请求改道到本地池」。
+     *
+     *   - 边缘模式的会话**不再改写选型**（§7.176 的钉选 / §7.179 的补钉 /
+     *     §7.183 的回钉全部退役）⇒ 宿主模型选择器保持主人选的那个，不跳。
+     *   - 但「本轮必须留在设备上」这条不变式**不能松** ⇒ 真正跑哪儿由**出网
+     *     那一跳**决定：LOCAL 轮次的请求在 `llm/stream` 被换成 provider = 本地池。
+     *
+     * 为什么能在这一跳改：`llm/stream` 的 waterfall **默认处理**才是解析适配器的
+     * 地方（dsh-llm `adapterStream()`：`registration = this.registration(options.provider)`）
+     * ⇒ 换掉 `options.provider` 就换掉了真正发出去的适配器。
+     * 而且 cordis 的 waterfall **不接受替换载荷**（`next()` 无参，载荷被闭包捕获）
+     * ⇒ 只能换一个请求对象**重新派发**（与 §7.151 的出网裁剪同一个姿势）。
+     *
+     * 重新派发会再进一次 waterfall ⇒ 那趟的 provider 已是本地池 ⇒ 天然不再改道
+     * （**防自锁**），且本地池按 §7.131 带**全部**历史（本地池不出网，不裁）。
+     *
+     * fail-closed：改不动（本地路由不存在 / 解析不到 model id / 宿主 LLM runtime
+     * 不可用）⇒ **抛错**，绝不放行到可能上云的 provider。
+     */
+    /** §7.184: 这一通请求要不要改道到本地池？ */
+    private needsLocalReroute;
+    /**
+     * §7.184: 换掉请求对象**重新派发**到本地池（与 §7.151 的出网裁剪同一姿势）。
+     *
+     * 为什么不能就地改写：宿主契约明写 LOOP 构建的请求是 **deep-frozen**
+     * （`markAgentLoopRequest` + `deepFreeze`），"listeners read it, never rewrite it"。
+     */
+    private dispatchRerouted;
+    constructor(ctx: Context, config: Config, promptGuard?: PromptGuardLike, privacyPolicy?: PrivacyPolicyLike, intentRouter?: IntentRouterLike, sanitizer?: SanitizerLike, auditLog?: AuditLogLike);
+    private audit;
+    /** 当前 session 是否有活跃的脱敏状态（desanitize 用）。*/
+    getStepState(sessionId: string): StepSanitizationState | undefined;
+    /** Exposed for tests: the step-state map the turn/end restore listener reads. */
+    setStepState(sessionId: string, state: StepSanitizationState): void;
+    /** Seed/override the session's last routed category. Tests drive the
+     *  LOCAL-credential exemption with it; http-api could pre-seed a known
+     *  route the same way. */
+    setTurnCategory(sessionId: string, category: string): void;
+    /** 会话状态 Map 的 LRU 上限。活跃会话远小于此（http-api 默认
+     *  maxActiveSessions=8），被淘汰的是早已结束的 session —— 这两个
+     *  Map 曾经只增不减，长驻进程里随历史会话数无限增长。 */
+    private static readonly SESSION_STATE_CAP;
+    /** LRU 写入：delete-then-set 让最近路由的 session 排到队尾，超限
+     *  淘汰队头（最久未访问的 session）。 */
+    private putStepState;
+    private putTurnCategory;
+    private evictOldestSessionState;
+    /**
+     * 清洗 messages 数组中的孤儿 tool_call。
+     *
+     * 背景（2026-08-31）：当 session 历史里残留一条 assistant 消息含
+     * `tool_calls`，但后续没有匹配的 `role: tool` + `tool_call_id` 时，
+     * OpenAI / DeepSeek API 会返回 400 invalid_request_error
+     * "An assistant message with 'tool_calls' must be followed by tool
+     *  messages responding to each 'tool_call_id'."
+     *
+     * 根因：webui 复用先前 http-api 创建的会话做 session.prompt，但
+     * agent-loop 把整个 history 投影到 OpenAI 兼容 schema 时保留了
+     * 没有 tool 响应的 tool_call。
+     *
+     * 修复策略：对每个 orphan tool_call，在 assistant 之后紧邻位置插入一条
+     * 合成的 `{role:'user', content:[{type:'tool-result', toolCallId, content:'{\"error\":\"aborted\"}...'}]}`。
+     * 这样：
+     *   - assistant 消息被原样保留（tool-call 块不动）——必须保证 wire 端
+     *     assistant.tool_calls 包含所有 ids，synthetic 才能与之匹配
+     *   - wire 转换后 API 看到完整的 tool_calls ↔ tool 配对，校验通过
+     *   - LLM 收到"之前那次工具调用被中止了"的信号，自然续写
+     *
+     * 关键：不要剥离 orphan tool-call 块（初版犯的错）。如果剥离，Case B
+     * （assistant 同时含 responded + orphan ids）会让合成的 tool-result
+     * 找不到匹配的 tool_call_id，wire 端再次 400。
+     *
+     * 副作用：上游 provider 可能继续推演被中止的工具调用（如果 LLM 智能
+     * 不足）。优先级：先让请求能跑通，再考虑 LLM 行为。这是 input-guard
+     * 的职责边界：保证 schema 合规，不保证 LLM 行为合理。
+     *
+     * §7.58 (2026-09-16) Pass 0——重复 tool_call id 唯一化：同一次 sanitize 内
+     * 第 2..n 次出现的同 id tool-call 块（及其第 2..n 个配对 tool-result 块，
+     * 含 message.source.callId）改名为 `${id}-dup${k}`，避免 DeepSeek 400
+     * "Duplicate value for 'tool_call_id' … in message[N]"。来源：(a) 旧版
+     * openai-sse.ts delta / block-end 索引错位使一次调用在一条 assistant 消息
+     * 里落成两个同 id 块（已源头修复），修复前落盘的 session 历史仍在——
+     * 2026-09-15 session 24303d6a turn 2 实锤；(b) 未来其他模型 / adapter 的
+     * 同类重复输出。Pass 0 先于 orphan 扫描，保证后续 pass 看到全局唯一 id。
+     *
+     * 调用方：cloud-llm-adapter / local-llm-adapter 在 buildChatCompletionsBody
+     * 前调用。如 input-guard 未启用（enableInputGuard=false）则跳过。
+     */
+    sanitizeOrphanToolCalls(messages: ReadonlyArray<Record<string, unknown>>, sessionId?: string): {
+        messages: Array<Record<string, unknown>>;
+        orphanCount: number;
+        syntheticInjected: number;
+        /** §7.58 (2026-09-16): 本消息集内被改名的重复 tool-call 块数。 */
+        duplicateCount: number;
+    };
+    /**
+     * 把拒收原因挂到 agent 对象上，供 http-api 在订阅 `session/event` 的
+     * turn/end 监听器里读取（因为 agent-loop 把 `{ kind: 'reject' }` 翻译成
+     * `turnEnds = { kind: 'blocked' }` 时会丢掉 reason 字符串）。
+     *
+     * 只在 reject 路径写入；正常 turn 不污染 agent 状态。
+     */
+    private attachRejection;
+    /**
+     * 读取 agent 上的 edge-route（由 http-api / 其他入口在 followup 前写入）。
+     *  避免 input-guard 重复跑 intent-router.classify()（每次 ~0.5-1s）。*/
+    private readEdgeRoute;
+    /**
+     * §7.175 (2026-11-11): 读宿主给本轮选的模型（agent/pre-step payload **顶层**
+     *  的 `modelSelection`）。
+     *
+     *  宿主契约（dsh-agent-loop 0.2.2-rc.1，实测 app.asar）：
+     *  `preStep` 里 `const selection = this.model.current()`，再以
+     *  `waterfall('agent/pre-step', { messages, ...position, signal, modelSelection: selection })`
+     *  派发 —— `modelSelection` 在 payload 顶层，形状 `{ provider, model, reasoningEffort? }`。
+     *
+     *  返回 undefined = **拿不到**（缺失 / 不是对象 / provider 不是非空字符串）
+     *  ⇒ 无法证明本轮走本地 ⇒ 调用方必须 fail-closed。
+     */
+    private readModelSelection;
+    /** 正向 hook：agent/pre-step handler。暴露给测试。*/
+    handlePreStep(payload: {
+        agent: {
+            session: object & {
+                id?: string;
+            };
+            id?: string;
+            _edgeRoute?: AgentEdgeRoute;
+        } & Record<string, unknown>;
+        messages: ReadonlyArray<Record<string, unknown>>;
+        step: number;
+        signal?: AbortSignal;
+        /** §7.175: 宿主给本轮选的模型 —— payload **顶层**的
+         *  `{ provider, model, reasoningEffort? }`（dsh-agent-loop 0.2.2-rc.1）。
+         *  缺失 ⇒ 无法证明本轮走本地 ⇒ fail-closed 拒收。*/
+        modelSelection?: unknown;
+    }, next: () => Promise<{
+        kind: string;
+        messages?: ReadonlyArray<Record<string, unknown>>;
+        reason?: string;
+    }>): Promise<{
+        kind: string;
+        messages?: ReadonlyArray<Record<string, unknown>>;
+        reason?: string;
+    }>;
+    /** `agent/request` handler —— §7.175 起**只放行，不改路由**。
+     *
+     *  为什么不再改写：宿主 dsh-agent-loop 的 prepareRequest() 会拿
+     *  `proposedConfig` 与 `this.model.current()`（宿主给本轮选的模型）比对，
+     *  provider / model / reasoningEffort 任一不同就**直接抛错**。所以在
+     *  agent/request 里改写 provider/model 不是「降级到本地」，而是让整轮
+     *  直接失败。
+     *
+     *  现在：路由恒由宿主的 modelSelection 决定，边缘模式恒为本地模型
+     *  （主人裁决 2026-11-10）；「本该本地却可能上云」的判定与 fail-closed
+     *  拦截都在 handlePreStep 里做（见那里的 modelSelection 闸门）。
+     *
+     *  这里保留这个 handler 只为把「不改路由」这条契约钉死：seedConfig 原样
+     *  返回，一个字节都不改。
+     *
+     *  注意 DSH waterfall 契约：监听器真实签名是 `(payload, next)`，
+     *  其中 `payload` 已被 dsh-agent 的 fused wrapper 注入 `agent` 字段
+     *  （见 @deepseek-ai/dsh-agent/lib/types/dispatch.js#agentEvents）。
+     *  上一层 apply() 必须先 `await next()` 取出 seedConfig 后再传进来，
+     *  因为 next() 是 chain 的下一步，handler 不能跳过它直接返回。*/
+    handleAgentRequest(payload: {
+        turn?: number;
+        step?: number;
+        signal?: AbortSignal;
+        agent?: {
+            session?: {
+                id?: string;
+            };
+        };
+    }, seedConfig: AgentRequestConfig, next: () => Promise<AgentRequestConfig>): Promise<AgentRequestConfig>;
+    /**
+     * §7.144: 宿主 provider 的调用要不要记？返回一个记录器，或 undefined。
+     *
+     * **不记**的三种情形：
+     *
+     *   1. provider 属于本项目自管池（`local-llm` / `cloud-llm`）—— adapter
+     *      自己已经记过（REQ + RESP），这里再记一遍面板上就是同一通调用出现
+     *      两条。
+     *   2. `purpose` 非空 —— 宿主的内部用途（compaction / session-title），
+     *      不是主人关心的「这一轮调用」，记了只给面板添噪音。
+     *   3. provider 缺失 / trace 总开关关闭 / 任何异常 ⇒ 不记（观测路径永不
+     *      拖垮主链路）。
+     *
+     * 记的那一类是**宿主自己的 provider**（delegate 出去的云池，如
+     * `qwen-token-plan-cn`）—— 它不经过本项目任何 adapter，是面板里唯一
+     * 「完全看不见」的一跳。
+     */
+    private hostCallRecorder;
+    /**
+     * §7.151 (2026-10-29): 换掉请求体**重新派发**这一通出网调用。
+     *
+     * 为什么不能就地改写：宿主契约明写 LOOP 构建的请求是 **deep-frozen**
+     * （`markAgentLoopRequest` + `deepFreeze`），"listeners read it, never rewrite
+     * it"。所以唯一能换掉请求体的姿势就是换一个请求对象再派发一次 ——
+     * 与 `cloud-llm-adapter` 的 delegate 路径同一个姿势，宿主侧已验证可行。
+     *
+     * 重新派发会**再进一次 waterfall**：本方法给裁过的请求对象打标记
+     * （`HostEgressGuard.markTrimmed`），守卫下一次看到它直接放行 ⇒ 不递归、
+     * 不二次裁剪；那一趟里 trace 记录的是**真正发出去的那一份**。
+     *
+     * fail-closed：裁不动就不许出网 —— 放行等于把本地历史原样送上去。
+     */
+    private dispatchTrimmed;
+    /**
+     * 反向 hook：llm/stream handler。暴露给测试。
+     *
+     * `options` 的索引签名是**如实描述**宿主的载荷：`llm/stream` 派发的是
+     * 完整的 `GenerateOptions`（provider / model / messages / tools / …），
+     * §7.144 的宿主调用记录正是从这些字段里取「发出去的那一坨」。
+     */
+    handleLlmStream(options: {
+        signal?: AbortSignal;
+        sessionId?: string;
+        [key: string]: unknown;
+    }, next: () => AsyncIterable<StreamChunkLike>): AsyncIterable<StreamChunkLike>;
+}
+export declare function apply(ctx: Context, config: Config): Promise<() => Promise<void>>;
+export {};
+//# sourceMappingURL=input-guard.d.ts.map

package/lib/dsh-adapter/input-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"input-guard.d.ts","sourceRoot":"","sources":["../../src/dsh-adapter/input-guard.ts"],"names":[],"mappings":"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"}