@gt-fe/eap-runtime 0.0.8

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

@@ -0,0 +1,85 @@
+/**
+ * Tool 执行契约 — IToolExecutor 与请求/响应类型
+ *
+ * @see docs/contracts/tool-execution.md §3
+ * @see .kiro/specs/04-runtime-core/tasks.md Task 19.1
+ */
+/**
+ * AuthContext — 调用权限上下文
+ */
+export interface AuthContext {
+    userId: string;
+    delegationToken: string;
+    /** Agent 对外主键 */
+    agentCode: string;
+    /**
+     * @deprecated 使用 agentCode；仅作历史调用方双读兜底
+     */
+    agentId?: string;
+}
+/**
+ * ToolCallRequest — Tool 调用请求
+ */
+export interface ToolCallRequest {
+    toolCallId: string;
+    toolName: string;
+    arguments: Record<string, unknown>;
+    authContext: AuthContext;
+    dataScope?: 'user-bound' | 'department-bound' | 'global';
+    resourceOwnerId?: string;
+    /** Hosting/Runtime Task ID（写入 tool_call_logs） */
+    taskId?: string;
+    /** 链路关联 ID；缺省可用 toolCallId */
+    correlationId?: string;
+    /** 路由用：manifest type */
+    toolType?: string;
+    /** 路由用：manifest runtime */
+    toolRuntime?: 'local' | 'server' | 'both';
+    /** both 类型时强制走服务端 Gateway */
+    forceServer?: boolean;
+    /**
+     * 执行配置（来自 tool.manifest.execution / Skill scripts 虚拟 Tool）
+     *
+     * - protocol=mcp：DevMcpExecutor / Gateway MCP 路径
+     * - localPreferred / source=skill-script：LocalToolExecutor 本机执行
+     * - 其余 code：server 走 Gateway；desktop 按 installStore 分流
+     */
+    execution?: unknown;
+}
+/**
+ * ToolCallResult — Tool 调用结果
+ */
+export interface ToolCallResult {
+    toolCallId: string;
+    toolName: string;
+    content: string;
+    success: boolean;
+    error?: string;
+    /** Gateway / 本地执行结构化错误码 */
+    errorCode?: string;
+    retryable?: boolean;
+    runtime?: 'local' | 'server' | 'mock';
+    /** 工具产出的可下载/可打开文件；不进模型正文 */
+    file?: {
+        fileName: string;
+        fileType: string;
+        size: number;
+        url: string;
+    };
+}
+export interface LLMToolCall {
+    id: string;
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+export interface LLMToolCallResponse {
+    toolCalls: LLMToolCall[];
+}
+/**
+ * IToolExecutor — Tool 执行网关接口
+ */
+export interface IToolExecutor {
+    execute(request: ToolCallRequest): Promise<ToolCallResult>;
+}

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

@@ -0,0 +1,7 @@
+/**
+ * Tool 执行契约 — IToolExecutor 与请求/响应类型
+ *
+ * @see docs/contracts/tool-execution.md §3
+ * @see .kiro/specs/04-runtime-core/tasks.md Task 19.1
+ */
+export {};

package/dist/tool/tool-orchestrator.d.ts

@@ -0,0 +1,22 @@
+/**
+ * ToolOrchestrator — Tool 调用编排服务
+ *
+ * @see design.md §1.1 Tool调用编排
+ * @see requirements.md Requirement 8 AC1, AC3
+ */
+import type { ExecutionContext } from '@gt-fe/eap-contracts';
+import type { IGovernanceClient } from '../governance/governance-client.js';
+export type { AuthContext, ToolCallRequest, ToolCallResult, LLMToolCall, LLMToolCallResponse, IToolExecutor, } from './tool-executor.interface.js';
+import type { AuthContext, ToolCallRequest, ToolCallResult, LLMToolCallResponse, IToolExecutor } from './tool-executor.interface.js';
+/**
+ * ToolOrchestrator — Tool 调用编排主服务
+ */
+export declare class ToolOrchestrator {
+    private readonly toolExecutor;
+    private readonly governanceClient?;
+    constructor(toolExecutor: IToolExecutor, governanceClient?: IGovernanceClient | undefined);
+    extractToolCalls(llmResponse: LLMToolCallResponse, authContext: AuthContext): ToolCallRequest[];
+    executeSingle(request: ToolCallRequest, executionContext?: ExecutionContext): Promise<ToolCallResult>;
+    executeAll(requests: ToolCallRequest[], executionContext?: ExecutionContext): Promise<ToolCallResult[]>;
+    executeSequential(requests: ToolCallRequest[]): Promise<ToolCallResult[]>;
+}

package/dist/tool/tool-orchestrator.js

@@ -0,0 +1,104 @@
+/**
+ * ToolOrchestrator — Tool 调用编排服务
+ *
+ * @see design.md §1.1 Tool调用编排
+ * @see requirements.md Requirement 8 AC1, AC3
+ */
+import { assertToolPermission, GovernanceUnavailableError, PermissionDeniedError, } from '../governance/permission-guard.js';
+/**
+ * ToolOrchestrator — Tool 调用编排主服务
+ */
+export class ToolOrchestrator {
+    toolExecutor;
+    governanceClient;
+    constructor(toolExecutor, governanceClient) {
+        this.toolExecutor = toolExecutor;
+        this.governanceClient = governanceClient;
+    }
+    extractToolCalls(llmResponse, authContext) {
+        if (!llmResponse.toolCalls || llmResponse.toolCalls.length === 0) {
+            return [];
+        }
+        return llmResponse.toolCalls.map((toolCall) => {
+            let parsedArguments;
+            try {
+                parsedArguments = JSON.parse(toolCall.function.arguments);
+            }
+            catch {
+                parsedArguments = {};
+            }
+            return {
+                toolCallId: toolCall.id,
+                toolName: toolCall.function.name,
+                arguments: parsedArguments,
+                authContext,
+            };
+        });
+    }
+    async executeSingle(request, executionContext) {
+        if (this.governanceClient && executionContext?.delegationToken) {
+            try {
+                await assertToolPermission(this.governanceClient, executionContext, request.toolName, {
+                    dataScope: request.dataScope ?? 'user-bound',
+                    resourceOwnerId: request.resourceOwnerId ?? executionContext.userId ?? undefined,
+                });
+            }
+            catch (error) {
+                if (error instanceof PermissionDeniedError || error instanceof GovernanceUnavailableError) {
+                    return {
+                        toolCallId: request.toolCallId,
+                        toolName: request.toolName,
+                        content: '',
+                        success: false,
+                        error: error.reason,
+                        errorCode: error instanceof PermissionDeniedError ? 'NO_PERMISSION' : 'GOVERNANCE_UNAVAILABLE',
+                    };
+                }
+                throw error;
+            }
+        }
+        try {
+            return await this.toolExecutor.execute(request);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : 'Unknown execution error';
+            return {
+                toolCallId: request.toolCallId,
+                toolName: request.toolName,
+                content: '',
+                success: false,
+                error: message,
+            };
+        }
+    }
+    async executeAll(requests, executionContext) {
+        if (requests.length === 0) {
+            return [];
+        }
+        const settled = await Promise.allSettled(requests.map((request) => this.executeSingle(request, executionContext)));
+        return settled.map((outcome, index) => {
+            if (outcome.status === 'fulfilled') {
+                return outcome.value;
+            }
+            const request = requests[index];
+            const message = outcome.reason instanceof Error
+                ? outcome.reason.message
+                : 'Unknown execution error';
+            return {
+                toolCallId: request.toolCallId,
+                toolName: request.toolName,
+                content: '',
+                success: false,
+                error: message,
+            };
+        });
+    }
+    async executeSequential(requests) {
+        const results = [];
+        for (const request of requests) {
+            const result = await this.executeSingle(request);
+            results.push(result);
+        }
+        return results;
+    }
+}

package/dist/tool/tool-result-injector.d.ts

@@ -0,0 +1,64 @@
+/**
+ * ToolResultInjector — Tool 结果注入服务
+ *
+ * 将 Tool 执行结果写回 Graph State，作为 'tool' 角色消息追加到消息历史中，
+ * 从而触发下一轮 LLM 推理（ReAct 循环）。
+ *
+ * 流程：LLM → ToolCall → Tool执行 → **结果注入State** → LLM再次推理 → ... → 最终回复
+ *
+ * @see design.md §1.1 结果注入: Tool结果写回Graph State
+ * @see design.md §1.2 Tool结果注入State → 回到LLM节点（ReAct循环）
+ * @see requirements.md Requirement 8 AC4
+ */
+import type { GraphState, GraphMessage } from '../graph/contracts/executable-graph.js';
+import type { ToolCallResult } from './tool-executor.interface.js';
+/**
+ * ToolMessage — 注入到 Graph State 的 Tool 结果消息结构
+ *
+ * 遵循 LLM function-calling 协议，通过 toolCallId 让 LLM 将结果
+ * 与其原始 tool_calls 请求关联匹配。
+ */
+export interface ToolMessage extends GraphMessage {
+    /** 固定为 'tool' */
+    role: 'tool';
+    /** Tool 执行结果内容（成功时为结果，失败时为错误信息） */
+    content: string;
+    /** 对应的 tool_call ID，LLM 用此匹配原始请求 */
+    toolCallId: string;
+    /** Tool 名称（辅助调试/Trace） */
+    toolName: string;
+    /** 是否执行成功 */
+    success: boolean;
+}
+/**
+ * ToolResultInjector — Tool 结果注入到 Graph State
+ *
+ * 职责：
+ * 1. 将 ToolCallResult[] 转换为 ToolMessage[]
+ * 2. 追加到 GraphState.messages 末尾
+ * 3. 返回新的 GraphState（不可变更新），供下一轮 LLM 推理使用
+ */
+export declare class ToolResultInjector {
+    /**
+     * 将 Tool 执行结果注入到 Graph State 中
+     *
+     * 每个 ToolCallResult 转换为一条 role='tool' 的消息，包含：
+     * - toolCallId: 供 LLM 匹配原始 tool_calls 请求
+     * - content: 成功时为 result.content，失败时为错误描述
+     * - toolName/success: 辅助信息
+     *
+     * 返回全新的 GraphState 对象（不修改原始 state），
+     * 确保 Graph 执行的不可变语义。
+     *
+     * @param state - 当前 Graph State
+     * @param results - Tool 调用结果列表
+     * @returns 包含 Tool 结果消息的新 GraphState
+     */
+    injectResults(state: GraphState, results: ToolCallResult[]): GraphState;
+    /**
+     * 将单个 ToolCallResult 转换为 ToolMessage
+     *
+     * 失败时 content 为格式化的错误信息，方便 LLM 理解并决策下一步。
+     */
+    private buildToolMessage;
+}

package/dist/tool/tool-result-injector.js

@@ -0,0 +1,65 @@
+/**
+ * ToolResultInjector — Tool 结果注入服务
+ *
+ * 将 Tool 执行结果写回 Graph State，作为 'tool' 角色消息追加到消息历史中，
+ * 从而触发下一轮 LLM 推理（ReAct 循环）。
+ *
+ * 流程：LLM → ToolCall → Tool执行 → **结果注入State** → LLM再次推理 → ... → 最终回复
+ *
+ * @see design.md §1.1 结果注入: Tool结果写回Graph State
+ * @see design.md §1.2 Tool结果注入State → 回到LLM节点（ReAct循环）
+ * @see requirements.md Requirement 8 AC4
+ */
+// ─────────────────────────────────────────────
+// ToolResultInjector
+// ─────────────────────────────────────────────
+/**
+ * ToolResultInjector — Tool 结果注入到 Graph State
+ *
+ * 职责：
+ * 1. 将 ToolCallResult[] 转换为 ToolMessage[]
+ * 2. 追加到 GraphState.messages 末尾
+ * 3. 返回新的 GraphState（不可变更新），供下一轮 LLM 推理使用
+ */
+export class ToolResultInjector {
+    /**
+     * 将 Tool 执行结果注入到 Graph State 中
+     *
+     * 每个 ToolCallResult 转换为一条 role='tool' 的消息，包含：
+     * - toolCallId: 供 LLM 匹配原始 tool_calls 请求
+     * - content: 成功时为 result.content，失败时为错误描述
+     * - toolName/success: 辅助信息
+     *
+     * 返回全新的 GraphState 对象（不修改原始 state），
+     * 确保 Graph 执行的不可变语义。
+     *
+     * @param state - 当前 Graph State
+     * @param results - Tool 调用结果列表
+     * @returns 包含 Tool 结果消息的新 GraphState
+     */
+    injectResults(state, results) {
+        const toolMessages = results.map((result) => this.buildToolMessage(result));
+        return {
+            ...state,
+            messages: [...state.messages, ...toolMessages],
+        };
+    }
+    /**
+     * 将单个 ToolCallResult 转换为 ToolMessage
+     *
+     * 失败时 content 为格式化的错误信息，方便 LLM 理解并决策下一步。
+     */
+    buildToolMessage(result) {
+        const content = result.success
+            ? result.content
+            : `[Tool Error] ${result.error ?? 'Unknown error'}`;
+        return {
+            role: 'tool',
+            content,
+            toolCallId: result.toolCallId,
+            toolName: result.toolName,
+            success: result.success,
+            ...(result.file ? { file: result.file } : {}),
+        };
+    }
+}

package/dist/utils/format-error.d.ts

@@ -0,0 +1,4 @@
+/**
+ * 将未知异常格式化为可读字符串 — 委托 @gt-fe/eap-contracts
+ */
+export { formatUnknownError } from '@gt-fe/eap-contracts';

package/dist/utils/format-error.js

@@ -0,0 +1,4 @@
+/**
+ * 将未知异常格式化为可读字符串 — 委托 @gt-fe/eap-contracts
+ */
+export { formatUnknownError } from '@gt-fe/eap-contracts';

package/dist/utils/http-error.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Runtime HTTP 错误出口 — 对齐 @gt-fe/eap-contracts ErrorCodes / AppError
+ */
+import { type ErrorCode, type AppError } from '@gt-fe/eap-contracts';
+import type { ServerResponse } from 'node:http';
+/** 公共 classify；连接失败不再误标为 GOVERNANCE_UNAVAILABLE */
+export declare function classifyRuntimeError(error: unknown): AppError;
+export declare function runtimeErrorCode(error: unknown): ErrorCode;
+export declare function sendErrorJson(res: ServerResponse, error: unknown, options?: {
+    traceId?: string;
+}): void;

package/dist/utils/http-error.js

@@ -0,0 +1,24 @@
+/**
+ * Runtime HTTP 错误出口 — 对齐 @gt-fe/eap-contracts ErrorCodes / AppError
+ */
+import { classifyError, formatUnknownError, ErrorCodes, } from '@gt-fe/eap-contracts';
+/** 公共 classify；连接失败不再误标为 GOVERNANCE_UNAVAILABLE */
+export function classifyRuntimeError(error) {
+    return classifyError(error);
+}
+export function runtimeErrorCode(error) {
+    return classifyRuntimeError(error).code;
+}
+export function sendErrorJson(res, error, options) {
+    if (res.writableEnded || res.headersSent) {
+        console.error('Error after response started:', formatUnknownError(error));
+        return;
+    }
+    const appErr = classifyRuntimeError(error);
+    if (appErr.code === ErrorCodes.PLATFORM_INTERNAL_UNEXPECTED) {
+        console.error('Runtime internal error:', formatUnknownError(error), error);
+    }
+    const body = appErr.toApiResponse(options?.traceId);
+    res.writeHead(appErr.httpStatus, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify(body));
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@gt-fe/eap-runtime",
+  "version": "0.0.8",
+  "description": "Enterprise Agent Platform — Runtime核心：Graph执行引擎、Task生命周期、Session管理、Checkpoint持久化",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/server.js",
+    "dev": "npx tsx src/server.ts",
+    "clean": "rm -rf dist",
+    "lint": "eslint src --ext .ts",
+    "test": "vitest run"
+  },
+  "keywords": [
+    "eap",
+    "runtime",
+    "agent",
+    "langgraph",
+    "graph-engine"
+  ],
+  "license": "UNLICENSED",
+  "dependencies": {
+    "@langchain/langgraph": "^0.2.0",
+    "amqplib": "^0.10.0",
+    "ioredis": "^5.4.0",
+    "pg": "^8.13.0",
+    "yaml": "^2.6.1",
+    "@gt-fe/eap-contracts": "0.0.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "esbuild"
+    ]
+  },
+  "packageManager": "pnpm@9.15.9"
+}