@gt-fe/eap-runtime 0.0.8

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

@@ -0,0 +1,37 @@
+/**
+ * LocalToolExecutor — 桌面本地 Code / MCP Tool 执行
+ *
+ * 优先 ILocalToolInstallStore；若无安装记录但 request.execution 带
+ * localPreferred / skill-script（或可解析的 code bundlePath+handler），则直接本机执行。
+ */
+import type { ILocalToolInstallStore } from '@gt-fe/eap-contracts';
+import type { IToolExecutor, ToolCallRequest, ToolCallResult } from './tool-executor.interface.js';
+import { type ILocalMcpClient } from './local-mcp-client.js';
+export interface LocalToolExecutorOptions {
+    installStore: ILocalToolInstallStore;
+    mcpClient?: ILocalMcpClient;
+    defaultHandler?: string;
+    timeoutMs?: number;
+}
+interface CodeExecutionSpec {
+    handlerPath: string;
+    runtime?: string;
+    args?: string[];
+    timeoutMs?: number;
+}
+/** 是否为应本机执行的 Skill script / 显式 localPreferred code execution */
+export declare function isLocalPreferredExecution(raw: unknown): boolean;
+/**
+ * 从 ToolCallRequest.execution 解析本机 code 执行规格（Skill scripts 等）。
+ */
+export declare function resolveCodeExecutionFromRequest(request: ToolCallRequest): CodeExecutionSpec | null;
+export declare class LocalToolExecutor implements IToolExecutor {
+    private readonly options;
+    private readonly mcpClient;
+    constructor(options: LocalToolExecutorOptions);
+    execute(request: ToolCallRequest): Promise<ToolCallResult>;
+    private executeCodeSpec;
+    private executeCode;
+    private executeMcp;
+}
+export {};

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

@@ -0,0 +1,249 @@
+/**
+ * LocalToolExecutor — 桌面本地 Code / MCP Tool 执行
+ *
+ * 优先 ILocalToolInstallStore；若无安装记录但 request.execution 带
+ * localPreferred / skill-script（或可解析的 code bundlePath+handler），则直接本机执行。
+ */
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { resolveReadyInstallByToolName, resolveMcpExecutionFromInstall, resolveCodeHandlerFromInstall, } from '@gt-fe/eap-contracts';
+import { fileArtifactFromToolOutput, fileBasesFromEnv } from './file-artifact.js';
+import { LocalMcpClient } from './local-mcp-client.js';
+/**
+ * 根据 execution.runtime 解析执行命令：
+ * - node（默认）→ process.execPath + [handlerPath]
+ * - python → python3 + [handlerPath]
+ * - executable → handlerPath 本身为可执行文件 + args
+ */
+function resolveCommand(handlerPath, execution) {
+    const runtime = execution?.runtime;
+    switch (runtime) {
+        case 'python':
+            return { cmd: 'python3', args: [handlerPath, ...(execution?.args ?? [])] };
+        case 'executable':
+            return { cmd: handlerPath, args: execution?.args ?? [] };
+        case 'node':
+        default:
+            return { cmd: process.execPath, args: [handlerPath, ...(execution?.args ?? [])] };
+    }
+}
+function formatCodeLaunchError(err, spec) {
+    const code = err && typeof err === 'object' && 'code' in err
+        ? String(err.code)
+        : '';
+    const runtime = spec.runtime === 'python' || spec.runtime === 'executable' ? spec.runtime : 'node';
+    if (code === 'ENOENT') {
+        if (runtime === 'python') {
+            return new Error(`找不到 python3（tools[].runtime=python）。请安装 Python 3，并保证 python3 在 PATH 中。handler=${spec.handlerPath}`);
+        }
+        if (runtime === 'executable') {
+            return new Error(`找不到可执行文件 ${spec.cmd}（tools[].runtime=executable）。请确认文件存在、已 chmod +x，且匹配当前操作系统/架构。`);
+        }
+        return new Error(`找不到 Node 或 handler 文件：${spec.handlerPath}`);
+    }
+    if (code === 'EACCES') {
+        return new Error(`没有执行权限：${spec.cmd}。请 chmod +x 后重试。`);
+    }
+    return new Error(err instanceof Error ? err.message : String(err));
+}
+function runHandler(handlerPath, input, timeoutMs, execution) {
+    if (!existsSync(handlerPath)) {
+        return Promise.reject(new Error(`找不到 handler 文件：${handlerPath}。请检查 toolset.manifest.json 的 tools[].handler 与工具目录。`));
+    }
+    const { cmd, args } = resolveCommand(handlerPath, execution);
+    return new Promise((resolve, reject) => {
+        const child = spawn(cmd, args, { stdio: ['pipe', 'pipe', 'pipe'] });
+        let stdout = '';
+        let stderr = '';
+        let settled = false;
+        const finish = (fn) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            fn();
+        };
+        const timer = setTimeout(() => {
+            child.kill('SIGKILL');
+            finish(() => reject(new Error(`Local tool timeout after ${timeoutMs}ms`)));
+        }, timeoutMs);
+        child.stdout.on('data', (d) => { stdout += d.toString(); });
+        child.stderr.on('data', (d) => { stderr += d.toString(); });
+        child.on('error', (err) => {
+            finish(() => reject(formatCodeLaunchError(err, {
+                runtime: execution?.runtime,
+                cmd,
+                handlerPath,
+            })));
+        });
+        child.on('close', (code) => {
+            if (code === 0) {
+                finish(() => resolve(stdout.trim()));
+                return;
+            }
+            finish(() => reject(new Error(stderr.trim() || `code 工具退出码 ${code}`)));
+        });
+        child.stdin.write(JSON.stringify(input ?? {}));
+        child.stdin.end();
+    });
+}
+/** 是否为应本机执行的 Skill script / 显式 localPreferred code execution */
+export function isLocalPreferredExecution(raw) {
+    if (!raw || typeof raw !== 'object')
+        return false;
+    const e = raw;
+    if (e.protocol === 'mcp')
+        return false;
+    if (e.localPreferred === true || e.source === 'skill-script')
+        return true;
+    return false;
+}
+/**
+ * 从 ToolCallRequest.execution 解析本机 code 执行规格（Skill scripts 等）。
+ */
+export function resolveCodeExecutionFromRequest(request) {
+    const raw = request.execution;
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const e = raw;
+    if (e.protocol === 'mcp')
+        return null;
+    const runtime = typeof e.runtime === 'string' ? e.runtime : undefined;
+    const bundlePath = typeof e.bundlePath === 'string' ? e.bundlePath : undefined;
+    const handler = typeof e.handler === 'string' ? e.handler : '';
+    const command = typeof e.command === 'string' ? e.command : undefined;
+    const args = Array.isArray(e.args) ? e.args.map(String) : undefined;
+    const timeoutMs = typeof e.timeout === 'number' && e.timeout > 0 ? e.timeout : undefined;
+    if (runtime === 'executable') {
+        const handlerPath = handler
+            ? (path.isAbsolute(handler) || !bundlePath
+                ? handler
+                : path.resolve(bundlePath, handler.replace(/^\.\//, '')))
+            : (command ?? '');
+        if (!handlerPath)
+            return null;
+        return { handlerPath, runtime: 'executable', args, timeoutMs };
+    }
+    if (!handler)
+        return null;
+    const handlerPath = bundlePath
+        ? path.resolve(bundlePath, handler.replace(/^\.\//, ''))
+        : path.resolve(handler);
+    return {
+        handlerPath,
+        runtime: runtime ?? (command === 'python3' || command === 'python' ? 'python' : 'node'),
+        args,
+        timeoutMs,
+    };
+}
+export class LocalToolExecutor {
+    options;
+    mcpClient;
+    constructor(options) {
+        this.options = options;
+        this.mcpClient = options.mcpClient ?? new LocalMcpClient();
+    }
+    async execute(request) {
+        const install = resolveReadyInstallByToolName(this.options.installStore, request.toolName);
+        if (install && install.installStatus === 'ready') {
+            const toolType = install.type ?? request.toolType ?? 'code';
+            if (toolType === 'mcp') {
+                return this.executeMcp(request, install);
+            }
+            return this.executeCode(request, install);
+        }
+        // 无本地安装：仅 Skill scripts / localPreferred 走 request.execution
+        if (isLocalPreferredExecution(request.execution)) {
+            const fromReq = resolveCodeExecutionFromRequest(request);
+            if (fromReq) {
+                return this.executeCodeSpec(request, fromReq);
+            }
+        }
+        return {
+            toolCallId: request.toolCallId,
+            toolName: request.toolName,
+            content: '',
+            success: false,
+            error: `Tool not installed locally: ${request.toolName}`,
+            errorCode: 'NOT_INSTALLED',
+            runtime: 'local',
+        };
+    }
+    async executeCodeSpec(request, spec) {
+        try {
+            const stdout = await runHandler(spec.handlerPath, request.arguments, spec.timeoutMs ?? this.options.timeoutMs ?? 30_000, { runtime: spec.runtime, args: spec.args });
+            return {
+                toolCallId: request.toolCallId,
+                toolName: request.toolName,
+                content: stdout,
+                success: true,
+                runtime: 'local',
+                file: fileArtifactFromToolOutput(stdout, fileBasesFromEnv()),
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+                toolCallId: request.toolCallId,
+                toolName: request.toolName,
+                content: '',
+                success: false,
+                error: message,
+                errorCode: 'EXECUTION_FAILED',
+                runtime: 'local',
+            };
+        }
+    }
+    async executeCode(request, install) {
+        const handlerFile = resolveCodeHandlerFromInstall(install)
+            ?? this.options.defaultHandler
+            ?? 'handler.js';
+        const handlerPath = path.resolve(install.bundlePath, handlerFile.replace(/^\.\//, ''));
+        const execution = install.execution;
+        return this.executeCodeSpec(request, {
+            handlerPath,
+            runtime: execution?.runtime,
+            args: execution?.args,
+        });
+    }
+    async executeMcp(request, install) {
+        const execution = resolveMcpExecutionFromInstall(install);
+        if (!execution?.toolName) {
+            return {
+                toolCallId: request.toolCallId,
+                toolName: request.toolName,
+                content: '',
+                success: false,
+                error: `MCP execution not configured for: ${request.toolName}`,
+                errorCode: 'NOT_CONFIGURED',
+                runtime: 'local',
+            };
+        }
+        try {
+            const { content, file } = await this.mcpClient.invoke(execution, request.arguments, {
+                userId: request.authContext?.userId,
+            });
+            return {
+                toolCallId: request.toolCallId,
+                toolName: request.toolName,
+                content,
+                success: true,
+                runtime: 'local',
+                file,
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+                toolCallId: request.toolCallId,
+                toolName: request.toolName,
+                content: '',
+                success: false,
+                error: message,
+                errorCode: 'EXECUTION_FAILED',
+                runtime: 'local',
+            };
+        }
+    }
+}

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

@@ -0,0 +1,23 @@
+/**
+ * McpToolExecutor — Runtime → Tool Gateway 正式 MCP 出站（JSON-RPC over HTTP）
+ *
+ * @see docs/contracts/tool-execution.md §2.0
+ */
+import type { IToolExecutor, ToolCallRequest, ToolCallResult } from './tool-executor.interface.js';
+export interface McpToolExecutorOptions {
+    baseUrl: string;
+    timeout?: number;
+    /** MCP 入口路径，默认 /api/v1/mcp */
+    mcpPath?: string;
+}
+export declare class McpToolExecutor implements IToolExecutor {
+    private readonly baseUrl;
+    private readonly timeout;
+    private readonly mcpUrl;
+    private rpcId;
+    private initialized;
+    constructor(options: McpToolExecutorOptions);
+    execute(request: ToolCallRequest): Promise<ToolCallResult>;
+    private ensureInitialized;
+    private postRpc;
+}

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

@@ -0,0 +1,160 @@
+/**
+ * McpToolExecutor — Runtime → Tool Gateway 正式 MCP 出站（JSON-RPC over HTTP）
+ *
+ * @see docs/contracts/tool-execution.md §2.0
+ */
+function resolveAgentCode(request) {
+    return request.authContext.agentCode ?? request.authContext.agentId;
+}
+function formatContent(result) {
+    const text = result?.content?.[0]?.text;
+    if (text != null)
+        return text;
+    return JSON.stringify(result ?? {});
+}
+function mapMcpError(status, body) {
+    const eapCode = body?.error?.data?.eapCode;
+    const message = body?.error?.message ?? `HTTP ${status}`;
+    if (status === 403 || eapCode?.includes('forbidden') || eapCode?.includes('auth')) {
+        return { error: message, errorCode: eapCode ?? 'NO_PERMISSION', retryable: false };
+    }
+    if (status === 429) {
+        return { error: message, errorCode: eapCode ?? 'RATE_LIMITED', retryable: true };
+    }
+    if (status === 503) {
+        return { error: message, errorCode: eapCode ?? 'CIRCUIT_OPEN', retryable: true };
+    }
+    if (status === 404) {
+        return { error: message, errorCode: eapCode ?? 'TOOL_NOT_FOUND', retryable: false };
+    }
+    if (status === 400) {
+        return { error: message, errorCode: eapCode ?? 'INVALID_ARGUMENTS', retryable: false };
+    }
+    return { error: message, errorCode: eapCode ?? 'EXECUTION_FAILED', retryable: false };
+}
+export class McpToolExecutor {
+    baseUrl;
+    timeout;
+    mcpUrl;
+    rpcId = 1;
+    initialized = false;
+    constructor(options) {
+        this.baseUrl = options.baseUrl.replace(/\/+$/, '');
+        this.timeout = options.timeout ?? 30_000;
+        const path = options.mcpPath ?? '/api/v1/mcp';
+        this.mcpUrl = `${this.baseUrl}${path.startsWith('/') ? path : `/${path}`}`;
+    }
+    async execute(request) {
+        try {
+            await this.ensureInitialized(request);
+            const agentCode = resolveAgentCode(request);
+            const correlationId = request.correlationId ?? request.toolCallId;
+            const id = this.rpcId++;
+            const response = await this.postRpc({
+                jsonrpc: '2.0',
+                id,
+                method: 'tools/call',
+                params: {
+                    name: request.toolName,
+                    arguments: request.arguments,
+                },
+            }, request, agentCode, correlationId);
+            if (!response.ok) {
+                let body = null;
+                try {
+                    body = (await response.json());
+                }
+                catch {
+                    body = null;
+                }
+                const mapped = mapMcpError(response.status, body);
+                return {
+                    toolCallId: request.toolCallId,
+                    toolName: request.toolName,
+                    content: '',
+                    success: false,
+                    runtime: 'server',
+                    ...mapped,
+                };
+            }
+            const body = (await response.json());
+            if (body.error) {
+                const mapped = mapMcpError(500, body);
+                return {
+                    toolCallId: request.toolCallId,
+                    toolName: request.toolName,
+                    content: '',
+                    success: false,
+                    runtime: 'server',
+                    ...mapped,
+                };
+            }
+            return {
+                toolCallId: request.toolCallId,
+                toolName: request.toolName,
+                content: formatContent(body.result),
+                success: true,
+                runtime: 'server',
+            };
+        }
+        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',
+                retryable: false,
+                runtime: 'server',
+            };
+        }
+    }
+    async ensureInitialized(request) {
+        if (this.initialized)
+            return;
+        const agentCode = resolveAgentCode(request);
+        const correlationId = request.correlationId ?? request.toolCallId;
+        const id = this.rpcId++;
+        const response = await this.postRpc({
+            jsonrpc: '2.0',
+            id,
+            method: 'initialize',
+            params: {
+                protocolVersion: '2024-11-05',
+                capabilities: {},
+                clientInfo: { name: 'eap-runtime', version: '0.1.0' },
+            },
+        }, request, agentCode, correlationId);
+        if (!response.ok) {
+            throw new Error(`MCP initialize failed: HTTP ${response.status}`);
+        }
+        this.initialized = true;
+    }
+    async postRpc(payload, request, agentCode, correlationId) {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+        try {
+            return await fetch(this.mcpUrl, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    Authorization: `Bearer ${request.authContext.delegationToken}`,
+                    'X-Agent-Code': agentCode,
+                    'X-Agent-Id': agentCode,
+                    'X-User-Id': request.authContext.userId,
+                    // 上游 mcp-data-service 认 `userId`；Gateway 侧亦保留 X-User-Id
+                    userId: request.authContext.userId,
+                    'X-Correlation-Id': correlationId,
+                    ...(request.taskId ? { 'X-Task-Id': request.taskId } : {}),
+                },
+                body: JSON.stringify(payload),
+                signal: controller.signal,
+            });
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
+}

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

@@ -0,0 +1,28 @@
+/**
+ * MockToolExecutor — 本地开发模式的模拟 Tool 执行器
+ *
+ * 定位：`eap dev --tool-mode mock` 场景下替代真实 Gateway/Local 执行器，
+ * 让 Agent 开发者在无 foundation-service、无真实 Tool 依赖的前提下跑通 Graph。
+ *
+ * 响应查找顺序：
+ * 1. `${toolsDir}/<toolName>/mock.json`（用户自定义 Mock 响应）
+ * 2. `${toolsDir}/<toolName>/tool.manifest.json` 内嵌 `mockResponse` 字段
+ * 3. 兜底 echo：`{ toolName, arguments, note: "mock" }`
+ *
+ * 使用示例：
+ *   const executor = new MockToolExecutor({ toolsDir: './tools' });
+ */
+import type { IToolExecutor, ToolCallRequest, ToolCallResult } from './tool-executor.interface.js';
+export interface MockToolExecutorOptions {
+    /** 本地 tools 根目录，默认 `./tools` 或读 `EAP_LOCAL_TOOLS_DIR` */
+    toolsDir?: string;
+    /** Mock 响应可自定义 delay，用于验证 SSE/流式表现 */
+    delayMs?: number;
+}
+export declare class MockToolExecutor implements IToolExecutor {
+    private readonly toolsDir;
+    private readonly delayMs;
+    constructor(options?: MockToolExecutorOptions);
+    execute(request: ToolCallRequest): Promise<ToolCallResult>;
+    private resolveMockResponse;
+}

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

@@ -0,0 +1,65 @@
+/**
+ * MockToolExecutor — 本地开发模式的模拟 Tool 执行器
+ *
+ * 定位：`eap dev --tool-mode mock` 场景下替代真实 Gateway/Local 执行器，
+ * 让 Agent 开发者在无 foundation-service、无真实 Tool 依赖的前提下跑通 Graph。
+ *
+ * 响应查找顺序：
+ * 1. `${toolsDir}/<toolName>/mock.json`（用户自定义 Mock 响应）
+ * 2. `${toolsDir}/<toolName>/tool.manifest.json` 内嵌 `mockResponse` 字段
+ * 3. 兜底 echo：`{ toolName, arguments, note: "mock" }`
+ *
+ * 使用示例：
+ *   const executor = new MockToolExecutor({ toolsDir: './tools' });
+ */
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+async function readJsonFile(filePath) {
+    try {
+        const raw = await readFile(filePath, 'utf-8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+}
+export class MockToolExecutor {
+    toolsDir;
+    delayMs;
+    constructor(options = {}) {
+        this.toolsDir =
+            options.toolsDir ?? process.env.EAP_LOCAL_TOOLS_DIR ?? './tools';
+        this.delayMs = options.delayMs ?? 0;
+    }
+    async execute(request) {
+        if (this.delayMs > 0) {
+            await new Promise((r) => setTimeout(r, this.delayMs));
+        }
+        const mockResponse = await this.resolveMockResponse(request.toolName);
+        const payload = mockResponse ?? {
+            toolName: request.toolName,
+            arguments: request.arguments,
+            note: 'mock: no explicit mockResponse found, echoing arguments',
+        };
+        return {
+            toolCallId: request.toolCallId,
+            toolName: request.toolName,
+            content: typeof payload === 'string' ? payload : JSON.stringify(payload),
+            success: true,
+            runtime: 'mock',
+        };
+    }
+    async resolveMockResponse(toolName) {
+        const toolDir = path.join(this.toolsDir, toolName);
+        // 优先级 1：独立 mock.json
+        const explicit = await readJsonFile(path.join(toolDir, 'mock.json'));
+        if (explicit !== undefined)
+            return explicit;
+        // 优先级 2：manifest 内嵌 mockResponse
+        const manifest = (await readJsonFile(path.join(toolDir, 'tool.manifest.json')));
+        if (manifest && manifest.mockResponse !== undefined) {
+            return manifest.mockResponse;
+        }
+        return undefined;
+    }
+}

package/dist/tool/system-prompt-builder.d.ts

@@ -0,0 +1,114 @@
+/**
+ * SystemPromptBuilder — 系统级提示词拼接（RT-5）
+ *
+ * 职责极简：代码常量 + 配置透传 + 字符串拼接。
+ *
+ * 输出结构：
+ * ```
+ * [平台规则常量]          ← 代码内置，安全约束 + 行为准则（最高优先级）
+ * [当前时间]              ← 运行时动态注入（自然周等时间规则的判定基准）
+ * [Agent 身份]            ← agentName / agentCode
+ * [开发者提示词]          ← Graph LLM 节点 config.systemPrompt，平台透传
+ *                           （Registry 无内嵌 Graph 的兜底路径读 agent.manifest.json prompts.system）
+ * ```
+ *
+ * Tools 不经过本类，走 API 的 tools 参数（见 loadedToolsToApiTools）。
+ *
+ * @see docs/status/module-status-and-backlog.md RT-5
+ */
+import type { LoadedToolMap } from './loaded-tool-definition.js';
+import type { LLMToolDefinition } from '../graph/nodes/llm-node.js';
+/**
+
+ * 已装配 Skill 定义（由 GraphLoader 从预装快照加载）
+ * workflow / prompt 供子图按 skillId 解析与入口提示注入
+ */
+export interface LoadedSkillInfo {
+    skillId: string;
+    name: string;
+    description?: string;
+    version?: string;
+    /** Skill 工作流（GraphDSL）；缺省时子图节点须自带 subgraphDsl */
+    workflow?: import('../graph/contracts/executable-graph.js').GraphDSL;
+    /** 注入子图入口 LLM 系统上下文 */
+    prompt?: string;
+    toolRefs?: Array<string | {
+        toolId?: string;
+        name?: string;
+        version?: string;
+        toolset?: string;
+        enabledTools?: string[];
+        autoApprove?: string[];
+    }>;
+    inputDef?: unknown;
+    outputDef?: unknown;
+    /** Skill 包 scripts[] 物化出的虚拟 Tool（装配时并入 loadedTools） */
+    scriptTools?: import('./loaded-tool-definition.js').LoadedToolDefinition[];
+}
+/** skillId → 完整定义 */
+export type LoadedSkillMap = Record<string, LoadedSkillInfo>;
+export declare function toLoadedSkillMap(skills: LoadedSkillInfo[] | undefined): LoadedSkillMap | undefined;
+/**
+ * 将各 Skill 的 scripts 虚拟 Tool 并入 loadedTools（同名不覆盖平台 Tool）。
+ * 装配点（invoke/stream/fork）在构造 GraphState 前调用。
+ */
+export declare function mergeSkillScriptTools(loadedTools: LoadedToolMap | undefined, skills: LoadedSkillInfo[] | undefined): LoadedToolMap | undefined;
+/**
+ * 按 Skill.toolRefs 收窄工具集。
+ * - 无 toolRefs / 空数组：不收窄（保持 Agent 全量，兼容旧 Skill）
+ * - string / name / toolId：精确匹配工具名
+ * - toolset + enabledTools：仅白名单子工具
+ * - toolset 无 enabledTools：匹配 toolId 前缀 `<toolset>:` 或 id 等于 toolset
+ * - 始终保留该 Skill 的 scriptTools
+ */
+export declare function filterLoadedToolsForSkill(loadedTools: LoadedToolMap | undefined, skill: LoadedSkillInfo | undefined): LoadedToolMap | undefined;
+/**
+ * 提示词构建上下文
+ */
+export interface PromptBuildContext {
+    /**
+     * 开发者编写的系统提示词。
+     * 来源：Graph LLM 节点 config.systemPrompt（主路径）；
+     * Registry 无内嵌 Graph 的兜底路径为 agent.manifest.json prompts.system。
+     */
+    developerPrompt?: string;
+    /** Agent 名称 */
+    agentName?: string;
+    /** Agent 代码标识 */
+    agentCode?: string;
+    /** 当前调用用户标识（可选，供「我 / 我的」类指代） */
+    userId?: string | null;
+}
+/**
+ * SystemPromptBuilder — 系统提示词拼接
+ *
+ * 四段式拼接：平台规则 + 当前时间 + Agent 身份 + 开发者提示词。
+ * 不注入工具列表（工具走 API tools 参数）。
+ * 不支持模板变量替换（开发者直接写最终文本）。
+ */
+export declare class SystemPromptBuilder {
+    /**
+     * 构建完整系统提示词
+     */
+    build(context: PromptBuildContext): string;
+    private buildCurrentTime;
+    private buildAgentIdentity;
+}
+/**
+ * OpenAI function-calling tool definition（API tools 参数格式）
+ *
+ * 与 LLMNode 的 LLMToolDefinition 结构一致，此处作为别名导出，
+ * 方便 tool 模块的使用者按领域引用。
+ */
+export type ApiToolDefinition = LLMToolDefinition;
+/**
+ * 将平台的 LoadedToolMap 转为 OpenAI API 的 tools 参数
+ *
+ * 工具通过 API 的 tools 参数传入 LLM，不嵌入 system prompt。
+ * 可按需传入 skillTools 过滤子集（只暴露当前 Skill 需要的工具）。
+ *
+ * @param loadedTools - 已装配的工具映射
+ * @param skillTools - 可选，当前 Skill 所需的工具名称列表（过滤子集）
+ * @returns OpenAI API tools 参数数组
+ */
+export declare function loadedToolsToApiTools(loadedTools: LoadedToolMap | undefined, skillTools?: string[]): ApiToolDefinition[];