@gt-fe/eap-runtime 0.0.8

package/dist/token/token-estimator.js

@@ -0,0 +1,134 @@
+/**
+ * TiktokenEstimator — 基于 tiktoken 的 Token 估算器
+ *
+ * 提供更精确的 Token 计数，支持多种模型的 tokenizer。
+ * 当 tiktoken 不可用时，回退到基于字符的估算。
+ *
+ * @see message-compression.service.ts Token 估算
+ */
+// ─────────────────────────────────────────────
+// 基于字符的估算器（默认）
+// ─────────────────────────────────────────────
+/**
+ * 基于字符的 Token 估算器
+ *
+ * 粗略但快速，适用于：
+ * - tiktoken 不可用时的回退方案
+ * - 对精度要求不高的场景
+ */
+export class CharBasedTokenEstimator {
+    /**
+     * 估算文本的 Token 数
+     *
+     * 基于字符数估算：
+     * - 中文约 1.5 字符 = 1 Token
+     * - 英文约 4 字符 = 1 Token
+     */
+    estimateTokens(text) {
+        if (!text)
+            return 0;
+        // 统计中文字符数
+        const chineseChars = (text.match(/[\u4e00-\u9fff]/g) || []).length;
+        // 统计非中文字符数
+        const otherChars = text.length - chineseChars;
+        // 中文 1.5 字符 ≈ 1 Token，英文 4 字符 ≈ 1 Token
+        return Math.ceil(chineseChars / 1.5 + otherChars / 4);
+    }
+    estimateMessagesTokens(messages) {
+        let totalTokens = 0;
+        for (const msg of messages) {
+            // 基础开销（role、格式等）
+            totalTokens += 4;
+            // 内容 Token
+            if (msg.content) {
+                totalTokens += this.estimateTokens(msg.content);
+            }
+            // toolCalls 额外开销
+            if (msg.toolCalls) {
+                totalTokens += this.estimateTokens(JSON.stringify(msg.toolCalls));
+            }
+        }
+        return totalTokens;
+    }
+}
+// ─────────────────────────────────────────────
+// 基于模型的估算器（更精确）
+// ─────────────────────────────────────────────
+/**
+ * 模型特定的 Token 估算器
+ *
+ * 基于不同模型的 tokenizer 特性进行更精确的估算。
+ */
+export class ModelBasedTokenEstimator {
+    model;
+    charsPerToken;
+    constructor(model = 'gpt-4') {
+        this.model = model;
+        this.charsPerToken = this.getCharsPerToken(model);
+    }
+    estimateTokens(text) {
+        if (!text)
+            return 0;
+        return Math.ceil(text.length / this.charsPerToken);
+    }
+    estimateMessagesTokens(messages) {
+        let totalTokens = 0;
+        for (const msg of messages) {
+            // 基础开销（role、格式等）
+            totalTokens += 4;
+            // 内容 Token
+            if (msg.content) {
+                totalTokens += this.estimateTokens(msg.content);
+            }
+            // toolCalls 额外开销
+            if (msg.toolCalls) {
+                totalTokens += this.estimateTokens(JSON.stringify(msg.toolCalls));
+            }
+        }
+        return totalTokens;
+    }
+    /**
+     * 获取模型的字符/Token 比率
+     */
+    getCharsPerToken(model) {
+        // 不同模型的字符/Token 比率
+        const ratios = {
+            'gpt-4': 4,
+            'gpt-4-turbo': 4,
+            'gpt-4o': 4,
+            'gpt-3.5-turbo': 4,
+            'claude-3-opus': 3.5,
+            'claude-3-sonnet': 3.5,
+            'claude-3-haiku': 3.5,
+            'claude-2': 3.5,
+            'gemini-pro': 4,
+            'gemini-ultra': 4,
+            'llama-2': 4,
+            'llama-3': 4,
+            'mistral': 4,
+        };
+        // 查找模型对应的比率
+        for (const [key, ratio] of Object.entries(ratios)) {
+            if (model.toLowerCase().includes(key.toLowerCase())) {
+                return ratio;
+            }
+        }
+        // 默认比率
+        return 4;
+    }
+}
+// ─────────────────────────────────────────────
+// 工厂函数
+// ─────────────────────────────────────────────
+/**
+ * 创建 Token 估算器
+ *
+ * @param model - 模型名称（可选）
+ * @returns Token 估算器实例
+ */
+export function createTokenEstimator(model) {
+    if (model) {
+        return new ModelBasedTokenEstimator(model);
+    }
+    return new CharBasedTokenEstimator();
+}

package/dist/token/token-stats.service.d.ts

@@ -0,0 +1,88 @@
+/**
+ * TokenStatsService — Token 统计服务
+ *
+ * 收集每次 LLM 调用的 Token 消耗，按 taskId 聚合统计。
+ * 提供 total/byNode/byModel 多维度汇总能力。
+ *
+ * @see design.md §1.6 stats.token_usage / stats.node_token 事件
+ * @see requirements.md Requirement 6 AC1-AC4
+ */
+/**
+ * NodeTokenUsage — 单次 LLM 调用的 Token 消耗数据
+ *
+ * 对应 SSE 事件 stats.node_token 的 payload 结构。
+ */
+export interface NodeTokenUsage {
+    /** 产生消耗的节点 ID */
+    nodeId: string;
+    /** 使用的模型标识 */
+    model: string;
+    /** 输入 Token 数 */
+    inputTokens: number;
+    /** 输出 Token 数 */
+    outputTokens: number;
+    /** 预估成本（美元） */
+    costEstimate: number;
+}
+/**
+ * TokenBreakdown — Token 消耗分组统计
+ */
+export interface TokenBreakdown {
+    /** 输入 Token 总数 */
+    input: number;
+    /** 输出 Token 总数 */
+    output: number;
+    /** 输入 + 输出 总计 */
+    total: number;
+}
+/**
+ * TaskTokenSummary — Task 级 Token 消耗聚合汇总
+ *
+ * 对应 SSE 事件 stats.token_usage 的 payload 结构。
+ */
+export interface TaskTokenSummary {
+    /** 全局合计 */
+    total: TokenBreakdown;
+    /** 按节点 ID 分组的 Token 消耗 */
+    byNode: Record<string, TokenBreakdown>;
+    /** 按模型分组的 Token 消耗 */
+    byModel: Record<string, TokenBreakdown>;
+    /** 累计预估成本（美元） */
+    costEstimate: number;
+}
+/**
+ * TokenStatsService — 收集与聚合 Token 统计
+ *
+ * - record(): 记录单次 LLM 调用的 Token 消耗
+ * - getTaskStats(): 计算 Task 级聚合统计
+ * - clear(): 清除已完成 Task 的统计数据（释放内存）
+ */
+export declare class TokenStatsService {
+    /** 内存存储：taskId → 该 Task 的所有调用记录 */
+    private readonly usageStore;
+    /**
+     * 记录单次 LLM 调用的 Token 消耗
+     *
+     * @param taskId - 所属 Task ID
+     * @param usage - 本次调用的 Token 消耗数据
+     */
+    record(taskId: string, usage: NodeTokenUsage): void;
+    /**
+     * 获取 Task 级聚合统计
+     *
+     * 自动计算 total / byNode / byModel / costEstimate。
+     * 若 taskId 无记录，返回空统计（全零值）。
+     *
+     * @param taskId - Task ID
+     * @returns 聚合后的 TaskTokenSummary
+     */
+    getTaskStats(taskId: string): TaskTokenSummary;
+    /**
+     * 清除指定 Task 的统计数据
+     *
+     * Task 完成后调用，释放内存。
+     *
+     * @param taskId - Task ID
+     */
+    clear(taskId: string): void;
+}

package/dist/token/token-stats.service.js

@@ -0,0 +1,94 @@
+/**
+ * TokenStatsService — Token 统计服务
+ *
+ * 收集每次 LLM 调用的 Token 消耗，按 taskId 聚合统计。
+ * 提供 total/byNode/byModel 多维度汇总能力。
+ *
+ * @see design.md §1.6 stats.token_usage / stats.node_token 事件
+ * @see requirements.md Requirement 6 AC1-AC4
+ */
+// ─────────────────────────────────────────────
+// TokenStatsService
+// ─────────────────────────────────────────────
+/**
+ * TokenStatsService — 收集与聚合 Token 统计
+ *
+ * - record(): 记录单次 LLM 调用的 Token 消耗
+ * - getTaskStats(): 计算 Task 级聚合统计
+ * - clear(): 清除已完成 Task 的统计数据（释放内存）
+ */
+export class TokenStatsService {
+    /** 内存存储：taskId → 该 Task 的所有调用记录 */
+    usageStore = new Map();
+    /**
+     * 记录单次 LLM 调用的 Token 消耗
+     *
+     * @param taskId - 所属 Task ID
+     * @param usage - 本次调用的 Token 消耗数据
+     */
+    record(taskId, usage) {
+        const records = this.usageStore.get(taskId);
+        if (records) {
+            records.push(usage);
+        }
+        else {
+            this.usageStore.set(taskId, [usage]);
+        }
+    }
+    /**
+     * 获取 Task 级聚合统计
+     *
+     * 自动计算 total / byNode / byModel / costEstimate。
+     * 若 taskId 无记录，返回空统计（全零值）。
+     *
+     * @param taskId - Task ID
+     * @returns 聚合后的 TaskTokenSummary
+     */
+    getTaskStats(taskId) {
+        const records = this.usageStore.get(taskId) ?? [];
+        let totalInput = 0;
+        let totalOutput = 0;
+        let totalCost = 0;
+        const byNode = {};
+        const byModel = {};
+        for (const record of records) {
+            totalInput += record.inputTokens;
+            totalOutput += record.outputTokens;
+            totalCost += record.costEstimate;
+            // 按节点聚合
+            if (!byNode[record.nodeId]) {
+                byNode[record.nodeId] = { input: 0, output: 0, total: 0 };
+            }
+            byNode[record.nodeId].input += record.inputTokens;
+            byNode[record.nodeId].output += record.outputTokens;
+            byNode[record.nodeId].total += record.inputTokens + record.outputTokens;
+            // 按模型聚合
+            if (!byModel[record.model]) {
+                byModel[record.model] = { input: 0, output: 0, total: 0 };
+            }
+            byModel[record.model].input += record.inputTokens;
+            byModel[record.model].output += record.outputTokens;
+            byModel[record.model].total += record.inputTokens + record.outputTokens;
+        }
+        return {
+            total: {
+                input: totalInput,
+                output: totalOutput,
+                total: totalInput + totalOutput,
+            },
+            byNode,
+            byModel,
+            costEstimate: totalCost,
+        };
+    }
+    /**
+     * 清除指定 Task 的统计数据
+     *
+     * Task 完成后调用，释放内存。
+     *
+     * @param taskId - Task ID
+     */
+    clear(taskId) {
+        this.usageStore.delete(taskId);
+    }
+}

package/dist/tool/create-tool-executor.d.ts

@@ -0,0 +1,33 @@
+/**
+ * createToolExecutor — 按部署上下文组装 Router + Gateway/Local 执行器
+ *
+ * server / hosting：**默认 MCP**（McpToolExecutor → POST /api/v1/mcp）；
+ * `EAP_TOOL_GATEWAY_TRANSPORT=http` 时用 HttpToolExecutor（仅调试）。
+ * desktop 经 ToolExecutionRouter 分流 Local / Gateway。
+ */
+import type { ILocalToolInstallStore, LocalToolInstallRecord } from '@gt-fe/eap-contracts';
+import { type DeploymentContext } from './tool-execution-router.js';
+import type { IToolExecutor } from './tool-executor.interface.js';
+export declare class EmptyInstallStore implements ILocalToolInstallStore {
+    get(): null;
+    listReady(): LocalToolInstallRecord[];
+}
+export type ToolGatewayTransport = 'mcp' | 'http';
+export interface CreateToolExecutorOptions {
+    foundationUrl: string;
+    deploymentContext?: DeploymentContext;
+    installStore?: ILocalToolInstallStore;
+    forceToolServer?: string[];
+    httpTimeout?: number;
+    toolTypes?: Map<string, string>;
+    toolRuntimes?: Map<string, 'local' | 'server' | 'both'>;
+    /**
+     * Gateway 出站协议。默认 mcp；设 http 仅用于调试口联调。
+     * 也可用环境变量 EAP_TOOL_GATEWAY_TRANSPORT=http|mcp。
+     */
+    gatewayTransport?: ToolGatewayTransport;
+}
+/**
+ * 创建经 ToolExecutionRouter 包装的 IToolExecutor（生产装配入口）
+ */
+export declare function createToolExecutor(options: CreateToolExecutorOptions): IToolExecutor;

package/dist/tool/create-tool-executor.js

@@ -0,0 +1,60 @@
+/**
+ * createToolExecutor — 按部署上下文组装 Router + Gateway/Local 执行器
+ *
+ * server / hosting：**默认 MCP**（McpToolExecutor → POST /api/v1/mcp）；
+ * `EAP_TOOL_GATEWAY_TRANSPORT=http` 时用 HttpToolExecutor（仅调试）。
+ * desktop 经 ToolExecutionRouter 分流 Local / Gateway。
+ */
+import { HttpToolExecutor } from './http-tool-executor.js';
+import { McpToolExecutor } from './mcp-tool-executor.js';
+import { LocalToolExecutor } from './local-tool-executor.js';
+import { ToolExecutionRouter, } from './tool-execution-router.js';
+export class EmptyInstallStore {
+    get() {
+        return null;
+    }
+    listReady() {
+        return [];
+    }
+}
+function resolveDeploymentContext(explicit) {
+    if (explicit)
+        return explicit;
+    const fromEnv = process.env.EAP_DEPLOYMENT_CONTEXT;
+    if (fromEnv === 'desktop' || fromEnv === 'dev' || fromEnv === 'server') {
+        return fromEnv;
+    }
+    return 'server';
+}
+function resolveGatewayTransport(explicit) {
+    if (explicit)
+        return explicit;
+    const fromEnv = process.env.EAP_TOOL_GATEWAY_TRANSPORT;
+    if (fromEnv === 'http' || fromEnv === 'mcp')
+        return fromEnv;
+    return 'mcp';
+}
+function createServerExecutor(foundationUrl, transport, timeout) {
+    if (transport === 'http') {
+        return new HttpToolExecutor({ baseUrl: foundationUrl, timeout });
+    }
+    return new McpToolExecutor({ baseUrl: foundationUrl, timeout });
+}
+/**
+ * 创建经 ToolExecutionRouter 包装的 IToolExecutor（生产装配入口）
+ */
+export function createToolExecutor(options) {
+    const installStore = options.installStore ?? new EmptyInstallStore();
+    const transport = resolveGatewayTransport(options.gatewayTransport);
+    const serverExecutor = createServerExecutor(options.foundationUrl, transport, options.httpTimeout);
+    const localExecutor = new LocalToolExecutor({ installStore });
+    return new ToolExecutionRouter({
+        httpExecutor: serverExecutor,
+        localExecutor,
+        installStore,
+        deploymentContext: resolveDeploymentContext(options.deploymentContext),
+        toolTypes: options.toolTypes,
+        toolRuntimes: options.toolRuntimes,
+        forceToolServer: options.forceToolServer,
+    });
+}

package/dist/tool/dev-http-executor.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Dev 下按 type:http 清单直连出站（gateway.baseUrl + pathTemplate）。
+ * URL 拼接与 host 白名单与 Tool Gateway 共用 @gt-fe/eap-contracts http-outbound。
+ */
+import type { IToolExecutor, ToolCallRequest, ToolCallResult } from './tool-executor.interface.js';
+export interface DevHttpExecution {
+    protocol: 'http';
+    method?: string;
+    baseUrl?: string;
+    pathTemplate?: string;
+    allowedHosts?: string[];
+    timeout?: number;
+}
+export declare function resolveHttpExecutionFromRequest(request: ToolCallRequest): DevHttpExecution | null;
+export declare function buildHttpToolUrl(spec: DevHttpExecution, args: Record<string, unknown>): URL;
+export declare class DevHttpExecutor implements IToolExecutor {
+    execute(request: ToolCallRequest): Promise<ToolCallResult>;
+}

package/dist/tool/dev-http-executor.js

@@ -0,0 +1,96 @@
+/**
+ * Dev 下按 type:http 清单直连出站（gateway.baseUrl + pathTemplate）。
+ * URL 拼接与 host 白名单与 Tool Gateway 共用 @gt-fe/eap-contracts http-outbound。
+ */
+import { assertHttpHostAllowlisted, buildHttpToolUrl as buildSharedHttpToolUrl } from '@gt-fe/eap-contracts';
+export function resolveHttpExecutionFromRequest(request) {
+    const raw = request.execution;
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const e = raw;
+    if (e.protocol !== 'http')
+        return null;
+    const baseUrl = typeof e.baseUrl === 'string' ? e.baseUrl : '';
+    const pathTemplate = typeof e.pathTemplate === 'string' ? e.pathTemplate : '';
+    if (!baseUrl || !pathTemplate)
+        return null;
+    return {
+        protocol: 'http',
+        method: typeof e.method === 'string' ? e.method : 'GET',
+        baseUrl,
+        pathTemplate,
+        allowedHosts: Array.isArray(e.allowedHosts)
+            ? e.allowedHosts.filter((item) => typeof item === 'string')
+            : [],
+        timeout: typeof e.timeout === 'number' ? e.timeout : 10000,
+    };
+}
+export function buildHttpToolUrl(spec, args) {
+    const url = buildSharedHttpToolUrl(spec.baseUrl ?? '', spec.pathTemplate ?? '', args);
+    assertHttpHostAllowlisted(url, spec.allowedHosts ?? []);
+    return url;
+}
+export class DevHttpExecutor {
+    async execute(request) {
+        const spec = resolveHttpExecutionFromRequest(request);
+        if (!spec) {
+            return {
+                toolCallId: request.toolCallId,
+                toolName: request.toolName,
+                content: '',
+                success: false,
+                error: `Dev HTTP: tool "${request.toolName}" has no gateway.baseUrl / pathTemplate`,
+                errorCode: 'NOT_CONFIGURED',
+                runtime: 'local',
+            };
+        }
+        try {
+            const args = request.arguments ?? {};
+            const url = buildHttpToolUrl(spec, args);
+            const method = (spec.method ?? 'GET').toUpperCase();
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), spec.timeout ?? 10000);
+            const headers = {
+                Accept: 'application/json, text/plain;q=0.9',
+            };
+            const init = { method, headers, signal: controller.signal };
+            if (method !== 'GET' && method !== 'HEAD') {
+                headers['Content-Type'] = 'application/json';
+                init.body = JSON.stringify(args);
+            }
+            const response = await fetch(url, init);
+            clearTimeout(timer);
+            const text = await response.text();
+            if (!response.ok) {
+                return {
+                    toolCallId: request.toolCallId,
+                    toolName: request.toolName,
+                    content: text,
+                    success: false,
+                    error: `HTTP ${response.status}: ${response.statusText}`,
+                    errorCode: 'EXECUTION_FAILED',
+                    runtime: 'local',
+                };
+            }
+            return {
+                toolCallId: request.toolCallId,
+                toolName: request.toolName,
+                content: text,
+                success: true,
+                runtime: 'local',
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                toolCallId: request.toolCallId,
+                toolName: request.toolName,
+                content: '',
+                success: false,
+                error: message,
+                errorCode: 'EXECUTION_FAILED',
+                runtime: 'local',
+            };
+        }
+    }
+}

package/dist/tool/dev-mcp-executor.d.ts

@@ -0,0 +1,29 @@
+/**
+ * DevMcpExecutor — dev 上下文本地 MCP 直连执行器
+ *
+ * 定位：`eap dev --tool-mode mcp` 场景（deploymentContext=dev）下替代 McpToolExecutor / LocalToolExecutor，
+ * 让 Agent 开发者在 **无 foundation-service、无桌面 installStore** 的前提下直连真实 MCP Server。
+ *
+ * 与另两个 MCP 执行器的差异：
+ * - `McpToolExecutor`（server 上下文）：HTTP POST `foundation/api/v1/mcp/tools/call` → Tool Gateway 出站
+ *    ↳ 生产 K8s 内路径，foundation 不对外，dev 场景不可用
+ * - `LocalToolExecutor` + `LocalMcpClient`（desktop 上下文）：直连 stdio / streamable_http
+ *    ↳ 强依赖 `installStore.resolveReadyInstallByToolName`（gt-agent 预装记录），dev 场景没有该记录
+ * - `DevMcpExecutor`（dev 上下文，本文件）：直连 stdio / streamable_http
+ *    ↳ 从 `request.execution`（tool.manifest.execution）规范化读取，无 installStore 依赖
+ *
+ * 读取来源：`GraphLoader` 已将 `tool.manifest.execution` 沿 LoadedToolDefinition → ToolCallRequest 传下来。
+ *
+ * @see docs/workflows/local-agent-dev-loop.md
+ * @see runtime/src/tool/local-mcp-client.ts
+ */
+import { type ILocalMcpClient } from './local-mcp-client.js';
+import type { IToolExecutor, ToolCallRequest, ToolCallResult } from './tool-executor.interface.js';
+export interface DevMcpExecutorOptions {
+    client?: ILocalMcpClient;
+}
+export declare class DevMcpExecutor implements IToolExecutor {
+    private readonly client;
+    constructor(options?: DevMcpExecutorOptions);
+    execute(request: ToolCallRequest): Promise<ToolCallResult>;
+}

package/dist/tool/dev-mcp-executor.js

@@ -0,0 +1,84 @@
+/**
+ * DevMcpExecutor — dev 上下文本地 MCP 直连执行器
+ *
+ * 定位：`eap dev --tool-mode mcp` 场景（deploymentContext=dev）下替代 McpToolExecutor / LocalToolExecutor，
+ * 让 Agent 开发者在 **无 foundation-service、无桌面 installStore** 的前提下直连真实 MCP Server。
+ *
+ * 与另两个 MCP 执行器的差异：
+ * - `McpToolExecutor`（server 上下文）：HTTP POST `foundation/api/v1/mcp/tools/call` → Tool Gateway 出站
+ *    ↳ 生产 K8s 内路径，foundation 不对外，dev 场景不可用
+ * - `LocalToolExecutor` + `LocalMcpClient`（desktop 上下文）：直连 stdio / streamable_http
+ *    ↳ 强依赖 `installStore.resolveReadyInstallByToolName`（gt-agent 预装记录），dev 场景没有该记录
+ * - `DevMcpExecutor`（dev 上下文，本文件）：直连 stdio / streamable_http
+ *    ↳ 从 `request.execution`（tool.manifest.execution）规范化读取，无 installStore 依赖
+ *
+ * 读取来源：`GraphLoader` 已将 `tool.manifest.execution` 沿 LoadedToolDefinition → ToolCallRequest 传下来。
+ *
+ * @see docs/workflows/local-agent-dev-loop.md
+ * @see runtime/src/tool/local-mcp-client.ts
+ */
+import { LocalMcpClient } from './local-mcp-client.js';
+export class DevMcpExecutor {
+    client;
+    constructor(options = {}) {
+        this.client = options.client ?? new LocalMcpClient();
+    }
+    async execute(request) {
+        const execution = normalizeExecution(request.execution, request.toolName);
+        if (!execution) {
+            return {
+                toolCallId: request.toolCallId,
+                toolName: request.toolName,
+                content: '',
+                success: false,
+                error: `Dev MCP: tool "${request.toolName}" has no valid mcp execution config (expect manifest.execution.protocol="mcp")`,
+                errorCode: 'NOT_CONFIGURED',
+                runtime: 'local',
+            };
+        }
+        try {
+            const { content, file } = await this.client.invoke(execution, request.arguments, {
+                userId: request.authContext?.userId,
+            });
+            return {
+                toolCallId: request.toolCallId,
+                toolName: request.toolName,
+                content,
+                success: true,
+                runtime: 'local',
+                file,
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                toolCallId: request.toolCallId,
+                toolName: request.toolName,
+                content: '',
+                success: false,
+                error: message,
+                errorCode: 'EXECUTION_FAILED',
+                runtime: 'local',
+            };
+        }
+    }
+}
+/**
+ * 把 tool.manifest.execution（McpExecution 结构，transport 可为 stdio/sse/streamable_http）
+ * 规范化为 LocalMcpClient 消费的 McpRuntimeExecution（transport 只支持 stdio/streamable_http）。
+ *
+ * sse 归并到 streamable_http（LocalMcpClient 的 http 分支已能解析 SSE 响应）。
+ */
+function normalizeExecution(raw, fallbackToolName) {
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const e = raw;
+    if (e.protocol !== 'mcp')
+        return null;
+    const rawTransport = e.transport;
+    const transport = rawTransport === 'stdio' ? 'stdio' : 'streamable_http';
+    const server = (e.server ?? {});
+    const toolName = typeof e.toolName === 'string' && e.toolName ? e.toolName : fallbackToolName;
+    const timeout = typeof e.timeout === 'number' ? e.timeout : undefined;
+    return { protocol: 'mcp', transport, server, toolName, timeout };
+}

package/dist/tool/dev-tool-executor.d.ts

@@ -0,0 +1,23 @@
+/**
+ * DevToolExecutor — 本地 dev 总入口（不是 code 专用）
+ *
+ * 仅在 `EAP_TOOL_EXECUTION_MODE=mcp` 且 `deploymentContext=dev` 装配。
+ * 按清单分流，缺配置则失败，不回落 mock。
+ *
+ * - execution.protocol=mcp → DevMcpExecutor
+ * - execution.protocol=http → DevHttpExecutor
+ * - 能解析出 code handler → LocalToolExecutor
+ * - 其余 → NOT_CONFIGURED（mock 只走显式 `--tool-mode mock`）
+ */
+import { DevMcpExecutor } from './dev-mcp-executor.js';
+import type { IToolExecutor, ToolCallRequest, ToolCallResult } from './tool-executor.interface.js';
+export interface DevToolExecutorOptions {
+    mcp?: ConstructorParameters<typeof DevMcpExecutor>[0];
+}
+export declare class DevToolExecutor implements IToolExecutor {
+    private readonly mcp;
+    private readonly http;
+    private readonly local;
+    constructor(options?: DevToolExecutorOptions);
+    execute(request: ToolCallRequest): Promise<ToolCallResult>;
+}