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

package/lib/dsh-adapter/host-egress-guard.d.ts

@@ -0,0 +1,161 @@
+/**
+ * host-egress-guard — §7.151 出网那一跳的「只带云段历史」守卫
+ *
+ * ## 为什么需要这个模块（主人现场，2026-10-29）
+ *
+ * 主人在 Edge 面板看到：发往云端模型（`qwen-token-plan-cn/deepseek-v4.1-flash`）
+ * 的请求里带着**全部**本地历史 —— 三条 `provider: local-llm` 的 assistant
+ * 回复原样上云。那违反 §7.131 的裁决（2026-10-27）：
+ *
+ * > 发往 cloud-llm 的请求只能携带**之前上过 cloud-llm 的历史**；本地池带全部历史。
+ *
+ * ## 根因：这条出网**根本没经过**本项目的 cloud adapter
+ *
+ * §7.131 的裁剪一直住在 `cloud-llm-adapter` 里（直连路径 + delegate 路径各一份）。
+ * 但桌面部署的 CLOUD 轮次**压根不进那个 adapter**：
+ *
+ * ```
+ * intent.classify.end  category=CLOUD confidence=0.95 path=jev-adopt
+ * input-guard.routed   category=CLOUD edgeRouteUsed=False routeSource=webui
+ * llm.trace.index REQ  provider=qwen-token-plan-cn model=deepseek-v4.1-flash messageCount=31
+ * ```
+ *
+ * - `edgeRouteUsed=False` ⇒ webui 入口没有 `_edgeRoute`，edge 不改写路由；
+ * - 意图判成 CLOUD ⇒ `handleAgentRequest` **不**降级 ⇒ seed 的 provider 原样保留；
+ * - seed 的 provider 是宿主自己的 `qwen-token-plan-cn`（桌面 GUI 选的模型）⇒
+ *   agent-loop 直接派发给**宿主原生 provider**，不经过 `cloud-llm`。
+ *
+ * 于是 `cloud-llm-adapter` 里的 §7.131 裁剪**一次都没跑过**（审计链里
+ * `llm.cloud.delegate.resolved` / `llm.cloud.egress` 全是 0 条可证）。
+ *
+ * ## 修法：守卫落在**真正的出网那一跳**
+ *
+ * 宿主原生 provider 的那一跳只有一个必经之地：`llm/stream` waterfall
+ * （`ctx.llm.stream()` 的实现就是 `ctx.waterfall(this, 'llm/stream', options, …)`）。
+ * 守卫在那儿：
+ *
+ * 1. 判定这通调用是不是**出网**的（provider 不在本地池 / 自有池里）；
+ * 2. 用 `planCloudEgress`（与 adapter 同一份口径）算出「只带云段历史」的请求体；
+ * 3. 命中本地段 ⇒ **换掉请求体重新派发**（`ctx.llm.stream({...options, messages})`）。
+ *
+ * ### 为什么必须「重新派发」而不是就地改写
+ *
+ * 宿主契约（`@deepseek-ai/dsh-llm` 的 api-catalog 明写）：
+ *
+ * > A LOOP-built request carries the process-local `markAgentLoopRequest` identity
+ * > and arrives **deep-frozen (mutation throws)**: its content is a pure function
+ * > of the session log … so listeners **read it, never rewrite it**.
+ *
+ * 请求体是冻结的 ⇒ 只能换一个请求对象重新派发。这与 `cloud-llm-adapter` 的
+ * delegate 路径是同一个姿势（它也用 `{...options, messages: forwardMessages}`
+ * 重新派发），宿主侧已验证可行。
+ *
+ * 重新派发会**再进一次 waterfall**：本模块用 `markTrimmed` 打标记，
+ * 裁过的请求体进来直接放行 ⇒ 不会递归、不会二次裁剪。
+ *
+ * ## 裁剪口径与 adapter 完全同源
+ *
+ * 判据、段划分、丢弃规则全部复用 `cloud-egress.ts` 的 `planCloudEgress` ——
+ * 同一份事实源，杜绝「adapter 认为该带、守卫认为该丢」这种口径漂移。
+ *
+ * @module dsh-edge-agent/host-egress-guard
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { type EgressMessage } from './cloud-egress.js';
+import { LOCAL_POOL_FORWARD_MARKER } from './host-llm-trace.js';
+/** 一通 `llm/stream` 调用里守卫用得到的字段（结构化描述，不依赖宿主类型）。 */
+export interface HostEgressRequest {
+    provider?: unknown;
+    model?: unknown;
+    sessionId?: unknown;
+    purpose?: unknown;
+    messages?: unknown;
+    /** §7.171: 「本地池 delegate 转发」标记（见 `LOCAL_POOL_FORWARD_MARKER`）。 */
+    [LOCAL_POOL_FORWARD_MARKER]?: unknown;
+}
+/** 裁剪结果。 */
+export interface HostEgressPlan {
+    /** 允许出网的消息（按原顺序）。 */
+    messages: EgressMessage[];
+    /** 被拦下的消息条数（本地段 / 无法证明上过云的段）。 */
+    droppedCount: number;
+    /** assistant 消息的 provider 分布（观测用：让人一眼看出这段历史是谁产的）。 */
+    histogram: Record<string, number>;
+}
+/**
+ * 这通调用是不是**出网**的？
+ *
+ * - 自有池（`local-llm` / `cloud-llm`）⇒ **不归本守卫管**：
+ *   `local-llm` 按裁决带全部历史；`cloud-llm` 由 `cloud-llm-adapter` 自己裁
+ *   （直连与 delegate 两条路径都接了 §7.131，审计行也由它出）。
+ *   守卫再裁一遍会让 adapter 的 `historyDropped` 变成 0，**把证据洗掉**。
+ * - 本地池名单（model-router 的 LOCAL 名单）⇒ 本地池，带全部历史。
+ * - `local-` 前缀 ⇒ 同上（与 `providerSegment` 同源）。
+ * - 其余（宿主自选 provider，如 `qwen-token-plan-cn`）⇒ 出网，要裁。
+ */
+export declare function isCloudBoundProvider(provider: string, localProviders: readonly string[], own?: readonly string[]): boolean;
+/**
+ * 纯裁剪：只带云段历史。返回 `undefined` 表示**无需裁剪**（没有本地段）。
+ *
+ * `currentSegment: 'cloud'` —— 本轮正在出网，所以本轮归属云段。
+ */
+export declare function planHostEgress(messages: readonly EgressMessage[], localProviders: readonly string[]): HostEgressPlan | undefined;
+/**
+ * §7.171: 这通调用是不是「本地池 delegate 转发」？
+ *
+ * 本地池转发给宿主提供商时，`provider` 已经是宿主的目标路由（如
+ * `deepseek-official`）—— 与「用户直接选了那个模型」在 provider 维度上
+ * **无法区分**。唯一的区别在发起方：本地池的口径是「带全部历史」，宿主原生
+ * 路由的口径是「只带云段历史」。所以转发方必须在请求上打标记。
+ *
+ * 标记值刻意做成 truthy 判据（而不是 `=== true`）：宿主 spread options 时
+ * 原样透传，值是什么不重要，**有没有**才重要。
+ */
+export declare function isLocalPoolForward(request: HostEgressRequest | undefined): boolean;
+/**
+ * 出网守卫。
+ *
+ * 持有 ctx 只为两件事：取本地 provider 名单（与 adapter 同源）、给裁过的请求
+ * 打标记（防重新派发时递归）。
+ */
+export declare class HostEgressGuard {
+    private readonly ctx;
+    /** 已裁过的请求对象 —— 重新派发会再进一次 waterfall，靠它放行。 */
+    private readonly trimmed;
+    constructor(ctx: Context);
+    /**
+     * 运行时取本地 provider 名单。
+     *
+     * 用 model-router 的 `listDetailed()`（带 realm 标注）—— 与路由判定、adapter
+     * 的 §7.131 裁剪同一份事实源。model-router 在 patch 里排在 input-guard 之后，
+     * 所以运行时取（与 `CloudEgressGuard.localProviders()` 同款做法）。
+     *
+     * **必须走 `ctx.get()` 而不是 `ctx.modelRouter` 直取**：cordis 4.x 的 ctx 是
+     * Proxy —— 读一个既没 provide、也不在 `inject` 声明里的属性会**直接抛**
+     * `cannot get property "modelRouter" without inject`（input-guard 刻意不把
+     * model-router 放进 `inject`，见那处的注释）。`ctx.get()` 才是「可选服务」的
+     * 安全读法（input-guard 的 `localAvailable()` 用的就是它）。
+     */
+    localProviders(): string[];
+    /** 给裁过的请求对象打标记。 */
+    markTrimmed(options: object): void;
+    /** 这个请求对象是不是已经裁过了？（重新派发时进来 ⇒ 直接放行） */
+    isTrimmed(options: object): boolean;
+    /**
+     * 这通调用要不要裁？裁的话给出裁剪结果。
+     *
+     * 不裁的情形（逐条都要有理由，缺一条就是一条漏）：
+     * - 已经裁过的请求（重新派发进来的那一趟）⇒ 直接放行。
+     * - 没有 provider ⇒ 不是模型调用（防御）。
+     * - 自有池 / 本地池 ⇒ 按裁决不带云段 / 带全部历史。
+     * - **本地池 delegate 转发**（§7.171）⇒ 这通调用由本地池发起，口径是
+     *   「带全部历史」⇒ 不裁。转发后 `provider` 是宿主的目标 provider，光看
+     *   provider 判不出来（那是宿主原生路由），只能靠转发标记区分。
+     * - `purpose` 非空 ⇒ 宿主的内部用途（compaction / session-title），
+     *   不是主人关心的「这一轮对话」，裁它会破坏子系统的语义。
+     * - 没有可识别的用户输入 ⇒ `planCloudEgress` 走退化路径（全部保留）。
+     * - 裁完一条不丢 ⇒ 没有本地段，不需要裁。
+     */
+    plan(request: HostEgressRequest): HostEgressPlan | undefined;
+}
+//# sourceMappingURL=host-egress-guard.d.ts.map

package/lib/dsh-adapter/host-egress-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-egress-guard.d.ts","sourceRoot":"","sources":["../../src/dsh-adapter/host-egress-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAElD,OAAO,EAGL,KAAK,aAAa,EACnB,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EAAE,yBAAyB,EAAsB,MAAM,qBAAqB,CAAA;AAEnF,kDAAkD;AAClD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,kEAAkE;IAClE,CAAC,yBAAyB,CAAC,CAAC,EAAE,OAAO,CAAA;CACtC;AAED,YAAY;AACZ,MAAM,WAAW,cAAc;IAC7B,qBAAqB;IACrB,QAAQ,EAAE,aAAa,EAAE,CAAA;IACzB,iCAAiC;IACjC,YAAY,EAAE,MAAM,CAAA;IACpB,qDAAqD;IACrD,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAClC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,MAAM,EAChB,cAAc,EAAE,SAAS,MAAM,EAAE,EACjC,GAAG,GAAE,SAAS,MAAM,EAAuB,GAC1C,OAAO,CAMT;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,SAAS,aAAa,EAAE,EAClC,cAAc,EAAE,SAAS,MAAM,EAAE,GAChC,cAAc,GAAG,SAAS,CAW5B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,iBAAiB,GAAG,SAAS,GAAG,OAAO,CAIlF;AAED;;;;;GAKG;AACH,qBAAa,eAAe;IAId,OAAO,CAAC,QAAQ,CAAC,GAAG;IAHhC,4CAA4C;IAC5C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwB;gBAEnB,GAAG,EAAE,OAAO;IAEzC;;;;;;;;;;;;OAYG;IACH,cAAc,IAAI,MAAM,EAAE;IAmB1B,mBAAmB;IACnB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAIlC,sCAAsC;IACtC,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAInC;;;;;;;;;;;;;;OAcG;IACH,IAAI,CAAC,OAAO,EAAE,iBAAiB,GAAG,cAAc,GAAG,SAAS;CAiB7D"}

package/lib/dsh-adapter/host-egress-guard.js

@@ -0,0 +1,213 @@
+/**
+ * host-egress-guard — §7.151 出网那一跳的「只带云段历史」守卫
+ *
+ * ## 为什么需要这个模块（主人现场，2026-10-29）
+ *
+ * 主人在 Edge 面板看到：发往云端模型（`qwen-token-plan-cn/deepseek-v4.1-flash`）
+ * 的请求里带着**全部**本地历史 —— 三条 `provider: local-llm` 的 assistant
+ * 回复原样上云。那违反 §7.131 的裁决（2026-10-27）：
+ *
+ * > 发往 cloud-llm 的请求只能携带**之前上过 cloud-llm 的历史**；本地池带全部历史。
+ *
+ * ## 根因：这条出网**根本没经过**本项目的 cloud adapter
+ *
+ * §7.131 的裁剪一直住在 `cloud-llm-adapter` 里（直连路径 + delegate 路径各一份）。
+ * 但桌面部署的 CLOUD 轮次**压根不进那个 adapter**：
+ *
+ * ```
+ * intent.classify.end  category=CLOUD confidence=0.95 path=jev-adopt
+ * input-guard.routed   category=CLOUD edgeRouteUsed=False routeSource=webui
+ * llm.trace.index REQ  provider=qwen-token-plan-cn model=deepseek-v4.1-flash messageCount=31
+ * ```
+ *
+ * - `edgeRouteUsed=False` ⇒ webui 入口没有 `_edgeRoute`，edge 不改写路由；
+ * - 意图判成 CLOUD ⇒ `handleAgentRequest` **不**降级 ⇒ seed 的 provider 原样保留；
+ * - seed 的 provider 是宿主自己的 `qwen-token-plan-cn`（桌面 GUI 选的模型）⇒
+ *   agent-loop 直接派发给**宿主原生 provider**，不经过 `cloud-llm`。
+ *
+ * 于是 `cloud-llm-adapter` 里的 §7.131 裁剪**一次都没跑过**（审计链里
+ * `llm.cloud.delegate.resolved` / `llm.cloud.egress` 全是 0 条可证）。
+ *
+ * ## 修法：守卫落在**真正的出网那一跳**
+ *
+ * 宿主原生 provider 的那一跳只有一个必经之地：`llm/stream` waterfall
+ * （`ctx.llm.stream()` 的实现就是 `ctx.waterfall(this, 'llm/stream', options, …)`）。
+ * 守卫在那儿：
+ *
+ * 1. 判定这通调用是不是**出网**的（provider 不在本地池 / 自有池里）；
+ * 2. 用 `planCloudEgress`（与 adapter 同一份口径）算出「只带云段历史」的请求体；
+ * 3. 命中本地段 ⇒ **换掉请求体重新派发**（`ctx.llm.stream({...options, messages})`）。
+ *
+ * ### 为什么必须「重新派发」而不是就地改写
+ *
+ * 宿主契约（`@deepseek-ai/dsh-llm` 的 api-catalog 明写）：
+ *
+ * > A LOOP-built request carries the process-local `markAgentLoopRequest` identity
+ * > and arrives **deep-frozen (mutation throws)**: its content is a pure function
+ * > of the session log … so listeners **read it, never rewrite it**.
+ *
+ * 请求体是冻结的 ⇒ 只能换一个请求对象重新派发。这与 `cloud-llm-adapter` 的
+ * delegate 路径是同一个姿势（它也用 `{...options, messages: forwardMessages}`
+ * 重新派发），宿主侧已验证可行。
+ *
+ * 重新派发会**再进一次 waterfall**：本模块用 `markTrimmed` 打标记，
+ * 裁过的请求体进来直接放行 ⇒ 不会递归、不会二次裁剪。
+ *
+ * ## 裁剪口径与 adapter 完全同源
+ *
+ * 判据、段划分、丢弃规则全部复用 `cloud-egress.ts` 的 `planCloudEgress` ——
+ * 同一份事实源，杜绝「adapter 认为该带、守卫认为该丢」这种口径漂移。
+ *
+ * @module dsh-edge-agent/host-egress-guard
+ */
+import { assistantProviderHistogram, planCloudEgress, } from './cloud-egress.js';
+import { LOCAL_POOL_FORWARD_MARKER, OWN_POOL_PROVIDERS } from './host-llm-trace.js';
+/**
+ * 这通调用是不是**出网**的？
+ *
+ * - 自有池（`local-llm` / `cloud-llm`）⇒ **不归本守卫管**：
+ *   `local-llm` 按裁决带全部历史；`cloud-llm` 由 `cloud-llm-adapter` 自己裁
+ *   （直连与 delegate 两条路径都接了 §7.131，审计行也由它出）。
+ *   守卫再裁一遍会让 adapter 的 `historyDropped` 变成 0，**把证据洗掉**。
+ * - 本地池名单（model-router 的 LOCAL 名单）⇒ 本地池，带全部历史。
+ * - `local-` 前缀 ⇒ 同上（与 `providerSegment` 同源）。
+ * - 其余（宿主自选 provider，如 `qwen-token-plan-cn`）⇒ 出网，要裁。
+ */
+export function isCloudBoundProvider(provider, localProviders, own = OWN_POOL_PROVIDERS) {
+    if (provider.length === 0)
+        return false;
+    if (own.includes(provider))
+        return false;
+    if (localProviders.includes(provider))
+        return false;
+    if (provider.startsWith('local-'))
+        return false;
+    return true;
+}
+/**
+ * 纯裁剪：只带云段历史。返回 `undefined` 表示**无需裁剪**（没有本地段）。
+ *
+ * `currentSegment: 'cloud'` —— 本轮正在出网，所以本轮归属云段。
+ */
+export function planHostEgress(messages, localProviders) {
+    const plan = planCloudEgress(messages, {
+        currentSegment: 'cloud',
+        localProviders,
+    });
+    if (plan.droppedCount === 0)
+        return undefined;
+    return {
+        messages: plan.kept,
+        droppedCount: plan.droppedCount,
+        histogram: assistantProviderHistogram(messages),
+    };
+}
+/**
+ * §7.171: 这通调用是不是「本地池 delegate 转发」？
+ *
+ * 本地池转发给宿主提供商时，`provider` 已经是宿主的目标路由（如
+ * `deepseek-official`）—— 与「用户直接选了那个模型」在 provider 维度上
+ * **无法区分**。唯一的区别在发起方：本地池的口径是「带全部历史」，宿主原生
+ * 路由的口径是「只带云段历史」。所以转发方必须在请求上打标记。
+ *
+ * 标记值刻意做成 truthy 判据（而不是 `=== true`）：宿主 spread options 时
+ * 原样透传，值是什么不重要，**有没有**才重要。
+ */
+export function isLocalPoolForward(request) {
+    if (request == null || typeof request !== 'object')
+        return false;
+    const flag = request[LOCAL_POOL_FORWARD_MARKER];
+    return flag !== undefined && flag !== null && flag !== false;
+}
+/**
+ * 出网守卫。
+ *
+ * 持有 ctx 只为两件事：取本地 provider 名单（与 adapter 同源）、给裁过的请求
+ * 打标记（防重新派发时递归）。
+ */
+export class HostEgressGuard {
+    ctx;
+    /** 已裁过的请求对象 —— 重新派发会再进一次 waterfall，靠它放行。 */
+    trimmed = new WeakSet();
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    /**
+     * 运行时取本地 provider 名单。
+     *
+     * 用 model-router 的 `listDetailed()`（带 realm 标注）—— 与路由判定、adapter
+     * 的 §7.131 裁剪同一份事实源。model-router 在 patch 里排在 input-guard 之后，
+     * 所以运行时取（与 `CloudEgressGuard.localProviders()` 同款做法）。
+     *
+     * **必须走 `ctx.get()` 而不是 `ctx.modelRouter` 直取**：cordis 4.x 的 ctx 是
+     * Proxy —— 读一个既没 provide、也不在 `inject` 声明里的属性会**直接抛**
+     * `cannot get property "modelRouter" without inject`（input-guard 刻意不把
+     * model-router 放进 `inject`，见那处的注释）。`ctx.get()` 才是「可选服务」的
+     * 安全读法（input-guard 的 `localAvailable()` 用的就是它）。
+     */
+    localProviders() {
+        let router;
+        try {
+            router = this.ctx.get?.('modelRouter');
+        }
+        catch {
+            router = undefined;
+        }
+        try {
+            const detailed = router?.listDetailed?.() ?? [];
+            const locals = detailed
+                .filter(d => d.realm === 'LOCAL' && typeof d.provider === 'string')
+                .map(d => d.provider);
+            if (locals.length > 0)
+                return locals;
+        }
+        catch { /* fall through to the default */ }
+        return ['local-llm'];
+    }
+    /** 给裁过的请求对象打标记。 */
+    markTrimmed(options) {
+        this.trimmed.add(options);
+    }
+    /** 这个请求对象是不是已经裁过了？（重新派发时进来 ⇒ 直接放行） */
+    isTrimmed(options) {
+        return this.trimmed.has(options);
+    }
+    /**
+     * 这通调用要不要裁？裁的话给出裁剪结果。
+     *
+     * 不裁的情形（逐条都要有理由，缺一条就是一条漏）：
+     * - 已经裁过的请求（重新派发进来的那一趟）⇒ 直接放行。
+     * - 没有 provider ⇒ 不是模型调用（防御）。
+     * - 自有池 / 本地池 ⇒ 按裁决不带云段 / 带全部历史。
+     * - **本地池 delegate 转发**（§7.171）⇒ 这通调用由本地池发起，口径是
+     *   「带全部历史」⇒ 不裁。转发后 `provider` 是宿主的目标 provider，光看
+     *   provider 判不出来（那是宿主原生路由），只能靠转发标记区分。
+     * - `purpose` 非空 ⇒ 宿主的内部用途（compaction / session-title），
+     *   不是主人关心的「这一轮对话」，裁它会破坏子系统的语义。
+     * - 没有可识别的用户输入 ⇒ `planCloudEgress` 走退化路径（全部保留）。
+     * - 裁完一条不丢 ⇒ 没有本地段，不需要裁。
+     */
+    plan(request) {
+        // 已经裁过的请求（重新派发进来的那一趟）⇒ 直接放行：再裁一次是幂等的，
+        // 但**再派发一次就是递归**。
+        if (request != null && typeof request === 'object' && this.isTrimmed(request))
+            return undefined;
+        // §7.171: 本地池 delegate 转发 ⇒ 不裁（LOCAL 口径：带全部历史）。
+        // 标记由 `CloudLlmDelegateAdapterImpl` 在 poolKind='local' 时打上。
+        if (isLocalPoolForward(request))
+            return undefined;
+        const provider = typeof request?.provider === 'string' ? request.provider : '';
+        if (provider.length === 0)
+            return undefined;
+        const purpose = typeof request?.purpose === 'string' ? request.purpose : '';
+        if (purpose.length > 0)
+            return undefined;
+        const locals = this.localProviders();
+        if (!isCloudBoundProvider(provider, locals))
+            return undefined;
+        if (!Array.isArray(request?.messages))
+            return undefined;
+        const messages = request.messages;
+        return planHostEgress(messages, locals);
+    }
+}

package/lib/dsh-adapter/host-llm-trace.d.ts

@@ -0,0 +1,198 @@
+/**
+ * host-llm-trace — §7.144 记录**宿主 provider** 发出的 LLM 调用
+ *
+ * ## 为什么需要这个模块（主人现场发现）
+ *
+ * 主人在 Edge 面板看到「本轮走云端了，但 LLM 调用里没有云端模型」。查审计链
+ * 得到的硬事实是：那一轮**确实**判成了 CLOUD（jev 置信 0.83 < 门限 0.85 →
+ * 落到本地 LLM 分类器 → `llm-classified:cloud`），但整轮**零条**
+ * `llm.cloud.*` 事件 —— 只有 `llm.local.*`。
+ *
+ * 原因不是路由错了，是**观测漏了一跳**：
+ *
+ * - `config/edge.json` 的 `llm.cloud` 是 **delegate 模式**（`baseUrl` 空 +
+ *   `delegate: true`，§7.100）：CLOUD 请求**转发给宿主 profile 已配置的模型
+ *   提供商**（桌面 GUI 里选的那个，如 `qwen-token-plan-cn`），凭据全归宿主。
+ * - 于是主对话的请求**不经过本项目的 cloud adapter** ⇒ 没有 `llm.cloud.*`
+ *   审计事件，也没有 trace ⇒ 面板里云端模型整条缺席。
+ * - 面板是诚实的（它没编造），但**不完整** —— 主人看到的是「没发生过」，
+ *   实际是「没被记下来」。这正是 §7.129 最怕的那种误导：不是显示了一件
+ *   没发生的事，而是**漏显示**了一件真发生的事。
+ *
+ * ## 补在哪一跳
+ *
+ * 宿主的 `llm/stream` 事件带**完整信封**（`GenerateOptions`：provider /
+ * model / messages / system / tools / …），响应侧带**完整 chunk 流**
+ * （text-delta / block-end / tool-call-delta / usage / finish）。所以宿主
+ * provider 的这一跳**本来就完全可观测** —— 只是没人接。
+ *
+ * 本模块提供那一跳的记录能力；接线在 `input-guard` 的 `llm/stream` 钩子
+ * （那里已经握有 sessionId → 会话状态的映射，能区分「边缘会话」与「标准
+ * 模式会话」）。
+ *
+ * ## 与 adapter 记的那几条如何不重复
+ *
+ * 本项目自管两个池，provider 名固定：
+ *
+ * - `local-llm`（local adapter 注册名）
+ * - `cloud-llm`（cloud adapter 注册名；delegate 模式下它把请求**再**转发给
+ *   宿主 provider，那一跳的 provider 名是宿主自己的 ⇒ 正好被这里记到）
+ *
+ * 凡是 provider 属于自管池的调用，**adapter 自己已经记过**（REQ + RESP），
+ * 这里跳过 —— 否则面板上会出现同一通调用记两遍。
+ *
+ * ## 记什么
+ *
+ * | 侧 | 内容 |
+ * |---|---|
+ * | REQ | 宿主看到的信封：provider / model / messages / system / tools / 参数 |
+ * | RESP | 完整正文（block-end 优先）+ 工具调用 + finish reason + usage |
+ *
+ * `body` 快照是**宿主层信封**，不是 provider 的 wire body —— 后者在 adapter
+ * 内部，宿主这一跳看不见。面板上 provider/model 字段会显示宿主 provider
+ * 名（如 `qwen-token-plan-cn/deepseek-v4.1-flash`），一眼能认出「这是云端
+ * 模型那一条」。
+ *
+ * @module dsh-edge-agent/host-llm-trace
+ */
+import type { LlmRequestTrace, LlmResponseTrace, LlmTraceConfig, TraceSink } from './llm-trace.js';
+/**
+ * 本项目自管池的 provider 名（adapter 注册名）。
+ *
+ * 这两个名字来自 adapter 的注册表（cloud adapter 的 `providers` 默认
+ * `['cloud-llm']`），不是配置项 —— 改成别的名字会破坏 §7.100 的 delegate
+ * 语义，所以这里写死成常量。
+ */
+export declare const OWN_POOL_PROVIDERS: readonly string[];
+/**
+ * §7.171 (2026-11-10): 「本地池 delegate 转发」标记。
+ *
+ * `local-llm` 走 delegate 时会把请求转发给宿主提供商（§7.171 新增），转发时
+ * `provider` 变成了**目标** provider（不再是 `local-llm`）⇒ `host-egress-guard`
+ * 会把它当成「宿主原生 provider 的出网那一跳」⇒ 按 §7.131 口径裁掉本地段历史。
+ *
+ * 但本地池的口径恰恰相反：**带全部历史**（§7.131 的不对称规则第一条）。
+ * ⇒ 转发时打这个标记，出网守卫看到它就放行（不裁）。
+ *
+ * 打在 options 上是安全的：宿主 `LlmRuntime.stream` 走
+ * `{...options, ...resolvedConfig}` 的 spread（`@deepseek-ai/dsh-llm`
+ * `lib/index.js` 的 `adapterStream`），未知字段原样透传，不会被拒。
+ *
+ * 住在这里（而不是 adapter 里）是因为**打标的一方与读标的一方分属两个模块**：
+ * `cloud-llm-adapter.ts`（打）↔ `host-egress-guard.ts`（读）。与
+ * `OWN_POOL_PROVIDERS` 同处一地 —— 自有池相关的判据只有这一份事实源。
+ */
+export declare const LOCAL_POOL_FORWARD_MARKER = "__edgeLocalPoolForward";
+/**
+ * 这个 provider 是不是本项目自己管的池？
+ *
+ * 是 ⇒ adapter 已经记过这次调用，这里必须跳过（否则同一通调用记两遍）。
+ * 否 ⇒ 宿主自己的 provider（delegate 出去的云池），**这里要补记**。
+ */
+export declare function isOwnPoolProvider(provider: string, own?: readonly string[]): boolean;
+/** 宿主 `llm/stream` 的 options 里我们用得到的部分。 */
+export interface HostCallRequest {
+    provider: string;
+    model: string;
+    sessionId: string;
+    messages: Array<{
+        role: string;
+        content: unknown;
+        source?: {
+            kind?: string;
+            provider?: string;
+        };
+    }>;
+    system?: string;
+    tools?: Array<{
+        name?: string;
+        function?: {
+            name?: string;
+        };
+    }>;
+    params?: {
+        temperature?: number;
+        maxTokens?: number;
+        stream?: boolean;
+    };
+}
+/**
+ * 构造宿主调用的 request trace。
+ *
+ * `rawBody` 记的是**宿主层信封**（provider / model / messages / system /
+ * tools / 参数）—— 宿主这一跳能看到的全部。provider 的 wire body 在 adapter
+ * 内部，从这里看不见（那一侧由 adapter 自己记）。
+ */
+export declare function buildHostRequestTrace(input: {
+    request: HostCallRequest;
+    config: LlmTraceConfig;
+}): LlmRequestTrace;
+/** 一次宿主调用的响应摘要。 */
+export interface HostResponseSnapshot {
+    content: string;
+    toolCalls: Array<{
+        id?: string;
+        name: string;
+        arguments?: string;
+    }>;
+    finishReason?: string;
+    usage?: {
+        promptTokens?: number;
+        completionTokens?: number;
+        totalTokens?: number;
+    };
+}
+/**
+ * 从宿主的 chunk 流里累积一次响应。
+ *
+ * 正文优先取 `block-end` 的 `block.text`（宿主在 block 结束时给的是**全文**
+ * 比逐个 text-delta 拼更准）；拿不到才回落累积 delta。
+ */
+export declare class HostResponseAccumulator {
+    private text;
+    private textTruncated;
+    private readonly calls;
+    private finishReason;
+    private usage;
+    /** 吃掉一个 chunk。永不抛 —— 畸形 chunk 直接忽略。 */
+    push(chunk: unknown): void;
+    private appendText;
+    /** 当前累积结果。 */
+    snapshot(): HostResponseSnapshot;
+    /** 累积时是否撞到上限（面板据此说明正文不全）。 */
+    get truncated(): boolean;
+}
+/** 构造宿主调用的 response trace。 */
+export declare function buildHostResponseTrace(input: {
+    sessionId: string;
+    provider: string;
+    model: string;
+    snapshot: HostResponseSnapshot;
+    durationMs?: number;
+    config: LlmTraceConfig;
+}): LlmResponseTrace;
+/** 记录器的依赖面。 */
+export interface HostCallRecorderOptions {
+    sink: TraceSink;
+    config: LlmTraceConfig;
+    request: HostCallRequest;
+    /** §7.134：与面板配对用的 callId（REQ/RESP 共用）。 */
+    callId: string;
+}
+/**
+ * 一次宿主 provider 调用的记录器。
+ *
+ * 构造即记 REQ；`wrap()` 包住 chunk 流，流结束时记 RESP。REQ/RESP 共用
+ * 同一个 callId ⇒ 面板上仍然「上请求、下响应」成对显示。
+ */
+export declare class HostCallRecorder {
+    private readonly options;
+    private readonly accumulator;
+    private readonly startedAt;
+    private responseEmitted;
+    constructor(options: HostCallRecorderOptions);
+    /** 包住 chunk 流：边转发边累积，流结束记 RESP。 */
+    wrap(stream: AsyncIterable<unknown>): AsyncIterable<unknown>;
+    private emitResponse;
+}
+//# sourceMappingURL=host-llm-trace.d.ts.map

package/lib/dsh-adapter/host-llm-trace.d.ts.map

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