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

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

@@ -0,0 +1,787 @@
+/**
+ * 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 Schema from '@deepseek-ai/schemastery';
+import { attributionHeaders, LlmAdapter, LlmError } from '@deepseek-ai/dsh-llm';
+import { buildChatCompletionsBody, extractText, iterateSseFrames, sseEventToChunk, sseFinishReason, terminalChunks, } from './openai-sse.js';
+// §7.171: 本地池的 DELEGATE 模式复用云池的转发适配器（同一个类，`poolKind` 区分口径）。
+// cloud-llm-adapter 不 import 本模块 ⇒ 无环。
+import { CloudLlmDelegateAdapterImpl, localPoolTargetCache, } from './cloud-llm-adapter.js';
+import { danglingSecretRefs, formatDanglingSecretRefs, localPool, loadEdgeConfig, } from './edge-config.js';
+import { buildRequestTrace, buildResponseTrace, emitTrace, resolveLlmTraceConfig, } from './llm-trace.js';
+import { getTraceStore, callIdFor } from './llm-trace-store.js';
+import { bumpSessionToolCallCount, MAX_CONSECUTIVE_TOOL_CALLS, resetSessionToolCallCount, } from './llm-max-turns.js';
+import { egressAuditFields, internalCallerOf } from './llm-internal-caller.js';
+import { PRE_SESSION_SENTINEL, sessionIdField } from './session-attribution.js';
+export const name = 'local-llm-adapter';
+export const inject = ['llm', 'auditLog', 'inputGuard'];
+function audit(log, level, kind, payload) {
+    if (!log)
+        return;
+    void log.log({ level, kind, source: 'local-llm-adapter', payload }).catch(() => { });
+}
+export const Config = Schema.object({
+    providers: Schema.array(Schema.string()).default(['local-llm']),
+    // No default on purpose: an unset endpoint must never become a
+    // hard-coded port (the old `127.0.0.1:8080` default collided with
+    // unrelated daemons). §7.171: unset now means DELEGATE — forward to the
+    // host profile's provider, symmetric with `llm.cloud`. The operator opts
+    // into a DIRECT pool with llm.local.baseUrl in config/edge.json (§7.102).
+    baseUrl: Schema.string().description('OpenAI-compatible endpoint base; unset = DELEGATE mode (forward to the host provider, §7.171); set llm.local.delegate=false to leave the route unregistered.'),
+    defaultModel: Schema.string().default('qwen3-4b'),
+    apiKey: Schema.string().description('Optional bearer token for an authenticated endpoint (literal value from config/edge.json).'),
+    apiKeyEnv: Schema.string().description('Deprecated: env-slot name carrying an auth bearer. Prefer apiKey.'),
+    stripTools: Schema.boolean().default(false),
+    // §7.87.5 (2026-09-19): default false — production wants fast answers.
+    // qwen3.5 / QwQ / DeepSeek-R1 will burn max_tokens on reasoning by default.
+    enableThinking: Schema.boolean().default(false),
+    reasoningEffortNone: Schema.boolean().default(false).description('Send reasoning_effort:"none" alongside think-off (ollama dialect; strict gateways 400 it).'),
+    // §7.171: no default on purpose — `undefined` means "not set at this layer".
+    // The effective switch is AND(file `llm.local.delegate`, this field): either
+    // side saying false turns delegation OFF.
+    delegate: Schema.boolean().description('§7.171: baseUrl 留空时转发宿主提供商（DELEGATE）；false = 不注册本地路由（opt-in 语义）。'),
+    delegateProvider: Schema.string().description('§7.171: delegate 模式：显式目标 provider route id。'),
+    delegateModel: Schema.string().description('§7.171: delegate 模式：wire model override（压过宿主选择）。'),
+});
+/**
+ * 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 class LocalLlmAdapterImpl extends LlmAdapter {
+    providersList;
+    innerByProvider;
+    constructor(config, auditLog, inputGuard, logger) {
+        super();
+        this.providersList = [...config.providers];
+        this.innerByProvider = new Map();
+        // An unset endpoint leaves every route without a backend. `apply` keeps
+        // the adapter unregistered in that case; the guard here keeps the
+        // facade honest for direct construction (tests, embedding).
+        const baseUrl = (config.baseUrl ?? '').trim();
+        if (baseUrl.length === 0)
+            return;
+        for (const provider of this.providersList) {
+            this.innerByProvider.set(provider, new RealLocalAdapter(provider, config, baseUrl, auditLog, inputGuard, logger));
+        }
+    }
+    get providers() {
+        return [...this.providersList];
+    }
+    providerInfo(provider) {
+        return { id: provider, name: provider };
+    }
+    listModels(provider) {
+        const inner = this.innerByProvider.get(provider);
+        return inner
+            ? inner.listModels(provider)
+            : Promise.resolve([]);
+    }
+    resolveModel(provider, model, signal) {
+        const inner = this.innerByProvider.get(provider);
+        return inner
+            ? inner.resolveModel(provider, model, signal)
+            : Promise.resolve({ provider, id: model, name: model });
+    }
+    async *stream(options) {
+        const inner = this.innerByProvider.get(options.provider);
+        if (inner === undefined) {
+            throw new LlmError(`local-llm-adapter: unknown provider route "${options.provider}" (registered: ${this.providersList.join(', ')})`, 'UNKNOWN_PROVIDER');
+        }
+        yield* inner.stream(options);
+    }
+}
+/**
+ * Real backend. Mirrors `CloudLlmAdapterImpl` but skips the bearer
+ * header unless `Config.apiKeyEnv` is set (llama.cpp `server` does
+ * not require auth by default). Bound to LAN/loopback endpoints only.
+ */
+class RealLocalAdapter extends LlmAdapter {
+    providerName;
+    baseUrl;
+    defaultModel;
+    apiKey;
+    apiKeyEnv;
+    auditLog;
+    inputGuard;
+    logger;
+    stripTools;
+    enableThinking;
+    /** §7.106: pool-level opt-in for the reasoning_effort:"none" dialect. */
+    reasoningEffortNone;
+    constructor(provider, config, baseUrl, auditLog, inputGuard, logger) {
+        super();
+        this.providerName = provider;
+        this.baseUrl = baseUrl.replace(/\/+$/u, '');
+        this.defaultModel = config.defaultModel;
+        // §7.102: prefer the literal key from config/edge.json; fall back to the
+        // deprecated env-slot lookup so an in-flight migration still authenticates.
+        this.apiKey = config.apiKey;
+        this.apiKeyEnv = config.apiKeyEnv;
+        this.auditLog = auditLog;
+        this.inputGuard = inputGuard;
+        this.logger = logger;
+        this.stripTools = config.stripTools ?? false;
+        // §7.87.5 (2026-09-19): opt-in flag for thinking-capable models.
+        this.enableThinking = config.enableThinking ?? false;
+        this.reasoningEffortNone = config.reasoningEffortNone ?? false;
+    }
+    /** Resolve the bearer token: literal key first, env slot second. */
+    resolveApiKey() {
+        if (this.apiKey !== undefined && this.apiKey.length > 0)
+            return this.apiKey;
+        return this.apiKeyEnv !== undefined ? readApiKey(this.apiKeyEnv) : undefined;
+    }
+    /**
+     * §7.118: 当前生效的 LLM trace 配置。
+     *
+     * 现取而非 apply() 存一份 —— `loadEdgeConfig()` 自带 mtime+size 指纹缓存，
+     * 改了 config/edge.json 立即生效。详见 ./llm-trace.js。
+     */
+    traceConfig() {
+        return resolveLlmTraceConfig(loadEdgeConfig());
+    }
+    /**
+     * §7.118: 详细 request trace → ops log（info 级别，凭据 + PII 脱敏、按字段截断）。
+     * §7.133: 同时落 Edge 面板的**索引行** + **正文**（正文按需拉取）。
+     */
+    traceRequest(sessionId, options, system, messages, rawBody) {
+        try {
+            const cfg = this.traceConfig();
+            if (!cfg.enabled || !cfg.includeRequest)
+                return;
+            const trace = buildRequestTrace({
+                sessionId,
+                provider: options.provider,
+                model: this.defaultModel,
+                baseUrl: this.baseUrl,
+                system,
+                messages,
+                tools: options.tools,
+                // §7.144: 真正发出去的 wire body（含 chat_template_kwargs / reasoning_effort
+                // / 工具 schema …）—— 面板上要能核对「发了什么」，不是只看投影。
+                rawBody,
+                params: { stream: true },
+                config: cfg,
+            });
+            this.emit('REQ', 'local-llm-adapter LLM_REQUEST', trace, options);
+        }
+        catch { /* 观测失败不拖垮主链路 */ }
+    }
+    /**
+     * §7.118: 详细 response trace → ops log。
+     * §7.133: 同时落 Edge 面板的索引行 + 正文。
+     */
+    traceResponse(sessionId, provider, content, toolCalls, finishKind, durationMs, error, options, rawBody) {
+        try {
+            const cfg = this.traceConfig();
+            if (!cfg.enabled || !cfg.includeResponse)
+                return;
+            const trace = buildResponseTrace({
+                sessionId,
+                provider,
+                model: this.defaultModel,
+                durationMs,
+                finishReason: finishKind,
+                content,
+                toolCalls,
+                // §7.144: 完整响应体（正文 + 工具调用 + finish_reason 的组装体）。
+                rawBody,
+                error,
+                config: cfg,
+            });
+            this.emit('RESP', 'local-llm-adapter LLM_RESPONSE', trace, options);
+        }
+        catch { /* 观测失败不拖垮主链路 */ }
+    }
+    /**
+     * §7.133: trace 的统一出口 —— ops log + Edge 面板索引行 + 正文。
+     *
+     * `options` 里有 §7.132 的 `edgeInternalCaller` 标记时，索引行带上
+     * caller，面板据此把「检测调用」（安检 / 分类器）与「主对话出网」分开
+     * 显示。检测调用与主对话走的是**同一段代码** —— 不存在「检测调用忘了
+     * 记」的第二套实现。
+     */
+    emit(kind, tag, trace, options) {
+        const caller = internalCallerOf(options);
+        const sink = {
+            log: (entry) => this.auditLog?.log(entry) ?? Promise.resolve(),
+            logger: this.logger,
+            store: getTraceStore(),
+        };
+        // §7.132 的判据落到索引行：带工具 = 主对话，一件不带 = 内部调用。
+        const tools = options?.tools;
+        emitTrace(sink, kind, tag, trace, caller, {
+            toolCount: Array.isArray(tools) ? tools.length : 0,
+            // §7.134: REQ 与 RESP 共用一个 callId —— 面板据此把两半配成一对。
+            // 键是 `options` 的对象身份：宿主每次 stream() 传新对象，而同一次
+            // 往返的 REQ/RESP 拿到的是**同一个**引用。
+            callId: callIdFor(options),
+        });
+    }
+    get providers() {
+        return [this.providerName];
+    }
+    providerInfo(_provider) {
+        return { id: this.providerName, name: this.providerName };
+    }
+    /**
+     * §7.180: 直连池在模型目录里**如实声明它唯一会跑的那个模型**。
+     *
+     * §7.106 Option A 当初让目录恒空，理由是「local-llm 是隐私管线内部件，
+     * 不是给用户选的」—— 那条理由对**云池**成立（避免误选 cloud-llm/
+     * deepseek-chat，也避免 INVALID_CATALOG），对**本地池**不再成立：边缘
+     * 模式会话本来就该指向本地池，目录里没有它 ⇒ 宿主选择器只能显示
+     * 「请选择模型」（主人 2026-11-11 13:52 实测）。
+     *
+     * 直连池的 wire body 恒用 `this.defaultModel`（`options.model` 只是路由键
+     * `route=`）⇒ 目录里就只声明这一个 id，不多不少。
+     */
+    listModels(_provider) {
+        const id = this.defaultModel.trim();
+        if (id.length === 0)
+            return Promise.resolve([]);
+        // §7.180: 留审计行 —— 「宿主模型目录里 local-llm 声明了什么」是可查证的事实。
+        void this.auditLog?.log({
+            level: 'info',
+            kind: 'llm.local.catalog',
+            source: 'local-llm-adapter',
+            payload: { provider: this.providerName, model: id, mode: 'direct' },
+        }).catch(() => { });
+        return Promise.resolve([{ provider: this.providerName, id, name: id }]);
+    }
+    resolveModel(_provider, model) {
+        // §7.40 (2026-09-04): see listModels comment — contextWindow must also
+        // surface through resolveModel so the runtime normalises it onto the
+        // active session's `info.context.contextWindow`. Without this the
+        // adapter's advertised contextWindow is ignored.
+        return Promise.resolve({
+            provider: this.providerName,
+            id: model,
+            name: model,
+            context: { contextWindow: 16384 },
+        });
+    }
+    async *stream(options) {
+        const url = `${this.baseUrl}/chat/completions`;
+        // 2026-08-31：input-guard 清洗孤儿 tool_call。
+        let sanitizedMessages = options.messages;
+        if (this.inputGuard) {
+            const result = this.inputGuard.sanitizeOrphanToolCalls(options.messages, options.sessionId);
+            sanitizedMessages = result.messages;
+        }
+        // §7.4? (2026-09-17) LAN minicpm5-2b Jinja2 `tojson(ensure_ascii)` bug:
+        // when stripTools is on, set `tools: undefined` in the spread so the
+        // openai-sse.ts guard skips `body.tools` assignment and the server
+        // template's `{% if tools %}` block is skipped. Default false → wire
+        // body unchanged for unaffected servers/models.
+        const wireOptions = this.stripTools
+            ? { ...options, tools: undefined, messages: sanitizedMessages }
+            : { ...options, messages: sanitizedMessages };
+        // §7.106 (2026-10-23): the reasoning_effort dialect is POOL-CONFIGURED,
+        // not always-on. ollama drops chat_template_kwargs and bills reasoning
+        // into max_tokens (content-starved model-detect → json-parse-fail), so
+        // ollama pools set llm.local.reasoningEffortNone=true; strict gateways
+        // 400 the unknown param (minimax measured) and must leave it false.
+        const body = buildChatCompletionsBody(wireOptions, this.defaultModel, undefined, this.enableThinking, this.reasoningEffortNone);
+        const headers = {
+            'content-type': 'application/json',
+            'accept': 'text/event-stream',
+            ...attributionHeaders(),
+        };
+        const apiKey = this.resolveApiKey();
+        if (apiKey !== undefined)
+            headers.authorization = `Bearer ${apiKey}`;
+        const promptText = sanitizedMessages.map((m) => `${m.role}:${extractText(m.content)}`).join('\n');
+        const promptLen = promptText.length;
+        // §7.54.7 (2026-09-14): capture wire-system (passed to
+        // buildChatCompletionsBody) for ops log so operator can see what system
+        // prompt actually went out to local LLM. Truncate to first 200 chars to
+        // keep log lines readable; full text is in the request body which
+        // DSH_EDGE_LOG_LEVEL=debug exposes via LLM_MESSAGES.
+        const wireSystem = typeof options.system === 'string' ? options.system : '';
+        const systemLen = wireSystem.length;
+        const systemPreview = systemLen > 0 ? wireSystem.slice(0, 200).replace(/\s+/g, ' ') : '';
+        const start = Date.now();
+        // §7.46.1 (2026-09-11): ops log 让 TUI 路径调哪个 local LLM / 多久 / 多少
+        // token 在 ops log 里可见。配合 realm-skill-bridge pre-step + tool allow
+        // 形成完整 trace。
+        const sessionId = options.sessionId ?? PRE_SESSION_SENTINEL;
+        try {
+            // §7.54 (2026-09-14): show the wire body model (`this.defaultModel`,
+            // which buildChatCompletionsBody uses) instead of `options.model` (which
+            // model-router may overwrite to the provider route id, e.g.
+            // 'local-llm'). Operators reading the ops log expect to see the actual
+            // model name qwen3.7-plus, not the routing key. `route=${options.model}`
+            // preserves the upstream-visible routing key for diagnosis.
+            this.logger?.info?.(`[local-llm-adapter] LLM call start sessionId=${sessionId} provider=${options.provider} model=${this.defaultModel} route=${options.model} messageCount=${sanitizedMessages.length} promptLen=${promptLen} systemLen=${systemLen}${systemPreview ? ` systemPreview="${systemPreview}${systemLen > 200 ? '...' : ''}"` : ''} baseUrl=${this.baseUrl}`);
+        }
+        catch { /* debug only */ }
+        // 2026-09-02: per-call request/response body logging to ops log at
+        // debug level (mirrors cloud-llm-adapter). LOCAL content never
+        // leaves the device, so this is purely a local-debug aid; CLOUD
+        // prompts are pre-sanitized by input-guard before egress. Set
+        // `DSH_EDGE_LOG_LEVEL=info` to suppress bodies entirely.
+        this.logger?.debug?.(`[local-llm-adapter] LLM_REQUEST provider=${options.provider} model=${options.model} messageCount=${sanitizedMessages.length} promptLen=${promptLen}`);
+        this.logger?.debug?.(`[local-llm-adapter] LLM_MESSAGES ${JSON.stringify({ messages: sanitizedMessages })}`);
+        // §7.118: 详细 request trace —— 逐条 message 的角色 / 正文 / 工具回显，
+        // 经凭据 + PII 脱敏、按字段截断后写进 ops log（info 级别，默认可见）。
+        this.traceRequest(sessionId, options, wireSystem, sanitizedMessages, body);
+        // §7.147: 这条**开始**行必须带 sessionId —— 否则它落全局桶，Edge 面板的
+        // 路由面板永远说不清「这一轮」（实测：本仓 640 条 `llm.local.start` 无一带
+        // sessionId，而同一调用的 `llm.local.end` 带了 483/569 —— 同一个调用，两半
+        // 归属不一致）。
+        //
+        // 用 `options.sessionId`（原始值）而不是上面那个 `sessionId` 变量：后者在
+        // 无会话时是 `'<pre-session>'` **哨兵**，写进载荷会造出一个不存在的桶，
+        // 把这些行从所有真实会话的视图里藏掉（比全局可见更糟）。哨兵在这里被判
+        // 成「没有会话」⇒ 不写这个键 ⇒ 归全局桶。
+        audit(this.auditLog, 'info', 'llm.local.start', { ...sessionIdField(options.sessionId), provider: options.provider, model: this.defaultModel, route: options.model, messageCount: sanitizedMessages.length, promptLen, baseUrl: this.baseUrl, ...egressAuditFields(options) });
+        // §7.106 (2026-10-23): ONE retry on transport-level failure with a short
+        // backoff. The LAN ollama blips (observed 11:35:09: `fetch failed` mid
+        // agent-turn while the same server answered fine minutes before/after —
+        // a single 2.6s connection drop killed the whole turn). HTTP error
+        // responses are NOT retried here (non-ok path untouched), and a caller
+        // abort never retries — the signal check keeps AbortError semantics.
+        const attempt = () => fetch(url, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify(body),
+            signal: options.signal,
+        });
+        let response;
+        try {
+            response = await attempt();
+        }
+        catch (err) {
+            const aborted = options.signal?.aborted === true || err?.name === 'AbortError';
+            if (aborted) {
+                // §7.148: 错误行同样要带 sessionId —— 它们与 `llm.local.start` 是同一次
+                // 调用的两半（实测：本仓 43 条 `llm.local.http_error` / 22 条
+                // `llm.local.network_error` / 4 条 `llm.local.network_retry` 无一带
+                // sessionId）。失败行落全局桶 ⇒ Edge 面板看不到「哪一轮失败了」。
+                audit(this.auditLog, 'error', 'llm.local.network_error', { ...sessionIdField(options.sessionId), provider: options.provider, model: this.defaultModel, route: options.model, durationMs: Date.now() - start, error: err?.message ?? String(err), ...egressAuditFields(options) });
+                throw err;
+            }
+            audit(this.auditLog, 'warn', 'llm.local.network_retry', { ...sessionIdField(options.sessionId), provider: options.provider, model: this.defaultModel, route: options.model, error: String(err?.message ?? err), afterMs: Date.now() - start });
+            await new Promise(resolve => setTimeout(resolve, 800));
+            try {
+                response = await attempt();
+            }
+            catch (err2) {
+                audit(this.auditLog, 'error', 'llm.local.network_error', { ...sessionIdField(options.sessionId), provider: options.provider, model: this.defaultModel, route: options.model, durationMs: Date.now() - start, error: err2?.message ?? String(err2), afterRetry: true, ...egressAuditFields(options) });
+                throw err2;
+            }
+        }
+        if (!response.ok) {
+            const durationMs = Date.now() - start;
+            let respBody = '';
+            try {
+                respBody = await response.text();
+            }
+            catch { /* ignore */ }
+            audit(this.auditLog, 'error', 'llm.local.http_error', { ...sessionIdField(options.sessionId), provider: options.provider, model: this.defaultModel, route: options.model, status: response.status, durationMs, respBody: respBody.slice(0, 500), ...egressAuditFields(options) });
+            // 2026-10-21: 401/403 almost always means "this endpoint wants a
+            // bearer" (or "the port belongs to something else entirely"). Name the
+            // knob so the operator does not have to reverse-engineer the envelope.
+            const authHint = response.status === 401 || response.status === 403
+                ? ` — the endpoint requires an Authorization: Bearer token; set llm.local.keyRef`
+                    + ` in config/edge.json to the name of a key under "secrets"`
+                    + `${this.apiKeyEnv === undefined ? '' : `, or point apiKeyEnv at the env slot <${this.apiKeyEnv}>`}`
+                    + `, and confirm ${this.baseUrl} is really your local LLM server.`
+                : '';
+            throw new LlmError(`local-llm-adapter (${this.providerName}): HTTP ${response.status}: ${respBody.slice(0, 200)}${authHint}`, 'PROVIDER_ERROR');
+        }
+        // 2026-09-03 §7.34.2 fix: defer `block-start` until the first text-delta.
+        // 之前无条件 yield block-start → 如果 LLM 返回 0 token（completion_tokens=0
+        // 但 finish_reason='stop'，llama.cpp 在 24 条 message / 2535 tokens prompt
+        // 下实测会发生），BlockAssembler 拿到一个未关闭的 text block + finish，
+        // 状态机卡住、agent-loop 永远等不到 block-end。
+        //
+        // 实测数据：webui chat "查询下密盒有哪些图片文件"（17:20:40 +08:00），
+        // 远端 llama.cpp 192.0.2.102:11017 返回 completion_tokens=0 finish=stop
+        // （254ms），dsh 进入 idle 4+ 分钟无响应。
+        //
+        // 修复：block-start 改为 lazy（首次 text-delta 前 yield 一次），empty stream
+        // 不再 yield block-start → BlockAssembler 不创建 orphan block → finish
+        // 正常传递 → agent-loop 状态机清零。
+        let blockStartYielded = false;
+        const yieldBlockStartOnce = () => {
+            if (blockStartYielded)
+                return false;
+            blockStartYielded = true;
+            return true;
+        };
+        let assembledText = '';
+        let finishKind;
+        const toolCalls = new Map();
+        let sawText = false;
+        let sawToolCall = false;
+        const throwOnWire = (message) => {
+            throw new LlmError(`local-llm-adapter (${this.providerName}): SSE stream interrupted: ${message}`, 'PROVIDER_ERROR');
+        };
+        let wireError;
+        try {
+            for await (const event of iterateSseFrames(response, throwOnWire)) {
+                const reason = sseFinishReason(event);
+                if (reason !== undefined) {
+                    finishKind = reason;
+                    continue;
+                }
+                const result = sseEventToChunk(event, toolCalls);
+                if (result === null)
+                    continue;
+                if (result.chunk.type === 'text-delta') {
+                    // §7.34.2: yield block-start lazily before the first text-delta
+                    if (yieldBlockStartOnce()) {
+                        yield { type: 'block-start', index: 0, blockType: 'text' };
+                    }
+                    assembledText += result.chunk.text;
+                    sawText = result.sawText;
+                }
+                else if (result.chunk.type === 'tool-call-delta') {
+                    sawToolCall = result.sawToolCall;
+                }
+                yield result.chunk;
+            }
+        }
+        catch (err) {
+            wireError = err?.message ?? String(err);
+            throw err;
+        }
+        finally {
+            const durationMs = Date.now() - start;
+            // §7.46.1: ops log done 行
+            // §7.54 (2026-09-14): show defaultModel (= wire body) for consistency
+            // with start line; options.model may be the routing key 'local-llm'.
+            try {
+                this.logger?.info?.(`[local-llm-adapter] LLM call done sessionId=${sessionId} provider=${options.provider} model=${this.defaultModel} route=${options.model} durationMs=${durationMs} resultLen=${assembledText.length} toolCallCount=${toolCalls.size} finishKind=${finishKind ?? 'unknown'}${wireError !== undefined ? ` wireError=${wireError}` : ''}`);
+            }
+            catch { /* debug only */ }
+            audit(this.auditLog, 'info', 'llm.local.end', { sessionId: options.sessionId,
+                provider: options.provider,
+                model: this.defaultModel,
+                route: options.model,
+                durationMs,
+                promptLen,
+                resultLen: assembledText.length,
+                toolCallCount: toolCalls.size,
+                finishKind,
+                sawText,
+                sawToolCall,
+                ...(wireError !== undefined ? { wireError } : {}),
+                ...egressAuditFields(options),
+            });
+            // 2026-09-02: dump response summary + full text to the ops log at
+            // debug level (mirrors cloud-llm-adapter).
+            this.logger?.debug?.(`[local-llm-adapter] LLM_RESPONSE provider=${options.provider} durationMs=${durationMs} resultLen=${assembledText.length} finishKind=${finishKind ?? 'unknown'}`);
+            this.logger?.debug?.(`[local-llm-adapter] LLM_RESPONSE_TEXT ${JSON.stringify({ text: assembledText })}`);
+            // §7.118: 详细 response trace（正文 + tool calls + finish reason）。
+            this.traceResponse(sessionId, options.provider, assembledText, [...toolCalls.values()].map((c) => ({ id: c.id, name: c.name, arguments: c.arguments })), finishKind, durationMs, wireError, options, 
+            // §7.144: 完整响应体 —— 上游回来的语义全文（正文 + 工具调用 + 结束原因）。
+            {
+                content: assembledText,
+                tool_calls: [...toolCalls.values()].map((c) => ({ id: c.id, name: c.name, arguments: c.arguments })),
+                finish_reason: finishKind ?? 'unknown',
+                ...(wireError !== undefined ? { wire_error: wireError } : {}),
+            });
+        }
+        // §7.42 (2026-09-05) P0-1: malformed-tool-call detection.
+        // qwen3-4b-instruct-2507 @ OpenAI-compatible endpoints sometimes emit
+        // ~12 bytes of XML tag fragments (e.g. `\n<think>\n`) as plain-text
+        // content while setting finish_reason=tool_calls. Two patterns observed:
+        //
+        // Pattern A (rare, ~1%): toolCalls.size === 0, no real tool call accumulated.
+        //   Agent loop sees "tool-calls" but nothing to dispatch -> runaway (152
+        //   iterations observed in tui-probe-1). Fix: rewrite finishKind='stop'.
+        //
+        // Pattern B (dominant, ~99%): toolCalls.size >= 1, real tool call also emitted.
+        //   Agent loop dispatches the tool call, but the XML fragment text confuses
+        //   the model -> loop retries a few times then terminates (5 iterations, 70s
+        //   observed in p0-local test). Fix: strip the XML fragment from assembledText
+        //   so it doesn't pollute the session context, but let the tool call proceed.
+        //
+        // Both patterns logged at WARN + audit for ops visibility.
+        const MALFORMED_TOOL_CALL_TEXT_RE = /^[\s<>\/a-z_]{0,30}$/u;
+        if (finishKind === 'tool-calls' &&
+            assembledText.length > 0 &&
+            assembledText.length <= 30 &&
+            MALFORMED_TOOL_CALL_TEXT_RE.test(assembledText)) {
+            const hasRealToolCalls = toolCalls.size > 0;
+            audit(this.auditLog, 'warn', 'llm.local.malformed_tool_call', { sessionId: options.sessionId,
+                provider: options.provider,
+                model: options.model,
+                resultLen: assembledText.length,
+                assembledTextPreview: assembledText.slice(0, 100),
+                messageCount: sanitizedMessages.length,
+                toolCallCount: toolCalls.size,
+                pattern: hasRealToolCalls ? 'B' : 'A',
+            });
+            this.logger?.warn?.(`[local-llm-adapter] malformed tool-call response detected (pattern=${hasRealToolCalls ? 'B' : 'A'}, toolCallCount=${toolCalls.size}, text=${JSON.stringify(assembledText.slice(0, 40))})`);
+            if (!hasRealToolCalls) {
+                // Pattern A: no real tool call -> rewrite to stop, loop terminates
+                finishKind = 'stop';
+                sawToolCall = false;
+            }
+            else {
+                // Pattern B: real tool call present -> strip XML fragment text, let tool proceed
+                // Note: text-delta chunks already yielded, can't un-yield. But we clear
+                // assembledText so subsequent context doesn't include the fragment.
+                assembledText = '';
+                sawText = false;
+            }
+        }
+        // §7.42 (2026-09-05) P0-2: per-session max-turns guard.
+        // If the local LLM keeps returning tool-calls without making progress
+        // (no text content, no stop/length finish), bound the resource usage
+        // by throwing after MAX_CONSECUTIVE_TOOL_CALLS consecutive tool-call
+        // responses. The counter resets on stop/length (agent loop terminates
+        // naturally) or on text-bearing tool-call responses (progress signal).
+        //
+        // Trigger: finishKind === 'tool-calls' && !sawText (no text content).
+        //   - Pattern B malformed (P0-1 above) sets assembledText='' and sawText=false,
+        //     so it also increments this counter — correct, since it's not making progress.
+        //   - Real tool-call with text (e.g. model explains what it's doing) does NOT
+        //     increment — that's a progress signal.
+        //
+        // Session tracking via shared module (./llm-max-turns.ts). Cross-adapter
+        // sessions keep a single counter so e.g. classifier fallback LOCAL → CLOUD
+        // doesn't reset the runaway count.
+        if (finishKind === 'tool-calls') {
+            if (!sawText) {
+                const consecutiveCount = bumpSessionToolCallCount(options.sessionId);
+                const sessionKeyForLog = typeof options.sessionId === 'string' && options.sessionId.length > 0
+                    ? options.sessionId
+                    : 'default';
+                if (consecutiveCount > MAX_CONSECUTIVE_TOOL_CALLS) {
+                    audit(this.auditLog, 'warn', 'llm.local.max_turns_exceeded', {
+                        provider: options.provider,
+                        model: options.model,
+                        sessionId: sessionKeyForLog,
+                        consecutiveCount,
+                    });
+                    this.logger?.error?.(`[local-llm-adapter] per-session max-turns exceeded (session=${sessionKeyForLog}, count=${consecutiveCount}/${MAX_CONSECUTIVE_TOOL_CALLS})`);
+                    // Reset counter so next call starts fresh (agent loop may retry).
+                    resetSessionToolCallCount(options.sessionId);
+                    throw new LlmError(`local-llm-adapter (${this.providerName}): per-session max-turns exceeded (count=${consecutiveCount})`, 'MAX_TURNS_EXCEEDED');
+                }
+            }
+            else {
+                // Tool-call response with text content -> progress, reset counter.
+                resetSessionToolCallCount(options.sessionId);
+            }
+        }
+        else if (finishKind === 'stop' || finishKind === 'length') {
+            // Natural termination -> reset counter.
+            resetSessionToolCallCount(options.sessionId);
+        }
+        yield* terminalChunks(sawText, assembledText, toolCalls, finishKind, sawToolCall);
+    }
+}
+function readApiKey(slot) {
+    if (typeof process === 'undefined' || !process.env)
+        return undefined;
+    const value = process.env[slot];
+    if (typeof value !== 'string' || value.length === 0)
+        return undefined;
+    return value;
+}
+/**
+ * §7.171 (2026-11-10): DELEGATE mode for the local pool.
+ *
+ * The local pool has no endpoint of its own ⇒ forward every request to the
+ * host provider (the model the operator picked in the host profile), exactly
+ * like `llm.cloud`'s delegate mode. The implementation is the SAME class as
+ * the cloud pool's (`CloudLlmDelegateAdapterImpl`) with `poolKind='local'` —
+ * one forwarding mechanism, one place to fix bugs, and the privacy口径
+ * difference is a single switch:
+ *
+ *   - `'local'` ⇒ **no trimming, no scrubbing** (the LOCAL 口径: 带全部历史).
+ *     The request carries the `LOCAL_POOL_FORWARD_MARKER` so the host-side
+ *     `host-egress-guard` lets it through untouched.
+ *   - `'cloud'` ⇒ §7.131 trimming (cloud-segment history only) + scrubbing.
+ *
+ * `egress` is passed as `undefined` for the local pool: the delegate only
+ * applies it when `poolKind === 'cloud'`, and leaving the guard unconstructed
+ * makes "the local pool never trims" structural rather than conditional.
+ */
+async function applyDelegate(ctx, config, pool) {
+    const auditLog = ctx.auditLog;
+    const inputGuard = ctx.inputGuard;
+    const logger = ctx.logger;
+    const llm = ctx.llm;
+    const accessors = {
+        llm: llm,
+        // soft dep: dsh-base absent (minimal graphs) → undefined, the probe then
+        // skips to the live-route step. Same read as cloud-llm-adapter.
+        getAgentDefaultModel: () => {
+            try {
+                return ctx.get?.('agentDefaultModel');
+            }
+            catch {
+                return undefined;
+            }
+        },
+    };
+    const delegateConfig = {
+        // Own route ids — the recursion guard excludes them from the probe's
+        // candidate set (§7.171: both own pools exclude each other).
+        providers: config.providers,
+        delegateProvider: pool.delegateProvider,
+        delegateModel: pool.delegateModel,
+        delegateEnabled: true,
+    };
+    const delegate = new CloudLlmDelegateAdapterImpl(delegateConfig, accessors, auditLog, inputGuard, logger, undefined, // egress: the local pool never trims (§7.131 asymmetry)
+    'local', // poolKind: LOCAL 口径 —— 带全部历史 + 不脱敏
+    // §7.180: 共享的委托目标缓存 —— wire（stream）、模型目录（listModels）
+    // 与会话补钉（input-guard）读同一份目标 ⇒ 界面上写的 model id 就是
+    // 真正会跑的那个。
+    localPoolTargetCache);
+    // §7.100 hot-reload parity: host route churn (pi-ai replace / adapter
+    // install-remove) → drop the cached probe target so the next call re-probes.
+    const offAdaptersUpdated = typeof ctx.on === 'function'
+        ? ctx.on('llm/adapters-updated', () => { delegate.invalidateTopology(); })
+        : undefined;
+    ctx.logger?.info?.(`[local-llm-adapter] DELEGATE mode (llm.local.baseUrl empty) — forwarding to the host provider `
+        + `for providers: ${config.providers?.join(', ')}`);
+    let registration;
+    try {
+        registration = llm.registerAdapter(config.providers, delegate);
+    }
+    catch (err) {
+        // A user-defined pi-ai route literally named 'local-llm' wins the name;
+        // that live route legitimately IS the local pool then. Degrade loudly
+        // instead of crashing the whole bundle (mirrors cloud-llm-adapter).
+        const isDuplicate = err?.code === 'DUPLICATE_ADAPTER'
+            || String(err?.message ?? err).includes('DUPLICATE_ADAPTER')
+            || String(err?.message ?? err).includes('already has an adapter');
+        if (isDuplicate) {
+            logger?.error?.(`[local-llm-adapter] DUPLICATE_ADAPTER on ${config.providers.join(',')}; host route owns it, edge adapter stands down`);
+            auditLog?.log({
+                level: 'security',
+                kind: 'llm.local.registration.duplicate',
+                source: 'local-llm-adapter',
+                payload: {
+                    providers: config.providers,
+                    mode: 'delegate',
+                    error: String(err?.message ?? err),
+                },
+            }).catch(() => { });
+            offAdaptersUpdated?.();
+            return async () => { };
+        }
+        throw err;
+    }
+    ctx.logger?.info?.('[local-llm-adapter] Adapter registered successfully');
+    return async () => {
+        registration();
+        offAdaptersUpdated?.();
+    };
+}
+export async function apply(ctx, config) {
+    ctx.logger?.info?.(`[local-llm-adapter] apply() called with providers: ${config.providers?.join(', ')}`);
+    // §7.102: the effective pool comes from config/edge.json. The cordis
+    // patch row no longer carries any local-LLM config (it used to read
+    // process.env.DSH_EDGE_LOCAL_LLM_*, which the desktop GUI never had).
+    const pool = localPool();
+    // The cordis config, when present, wins over the file (a profile that
+    // still passes an explicit baseUrl keeps working).
+    const baseUrl = (typeof config.baseUrl === 'string' && config.baseUrl.trim().length > 0
+        ? config.baseUrl
+        : pool.baseUrl ?? '').trim();
+    // §7.171 (2026-11-10): the local-LLM route has TWO modes now, symmetric
+    // with `llm.cloud`:
+    //
+    //   - DIRECT  : `llm.local.baseUrl` configured → own OpenAI-compatible pool
+    //               (unchanged behaviour, the key in `llm.local.keyRef` is used).
+    //   - DELEGATE: `llm.local.baseUrl` empty → forward to the host provider
+    //               (the model the operator picked in the host profile), exactly
+    //               like `llm.cloud`'s delegate mode. Credentials belong to the
+    //               host adapter, not to us.
+    //
+    // Before §7.171, "no endpoint" meant "register NOTHING" (the 2026-10-21
+    // opt-in semantics): the model registry never offered `local-llm`, the model
+    // router could not select it, and the internal intent/guard stages stayed on
+    // their keyword/regex tier instead of burning a request against whatever
+    // happens to own the default port. That behaviour is still reachable — it is
+    // now the explicit kill switch `llm.local.delegate=false`.
+    //
+    // Why the default flipped: `llm.cloud` already delegates to the host
+    // provider when it has no endpoint (§7.100), so a deployment that never
+    // configured `llm.local` ended up with a working CLOUD route and a dead
+    // LOCAL route — the asymmetry surprised operators ("cloud works, local
+    // doesn't"). §7.171 makes the two pools symmetric.
+    const delegateEnabled = pool.delegate !== false && config.delegate !== false;
+    if (baseUrl.length === 0) {
+        if (!delegateEnabled) {
+            ctx.logger?.info?.('[local-llm-adapter] no endpoint configured and delegation disabled — '
+                + 'the local-LLM route stays off (opt-in semantics). '
+                + 'Set llm.local.baseUrl in config/edge.json for a direct pool, '
+                + 'or drop llm.local.delegate=false to delegate to the host provider.');
+            return async () => { };
+        }
+        return applyDelegate(ctx, config, pool);
+    }
+    // §7.154: a keyRef that names a slot that is not there leaves the pool
+    // with NO credential. The local pool always uses its key, so this is
+    // always worth saying — and it must be said AT BOOT: otherwise the
+    // operator finds out at the first request, long after the edit that
+    // broke it. (DELEGATE mode returns above: there the credential belongs to
+    // the host adapter, not to us.)
+    {
+        const dangling = danglingSecretRefs().filter((r) => r.field.startsWith('llm.local'));
+        if (dangling.length > 0) {
+            ctx.logger?.error?.(`[local-llm-adapter] 配置里的密钥引用指向不存在的槽位：${formatDanglingSecretRefs(dangling)}`
+                + ` —— 本地池没有凭据，请求会以 MISSING_CREDENTIAL 失败`);
+        }
+    }
+    // Fold the file-derived pool into the config the adapter actually uses.
+    //
+    // Precedence: an explicit cordis config value wins, then the file, then the
+    // Schema default. The Schema default is already applied to `config` by the
+    // loader, so we cannot use it to detect "the operator did not configure a
+    // model" — that is why the file is consulted before falling back to the
+    // plugin's own default string.
+    const effective = {
+        ...config,
+        baseUrl,
+        defaultModel: pool.model ?? config.defaultModel,
+        apiKey: config.apiKey ?? pool.apiKey,
+        stripTools: config.stripTools ?? pool.stripTools,
+        enableThinking: config.enableThinking ?? pool.enableThinking,
+        // OR-fold: the Schema default (false) is already applied to `config` by
+        // the loader, so `??` would never let the file win — either source may
+        // opt in to the ollama dialect (§7.102 "file is the source of truth"
+        // doctrine, applied where a boolean default hides "unset").
+        reasoningEffortNone: config.reasoningEffortNone === true || pool.reasoningEffortNone === true,
+    };
+    const auditLog = ctx.auditLog;
+    // 2026-08-31: input-guard 可选注入；DSH_EDGE_INPUT_GUARD=false 或 plugin
+    // 启动顺序导致 inputGuard 未就绪时降级为不洗（保持旧行为）。
+    const inputGuard = ctx.inputGuard;
+    const logger = ctx.logger;
+    const adapter = new LocalLlmAdapterImpl(effective, auditLog, inputGuard, logger);
+    const llm = ctx.llm;
+    ctx.logger?.info?.(`[local-llm-adapter] Registering adapter for providers: ${config.providers?.join(', ')}`);
+    const registration = llm.registerAdapter(config.providers, adapter);
+    ctx.logger?.info?.(`[local-llm-adapter] Adapter registered successfully`);
+    return async () => {
+        registration();
+    };
+}