@gt-fe/eap-runtime 0.0.8 → 0.0.11

package/dist/tool/local-mcp-client.js

@@ -6,6 +6,7 @@
  */
 import { spawn } from 'node:child_process';
 import readline from 'node:readline';
+import { isAbortError, resolveToolTimeoutSec, toToolTimeoutMs, toolTimeoutErrorMessage, } from './timeout.js';
 import { fileArtifactFromToolOutput, fileBasesFromEnv } from './file-artifact.js';
 export function formatMcpOutput(result) {
     const r = result;
@@ -70,10 +71,13 @@ function withUserMeta(params, userId) {
 function rpcStdio(session, method, params) {
     const id = session.nextId++;
     const timeoutMs = session.timeoutMs;
+    const timeoutSec = Math.max(1, Math.round(timeoutMs / 1000));
     return new Promise((resolve, reject) => {
         const timer = setTimeout(() => {
             session.pending.delete(id);
-            reject(new Error(`MCP RPC timeout: ${method}`));
+            const err = new Error(toolTimeoutErrorMessage(timeoutSec));
+            err.name = 'TimeoutError';
+            reject(err);
         }, timeoutMs);
         session.pending.set(id, {
             resolve: (v) => { clearTimeout(timer); resolve(v); },
@@ -86,7 +90,7 @@ async function invokeStdio(execution, args, context) {
     const { server } = execution;
     const command = server.command ?? 'node';
     const spawnArgs = server.args ?? [];
-    const timeoutMs = execution.timeout ?? 30_000;
+    const timeoutMs = toToolTimeoutMs(execution.timeout);
     const userId = resolveUserId(execution, context);
     const child = spawn(command, spawnArgs, {
         stdio: ['pipe', 'pipe', 'pipe'],
@@ -138,12 +142,32 @@ async function invokeStdio(execution, args, context) {
         rl.close();
     }
 }
+async function postMcp(url, headers, payload, signal) {
+    const response = await fetch(url, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify(payload),
+        signal,
+    });
+    const sessionId = response.headers.get('mcp-session-id') ?? undefined;
+    const raw = await response.text();
+    if (!response.ok) {
+        const snippet = raw.replace(/\s+/g, ' ').trim().slice(0, 240);
+        throw new Error(`MCP HTTP ${response.status}: ${response.statusText}${snippet ? ` ${snippet}` : ''}`);
+    }
+    const body = parseMcpHttpBody(raw);
+    if (body.error) {
+        throw new Error(body.error.message ?? 'MCP HTTP error');
+    }
+    return { body, sessionId };
+}
 async function invokeStreamableHttp(execution, args, context) {
     const url = expandEnvRefs(execution.server.url);
     if (!url) {
         throw new Error('streamable_http MCP requires server.url');
     }
-    const timeoutMs = execution.timeout ?? 30_000;
+    const timeoutSec = resolveToolTimeoutSec(execution.timeout);
+    const timeoutMs = toToolTimeoutMs(timeoutSec);
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), timeoutMs);
     const userId = resolveUserId(execution, context);
@@ -161,28 +185,35 @@ async function invokeStreamableHttp(execution, args, context) {
     if (userId) {
         headers.userId = userId;
     }
-    const body = {
-        jsonrpc: '2.0',
-        id: 1,
-        method: 'tools/call',
-        params: withUserMeta({ name: execution.toolName, arguments: args }, userId),
-    };
     try {
-        const response = await fetch(url, {
-            method: 'POST',
-            headers,
-            body: JSON.stringify(body),
-            signal: controller.signal,
-        });
-        if (!response.ok) {
-            throw new Error(`MCP HTTP ${response.status}: ${response.statusText}`);
-        }
-        const raw = await response.text();
-        const payload = parseMcpHttpBody(raw);
-        if (payload.error) {
-            throw new Error(payload.error.message ?? 'MCP HTTP error');
+        const init = await postMcp(url, headers, {
+            jsonrpc: '2.0',
+            id: 1,
+            method: 'initialize',
+            params: {
+                protocolVersion: '2024-11-05',
+                capabilities: {},
+                clientInfo: { name: 'eap-runtime-local', version: '0.1.0' },
+            },
+        }, controller.signal);
+        const callHeaders = { ...headers };
+        if (init.sessionId)
+            callHeaders['mcp-session-id'] = init.sessionId;
+        const call = await postMcp(url, callHeaders, {
+            jsonrpc: '2.0',
+            id: 2,
+            method: 'tools/call',
+            params: withUserMeta({ name: execution.toolName, arguments: args }, userId),
+        }, controller.signal);
+        return toInvokeResult(call.body.result, execution.server.env);
+    }
+    catch (err) {
+        if (isAbortError(err)) {
+            const timeoutErr = new Error(toolTimeoutErrorMessage(timeoutSec));
+            timeoutErr.name = 'TimeoutError';
+            throw timeoutErr;
         }
-        return toInvokeResult(payload.result, execution.server.env);
+        throw err instanceof Error ? err : new Error(String(err));
     }
     finally {
         clearTimeout(timer);

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

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

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

@@ -2,12 +2,13 @@
  * LocalToolExecutor — 桌面本地 Code / MCP Tool 执行
  *
  * 优先 ILocalToolInstallStore；若无安装记录但 request.execution 带
- * localPreferred / skill-script（或可解析的 code bundlePath+handler），则直接本机执行。
+ * 或 request.execution 带可解析的 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 { ErrorCodes, resolveReadyInstallByToolName, resolveMcpExecutionFromInstall, resolveCodeHandlerFromInstall, } from '@eap/contracts';
+import { isAbortError, toToolTimeoutMs, toolTimeoutErrorMessage } from './timeout.js';
 import { fileArtifactFromToolOutput, fileBasesFromEnv } from './file-artifact.js';
 import { LocalMcpClient } from './local-mcp-client.js';
 /**
@@ -66,7 +67,9 @@ function runHandler(handlerPath, input, timeoutMs, execution) {
         };
         const timer = setTimeout(() => {
             child.kill('SIGKILL');
-            finish(() => reject(new Error(`Local tool timeout after ${timeoutMs}ms`)));
+            const timeoutErr = new Error(toolTimeoutErrorMessage(Math.max(1, Math.round(timeoutMs / 1000))));
+            timeoutErr.name = 'TimeoutError';
+            finish(() => reject(timeoutErr));
         }, timeoutMs);
         child.stdout.on('data', (d) => { stdout += d.toString(); });
         child.stderr.on('data', (d) => { stderr += d.toString(); });
@@ -88,19 +91,17 @@ function runHandler(handlerPath, input, timeoutMs, execution) {
         child.stdin.end();
     });
 }
-/** 是否为应本机执行的 Skill script / 显式 localPreferred code execution */
+/** 是否为应本机执行的 code（显式 localPreferred，例如 DevToolExecutor） */
 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;
+    return e.localPreferred === true;
 }
 /**
- * 从 ToolCallRequest.execution 解析本机 code 执行规格（Skill scripts 等）。
+ * 从 ToolCallRequest.execution 解析本机 code 执行规格。
  */
 export function resolveCodeExecutionFromRequest(request) {
     const raw = request.execution;
@@ -114,7 +115,7 @@ export function resolveCodeExecutionFromRequest(request) {
     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;
+    const timeoutMs = typeof e.timeout === 'number' && e.timeout > 0 ? toToolTimeoutMs(e.timeout) : undefined;
     if (runtime === 'executable') {
         const handlerPath = handler
             ? (path.isAbsolute(handler) || !bundlePath
@@ -153,7 +154,7 @@ export class LocalToolExecutor {
             }
             return this.executeCode(request, install);
         }
-        // 无本地安装：仅 Skill scripts / localPreferred 走 request.execution
+        // 无本地安装：仅显式 localPreferred 走 request.execution
         if (isLocalPreferredExecution(request.execution)) {
             const fromReq = resolveCodeExecutionFromRequest(request);
             if (fromReq) {
@@ -183,14 +184,14 @@ export class LocalToolExecutor {
             };
         }
         catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
+            const aborted = isAbortError(error);
             return {
                 toolCallId: request.toolCallId,
                 toolName: request.toolName,
                 content: '',
                 success: false,
-                error: message,
-                errorCode: 'EXECUTION_FAILED',
+                error: error instanceof Error ? error.message : String(error),
+                errorCode: aborted ? ErrorCodes.TOOL_TIMEOUT : 'EXECUTION_FAILED',
                 runtime: 'local',
             };
         }
@@ -205,6 +206,7 @@ export class LocalToolExecutor {
             handlerPath,
             runtime: execution?.runtime,
             args: execution?.args,
+            timeoutMs: typeof execution?.timeout === 'number' ? toToolTimeoutMs(execution.timeout) : undefined,
         });
     }
     async executeMcp(request, install) {
@@ -234,14 +236,14 @@ export class LocalToolExecutor {
             };
         }
         catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
+            const aborted = isAbortError(error);
             return {
                 toolCallId: request.toolCallId,
                 toolName: request.toolName,
                 content: '',
                 success: false,
-                error: message,
-                errorCode: 'EXECUTION_FAILED',
+                error: error instanceof Error ? error.message : String(error),
+                errorCode: aborted ? ErrorCodes.TOOL_TIMEOUT : 'EXECUTION_FAILED',
                 runtime: 'local',
             };
         }

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

@@ -3,8 +3,10 @@
  *
  * @see docs/contracts/tool-execution.md §2.0
  */
+import { ErrorCodes } from '@eap/contracts';
+import { abortOrTimeoutMessage, isAbortError } from './timeout.js';
 function resolveAgentCode(request) {
-    return request.authContext.agentCode ?? request.authContext.agentId;
+    return request.authContext.agentCode;
 }
 function formatContent(result) {
     const text = result?.content?.[0]?.text;
@@ -14,9 +16,14 @@ function formatContent(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 };
+    const message = (body?.error?.message ?? '').trim() || `HTTP ${status}`;
+    // 仅 HTTP 403 视为权限拒绝。eapCode 含 auth 是 hop 认证失败，不是 C2。
+    if (status === 403) {
+        return {
+            error: message === `HTTP ${status}` ? '用户无该 Tool 执行权限' : message,
+            errorCode: eapCode ?? 'NO_PERMISSION',
+            retryable: false,
+        };
     }
     if (status === 429) {
         return { error: message, errorCode: eapCode ?? 'RATE_LIMITED', retryable: true };
@@ -57,6 +64,12 @@ export class McpToolExecutor {
                 params: {
                     name: request.toolName,
                     arguments: request.arguments,
+                    ...(request.toolVersion
+                        ? {
+                            version: request.toolVersion,
+                            _meta: { version: request.toolVersion },
+                        }
+                        : {}),
                 },
             }, request, agentCode, correlationId);
             if (!response.ok) {
@@ -98,14 +111,15 @@ export class McpToolExecutor {
             };
         }
         catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
+            const timeoutSec = Math.max(1, Math.round(this.timeout / 1000));
+            const aborted = isAbortError(err);
             return {
                 toolCallId: request.toolCallId,
                 toolName: request.toolName,
                 content: '',
                 success: false,
-                error: message,
-                errorCode: 'EXECUTION_FAILED',
+                error: abortOrTimeoutMessage(err, timeoutSec),
+                errorCode: aborted ? ErrorCodes.TOOL_TIMEOUT : 'EXECUTION_FAILED',
                 retryable: false,
                 runtime: 'server',
             };
@@ -140,6 +154,8 @@ export class McpToolExecutor {
                 method: 'POST',
                 headers: {
                     'Content-Type': 'application/json',
+                    // Streamable HTTP：Gateway /mcp 要求同时接受 JSON 与 SSE
+                    Accept: 'application/json, text/event-stream',
                     Authorization: `Bearer ${request.authContext.delegationToken}`,
                     'X-Agent-Code': agentCode,
                     'X-Agent-Id': agentCode,

package/dist/tool/skill-script-refs.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 喂给模型的 SKILL.md 正文展开（不改磁盘）。
+ * 对标 Claude `${CLAUDE_SKILL_DIR}`：作者仍写包内相对路径。
+ * 官方规范不要求脚本必须在 `scripts/`；EAP_SKILL_DIR 是整包绝对根。
+ * 展开成绝对路径，避免 Windows cmd 不认 `$VAR`、多技能时 env 未注入。
+ */
+export declare const EAP_SKILL_DIR_ENV = "EAP_SKILL_DIR";
+export interface ExpandSkillRefsOptions {
+    platform?: string;
+    exists?: (absPath: string) => boolean;
+}
+export declare function normalizeSkillDir(skillDir: string): string;
+export declare function skillEnvRef(platform?: string): string;
+/**
+ * 包内相对脚本路径 → 技能目录绝对路径。
+ * 带目录或 `./` 的（`bin/foo.py`、`./main.py`、`scripts/a.py`）一律展开。
+ * 根上的裸文件名（`main.py`）仅当包内确实有该文件才展开，以免改写「写到用户目录再跑」的例子。
+ */
+export declare function expandSkillScriptRefs(body: string, skillDir: string, platformOrOpts?: string | ExpandSkillRefsOptions): string;
+export declare function isSkillEntryFile(filePath: string): boolean;

package/dist/tool/skill-script-refs.js

@@ -0,0 +1,62 @@
+/**
+ * 喂给模型的 SKILL.md 正文展开（不改磁盘）。
+ * 对标 Claude `${CLAUDE_SKILL_DIR}`：作者仍写包内相对路径。
+ * 官方规范不要求脚本必须在 `scripts/`；EAP_SKILL_DIR 是整包绝对根。
+ * 展开成绝对路径，避免 Windows cmd 不认 `$VAR`、多技能时 env 未注入。
+ */
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+export const EAP_SKILL_DIR_ENV = 'EAP_SKILL_DIR';
+/** 看起来像可执行/源码的扩展名。不是目录白名单。 */
+const CODE_EXT = 'py|js|mjs|cjs|ts|tsx|jsx|sh|bash|zsh|ps1|bat|cmd|exe|rb|pl|php';
+const RELATIVE_CODE_PATH = new RegExp(`(^|[^$\\w./\\\\:%])(\\.\\/)?((?:[\\w.-]+[\\\\/])*[\\w.-]+\\.(?:${CODE_EXT}))\\b`, 'gi');
+export function normalizeSkillDir(skillDir) {
+    return skillDir.replace(/\\/g, '/').replace(/\/+$/, '');
+}
+export function skillEnvRef(platform = process.platform) {
+    return platform === 'win32' ? `%${EAP_SKILL_DIR_ENV}%` : `$${EAP_SKILL_DIR_ENV}`;
+}
+function asOptions(platformOrOpts) {
+    if (typeof platformOrOpts === 'string')
+        return { platform: platformOrOpts };
+    return platformOrOpts ?? {};
+}
+function defaultExists(absPath) {
+    try {
+        return existsSync(absPath);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 包内相对脚本路径 → 技能目录绝对路径。
+ * 带目录或 `./` 的（`bin/foo.py`、`./main.py`、`scripts/a.py`）一律展开。
+ * 根上的裸文件名（`main.py`）仅当包内确实有该文件才展开，以免改写「写到用户目录再跑」的例子。
+ */
+export function expandSkillScriptRefs(body, skillDir, platformOrOpts) {
+    const opts = asOptions(platformOrOpts);
+    const platform = opts.platform ?? process.platform;
+    const exists = opts.exists ?? defaultExists;
+    const dir = normalizeSkillDir(skillDir);
+    const expanded = body.replace(RELATIVE_CODE_PATH, (full, prefix, dotSlash, rel) => {
+        const relNorm = rel.replace(/\\/g, '/');
+        const packageRelative = Boolean(dotSlash) || relNorm.includes('/');
+        if (!packageRelative && !exists(path.join(skillDir, relNorm))) {
+            return full;
+        }
+        return `${prefix}${dir}/${relNorm}`;
+    });
+    const envRef = skillEnvRef(platform);
+    const envPath = platform === 'win32' ? `${envRef}\\<相对路径>` : `${envRef}/<相对路径>`;
+    const note = `技能目录（只读）环境变量 ${EAP_SKILL_DIR_ENV}=${dir}。` +
+        `包内任意文件用 ${envPath}（不限 scripts/）。` +
+        `读入正文里像包内脚本的相对路径已展开为绝对路径。` +
+        `当前工作目录是用户目录，相对路径写出在用户目录。\n\n`;
+    if (body.includes(`${EAP_SKILL_DIR_ENV}=`))
+        return expanded;
+    return note + expanded;
+}
+export function isSkillEntryFile(filePath) {
+    return /(^|[\\/])(SKILL\.md|skill\.md)$/i.test(filePath);
+}

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

@@ -8,11 +8,12 @@
  * [平台规则常量]          ← 代码内置，安全约束 + 行为准则（最高优先级）
  * [当前时间]              ← 运行时动态注入（自然周等时间规则的判定基准）
  * [Agent 身份]            ← agentName / agentCode
+ * [可用工具短目录]        ← 名称 + 一句话用途；完整 schema 仍走 API tools
  * [开发者提示词]          ← Graph LLM 节点 config.systemPrompt，平台透传
  *                           （Registry 无内嵌 Graph 的兜底路径读 agent.manifest.json prompts.system）
  * ```
  *
- * Tools 不经过本类，走 API 的 tools 参数（见 loadedToolsToApiTools）。
+ * 工具 schema 走 API 的 tools 参数（见 loadedToolsToApiTools）；system 短目录给模型发现用，不是对用户报菜名。
  *
  * @see docs/status/module-status-and-backlog.md RT-5
  */
@@ -28,38 +29,34 @@ export interface LoadedSkillInfo {
     name: string;
     description?: string;
     version?: string;
+    /** Skill 包目录（含 SKILL.md） */
+    bundlePath?: string;
+    /** SKILL.md 绝对路径 */
+    entryFile?: string;
     /** Skill 工作流（GraphDSL）；缺省时子图节点须自带 subgraphDsl */
     workflow?: import('../graph/contracts/executable-graph.js').GraphDSL;
-    /** 注入子图入口 LLM 系统上下文 */
+    /** 子图入口可选上下文；Harness 主路径不灌 system */
     prompt?: string;
-    toolRefs?: Array<string | {
-        toolId?: string;
+    toolsets?: Array<string | {
         name?: string;
         version?: string;
-        toolset?: string;
-        enabledTools?: string[];
+        code?: string;
+        enabled?: 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
+ * 按 Skill.toolsets 收窄工具集（子图用）。
+ * - 无 toolsets / 空数组：不收窄
+ * - string / name：精确匹配工具名
+ * - code + enabled：仅白名单子工具
+ * - code 无 enabled：匹配 toolId 前缀 `<code>:` 或 id 等于 code
+ * - 始终保留 Harness 原语
  */
 export declare function filterLoadedToolsForSkill(loadedTools: LoadedToolMap | undefined, skill: LoadedSkillInfo | undefined): LoadedToolMap | undefined;
 /**
@@ -78,22 +75,59 @@ export interface PromptBuildContext {
     agentCode?: string;
     /** 当前调用用户标识（可选，供「我 / 我的」类指代） */
     userId?: string | null;
+    /** 当前用户目录（`users/<userId>`，含用户 skills） */
+    workingDirectory?: string;
+    os?: {
+        platform: string;
+        release: string;
+    };
+    /** 允许 read_file 的根目录（写根 + 已装配 tools/skills） */
+    jailRoots?: string[];
+    skillDirs?: Array<{
+        skillId: string;
+        bundlePath: string;
+        entryFile?: string;
+    }>;
+    /** 已装配 Skill 短目录；单独成段，不并进开发者提示词 */
+    skillCatalog?: string;
+    /** 已装配工具短目录（名称 + 用途）；schema 仍走 API tools */
+    toolCatalog?: string;
+}
+export interface PromptSection {
+    id: string;
+    title: string;
+    body: string;
+}
+export interface AssembledSystemPrompt {
+    text: string;
+    sections: PromptSection[];
 }
 /**
  * SystemPromptBuilder — 系统提示词拼接
  *
- * 四段式拼接：平台规则 + 当前时间 + Agent 身份 + 开发者提示词。
- * 不注入工具列表（工具走 API tools 参数）。
- * 不支持模板变量替换（开发者直接写最终文本）。
+ * 具名段拼接（无模板引擎）。顺序固定，段标题用于排查。
+ * 工具短目录进 system；完整 schema 走 API tools 参数。
+ * 开发者提示词整段透传，不做 {{ }} 替换。
  */
 export declare class SystemPromptBuilder {
     /**
-     * 构建完整系统提示词
+     * 构建完整系统提示词（含具名段，便于对照落盘）。
      */
-    build(context: PromptBuildContext): string;
-    private buildCurrentTime;
+    build(context: PromptBuildContext): AssembledSystemPrompt;
+    private buildEnvironment;
     private buildAgentIdentity;
+    private buildJail;
 }
+/** 自然周（周一为一周第一天）及本月/上月窗口，供时间类推理。 */
+export declare function naturalTimeWindows(now?: Date): {
+    now: string;
+    weekday: string;
+    thisWeek: string;
+    lastWeek: string;
+    lastWeekend: string;
+    thisMonth: string;
+    lastMonth: string;
+};
 /**
  * OpenAI function-calling tool definition（API tools 参数格式）
  *
@@ -111,4 +145,6 @@ export type ApiToolDefinition = LLMToolDefinition;
  * @param skillTools - 可选，当前 Skill 所需的工具名称列表（过滤子集）
  * @returns OpenAI API tools 参数数组
  */
+/** 名称 + 一句话用途，供 system「可用工具」段。schema 仍走 loadedToolsToApiTools。 */
+export declare function buildToolCatalog(loadedTools: LoadedToolMap | undefined): string | undefined;
 export declare function loadedToolsToApiTools(loadedTools: LoadedToolMap | undefined, skillTools?: string[]): ApiToolDefinition[];