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

package/lib/dsh-adapter/td-bus.js

@@ -0,0 +1,196 @@
+/**
+ * td-bus — threat detection bus.
+ *
+ * Phase D: real threat-level state machine. Subscribes to high-volume
+ * audit events and raises a threat level when patterns indicate abuse.
+ * The http-api plugin reads `getThreatLevel()` and blocks incoming
+ * `/v1/chat` requests when the level reaches the configured block
+ * threshold (default: 'critical', env DSH_EDGE_TD_BLOCK_LEVEL).
+ *
+ * Phase D decision matrix (frequency-driven):
+ *   requests/min in window   threat level
+ *   ≥ thresholds.cloud...    elevated
+ *   ≥ 2 × thresholds...      high
+ *   ≥ 4 × thresholds...      critical  ← blockLevel default
+ *
+ * Other streams (failed-sanitization streak, permission-denied streak)
+ * are reserved for future escalation; Phase D only ships the cloud-
+ * requests-per-minute counter.
+ *
+ * @module dsh-edge-agent/td-bus
+ */
+import { Service } from '@deepseek-ai/cordis';
+import Schema from '@deepseek-ai/schemastery';
+import { loadEdgeConfig } from './edge-config.js';
+export const name = 'td-bus';
+export const inject = ['auditLog', 'privacyPolicy'];
+export const Config = Schema.object({
+    windowSeconds: Schema.natural().default(60),
+    // §7.102: cloudRequestsPerMinute / blockLevel carry no Schema default so
+    // apply()'s config/edge.json (threat.*) fill can tell "row omitted it"
+    // from "row pinned it" (the full patch pins 8 deliberately). The
+    // constructor keeps the ?? 20 / ?? 'critical' literals as last resort.
+    thresholds: Schema.object({
+        cloudRequestsPerMinute: Schema.natural(),
+        failedSanitizationStreak: Schema.natural().default(3),
+        permissionDeniedStreak: Schema.natural().default(5),
+    }),
+    blockLevel: Schema.union(['elevated', 'high', 'critical']),
+});
+export class TdBusServiceImpl extends Service {
+    windowMs;
+    cloudThreshold;
+    // Concrete union: the constructor's `?? 'critical'` guarantees a value
+    // even though the Config field is optional (§7.102 fill chain).
+    blockLevel;
+    currentLevel = 'normal';
+    /** When set, recomputeLevel() will not drop below this floor. Set by
+     *  escalate(); cleared only when the sliding window fully decays. */
+    stickyLevel = null;
+    /** Sliding-window timestamps of cloud requests. */
+    cloudHits = [];
+    listeners = new Map();
+    constructor(ctx, config) {
+        super(ctx, 'tdBus');
+        this.windowMs = (config?.windowSeconds ?? 60) * 1000;
+        this.cloudThreshold = config?.thresholds.cloudRequestsPerMinute ?? 20;
+        this.blockLevel = config?.blockLevel ?? 'critical';
+    }
+    /** Recompute threat level from the current window. Called after each
+     *  recordCloudRequest() and from getThreatLevel(). Decay: cloudHits
+     *  older than windowMs are shifted out first, so the count reflects
+     *  only fresh events. */
+    recomputeLevel() {
+        const now = Date.now();
+        while (this.cloudHits.length > 0 && now - this.cloudHits[0] > this.windowMs) {
+            this.cloudHits.shift();
+        }
+        const count = this.cloudHits.length;
+        let next = 'normal';
+        if (count >= this.cloudThreshold * 4)
+            next = 'critical';
+        else if (count >= this.cloudThreshold * 2)
+            next = 'high';
+        else if (count >= this.cloudThreshold)
+            next = 'elevated';
+        // Honor a manual sticky escalation: don't drop below it until the
+        // operator explicitly resets (no API for reset in Phase D).
+        if (this.stickyLevel) {
+            const order = { normal: 0, elevated: 1, high: 2, critical: 3 };
+            if (order[this.stickyLevel] > order[next])
+                next = this.stickyLevel;
+        }
+        if (next !== this.currentLevel) {
+            const prev = this.currentLevel;
+            this.currentLevel = next;
+            try {
+                const auditLog = this.ctx?.auditLog;
+                auditLog?.log?.({
+                    level: next === 'critical' ? 'security' : 'warn',
+                    kind: 'td-bus.escalated',
+                    source: 'td-bus',
+                    payload: { from: prev, to: next, count, threshold: this.cloudThreshold },
+                })?.catch?.(() => { });
+            }
+            catch { /* ignore */ }
+        }
+    }
+    getThreatLevel() {
+        // Each call triggers a re-decay so level reflects current window even
+        // when no fresh traffic has come in (e.g. 60s after a burst).
+        this.recomputeLevel();
+        return this.currentLevel;
+    }
+    on(action, listener) {
+        let set = this.listeners.get(action);
+        if (!set) {
+            set = new Set();
+            this.listeners.set(action, set);
+        }
+        set.add(listener);
+        return () => { set.delete(listener); };
+    }
+    escalate(reason) {
+        const prev = this.currentLevel;
+        this.currentLevel = 'critical';
+        this.stickyLevel = 'critical';
+        // Fire all registered listeners on manual escalation — operators
+        // explicitly want upstream plugins (secure-bridge, http-api) to react.
+        for (const set of this.listeners.values()) {
+            for (const fn of set) {
+                try {
+                    fn();
+                }
+                catch { /* ignore listener faults */ }
+            }
+        }
+        try {
+            const auditLog = this.ctx?.auditLog;
+            auditLog?.log?.({
+                level: 'security',
+                kind: 'td-bus.escalated',
+                source: 'td-bus',
+                payload: { from: prev, to: 'critical', reason },
+            })?.catch?.(() => { });
+        }
+        catch { /* ignore */ }
+    }
+    recordCloudRequest() {
+        this.cloudHits.push(Date.now());
+        this.recomputeLevel();
+    }
+    reset(reason) {
+        const prev = this.currentLevel;
+        this.stickyLevel = null;
+        this.cloudHits.length = 0;
+        this.currentLevel = 'normal';
+        try {
+            const auditLog = this.ctx?.auditLog;
+            auditLog?.log?.({
+                level: 'info',
+                kind: 'td-bus.reset',
+                source: 'td-bus',
+                payload: { from: prev, to: 'normal', reason },
+            })?.catch?.(() => { });
+        }
+        catch { /* ignore */ }
+    }
+    /** Phase D: helper for http-api to decide whether to deny the request.
+     *  Returns true iff current level is at or above the configured blockLevel. */
+    shouldBlock() {
+        const order = { normal: 0, elevated: 1, high: 2, critical: 3 };
+        return order[this.getThreatLevel()] >= order[this.blockLevel];
+    }
+}
+export async function apply(ctx, config) {
+    // §7.102: the thresholds come from config/edge.json (threat.*). The
+    // cordis patch row no longer reads process.env — the desktop GUI never
+    // had those variables.
+    // Fill-only-if-absent: a profile row may pin a deliberate value (the
+    // full patch runs cloudRequestsPerMinute=8, tighter than the shared
+    // file default) and that explicit wiring must win over edge.json.
+    const threat = loadEdgeConfig().threat;
+    if (threat) {
+        const thresholds = config.thresholds;
+        if (thresholds && thresholds.cloudRequestsPerMinute === undefined && threat.cloudRate !== undefined) {
+            thresholds.cloudRequestsPerMinute = threat.cloudRate;
+        }
+        if (config.blockLevel === undefined && threat.blockLevel !== undefined) {
+            config.blockLevel =
+                threat.blockLevel;
+        }
+    }
+    const service = new TdBusServiceImpl(ctx, config);
+    ctx.tdBus = service;
+    void config;
+    // 惯例对齐：其余插件的 apply 都返回真 dispose。这里原先返回空函数 —
+    // 插件 reload 后旧 service 既不注销、属性也悬空。
+    return async () => {
+        try {
+            service.dispose?.();
+        }
+        catch { /* best-effort */ }
+        if (ctx.tdBus === service)
+            ctx.tdBus = undefined;
+    };
+}

package/lib/dsh-adapter/tool-runner.d.ts

@@ -0,0 +1,185 @@
+/**
+ * tool-runner — §7.93 Phase 3:needle 提取结果的 TS 执行边界。
+ *
+ * needle 只产文本 + function_calls(不执行、不碰 PII、不做 realm 决策,
+ * user 终裁 #1)。本模块是 needle-produced tool_calls 的**唯一**执行入口,
+ * 与 LLM-produced tool_calls 享受完全相同的执法链:
+ *
+ *   1. schema 面校验 —— call.name 必须 ∈ POST 给 needle 的同一份 schemas
+ *      (getToolSchemasForExternal 产物,单一真相源);幻觉工具名直接拒。
+ *   2. ungrounded 处理(API.md v1.1 `validation.ungrounded`)——
+ *      required 参数被捏造 → **不执行**(skipped + audit external.fabricated_arg,
+ *      留给 LOCAL LLM synthesis 阶段补);非 required 被捏造 → 从 arguments
+ *      剥除后执行(drop),不带幻觉值进工具。
+ *   3. realm 预检(defense-in-depth)—— 复用 realm-skill-bridge
+ *      checkToolRealm(name, getAgentRealm(agent));deny → external.realm_rejected
+ *      (security 级),宿主管线都不进。
+ *   4. 宿主执行 —— `ctx.tools.execute()`(dsh-tools ToolRuntime),自动跑完整
+ *      pre-execute(Layer 3 权威 realm gate 再查一遍,零绕过)/ guards /
+ *      around-dispatch / post-execute 管线。**caller 必须透传 payload 里的
+ *      真 agent**:Layer 3 靠 agent.session.id 查 sessionRealms(input-guard
+ *      在 classify 时注册),假 agent = getAgentRealm undefined = fail-open。
+ *
+ * 审计纪律(PII):audit payload 只有 metadata(名字/时长/长度/计数),
+ * **绝不落 arguments 内容或 result 内容** —— 与 file-logger 两-channel
+ * 分工一致(ops log = 过程流水 metadata only;audit = 安全账本 redacted)。
+ *
+ * 失败契约:execute()/executeAll() **永不 throw** —— 一切异常归一成
+ * status:'error' outcome + external.execution_failed audit,调用方
+ * (function-call-external Phase 5)拿 outcome 决定合成消息或 fall through。
+ *
+ * 并发:executeAll 是**顺序**执行(不是计划草稿里的 Promise.all)——
+ * 并行调度是宿主 scheduler 的领地(isConcurrencySafe 门控),本边界不绕过;
+ * needle 单轮典型 1-2 个 call,顺序执行的延迟差可忽略,且 tool-result 合成
+ * 消息顺序确定。
+ *
+ * 本模块**不是 cordis plugin**(无 export const inject / apply):它是纯类,
+ * 由 function-call-external(Phase 4)构造并持有。类型全部结构化 loose-coupling
+ * (不 import dsh-tools/dsh-llm 类型,与 realm-skill-bridge 同款纪律);
+ * ToolCallId 在运行时就是普通 string(brand 只在类型层)。
+ *
+ * @module dsh-edge-agent/tool-runner
+ */
+/** 宿主 ToolRuntime(ctx.tools)的最小子集 —— 只用到 execute。 */
+export interface ToolRuntimeLike {
+    execute(input: {
+        callId: string;
+        name: string;
+        arguments: unknown;
+        agent?: unknown;
+        signal: AbortSignal;
+    }): Promise<ToolExecutionResultLike>;
+}
+/** dsh-tools ToolExecutionResult 的最小子集(success/failure 判别联合)。 */
+export interface ToolExecutionResultLike {
+    isError: boolean;
+    content?: ReadonlyArray<{
+        type?: string;
+        text?: string;
+        [k: string]: unknown;
+    }>;
+    error?: {
+        message?: string;
+        info?: {
+            name?: string;
+            code?: string;
+        };
+    };
+}
+/** realm-skill-bridge 服务的最小子集 —— realm 预检二方法。 */
+export interface RealmBridgeLike {
+    getAgentRealm(agent: unknown): string | undefined;
+    checkToolRealm(toolName: string, agentRealm: string | undefined): string | undefined;
+}
+/** audit-log 服务的最小子集(与 realm-skill-bridge AuditLogLike 同形)。 */
+export interface AuditLogLike {
+    log(entry: {
+        level: string;
+        kind: string;
+        source: string;
+        payload?: Record<string, unknown>;
+    }): void;
+}
+/** Phase 2 产物:getToolSchemasForExternal 返回的平面 wire schema。 */
+export interface ExternalToolSchemaLike {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+}
+/** needle /extract 返回的单个 function_call(API.md v1.1)。 */
+export interface ExternalFunctionCall {
+    name: string;
+    /** needle 已做 JSON 解析;防御性当 unknown 收,入口再校验。 */
+    arguments?: unknown;
+}
+/**
+ * - `executed`  宿主管线跑完且 isError=false
+ * - `denied`    realm 预检拒绝 / 幻觉工具名 / call 形状非法(宿主未进)
+ * - `skipped`   required 参数被捏造(ungrounded)→ 不执行,留给 synthesis
+ * - `error`     宿主执行失败(isError=true)或 execute() 抛异常
+ */
+export type ToolRunStatus = 'executed' | 'denied' | 'skipped' | 'error';
+export interface ToolRunOutcome {
+    status: ToolRunStatus;
+    name: string;
+    /** 运行时 callId(Phase 5 合成 assistant tool_call / tool_result 消息用)。 */
+    callId: string;
+    /** 模型可读的结果文本(content text 块拼接);非 executed 时为 ''。 */
+    text: string;
+    /** denied/skipped/error 的原因(人类可读);executed 时 undefined。 */
+    reason?: string;
+    /** 实际递进宿主的 arguments(捏造的非 required 参数已剥除)。 */
+    executedArguments?: Record<string, unknown>;
+    /** 被剥除(drop)或因之拒执行(skip)的捏造参数名。 */
+    fabricatedArgs?: string[];
+    durationMs: number;
+}
+export interface ToolRunRequest {
+    call: ExternalFunctionCall;
+    /**
+     * payload 里的**真 agent**(带 session.id)。Layer 3 gate 与 realm 预检都靠
+     * getAgentRealm(agent) → sessionRealms.get(session.id) 解析 realm;
+     * 传假 agent = realm 执法静默失效(fail-open)。
+     */
+    agent: unknown;
+    sessionId?: string;
+    /** POST 给 needle 的同一份 schemas(单一真相源,幻觉名在此拒)。 */
+    schemas: readonly ExternalToolSchemaLike[];
+    /** needle `validation.ungrounded`,形如 ["send_message.text"];可空。 */
+    ungrounded?: readonly string[];
+    /** caller 的取消信号;缺省时 runner 自建 executeTimeoutMs 超时信号。 */
+    signal?: AbortSignal;
+}
+export interface ToolRunnerDeps {
+    tools: ToolRuntimeLike;
+    realmSkillBridge: RealmBridgeLike;
+    auditLog?: AuditLogLike;
+    /** ops log(可选;与 http-api/realm-skill-bridge 同款 debug 通道)。 */
+    logger?: {
+        info?: (msg: string) => void;
+        warn?: (msg: string) => void;
+    };
+    /** audit source 字段;默认 'tool-runner'。 */
+    source?: string;
+    /** 无 caller signal 时的自建超时;默认 60_000ms。 */
+    executeTimeoutMs?: number;
+}
+/** content 块里抽文本(text 块拼接;非 text 块跳过 —— 与 http-api 同款投影)。 */
+export declare function extractResultText(content: ToolExecutionResultLike['content']): string;
+/** schema.parameters.required 里的字符串数组(JSON Schema 语义,防御性抽取)。 */
+export declare function requiredArgsOf(schema: ExternalToolSchemaLike | undefined): string[];
+/**
+ * 从 needle `validation.ungrounded`(dotted "toolName.argName")里挑出属于
+ * 本 call 的条目,按 schema.required 分成 skip 集(required 被捏造 → 整个
+ * call 不执行)与 drop 集(非 required → 从 arguments 剥除后照常执行)。
+ */
+export declare function partitionUngrounded(toolName: string, ungrounded: readonly string[] | undefined, schema: ExternalToolSchemaLike | undefined): {
+    skip: string[];
+    drop: string[];
+};
+export declare class ToolRunner {
+    private readonly tools;
+    private readonly bridge;
+    private readonly auditLog;
+    private readonly logger;
+    private readonly source;
+    private readonly executeTimeoutMs;
+    /** callId 单调计数(同 ms 内多 call 不撞号)。 */
+    private callSeq;
+    constructor(deps: ToolRunnerDeps);
+    /**
+     * 执行单个 needle function_call。永不 throw(失败契约见文件头)。
+     */
+    execute(req: ToolRunRequest): Promise<ToolRunOutcome>;
+    /**
+     * 顺序执行一组 calls(并发是宿主 scheduler 的领地,本边界不绕过 ——
+     * 见文件头)。单个失败不中断后续:每个 outcome 独立归一。
+     */
+    executeAll(calls: readonly ExternalFunctionCall[], shared: Omit<ToolRunRequest, 'call'>): Promise<ToolRunOutcome[]>;
+    private nextCallId;
+    /** ops log 一行(可观测性纪律 §7.46:每个关键环节都在 ops log 体现)。 */
+    private finish;
+    /** audit 只落 metadata —— 绝不落 arguments/result 内容(PII 纪律)。 */
+    private audit;
+}
+//# sourceMappingURL=tool-runner.d.ts.map

package/lib/dsh-adapter/tool-runner.d.ts.map

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

package/lib/dsh-adapter/tool-runner.js

@@ -0,0 +1,271 @@
+/**
+ * tool-runner — §7.93 Phase 3:needle 提取结果的 TS 执行边界。
+ *
+ * needle 只产文本 + function_calls(不执行、不碰 PII、不做 realm 决策,
+ * user 终裁 #1)。本模块是 needle-produced tool_calls 的**唯一**执行入口,
+ * 与 LLM-produced tool_calls 享受完全相同的执法链:
+ *
+ *   1. schema 面校验 —— call.name 必须 ∈ POST 给 needle 的同一份 schemas
+ *      (getToolSchemasForExternal 产物,单一真相源);幻觉工具名直接拒。
+ *   2. ungrounded 处理(API.md v1.1 `validation.ungrounded`)——
+ *      required 参数被捏造 → **不执行**(skipped + audit external.fabricated_arg,
+ *      留给 LOCAL LLM synthesis 阶段补);非 required 被捏造 → 从 arguments
+ *      剥除后执行(drop),不带幻觉值进工具。
+ *   3. realm 预检(defense-in-depth)—— 复用 realm-skill-bridge
+ *      checkToolRealm(name, getAgentRealm(agent));deny → external.realm_rejected
+ *      (security 级),宿主管线都不进。
+ *   4. 宿主执行 —— `ctx.tools.execute()`(dsh-tools ToolRuntime),自动跑完整
+ *      pre-execute(Layer 3 权威 realm gate 再查一遍,零绕过)/ guards /
+ *      around-dispatch / post-execute 管线。**caller 必须透传 payload 里的
+ *      真 agent**:Layer 3 靠 agent.session.id 查 sessionRealms(input-guard
+ *      在 classify 时注册),假 agent = getAgentRealm undefined = fail-open。
+ *
+ * 审计纪律(PII):audit payload 只有 metadata(名字/时长/长度/计数),
+ * **绝不落 arguments 内容或 result 内容** —— 与 file-logger 两-channel
+ * 分工一致(ops log = 过程流水 metadata only;audit = 安全账本 redacted)。
+ *
+ * 失败契约:execute()/executeAll() **永不 throw** —— 一切异常归一成
+ * status:'error' outcome + external.execution_failed audit,调用方
+ * (function-call-external Phase 5)拿 outcome 决定合成消息或 fall through。
+ *
+ * 并发:executeAll 是**顺序**执行(不是计划草稿里的 Promise.all)——
+ * 并行调度是宿主 scheduler 的领地(isConcurrencySafe 门控),本边界不绕过;
+ * needle 单轮典型 1-2 个 call,顺序执行的延迟差可忽略,且 tool-result 合成
+ * 消息顺序确定。
+ *
+ * 本模块**不是 cordis plugin**(无 export const inject / apply):它是纯类,
+ * 由 function-call-external(Phase 4)构造并持有。类型全部结构化 loose-coupling
+ * (不 import dsh-tools/dsh-llm 类型,与 realm-skill-bridge 同款纪律);
+ * ToolCallId 在运行时就是普通 string(brand 只在类型层)。
+ *
+ * @module dsh-edge-agent/tool-runner
+ */
+// ─────────────────────────────────────────────────────────────────────────────
+// Helpers (pure, exported for tests)
+// ─────────────────────────────────────────────────────────────────────────────
+function isPlainRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** content 块里抽文本(text 块拼接;非 text 块跳过 —— 与 http-api 同款投影)。 */
+export function extractResultText(content) {
+    if (!Array.isArray(content))
+        return '';
+    return content
+        .filter((b) => isPlainRecord(b) && b.type === 'text' && typeof b.text === 'string')
+        .map(b => b.text)
+        .join('');
+}
+/** schema.parameters.required 里的字符串数组(JSON Schema 语义,防御性抽取)。 */
+export function requiredArgsOf(schema) {
+    const req = schema?.parameters?.required;
+    if (!Array.isArray(req))
+        return [];
+    return req.filter((x) => typeof x === 'string');
+}
+/**
+ * 从 needle `validation.ungrounded`(dotted "toolName.argName")里挑出属于
+ * 本 call 的条目,按 schema.required 分成 skip 集(required 被捏造 → 整个
+ * call 不执行)与 drop 集(非 required → 从 arguments 剥除后照常执行)。
+ */
+export function partitionUngrounded(toolName, ungrounded, schema) {
+    const skip = [];
+    const drop = [];
+    if (!Array.isArray(ungrounded))
+        return { skip, drop };
+    const required = new Set(requiredArgsOf(schema));
+    const prefix = `${toolName}.`;
+    for (const entry of ungrounded) {
+        if (typeof entry !== 'string' || !entry.startsWith(prefix))
+            continue;
+        const arg = entry.slice(prefix.length);
+        if (arg === '')
+            continue;
+        (required.has(arg) ? skip : drop).push(arg);
+    }
+    return { skip, drop };
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// ToolRunner
+// ─────────────────────────────────────────────────────────────────────────────
+export class ToolRunner {
+    tools;
+    bridge;
+    auditLog;
+    logger;
+    source;
+    executeTimeoutMs;
+    /** callId 单调计数(同 ms 内多 call 不撞号)。 */
+    callSeq = 0;
+    constructor(deps) {
+        this.tools = deps.tools;
+        this.bridge = deps.realmSkillBridge;
+        this.auditLog = deps.auditLog;
+        this.logger = deps.logger;
+        this.source = deps.source ?? 'tool-runner';
+        this.executeTimeoutMs = deps.executeTimeoutMs ?? 60_000;
+    }
+    /**
+     * 执行单个 needle function_call。永不 throw(失败契约见文件头)。
+     */
+    async execute(req) {
+        const start = Date.now();
+        const rawName = req.call?.name;
+        const name = typeof rawName === 'string' ? rawName : '';
+        const callId = this.nextCallId(req.sessionId);
+        // ── 0. call 形状校验(name 非空 string;arguments 缺省 {}) ──────────
+        if (name === '') {
+            return this.finish({
+                status: 'denied', text: '', name: name || String(rawName ?? ''), callId,
+                reason: 'invalid_call: missing tool name',
+                durationMs: Date.now() - start,
+            }, undefined, req);
+        }
+        const argsIn = isPlainRecord(req.call.arguments) ? req.call.arguments : {};
+        // ── 1. schema 面校验(幻觉工具名拒;与 POST 给 needle 的同一份) ──────
+        const schema = req.schemas.find(s => s.name === name);
+        if (!schema) {
+            this.audit('warn', 'external.unknown_tool', { name, callId, sessionId: req.sessionId, schemaCount: req.schemas.length });
+            return this.finish({
+                status: 'denied', text: '', name, callId,
+                reason: 'unknown_tool: not in the schema set given to needle',
+                durationMs: Date.now() - start,
+            }, undefined, req);
+        }
+        // ── 2. ungrounded 处理(required 捏造 → skip;非 required → drop) ────
+        const { skip, drop } = partitionUngrounded(name, req.ungrounded, schema);
+        if (skip.length > 0) {
+            this.audit('warn', 'external.fabricated_arg', {
+                action: 'skip', name, callId, sessionId: req.sessionId,
+                fabricatedArgs: skip, ungroundedCount: (req.ungrounded ?? []).length,
+                detection: 'needle_ungrounded',
+            });
+            return this.finish({
+                status: 'skipped', text: '', name, callId,
+                reason: `fabricated required argument(s): ${skip.join(', ')} — left for LLM synthesis`,
+                fabricatedArgs: skip,
+                durationMs: Date.now() - start,
+            }, undefined, req);
+        }
+        // ── 2.5 客户端空参检测(§7.95:needle 不一定在 ungrounded 里标,
+        //       arguments:{} 或 required 缺失应直接拦下,不进引擎) ─────────
+        const required = requiredArgsOf(schema);
+        if (required.length > 0) {
+            const missing = required.filter(k => !(k in argsIn));
+            if (missing.length > 0) {
+                this.audit('warn', 'external.fabricated_arg', {
+                    action: 'skip', name, callId, sessionId: req.sessionId,
+                    fabricatedArgs: missing, ungroundedCount: (req.ungrounded ?? []).length,
+                    detection: 'client_side_missing_required',
+                });
+                return this.finish({
+                    status: 'skipped', text: '', name, callId,
+                    reason: `missing required argument(s): ${missing.join(', ')} — left for LLM synthesis`,
+                    fabricatedArgs: missing,
+                    durationMs: Date.now() - start,
+                }, undefined, req);
+            }
+        }
+        let args = argsIn;
+        if (drop.length > 0) {
+            args = { ...argsIn };
+            for (const k of drop)
+                delete args[k];
+            this.audit('warn', 'external.fabricated_arg', {
+                action: 'drop', name, callId, sessionId: req.sessionId,
+                fabricatedArgs: drop, ungroundedCount: (req.ungrounded ?? []).length,
+                detection: 'needle_ungrounded',
+            });
+        }
+        // ── 3. realm 预检(defense-in-depth;Layer 3 在宿主管线里还会再查) ────
+        const agentRealm = this.bridge.getAgentRealm(req.agent);
+        const denyReason = this.bridge.checkToolRealm(name, agentRealm);
+        if (denyReason !== undefined) {
+            this.audit('security', 'external.realm_rejected', {
+                name, callId, sessionId: req.sessionId,
+                agentRealm: agentRealm ?? 'unknown', reason: denyReason,
+            });
+            return this.finish({
+                status: 'denied', text: '', name, callId, reason: denyReason,
+                durationMs: Date.now() - start,
+            }, undefined, req);
+        }
+        // ── 4. 宿主执行(ctx.tools.execute → 完整 pre/guard/around/post 管线) ──
+        try {
+            const signal = req.signal ?? AbortSignal.timeout(this.executeTimeoutMs);
+            const result = await this.tools.execute({
+                callId, name, arguments: args, agent: req.agent, signal,
+            });
+            const durationMs = Date.now() - start;
+            if (result?.isError) {
+                const message = result.error?.message ?? 'tool execution failed';
+                this.audit('warn', 'external.execution_failed', {
+                    name, callId, sessionId: req.sessionId, durationMs,
+                    errorCode: result.error?.info?.code, errorLen: message.length,
+                });
+                return this.finish({
+                    status: 'error', text: '', name, callId, reason: message,
+                    executedArguments: args, durationMs,
+                }, undefined, req);
+            }
+            const text = extractResultText(result?.content);
+            this.audit('info', 'external.executed', {
+                name, callId, sessionId: req.sessionId, durationMs,
+                resultLen: text.length, droppedFabricated: drop.length,
+            });
+            return this.finish({
+                status: 'executed', name, callId, text,
+                executedArguments: args,
+                fabricatedArgs: drop.length > 0 ? drop : undefined,
+                durationMs,
+            }, text, req);
+        }
+        catch (err) {
+            // 宿主 execute 契约上不 throw(失败也 materialize 成 isError result),
+            // 但 registry 未挂载 / cordis proxy trap(§7.92.2)等仍可能炸 —— 归一。
+            const durationMs = Date.now() - start;
+            const message = err instanceof Error ? err.message : String(err);
+            this.audit('warn', 'external.execution_failed', {
+                name, callId, sessionId: req.sessionId, durationMs,
+                thrown: true, errorLen: message.length,
+            });
+            return this.finish({
+                status: 'error', text: '', name, callId, reason: message,
+                executedArguments: args, durationMs,
+            }, undefined, req);
+        }
+    }
+    /**
+     * 顺序执行一组 calls(并发是宿主 scheduler 的领地,本边界不绕过 ——
+     * 见文件头)。单个失败不中断后续:每个 outcome 独立归一。
+     */
+    async executeAll(calls, shared) {
+        const out = [];
+        for (const call of calls ?? []) {
+            out.push(await this.execute({ ...shared, call }));
+        }
+        return out;
+    }
+    // ── internals ─────────────────────────────────────────────────────────────
+    nextCallId(sessionId) {
+        this.callSeq += 1;
+        const sess = sessionId ? `-${sessionId.slice(0, 12)}` : '';
+        return `fcx${sess}-${Date.now().toString(36)}-${this.callSeq}`;
+    }
+    /** ops log 一行(可观测性纪律 §7.46:每个关键环节都在 ops log 体现)。 */
+    finish(outcome, _text, req) {
+        try {
+            this.logger?.info?.(`[tool-runner] ${outcome.status} tool=${outcome.name} callId=${outcome.callId}` +
+                ` sessionId=${req.sessionId ?? 'unknown'} durationMs=${outcome.durationMs}` +
+                (outcome.reason ? ` reason=${outcome.reason}` : ''));
+        }
+        catch { /* debug only */ }
+        return outcome;
+    }
+    /** audit 只落 metadata —— 绝不落 arguments/result 内容(PII 纪律)。 */
+    audit(level, kind, payload) {
+        try {
+            this.auditLog?.log({ level, kind, source: this.source, payload });
+        }
+        catch { /* audit 失败不阻断执行链 */ }
+    }
+}