@gt-fe/eap-runtime 0.0.8 → 0.0.10

package/dist/tool/harness-primitives.js

@@ -0,0 +1,385 @@
+/**
+ * 平台默认 Harness 原语：read_file / write_file / execute_command。
+ *
+ * 不写进 agent.manifest.toolsets。同名业务工具优先（问数 file-io 等）。
+ * 读：工作目录 + 技能包 + EAP_LOCAL_SKILLS_DIR + FILE_IO_ROOT。
+ * 写：仅工作目录，且不跟随符号链接。
+ * 命令：cwd 落在 jail 内；环境变量白名单，不继承 process.env。
+ */
+import { spawn } from 'node:child_process';
+import { constants as fsConstants, realpathSync } from 'node:fs';
+import { mkdir, open, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { BUILTIN_TOOL_SOURCE, DEFAULT_BUILTIN_TIMEOUT_MS, MAX_BUILTIN_TIMEOUT_MS, clampBuiltinTimeout, isBuiltinToolExecution, resolveBuiltinToolsConfig, } from '@gt-fe/eap-contracts';
+function builtinConfig() {
+    return resolveBuiltinToolsConfig(process.env);
+}
+function harnessDefinitions() {
+    const common = {
+        version: '1.0.0',
+        type: 'code',
+        status: 'active',
+        toolRuntime: 'local',
+        execution: { source: BUILTIN_TOOL_SOURCE },
+    };
+    return [
+        {
+            toolId: 'builtin:read_file',
+            name: 'read_file',
+            manifest: {
+                id: 'builtin:read_file',
+                name: 'read_file',
+                description: '读取工作目录或技能目录内的文本。要用某个技能时读该技能文件夹下的 SKILL.md。超限会截断并注明。',
+                ...common,
+            },
+            inputSchema: {
+                type: 'object',
+                required: ['path'],
+                properties: {
+                    path: { type: 'string', description: '相对工作目录或技能根的路径' },
+                    offset: { type: 'integer', description: '从第几行开始读，从 1 起。省略则从头。' },
+                    limit: { type: 'integer', description: '最多读多少行。省略则读到末尾或字节上限。' },
+                },
+            },
+        },
+        {
+            toolId: 'builtin:write_file',
+            name: 'write_file',
+            manifest: {
+                id: 'builtin:write_file',
+                name: 'write_file',
+                description: '写入工作目录内的文本文件。技能目录只读，禁止写出 jail。',
+                ...common,
+            },
+            inputSchema: {
+                type: 'object',
+                required: ['path', 'content'],
+                properties: {
+                    path: { type: 'string' },
+                    content: { type: 'string' },
+                },
+            },
+        },
+        {
+            toolId: 'builtin:execute_command',
+            name: 'execute_command',
+            manifest: {
+                id: 'builtin:execute_command',
+                name: 'execute_command',
+                description: `在 jail 内执行命令（跑技能包 scripts、pip 等）。默认超时 ${DEFAULT_BUILTIN_TIMEOUT_MS}ms，可用 timeoutMs 延长，上限 ${MAX_BUILTIN_TIMEOUT_MS}ms。不继承密钥环境变量。`,
+                ...common,
+            },
+            inputSchema: {
+                type: 'object',
+                required: ['command'],
+                properties: {
+                    command: { type: 'string' },
+                    cwd: { type: 'string', description: '相对工作目录的子目录，可选' },
+                    timeoutMs: {
+                        type: 'integer',
+                        description: `超时毫秒。省略则 ${DEFAULT_BUILTIN_TIMEOUT_MS}。上限 ${MAX_BUILTIN_TIMEOUT_MS}。`,
+                    },
+                },
+            },
+        },
+    ];
+}
+export function mergeHarnessPrimitives(loadedTools) {
+    if (!builtinConfig().enabled) {
+        return loadedTools;
+    }
+    const merged = { ...(loadedTools ?? {}) };
+    for (const tool of harnessDefinitions()) {
+        if (!merged[tool.name])
+            merged[tool.name] = tool;
+    }
+    return merged;
+}
+/** 装配点：业务 toolsets + 平台 Harness 原语。 */
+export function assembleLoadedTools(loadedTools) {
+    return mergeHarnessPrimitives(loadedTools);
+}
+function defaultExtraRoots() {
+    const extra = [path.resolve(process.cwd(), 'skills')];
+    for (const key of ['EAP_LOCAL_SKILLS_DIR', 'FILE_IO_ROOT']) {
+        const value = process.env[key]?.trim();
+        if (value)
+            extra.push(value);
+    }
+    return extra;
+}
+function tryRealpath(p) {
+    try {
+        return realpathSync(p);
+    }
+    catch {
+        return undefined;
+    }
+}
+export function resolveJailRoots(options) {
+    const workdir = path.resolve(options?.workdir ?? process.cwd());
+    const candidates = [workdir, ...defaultExtraRoots(), ...(options?.extraRoots ?? [])];
+    const roots = [];
+    for (const raw of candidates) {
+        const resolved = path.resolve(raw);
+        const real = tryRealpath(resolved) ?? resolved;
+        if (!roots.includes(real))
+            roots.push(real);
+    }
+    return roots;
+}
+function sandboxEnv(workdir, cwd, allowlist) {
+    const env = {
+        PATH: process.env.PATH ?? '/usr/bin:/bin:/usr/local/bin',
+        LANG: process.env.LANG ?? 'C.UTF-8',
+        LC_ALL: process.env.LC_ALL ?? process.env.LANG ?? 'C.UTF-8',
+        HOME: workdir,
+        TMPDIR: workdir,
+        TMP: workdir,
+        TEMP: workdir,
+        PWD: cwd,
+    };
+    const pinned = new Set(['HOME', 'TMPDIR', 'TMP', 'TEMP', 'PWD']);
+    for (const key of allowlist) {
+        if (pinned.has(key))
+            continue;
+        const value = process.env[key];
+        if (value !== undefined)
+            env[key] = value;
+    }
+    return env;
+}
+async function writeFileNoFollow(target, content) {
+    const flags = fsConstants.O_WRONLY |
+        fsConstants.O_CREAT |
+        fsConstants.O_TRUNC |
+        (fsConstants.O_NOFOLLOW ?? 0);
+    let handle;
+    try {
+        handle = await open(target, flags, 0o644);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === 'ELOOP') {
+            throw new Error('拒绝写入符号链接');
+        }
+        throw err;
+    }
+    try {
+        await handle.writeFile(content, 'utf8');
+    }
+    finally {
+        await handle.close();
+    }
+}
+function isInsideRoot(candidate, root) {
+    const rel = path.relative(root, candidate);
+    return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
+}
+function resolveViaExistingAncestor(abs) {
+    const suffix = [];
+    let cur = abs;
+    while (true) {
+        const real = tryRealpath(cur);
+        if (real)
+            return path.resolve(real, ...suffix);
+        const parent = path.dirname(cur);
+        if (parent === cur)
+            return abs;
+        suffix.unshift(path.basename(cur));
+        cur = parent;
+    }
+}
+export function resolveJailedPath(requested, roots, opts) {
+    const trimmed = requested.trim();
+    if (!trimmed || trimmed.includes('\0')) {
+        throw new Error('非法路径');
+    }
+    const workdir = roots[0] ?? path.resolve(process.cwd());
+    const abs = path.isAbsolute(trimmed) ? path.normalize(trimmed) : path.resolve(workdir, trimmed);
+    const existing = tryRealpath(abs);
+    if (opts?.mustExist && !existing) {
+        throw new Error(`文件不存在：${trimmed}`);
+    }
+    const target = existing ?? resolveViaExistingAncestor(abs);
+    if (!roots.some((root) => isInsideRoot(target, root))) {
+        throw new Error(`路径超出允许目录：${trimmed}`);
+    }
+    return target;
+}
+function fail(request, error) {
+    return {
+        toolCallId: request.toolCallId,
+        toolName: request.toolName,
+        content: '',
+        success: false,
+        error,
+        runtime: 'local',
+    };
+}
+function ok(request, content) {
+    return {
+        toolCallId: request.toolCallId,
+        toolName: request.toolName,
+        content,
+        success: true,
+        runtime: 'local',
+    };
+}
+export class HarnessPrimitiveExecutor {
+    workdir;
+    extraRoots;
+    constructor(options) {
+        this.workdir = options?.workdir;
+        this.extraRoots = options?.extraRoots;
+    }
+    rootsFor(request) {
+        return resolveJailRoots({
+            workdir: this.workdir,
+            extraRoots: [...(this.extraRoots ?? []), ...(request.jailExtraRoots ?? [])],
+        });
+    }
+    async execute(request) {
+        try {
+            switch (request.toolName) {
+                case 'read_file':
+                    return await this.readFile(request);
+                case 'write_file':
+                    return await this.writeFile(request);
+                case 'execute_command':
+                    return await this.executeCommand(request);
+                default:
+                    return fail(request, `未知 Harness 原语：${request.toolName}`);
+            }
+        }
+        catch (err) {
+            return fail(request, err instanceof Error ? err.message : String(err));
+        }
+    }
+    async readFile(request) {
+        const filePath = String(request.arguments.path ?? request.arguments.file ?? '');
+        const target = resolveJailedPath(filePath, this.rootsFor(request), { mustExist: true });
+        const buf = await readFile(target);
+        const config = builtinConfig();
+        const lines = buf.toString('utf8').split('\n');
+        const startLine = typeof request.arguments.offset === 'number' && request.arguments.offset > 1
+            ? Math.floor(request.arguments.offset) - 1
+            : 0;
+        const maxLines = typeof request.arguments.limit === 'number' && request.arguments.limit > 0
+            ? Math.floor(request.arguments.limit)
+            : undefined;
+        const sliced = maxLines != null ? lines.slice(startLine, startLine + maxLines) : lines.slice(startLine);
+        let text = sliced.join('\n');
+        const notes = [];
+        if (startLine > 0 || maxLines != null) {
+            notes.push(`showing lines ${startLine + 1}-${startLine + sliced.length} of ${lines.length}`);
+        }
+        const byteLength = Buffer.byteLength(text, 'utf8');
+        if (byteLength > config.maxReadBytes) {
+            let cut = text;
+            while (Buffer.byteLength(cut, 'utf8') > config.maxReadBytes && cut.length > 0) {
+                cut = cut.slice(0, Math.floor(cut.length * 0.9));
+            }
+            text = cut;
+            notes.push(`truncated to ${config.maxReadBytes} bytes (file was ${buf.byteLength} bytes)`);
+        }
+        if (notes.length > 0) {
+            text = `${text}\n[${notes.join('; ')}]`;
+        }
+        return ok(request, text);
+    }
+    async writeFile(request) {
+        const filePath = String(request.arguments.path ?? '');
+        const content = String(request.arguments.content ?? '');
+        const workdir = this.rootsFor(request)[0];
+        const writeRoots = [workdir];
+        const target = resolveJailedPath(filePath, writeRoots);
+        await mkdir(path.dirname(target), { recursive: true });
+        const recast = resolveJailedPath(filePath, writeRoots);
+        await writeFileNoFollow(recast, content);
+        return ok(request, JSON.stringify({ ok: true, path: path.relative(workdir, recast) }));
+    }
+    async executeCommand(request) {
+        const command = String(request.arguments.command ?? '').trim();
+        if (!command)
+            return fail(request, 'command 不能为空');
+        const roots = this.rootsFor(request);
+        const workdir = roots[0];
+        const cwdArg = request.arguments.cwd != null ? String(request.arguments.cwd) : workdir;
+        const cwd = resolveJailedPath(cwdArg, roots, { mustExist: true });
+        const config = builtinConfig();
+        const timeoutMs = clampBuiltinTimeout(request.arguments.timeoutMs, config);
+        const maxOutput = config.maxOutputBytes;
+        const output = await new Promise((resolve, reject) => {
+            const child = spawn('/bin/sh', ['-c', command], {
+                cwd,
+                env: sandboxEnv(workdir, cwd, config.envAllowlist),
+                stdio: ['ignore', 'pipe', 'pipe'],
+            });
+            let stdout = Buffer.alloc(0);
+            let stderr = Buffer.alloc(0);
+            let stdoutTruncated = false;
+            let stderrTruncated = false;
+            const timer = setTimeout(() => {
+                child.kill('SIGKILL');
+                reject(new Error(`命令超时（${timeoutMs}ms）`));
+            }, timeoutMs);
+            child.stdout?.on('data', (chunk) => {
+                if (stdout.length >= maxOutput) {
+                    stdoutTruncated = true;
+                    return;
+                }
+                stdout = Buffer.concat([stdout, chunk]).subarray(0, maxOutput);
+                if (stdout.length >= maxOutput)
+                    stdoutTruncated = true;
+            });
+            child.stderr?.on('data', (chunk) => {
+                if (stderr.length >= maxOutput) {
+                    stderrTruncated = true;
+                    return;
+                }
+                stderr = Buffer.concat([stderr, chunk]).subarray(0, maxOutput);
+                if (stderr.length >= maxOutput)
+                    stderrTruncated = true;
+            });
+            child.on('error', (err) => {
+                clearTimeout(timer);
+                reject(err);
+            });
+            child.on('close', (code) => {
+                clearTimeout(timer);
+                resolve({
+                    stdout: stdout.toString('utf8'),
+                    stderr: stderr.toString('utf8'),
+                    code,
+                    stdoutTruncated,
+                    stderrTruncated,
+                });
+            });
+        });
+        const body = [
+            output.stdout.trimEnd(),
+            output.stdoutTruncated ? `[stdout truncated at ${maxOutput} bytes]` : '',
+            output.stderr.trim() ? `stderr:\n${output.stderr.trimEnd()}` : '',
+            output.stderrTruncated ? `[stderr truncated at ${maxOutput} bytes]` : '',
+            `exit ${output.code ?? -1}`,
+        ]
+            .filter(Boolean)
+            .join('\n');
+        if (output.code !== 0) {
+            return { ...fail(request, `命令退出码 ${output.code}`), content: body };
+        }
+        return ok(request, body);
+    }
+}
+export function withHarnessPrimitives(inner, options) {
+    const harness = new HarnessPrimitiveExecutor(options);
+    return {
+        execute(request) {
+            if (isBuiltinToolExecution(request.execution)) {
+                return harness.execute(request);
+            }
+            return inner.execute(request);
+        },
+    };
+}

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

@@ -57,7 +57,7 @@ export class HttpToolExecutor {
     }
     async execute(request) {
         const url = `${this.baseUrl}/api/v1/tools/${encodeURIComponent(request.toolName)}/execute`;
-        const agentCode = request.authContext.agentCode ?? request.authContext.agentId;
+        const agentCode = request.authContext.agentCode;
         const correlationId = request.correlationId ?? request.toolCallId;
         const taskId = request.taskId ?? request.toolCallId;
         const body = {

package/dist/tool/index.d.ts

@@ -12,7 +12,8 @@ export { LocalMcpClient, type ILocalMcpClient, type LocalMcpInvokeContext, type
 export { fileArtifactFromToolOutput, extractFileReference, resolveFileArtifact, type FileArtifact, } from './file-artifact.js';
 export { ToolExecutionRouter, type DeploymentContext, type ToolExecutionRouterOptions, } from './tool-execution-router.js';
 export { createToolExecutor, EmptyInstallStore, type CreateToolExecutorOptions, } from './create-tool-executor.js';
+export { assembleLoadedTools, mergeHarnessPrimitives as mergeBuiltinTools, withHarnessPrimitives as withBuiltinTools, HarnessPrimitiveExecutor as BuiltinToolExecutor, type HarnessJailOptions as BuiltinJailOptions, } from './harness-primitives.js';
 export { ToolResultInjector, type ToolMessage, } from './tool-result-injector.js';
 export { ToolEventEmitter } from './tool-event-emitter.js';
 export { ToolConfirmationInterceptor } from './tool-confirmation.js';
-export { SystemPromptBuilder, loadedToolsToApiTools, toLoadedSkillMap, mergeSkillScriptTools, filterLoadedToolsForSkill, type PromptBuildContext, type ApiToolDefinition, type LoadedSkillInfo, type LoadedSkillMap, } from './system-prompt-builder.js';
+export { SystemPromptBuilder, naturalTimeWindows, loadedToolsToApiTools, toLoadedSkillMap, filterLoadedToolsForSkill, type PromptBuildContext, type PromptSection, type AssembledSystemPrompt, type ApiToolDefinition, type LoadedSkillInfo, type LoadedSkillMap, } from './system-prompt-builder.js';

package/dist/tool/index.js

@@ -11,7 +11,8 @@ export { LocalMcpClient, } from './local-mcp-client.js';
 export { fileArtifactFromToolOutput, extractFileReference, resolveFileArtifact, } from './file-artifact.js';
 export { ToolExecutionRouter, } from './tool-execution-router.js';
 export { createToolExecutor, EmptyInstallStore, } from './create-tool-executor.js';
+export { assembleLoadedTools, mergeHarnessPrimitives as mergeBuiltinTools, withHarnessPrimitives as withBuiltinTools, HarnessPrimitiveExecutor as BuiltinToolExecutor, } from './harness-primitives.js';
 export { ToolResultInjector, } from './tool-result-injector.js';
 export { ToolEventEmitter } from './tool-event-emitter.js';
 export { ToolConfirmationInterceptor } from './tool-confirmation.js';
-export { SystemPromptBuilder, loadedToolsToApiTools, toLoadedSkillMap, mergeSkillScriptTools, filterLoadedToolsForSkill, } from './system-prompt-builder.js';
+export { SystemPromptBuilder, naturalTimeWindows, loadedToolsToApiTools, toLoadedSkillMap, filterLoadedToolsForSkill, } from './system-prompt-builder.js';

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

@@ -2,7 +2,7 @@
  * 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 { IToolExecutor, ToolCallRequest, ToolCallResult } from './tool-executor.interface.js';
@@ -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,7 +2,7 @@
  * 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';
@@ -88,19 +88,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;
@@ -153,7 +151,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) {

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

@@ -4,7 +4,7 @@
  * @see docs/contracts/tool-execution.md §2.0
  */
 function resolveAgentCode(request) {
-    return request.authContext.agentCode ?? request.authContext.agentId;
+    return request.authContext.agentCode;
 }
 function formatContent(result) {
     const text = result?.content?.[0]?.text;
@@ -57,6 +57,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) {
@@ -140,6 +146,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/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;
+    /** 进程工作目录（文件/命令 jail） */
+    workingDirectory?: string;
+    os?: {
+        platform: string;
+        release: string;
+    };
+    /** 允许读写/执行的根目录（工作目录 + 技能包 + FILE_IO_ROOT 等） */
+    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[];