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

package/lib/dsh-adapter/llm-trace.js

@@ -0,0 +1,463 @@
+/**
+ * llm-trace — 详细的 LLM request / response 追踪，写进 ops log。
+ *
+ * ## 为什么需要这个模块
+ *
+ * 现状（§7.118, 2026-10-26）：adapters 只在 ops log 里记**长度**——
+ * `promptLen=121853 systemLen=225 resultLen=5006`。真正想看"到底发了什么、
+ * 回了什么"的时候，唯一去处是把 `DSH_EDGE_LOG_LEVEL` 降到 `debug`，而
+ * `LLM_MESSAGES` / `LLM_RESPONSE_TEXT` 那两条全量 dump 才会出现：
+ *
+ *   - 全量 dump 没有脱敏 → 用户原文、工具回显、可能夹带的凭据直接落盘；
+ *   - 全量 dump 没有截断 → 一条 120KB 的 prompt 能撑爆一行日志；
+ *   - `debug` 级别默认被压制 → 运维默认看不到，而需要看的人往往是在出事之后。
+ *
+ * 这个模块把"详细"拆成三个**可独立关闭**的维度，并给每一维加上硬边界：
+ *
+ *   1. **脱敏**（`redactPii` / `redactSecrets`）——PII 走 `pii-utils` 的
+ *      10 类规则，凭据走本模块自己的密钥掩码（`pii-utils` 的 api-key 规则
+ *      匹配不到 `sk-cp-` / `tvly-` 这类带前缀的厂商密钥，见
+ *      `SECRET_PATTERNS`）。
+ *   2. **截断**（`maxChars` / `maxMessages`）——每个字段独立上限，且**截断
+ *      必须显式可见**（`truncated: true` + `…[+N chars]`），绝不让"日志里
+ *      看起来是完整的"成为可能。
+ *   3. **分级**（`includeRequest` / `includeResponse`）——只要 request 或
+ *      只要 response，各自可关。
+ *
+ * ## 落盘位置
+ *
+ * 走 `ctx.logger.info` —— 即 ops log 的默认级别。**不是** debug：运维在
+ * 出事后 tail 的是 ops log，不是 debug 日志。
+ *
+ * ## 安全边界
+ *
+ * - 本模块**不**写明文密钥：`authorization` 头、`apiKey` 参数一律不进 trace。
+ * - 本模块**不**改变任何出网行为：它只在本地组装一个日志对象。
+ * - 本模块对畸形输入**永不抛错**：trace 是观测手段，不能把主链路带崩。
+ *
+ * @module dsh-edge-agent/llm-trace
+ */
+import { redactString } from './pii-utils.js';
+import { nextTraceId } from './llm-trace-store.js';
+import { realSessionId } from './session-attribution.js';
+/**
+ * 出厂默认。
+ *
+ * `maxChars=2000` 的取舍：一条 message 的正文通常在几百字，2000 足够看清
+ * 上下文；整轮 12 条 message × 2000 字 ≈ 24KB 一行，日志文件按 50MB 轮转，
+ * 完全可控。想看全量请走 `DSH_EDGE_LOG_LEVEL=debug` 的旧通道，不要把这个值
+ * 调到很大 —— 那是拿磁盘换眼睛。
+ */
+export const DEFAULT_LLM_TRACE_CONFIG = {
+    enabled: true,
+    includeRequest: true,
+    includeResponse: true,
+    maxChars: 2000,
+    maxMessages: 12,
+    maxBodyChars: 20000,
+    redactPii: true,
+    redactSecrets: true,
+};
+/**
+ * 从 `config/edge.json` 解析 trace 配置。
+ *
+ * 缺省逐字段回落到 `DEFAULT_LLM_TRACE_CONFIG`；`maxChars<=0` 视为"不截断"
+ * 但会在 trace 里标注 `truncated:false`，让读日志的人知道这是显式选择。
+ */
+export function resolveLlmTraceConfig(cfg) {
+    const raw = cfg?.audit?.llmTrace;
+    if (!raw)
+        return { ...DEFAULT_LLM_TRACE_CONFIG };
+    const pick = (k) => raw[k] === undefined ? DEFAULT_LLM_TRACE_CONFIG[k] : raw[k];
+    return {
+        enabled: pick('enabled'),
+        includeRequest: pick('includeRequest'),
+        includeResponse: pick('includeResponse'),
+        maxChars: pick('maxChars'),
+        maxMessages: pick('maxMessages'),
+        maxBodyChars: pick('maxBodyChars'),
+        redactPii: pick('redactPii'),
+        redactSecrets: pick('redactSecrets'),
+    };
+}
+/* ── 凭据掩码 ───────────────────────────────────────────────────────────── */
+/**
+ * 凭据字面量掩码（不依赖 pii-utils）。
+ *
+ * `pii-utils` 的 `api-key` 规则是
+ * `sk-(?:proj-|ant-|live-|test-|org-)?[a-zA-Z0-9]{20,}`，它**匹配不到**
+ * 厂商自定义前缀的密钥：`sk-cp-…`（MiniMax）在 `cp-` 处断了，且下一段含
+ * `_` 也不在字符类里；`tvly-…`（Tavily）、`sk-ws-…`（DashScope）同理。
+ * 实测 `config/edge.json` 里的三把真 key 全部逃逸。
+ *
+ * 所以这里独立覆盖"厂商前缀 + 通用形态"两类，并加两条**收敛条件**避免误伤
+ * 普通英文词：
+ *
+ *   - 厂商前缀密钥要求"长度 ≥16 **且** 至少含一个数字"。真密钥几乎必然带
+ *     数字；而 `key-representation`、`api-key-description` 这类正常词不含
+ *     数字，不会被误掩。字符类放宽到 `[A-Za-z0-9._-]`（含 `.`），否则
+ *     DashScope 的 `sk-ws-EXAMPLE0.dot0.…`（JWS 风格带点）会在第一个
+ *     点处断掉而逃逸。
+ *   - 另加一条全大写形态（`tvly-PLACEHOLDER_REPLACE_ME`），这类占位符不含
+ *     数字但仍是凭据位。
+ */
+export const SECRET_PATTERNS = [
+    // Authorization / Bearer 头：整个 token 换成固定掩码。
+    { name: 'bearer', pattern: /\b(Bearer|Basic)\s+[A-Za-z0-9._~+/=-]{8,}/gi },
+    // 厂商前缀密钥（含数字）：sk-cp-… / sk-ws-… / xai-… / pk-…
+    {
+        name: 'vendor-key',
+        pattern: /\b(?:sk|key|pk|tvly|xai|rk|ak)[-_](?=[A-Za-z0-9._-]*\d)[A-Za-z0-9._-]{16,}/gi,
+    },
+    // 厂商前缀密钥（全大写占位形态）：tvly-PLACEHOLDER_REPLACE_ME
+    { name: 'vendor-key-caps', pattern: /\b(?:sk|key|pk|tvly|xai|rk|ak)[-_][A-Z0-9_]{12,}\b/g },
+    // 标签式：apiKey=xxx / "api_key": "xxx" / secret: xxx / token=xxx
+    {
+        name: 'labeled-secret',
+        pattern: /\b(api[_-]?key|apikey|secret|access[_-]?token|refresh[_-]?token|authorization|password|passwd|pwd|token)\b\s*["']?\s*[:=]\s*["']?[A-Za-z0-9._~+/=-]{8,}/gi,
+    },
+];
+/** 掩码后的固定占位符。 */
+export const SECRET_MASK = '[REDACTED]';
+/**
+ * 把文本里的凭据字面量替换成 `SECRET_MASK`。
+ *
+ * 顺序有意义：先打标签式（`apiKey=…`），再打 `Bearer`，最后打裸厂商前缀 ——
+ * 否则 `Bearer sk-cp-xxx` 会被前两条先吃掉，留下一截尾巴。
+ */
+export function maskSecrets(text) {
+    let out = text;
+    const hits = new Set();
+    for (const { name, pattern } of SECRET_PATTERNS) {
+        // 克隆正则，避免共享实例的 lastIndex 在并发调用间串扰（同 pii-utils 的做法）
+        const re = new RegExp(pattern.source, pattern.flags);
+        if (!re.test(out))
+            continue;
+        hits.add(name);
+        out = out.replace(new RegExp(pattern.source, pattern.flags), (m) => {
+            // 标签式：保留标签名，只换值，保留可读性。
+            const idx = m.search(/[:=]/);
+            if (idx >= 0)
+                return `${m.slice(0, idx + 1)}${SECRET_MASK}`;
+            // Bearer：保留前缀（`Bearer `），换掉 token。
+            const sp = m.search(/\s/);
+            if (sp > 0 && /^(Bearer|Basic)$/i.test(m.slice(0, sp))) {
+                return `${m.slice(0, sp + 1)}${SECRET_MASK}`;
+            }
+            return SECRET_MASK;
+        });
+    }
+    return { text: out, hits: [...hits] };
+}
+/**
+ * 按字符数截断，**显式标注**溢出了多少。
+ *
+ * 不用 `…` 单字符收尾 —— 它和原文里的省略号没法区分。统一用
+ * `…[+N chars]`，`grep` 得到的就是真的。
+ */
+export function truncateForLog(text, maxChars) {
+    if (typeof text !== 'string')
+        return { text: '', length: 0, truncated: false };
+    const length = text.length;
+    if (maxChars <= 0 || length <= maxChars)
+        return { text, length, truncated: false };
+    const dropped = length - maxChars;
+    return { text: `${text.slice(0, maxChars)}…[+${dropped} chars]`, length, truncated: true };
+}
+/**
+ * 对一段要进日志的文本走完整条链：凭据掩码 → PII 脱敏 → 截断。
+ *
+ * 顺序同样有讲究：先掩码再脱敏，避免 PII 规则把密钥的一部分改写成别的形态
+ * 而逃过掩码；截断放最后，保证掩码与脱敏作用在**完整**文本上（否则密钥可能
+ * 恰好落在被切掉的那一段里……不对，那样反而安全了，但 PII 的部分掩码会因
+ * 截断而失配。结论：先处理完再截，语义最直观）。
+ */
+export function sanitizeTraceText(text, cfg) {
+    if (typeof text !== 'string' || text.length === 0) {
+        return { text: '', length: 0, truncated: false };
+    }
+    let out = text;
+    if (cfg.redactSecrets)
+        out = maskSecrets(out).text;
+    if (cfg.redactPii)
+        out = redactString(out).redacted;
+    return truncateForLog(out, cfg.maxChars);
+}
+/* ── body 快照（§7.144）────────────────────────────────────────────────── */
+/**
+ * 把任意 body 序列化成**可安全记录**的文本。
+ *
+ * 三个坑：
+ *   - **循环引用** → `JSON.stringify` 直接抛 `TypeError`。body 里出现循环
+ *     （宿主 options 被塞回 body 这类）就会把观测路径变成故障源。
+ *   - **BigInt** → 同样抛。
+ *   - **不可序列化的值**（函数 / Symbol）→ `JSON.stringify` 会静默丢掉，
+ *     让人以为"没发这个字段"。用 replacer 把它们替换成占位符，**显式**告诉
+ *     读日志的人「这里有个记不住的值」，而不是让它凭空消失。
+ */
+export function serializeTraceBody(value) {
+    if (typeof value === 'string')
+        return value;
+    const seen = new WeakSet();
+    try {
+        return JSON.stringify(value, (_key, v) => {
+            if (typeof v === 'bigint')
+                return `[bigint ${v.toString()}]`;
+            if (typeof v === 'function')
+                return '[function]';
+            if (typeof v === 'symbol')
+                return '[symbol]';
+            if (typeof v === 'object' && v !== null) {
+                if (seen.has(v))
+                    return '[circular]';
+                seen.add(v);
+            }
+            return v;
+        }) ?? '';
+    }
+    catch {
+        return '[unserializable body]';
+    }
+}
+/**
+ * body 快照的脱敏 + 截断。
+ *
+ * 走与正文同一条链（凭据掩码 → PII 脱敏 → 截断），只是上限换成
+ * `maxBodyChars`（body 比单条 message 大得多，按 2000 截就没意义了）。
+ */
+export function buildBodySnapshot(value, config) {
+    if (value === undefined || value === null)
+        return undefined;
+    const text = serializeTraceBody(value);
+    if (text.length === 0)
+        return undefined;
+    return sanitizeTraceText(text, { ...config, maxChars: config.maxBodyChars });
+}
+/**
+ * 把 `options.messages` 的 content 摊平成纯文本。
+ *
+ * dsh-llm 的 `Message.content` 有两种形态：content-block 数组（`{type:'text',
+ * text}`）和裸字符串。两种都要认，否则一半消息在 trace 里是空的。
+ */
+export function messageContentToText(content) {
+    if (typeof content === 'string')
+        return content;
+    if (!Array.isArray(content))
+        return '';
+    return content
+        .filter((b) => typeof b === 'object' && b !== null && b.type === 'text')
+        .map((b) => (typeof b.text === 'string' ? b.text : ''))
+        .join('');
+}
+/**
+ * 构造 request trace。
+ *
+ * 保留**最后** `maxMessages` 条 message（而不是前 `maxMessages` 条）：多轮
+ * 对话里真正决定这次请求的是最近几轮，开头的 system 指令已经被压进
+ * `system` 字段了。
+ */
+export function buildRequestTrace(input) {
+    const { config } = input;
+    const all = input.messages ?? [];
+    const keepFrom = Math.max(0, all.length - Math.max(0, config.maxMessages));
+    const kept = all.slice(keepFrom);
+    const promptLength = all.reduce((n, m) => n + messageContentToText(m.content).length, 0);
+    const messages = kept.map((m, i) => {
+        const raw = messageContentToText(m.content);
+        const trace = {
+            index: keepFrom + i,
+            role: m.role,
+            length: raw.length,
+        };
+        if (m.source?.kind)
+            trace.kind = m.source.kind;
+        if (m.source?.provider)
+            trace.provider = m.source.provider;
+        // 空正文的消息（比如只有 tool_calls 的 assistant 回合）留空，不写 `text`
+        // 字段 —— 让读日志的人分得清"没有正文"和"正文被截断成空"。
+        if (raw.length > 0)
+            trace.text = sanitizeTraceText(raw, config);
+        return trace;
+    });
+    const trace = {
+        sessionId: input.sessionId,
+        provider: input.provider,
+        model: input.model,
+        messageCount: all.length,
+        droppedMessages: all.length - kept.length,
+        promptLength,
+        messages,
+    };
+    if (input.baseUrl)
+        trace.baseUrl = input.baseUrl;
+    if (input.system && input.system.length > 0) {
+        trace.system = sanitizeTraceText(input.system, config);
+    }
+    // §7.144: 完整请求体快照（真正发出去的那一坨）。
+    const body = buildBodySnapshot(input.rawBody, config);
+    if (body !== undefined)
+        trace.body = body;
+    const toolNames = (input.tools ?? [])
+        .map((t) => t.name ?? t.function?.name)
+        .filter((n) => typeof n === 'string' && n.length > 0);
+    if (toolNames.length > 0)
+        trace.tools = toolNames;
+    if (input.params)
+        trace.params = input.params;
+    return trace;
+}
+/** 构造 response trace。 */
+export function buildResponseTrace(input) {
+    const { config } = input;
+    const trace = {
+        sessionId: input.sessionId,
+        provider: input.provider,
+        model: input.model,
+        toolCalls: [],
+    };
+    if (input.attempt !== undefined)
+        trace.attempt = input.attempt;
+    if (input.durationMs !== undefined)
+        trace.durationMs = input.durationMs;
+    if (input.finishReason)
+        trace.finishReason = input.finishReason;
+    if (input.content && input.content.length > 0) {
+        trace.content = sanitizeTraceText(input.content, config);
+    }
+    for (const call of input.toolCalls ?? []) {
+        const t = { name: call.name };
+        if (call.id)
+            t.id = call.id;
+        if (call.arguments && call.arguments.length > 0) {
+            t.arguments = sanitizeTraceText(call.arguments, config);
+        }
+        trace.toolCalls.push(t);
+    }
+    if (input.usage)
+        trace.usage = input.usage;
+    // §7.144: 完整响应体快照。
+    const body = buildBodySnapshot(input.rawBody, config);
+    if (body !== undefined)
+        trace.body = body;
+    if (input.error) {
+        trace.error = truncateForLog(input.error, Math.max(200, config.maxChars)).text;
+    }
+    return trace;
+}
+/* ── 输出格式化 ─────────────────────────────────────────────────────────── */
+/**
+ * 把 trace 压成**单行**字符串。
+ *
+ * ops log 的 `formatLine` 会把换行折成 `⏎`，所以这里自己保证单行：
+ * `JSON.stringify` 已经把字符串内的换行转义成 `\n`，但仍可能出现裸的
+ * 控制字符（U+2028/2029 等），统一替换掉，避免日志文件出现"一行日志占了
+ * 三行物理行"的破事。
+ */
+export function formatTraceLine(tag, trace) {
+    let json;
+    try {
+        json = JSON.stringify(trace);
+    }
+    catch {
+        // 循环引用 / BigInt 之类的破值：退回一个可读的占位，绝不让日志路径抛错。
+        json = JSON.stringify({ error: 'trace-not-serializable' });
+    }
+    const singleLine = json.replace(/[\u0000-\u001f\u007f\u2028\u2029]/g, ' ');
+    return `[${tag}] ${singleLine}`;
+}
+/**
+ * 构造索引行 payload。
+ *
+ * 从 trace 对象里**提取标量**——不复制正文。正文另存 store。
+ */
+export function buildTraceIndex(traceId, kind, trace, caller, extra) {
+    const t = (trace ?? {});
+    const out = {
+        traceId,
+        kind,
+        provider: typeof t.provider === 'string' ? t.provider : '?',
+        model: typeof t.model === 'string' ? t.model : '?',
+    };
+    if (caller !== undefined)
+        out.caller = caller;
+    // §7.147: 索引行带上会话归属。trace 对象里本来就有 sessionId
+    // （`LlmRequestTrace.sessionId` / `LlmResponseTrace.sessionId`），只是没被
+    // 抄进索引行 —— 于是 195 条索引行全部落全局桶。
+    //
+    // 用 `sessionIdField()` 而不是直接抄：trace 里的 sessionId 在「会话建立
+    // 之前」的调用上是 `'<pre-session>'` **哨兵**（ops log 的显示约定，§7.52），
+    // 抄进载荷会造出一个不存在的桶。哨兵 ⇒ 不写这个键 ⇒ 归全局桶。
+    const sessionId = realSessionId(t.sessionId);
+    if (sessionId !== undefined)
+        out.sessionId = sessionId;
+    if (typeof t.baseUrl === 'string')
+        out.baseUrl = t.baseUrl;
+    if (typeof t.messageCount === 'number')
+        out.messageCount = t.messageCount;
+    if (typeof t.droppedMessages === 'number')
+        out.droppedMessages = t.droppedMessages;
+    if (typeof t.promptLength === 'number')
+        out.promptLength = t.promptLength;
+    if (typeof t.content?.length === 'number')
+        out.contentLength = t.content.length;
+    if (Array.isArray(t.toolCalls))
+        out.toolCallCount = t.toolCalls.length;
+    if (typeof t.durationMs === 'number')
+        out.durationMs = t.durationMs;
+    if (typeof t.finishReason === 'string')
+        out.finishReason = t.finishReason;
+    if (typeof t.error === 'string')
+        out.error = t.error;
+    // 工具数：response trace 里没有请求的工具表，由调用方通过 extra 补上；
+    // request trace 自己带 tools[]。
+    if (extra?.toolCount !== undefined)
+        out.toolCount = extra.toolCount;
+    else if (Array.isArray(t.tools))
+        out.toolCount = t.tools.length;
+    if (extra?.callId !== undefined)
+        out.callId = extra.callId;
+    let bytes = 0;
+    try {
+        bytes = JSON.stringify(trace)?.length ?? 0;
+    }
+    catch {
+        bytes = 0;
+    }
+    out.bodyBytes = bytes;
+    return out;
+}
+/**
+ * §7.133: 一次 LLM 调用的**统一出口**。
+ *
+ * 三条通路同时写：
+ *   1. ops log（§7.118 的老行为，`LLM_REQUEST` / `LLM_RESPONSE` 单行）
+ *   2. audit 索引行（`llm.trace.index`）→ Edge 面板列出这次调用
+ *   3. 正文 store（`LlmTraceStore`）→ 面板点开时取
+ *
+ * 检测调用（安检 / 分类器）经 `caller` 标出来 —— §7.132 的
+ * `edgeInternalCaller` 是同一个标记体系。**标记的来源是 options**：
+ * adapter 调 `emitTrace` 时把 `options` 传进来，由 `internalCallerOf()`
+ * 读出标记。所以检测调用的 trace 与主对话的 trace 走的是**同一段代码**，
+ * 不存在「检测调用忘了记」的第二套实现。
+ */
+export function emitTrace(sink, kind, tag, trace, caller, extra) {
+    try {
+        // 老通路：ops log（§7.118）—— 保持不变，运维 tail ops log 的习惯不破。
+        sink.logger?.info?.(formatTraceLine(tag, trace));
+        const traceId = sink.nextTraceId?.() ?? nextTraceId();
+        // 正文进 store
+        sink.store?.put(traceId, { kind, ...(caller !== undefined ? { caller } : {}), trace });
+        // 索引行进 audit —— 面板 fold 认这个 kind
+        void sink.log({
+            level: 'info',
+            kind: 'llm.trace.index',
+            source: 'llm-trace',
+            payload: buildTraceIndex(traceId, kind, trace, caller, extra),
+        }).catch(() => { });
+        return traceId;
+    }
+    catch {
+        // 观测失败不拖垮主链路 —— 与本模块既有纪律一致。
+        return undefined;
+    }
+}

package/lib/dsh-adapter/local-llm-adapter.d.ts

@@ -0,0 +1,141 @@
+/**
+ * local-llm-adapter — M4 multi-model + routing.
+ *
+ * Registers one or more provider routes on the shared `ctx.llm`
+ * runtime, all backed by a real OpenAI-compatible `/chat/completions`
+ * endpoint. Defaults to `http://127.0.0.1:8080/v1` (llama.cpp's
+ * `server` binary); the reachable endpoint in this repo is
+ * `http://192.0.2.101:8701/v1`. No in-process mock — every call
+ * leaves the process.
+ *
+ * The wire-protocol parser lives in `./openai-sse.js` so changes to
+ * the SSE framing land in one place and are shared by the cloud
+ * adapter. The body builder flips `stream: true` and merges adapter
+ * defaults (model, temperature) so the upstream server sees the same
+ * shape the dsh agent loop emits.
+ *
+ * @module dsh-edge-agent/local-llm-adapter
+ */
+import type { Context, LoggerService } from '@deepseek-ai/cordis';
+import Schema from '@deepseek-ai/schemastery';
+import { LlmAdapter } from '@deepseek-ai/dsh-llm';
+import type { GenerateOptions, LlmModelInfo, LlmProviderInfo, LlmResolvedModelInfo, StreamChunk } from '@deepseek-ai/dsh-llm';
+export declare const name = "local-llm-adapter";
+export declare const inject: readonly ["llm", "auditLog", "inputGuard"];
+/**
+ * §7.42 (2026-09-05) P0-2: per-session runaway guard. If the local LLM emits
+ * more than this many consecutive REAL tool-call responses (finishKind=
+ * 'tool-calls' with toolCalls.size > 0 — malformed cases are handled by P0-1
+ * above and rewritten to finishKind='stop' before reaching the counter), the
+ * adapter throws `LlmError('MAX_TURNS_EXCEEDED')` to terminate the agent loop.
+ * 20 is conservative: a healthy tool-use turn rarely exceeds 3-5 iterations;
+ * 20 catches runaways without tripping on legitimate long chains.
+ *
+ * §7.47.5 (2026-09-13): shared with cloud-llm-adapter via ./llm-max-turns.ts
+ * so cross-adapter sessions (e.g. classifier fallback LOCAL → CLOUD) keep
+ * a single counter. See llm-max-turns.ts for the rationale.
+ */
+/** Minimal interface our adapter needs from the audit-log service. */
+interface AuditLike {
+    log(entry: {
+        level: 'debug' | 'info' | 'warn' | 'error' | 'security';
+        kind: string;
+        source: string;
+        payload: Record<string, unknown>;
+    }): Promise<unknown>;
+}
+/**
+ * 2026-08-31: input-guard 注入用于清洗孤儿 tool_call。
+ * qwen3 对 orphan tool_call 不像 DeepSeek 那么严格（不会 400），
+ * 但统一清洗可避免 LLM 上下文里出现悬空调用、提升模型行为稳定性。
+ */
+interface InputGuardLike {
+    sanitizeOrphanToolCalls(messages: ReadonlyArray<Record<string, unknown>>, sessionId?: string): {
+        messages: Array<Record<string, unknown>>;
+        orphanCount: number;
+        syntheticInjected: number;
+    };
+}
+/** Minimal duck-typed handle for Cordis `LoggerService`. Used by tests to stub
+ *  logger behavior; `apply()` injects the live `ctx.logger` from Cordis. */
+type LoggerLike = Pick<LoggerService, 'info' | 'warn' | 'error' | 'debug'>;
+export interface Config {
+    /** Provider route ids this adapter owns. */
+    providers: string[];
+    /** OpenAI-compatible endpoint. `/chat/completions` is appended.
+     *
+     *  Undefined/empty means "no local-LLM endpoint configured". §7.171: that is
+     *  no longer "no route at all" — the adapter falls back to DELEGATE mode
+     *  (forward to the host provider), symmetric with `llm.cloud`. Set
+     *  `llm.local.delegate=false` to restore the opt-in semantics (register
+     *  nothing). It must not fall back to a hard-coded port — a default like
+     *  `127.0.0.1:8080` collides with unrelated daemons that listen there
+     *  (observed 2026-10-21: TeleAgent's scheduler daemon owns 8080 and answers
+     *  401 "Missing bearer token"), which turned every turn into a failed
+     *  local-LLM call even though the operator never asked for a local model. */
+    baseUrl?: string;
+    /** Default model id when the request omits one. */
+    defaultModel: string;
+    /** Optional bearer header for an authenticated endpoint.
+     *
+     *  §7.102: the value is now the literal key, not an env-slot name. The
+     *  key lives in config/edge.json (gitignored) and reaches the adapter
+     *  through this field. `apiKeyEnv` is kept as a deprecated alias for
+     *  callers that still pass an env-slot name — it is read from
+     *  process.env when present, but new deployments should use `apiKey`. */
+    apiKey?: string;
+    /** @deprecated Use `apiKey` (literal). Kept so an env-slot name still
+     *  works for a transition period. */
+    apiKeyEnv?: string;
+    /** §7.4? (2026-09-17) LAN minicpm5-2b Jinja2 tojson(ensure_ascii) bug
+     *  workaround: when true, omit `body.tools` from wire request so the
+     *  server template `{% if tools %}` block is never evaluated. Model
+     *  falls back to plain-text tool defs in system prompt's
+     *  <available_tools>. Defaults to false. */
+    stripTools?: boolean;
+    /** §7.87.5 (2026-09-19): disable chain-of-thought for thinking-capable
+     *  models (qwen3.5 / QwQ / DeepSeek-R1). When false (default), the wire
+     *  body gets `chat_template_kwargs={enable_thinking: false}` so the model
+     *  returns final answer directly instead of burning max_tokens on reasoning.
+     *  Pass-through no-op for non-thinking servers. */
+    enableThinking?: boolean;
+    /** §7.106 (2026-10-23): also send `reasoning_effort:"none"` with think-off.
+     *  ollama /v1 honors that dialect; strict gateways 400 unknown params
+     *  (minimax measured). Opt-in per pool via `llm.local.reasoningEffortNone`. */
+    reasoningEffortNone?: boolean;
+    /** §7.171 (2026-11-10): baseUrl 留空时是否走 DELEGATE（转发宿主提供商），
+     *  与 `llm.cloud` 对称。默认 true（`llm.local.delegate` 未写 = 委托）。
+     *
+     *  false = kill switch：回到 opt-in 语义（不注册任何路由），LOCAL 意图
+     *  fail-closed 报错。**文件与本字段任一为 false 即关闭** —— 关闭方向上取
+     *  「最严」，避免任一侧漏配就意外出网。 */
+    delegate?: boolean;
+    /** §7.171: delegate 模式下的显式目标 provider route id（压过宿主选择）。 */
+    delegateProvider?: string;
+    /** §7.171: delegate 模式下的 wire model override（压过宿主选择）。 */
+    delegateModel?: string;
+}
+export declare const Config: Schema<Config>;
+export interface LocalLlmAdapter {
+    readonly providers: string[];
+    stream(options: GenerateOptions): AsyncIterable<StreamChunk>;
+}
+/**
+ * Adapter facade. Owns one real-HTTP inner adapter per configured
+ * provider route so `ctx.llm.registerAdapter([...], this)` can route
+ * any of them through the same instance — keeping the `dispose`
+ * set in lockstep with the registration.
+ */
+export declare class LocalLlmAdapterImpl extends LlmAdapter {
+    private readonly providersList;
+    private readonly innerByProvider;
+    constructor(config: Config, auditLog?: AuditLike, inputGuard?: InputGuardLike, logger?: LoggerLike);
+    get providers(): string[];
+    providerInfo(provider: string): LlmProviderInfo;
+    listModels(provider: string): Promise<readonly LlmModelInfo[]>;
+    resolveModel(provider: string, model: string, signal?: AbortSignal): Promise<LlmResolvedModelInfo>;
+    stream(options: GenerateOptions): AsyncIterable<StreamChunk>;
+}
+export declare function apply(ctx: Context, config: Config): Promise<() => Promise<void>>;
+export {};
+//# sourceMappingURL=local-llm-adapter.d.ts.map

package/lib/dsh-adapter/local-llm-adapter.d.ts.map

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