@gt-fe/eap-runtime 0.0.10 → 0.0.12

package/dist/runtime/agent-runtime.js

@@ -7,7 +7,7 @@
  * @see 04-runtime-core/design.md §1.5 / §1.7
  */
 import { randomUUID } from 'node:crypto';
-import { HitlAlreadyTimedOutError, HitlNotWaitingError, buildHitlWaitedPayload, isHitlDeadlinePassed, readPersistedHitlWaiting, unwrapHitlPaused, } from '../graph/hitl/hitl-handler.js';
+import { HITL_TIMEOUT_ERROR_CODE, HITL_TIMEOUT_MESSAGE, HitlAlreadyTimedOutError, HitlNotWaitingError, buildHitlWaitedPayload, isHitlDeadlinePassed, readPersistedHitlWaiting, unwrapHitlPaused, } from '../graph/hitl/hitl-handler.js';
 import { toLoadedSkillMap } from '../tool/system-prompt-builder.js';
 import { assembleLoadedTools } from '../tool/harness-primitives.js';
 import { createFileLlmTurnLogFromEnv, } from '../debug/llm-turn-log.js';
@@ -268,6 +268,9 @@ export class AgentRuntime {
         const promptRoots = this.deps.graphLoader
             ? await this.deps.graphLoader.resolvePromptRoots(agentCode, params.agentVersion)
             : [];
+        const agentDir = this.deps.graphLoader
+            ? (await this.deps.graphLoader.resolveAgentDir(agentCode, params.agentVersion)) ?? undefined
+            : undefined;
         const history = messageRecordsToGraphMessages(sessionContext.messages);
         const messages = await buildTurnGraphMessages({
             history,
@@ -297,6 +300,7 @@ export class AgentRuntime {
                 loadedSkills,
                 skillDefinitions,
                 promptRoots,
+                agentDir,
                 skillInput: resolveSkillInputFromInvokeInput(params.input),
                 traceId: resolveTraceId(params),
                 traceCollector: this.deps.traceCollector,
@@ -442,7 +446,7 @@ export class AgentRuntime {
         }
         catch (err) {
             if (err instanceof HitlAlreadyTimedOutError) {
-                throw new AppError(ErrorCodes.TASK_HITL_TIMEOUT, `Task ${taskId} HITL wait exceeded deadline`, { exposeMessage: true });
+                throw new AppError(ErrorCodes.TASK_HITL_TIMEOUT, HITL_TIMEOUT_MESSAGE, { exposeMessage: true });
             }
             if (err instanceof HitlNotWaitingError) {
                 throw new AppError(ErrorCodes.TASK_HITL_INVALID_STATE, `Task ${taskId} is not waiting for HITL`, { exposeMessage: true });
@@ -482,6 +486,10 @@ export class AgentRuntime {
             taskId,
             correlationId: resumedState.correlationId ?? correlationId,
             agentVersion: agentVersion ?? resumedState.agentVersion,
+            agentDir: (typeof resumedState.agentDir === 'string' && resumedState.agentDir) ||
+                (this.deps.graphLoader
+                    ? (await this.deps.graphLoader.resolveAgentDir(agentCode, agentVersion)) ?? undefined
+                    : undefined),
             activatedSkill: resumedState.activatedSkill,
             skillRoute: resumedState.skillRoute ??
                 (typeof resumedState.activatedSkill === 'string' && resumedState.activatedSkill
@@ -640,10 +648,15 @@ export class AgentRuntime {
         const loadedToolsBase = await this.resolveLoadedTools(agentCode, agentVersion);
         const skillBundle = await this.resolveLoadedSkills(agentCode, userId, agentVersion);
         const loadedTools = assembleLoadedTools(loadedToolsBase);
+        const agentDir = (typeof forkedCheckpoint.state.agentDir === 'string' && forkedCheckpoint.state.agentDir) ||
+            (this.deps.graphLoader
+                ? (await this.deps.graphLoader.resolveAgentDir(agentCode, agentVersion)) ?? undefined
+                : undefined);
         try {
             const result = await this.deps.graphEngine.invoke(graph, {
                 ...forkedCheckpoint.state,
                 agentVersion,
+                agentDir,
                 userId,
                 delegationToken: overrides.executionContext?.delegationToken,
                 executionContext: overrides.executionContext,
@@ -740,7 +753,7 @@ export class AgentRuntime {
                 toolSpanId: persisted.toolSpanId,
                 skillSpanId: persisted.skillSpanId,
             });
-            throw new AppError(ErrorCodes.TASK_HITL_TIMEOUT, `Task ${taskId} HITL wait exceeded deadline`, { exposeMessage: true });
+            throw new AppError(ErrorCodes.TASK_HITL_TIMEOUT, HITL_TIMEOUT_MESSAGE, { exposeMessage: true });
         }
         return {
             task,
@@ -780,7 +793,7 @@ export class AgentRuntime {
             return;
         }
         const collector = this.deps.traceCollector;
-        const error = event.behavior === 'cancel' ? 'HITL cancelled by timeout' : 'HITL wait timed out';
+        const error = HITL_TIMEOUT_MESSAGE;
         if (collector) {
             if (event.toolSpanId) {
                 try {
@@ -807,6 +820,7 @@ export class AgentRuntime {
                 toolCallId: event.toolCallId,
                 toolName: event.toolName,
                 error,
+                errorCode: HITL_TIMEOUT_ERROR_CODE,
             });
         }
         catch {

package/dist/runtime/dev-runtime.d.ts

@@ -18,7 +18,7 @@
  *
  * 装配策略（与 server.ts 一致）：
  * - LLM Provider: Routing > HttpLLMProvider(OpenAI) > Echo 兜底
- * - Tool Executor: mock（显式）/ DevToolExecutor（dev+mcp，缺配置失败）/ 通用路由
+ * - Tool Executor: DevToolExecutor（dev+mcp，缺配置失败）/ 通用路由
  * - Governance: AllowAll(本地闭环默认) / HttpGovernance(显式 GOVERNANCE_DISABLED=0)
  * - 存储: EAP_RUNTIME_STORAGE_PROFILE（默认 dev = File Session/Message/Checkpoint）
  * - Registry: 本地闭环不装配，由 GraphLoader.deploymentSnapshot 兜底

package/dist/runtime/dev-runtime.js

@@ -18,7 +18,7 @@
  *
  * 装配策略（与 server.ts 一致）：
  * - LLM Provider: Routing > HttpLLMProvider(OpenAI) > Echo 兜底
- * - Tool Executor: mock（显式）/ DevToolExecutor（dev+mcp，缺配置失败）/ 通用路由
+ * - Tool Executor: DevToolExecutor（dev+mcp，缺配置失败）/ 通用路由
  * - Governance: AllowAll(本地闭环默认) / HttpGovernance(显式 GOVERNANCE_DISABLED=0)
  * - 存储: EAP_RUNTIME_STORAGE_PROFILE（默认 dev = File Session/Message/Checkpoint）
  * - Registry: 本地闭环不装配，由 GraphLoader.deploymentSnapshot 兜底
@@ -28,7 +28,6 @@ import { HttpLLMProvider } from '../providers/http-llm-provider.js';
 import { createLocalLlmProvider, requireLocalLlmConnections } from '../providers/local-llm-provider.js';
 import { RoutingLLMProvider } from '../providers/routing-llm-provider.js';
 import { createToolExecutor } from '../tool/create-tool-executor.js';
-import { MockToolExecutor } from '../tool/mock-tool-executor.js';
 import { DevToolExecutor } from '../tool/dev-tool-executor.js';
 import { withHarnessPrimitives } from '../tool/harness-primitives.js';
 import { AllowAllGovernanceClient, HttpGovernanceClient, } from '../governance/index.js';
@@ -75,14 +74,11 @@ export function createDevRuntime() {
         llmProvider = createDefaultLLMProvider(turnLog);
         llmProviderKind = 'echo';
     }
-    // ── Tool Executor（显式 mock → dev+mcp 直连，缺配置失败 → 通用路由）──
-    const needsHarnessWrap = toolExecutionMode === 'mock' ||
-        (toolExecutionMode === 'mcp' && deploymentContext === 'dev');
-    const innerExecutor = toolExecutionMode === 'mock'
-        ? new MockToolExecutor({ toolsDir: process.env.EAP_LOCAL_TOOLS_DIR })
-        : toolExecutionMode === 'mcp' && deploymentContext === 'dev'
-            ? new DevToolExecutor()
-            : createToolExecutor({ foundationUrl, deploymentContext });
+    // ── Tool Executor（dev+mcp 直连，缺配置失败 → 通用路由）──
+    const needsHarnessWrap = toolExecutionMode === 'mcp' && deploymentContext === 'dev';
+    const innerExecutor = toolExecutionMode === 'mcp' && deploymentContext === 'dev'
+        ? new DevToolExecutor()
+        : createToolExecutor({ foundationUrl, deploymentContext });
     const toolExecutor = needsHarnessWrap
         ? withHarnessPrimitives(innerExecutor)
         : innerExecutor;

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

@@ -2,7 +2,8 @@
  * 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';
+import { assertHttpHostAllowlisted, buildHttpToolUrl as buildSharedHttpToolUrl, ErrorCodes } from '@gt-fe/eap-contracts';
+import { abortOrTimeoutMessage, DEFAULT_HTTP_TOOL_TIMEOUT_SEC, isAbortError, resolveToolTimeoutSec, toToolTimeoutMs, } from './timeout.js';
 export function resolveHttpExecutionFromRequest(request) {
     const raw = request.execution;
     if (!raw || typeof raw !== 'object')
@@ -22,7 +23,7 @@ export function resolveHttpExecutionFromRequest(request) {
         allowedHosts: Array.isArray(e.allowedHosts)
             ? e.allowedHosts.filter((item) => typeof item === 'string')
             : [],
-        timeout: typeof e.timeout === 'number' ? e.timeout : 10000,
+        timeout: resolveToolTimeoutSec(e.timeout, DEFAULT_HTTP_TOOL_TIMEOUT_SEC),
     };
 }
 export function buildHttpToolUrl(spec, args) {
@@ -48,8 +49,9 @@ export class DevHttpExecutor {
             const args = request.arguments ?? {};
             const url = buildHttpToolUrl(spec, args);
             const method = (spec.method ?? 'GET').toUpperCase();
+            const timeoutSec = resolveToolTimeoutSec(spec.timeout, DEFAULT_HTTP_TOOL_TIMEOUT_SEC);
             const controller = new AbortController();
-            const timer = setTimeout(() => controller.abort(), spec.timeout ?? 10000);
+            const timer = setTimeout(() => controller.abort(), toToolTimeoutMs(timeoutSec, DEFAULT_HTTP_TOOL_TIMEOUT_SEC));
             const headers = {
                 Accept: 'application/json, text/plain;q=0.9',
             };
@@ -81,14 +83,15 @@ export class DevHttpExecutor {
             };
         }
         catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
+            const timeoutSec = resolveToolTimeoutSec(spec?.timeout, DEFAULT_HTTP_TOOL_TIMEOUT_SEC);
+            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',
                 runtime: 'local',
             };
         }

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

@@ -17,6 +17,8 @@
  * @see docs/workflows/local-agent-dev-loop.md
  * @see runtime/src/tool/local-mcp-client.ts
  */
+import { ErrorCodes } from '@gt-fe/eap-contracts';
+import { isAbortError } from './timeout.js';
 import { LocalMcpClient } from './local-mcp-client.js';
 export class DevMcpExecutor {
     client;
@@ -50,14 +52,14 @@ export class DevMcpExecutor {
             };
         }
         catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
+            const aborted = isAbortError(err);
             return {
                 toolCallId: request.toolCallId,
                 toolName: request.toolName,
                 content: '',
                 success: false,
-                error: message,
-                errorCode: 'EXECUTION_FAILED',
+                error: err instanceof Error ? err.message : String(err),
+                errorCode: aborted ? ErrorCodes.TOOL_TIMEOUT : 'EXECUTION_FAILED',
                 runtime: 'local',
             };
         }

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

@@ -7,7 +7,7 @@
  * - execution.protocol=mcp → DevMcpExecutor
  * - execution.protocol=http → DevHttpExecutor
  * - 能解析出 code handler → LocalToolExecutor
- * - 其余 → NOT_CONFIGURED（mock 只走显式 `--tool-mode mock`）
+ * - 其余 → NOT_CONFIGURED
  */
 import { DevMcpExecutor } from './dev-mcp-executor.js';
 import type { IToolExecutor, ToolCallRequest, ToolCallResult } from './tool-executor.interface.js';

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

@@ -7,7 +7,7 @@
  * - execution.protocol=mcp → DevMcpExecutor
  * - execution.protocol=http → DevHttpExecutor
  * - 能解析出 code handler → LocalToolExecutor
- * - 其余 → NOT_CONFIGURED（mock 只走显式 `--tool-mode mock`）
+ * - 其余 → NOT_CONFIGURED
  */
 import { EmptyInstallStore } from './create-tool-executor.js';
 import { DevMcpExecutor } from './dev-mcp-executor.js';
@@ -42,7 +42,7 @@ export class DevToolExecutor {
             content: '',
             success: false,
             error: `Dev tool "${request.toolName}" is not executable: no MCP server, ` +
-                'HTTP gateway+pathTemplate, or code handler. Use --tool-mode mock for MockToolExecutor.',
+                'HTTP gateway+pathTemplate, or code handler.',
             errorCode: 'NOT_CONFIGURED',
             runtime: 'local',
         };

package/dist/tool/harness-command.d.ts

@@ -0,0 +1,32 @@
+/**
+ * execute_command 的跨 OS 底板：本机壳、沙箱环境、解释器 shim、超时杀树。
+ * 不翻译 ls/dir；命令字符串按当前壳解释。
+ */
+import { type ChildProcess, type SpawnOptions } from 'node:child_process';
+export interface ShellSpawn {
+    file: string;
+    args: string[];
+    shellName: string;
+    windowsVerbatimArguments?: boolean;
+    windowsHide?: boolean;
+}
+export declare function shellNameFor(platform?: string): string;
+/** system / 工具描述用的本机命令对照（只渲染当前 OS）。 */
+export declare function commandDialectLines(platform?: string): string[];
+export declare function resolveShellSpawn(command: string, platform?: string): ShellSpawn;
+export declare function spawnOptionsFor(shell: ShellSpawn): Pick<SpawnOptions, 'windowsHide' | 'windowsVerbatimArguments'>;
+export declare function findOnPath(names: string[], extraDirs?: string[]): string | undefined;
+export declare function findPythonInterpreter(): string | undefined;
+export declare function findNodeInterpreter(): string | undefined;
+/** 在写根建立 python/node/sh shim。本机一个都没有则返回 undefined。 */
+export declare function ensureInterpreterShims(workdir: string): string | undefined;
+/** @deprecated 使用 ensureInterpreterShims */
+export declare function ensurePythonShims(workdir: string): string | undefined;
+/**
+ * 模型可能从 SKILL.md 抄 `$EAP_SKILL_DIR`（POSIX）或 `%EAP_SKILL_DIR%`（cmd）。
+ * spawn 前替换成绝对路径，不依赖壳去展开。
+ */
+export declare function substituteSkillDir(command: string, skillDir?: string): string;
+export declare function sandboxEnv(workdir: string, cwd: string, allowlist: string[], shimDir?: string, skillDir?: string): NodeJS.ProcessEnv;
+export declare function formatSpawnError(err: unknown, shellFile: string): Error;
+export declare function killProcessTree(child: ChildProcess): void;

package/dist/tool/harness-command.js

@@ -0,0 +1,276 @@
+/**
+ * execute_command 的跨 OS 底板：本机壳、沙箱环境、解释器 shim、超时杀树。
+ * 不翻译 ls/dir；命令字符串按当前壳解释。
+ */
+import { spawnSync } from 'node:child_process';
+import { chmodSync, mkdirSync, statSync, writeFileSync, } from 'node:fs';
+import path from 'node:path';
+const SHIM_DIR_NAME = '.eap-shim';
+export function shellNameFor(platform = process.platform) {
+    return platform === 'win32' ? 'cmd.exe' : '/bin/sh';
+}
+/** system / 工具描述用的本机命令对照（只渲染当前 OS）。 */
+export function commandDialectLines(platform = process.platform) {
+    const shell = shellNameFor(platform);
+    const lines = [
+        `当前 shell：${shell}。\`execute_command\` 的 command 必须是该 shell 的语法。`,
+    ];
+    if (platform === 'win32') {
+        lines.push('基础命令：当前目录 `cd`；列目录 `dir`；环境变量 `%VAR%`；串命令用 `&&`。');
+    }
+    else {
+        lines.push('基础命令：当前目录 `pwd`；列目录 `ls`；环境变量 `$VAR`；串命令用 `&&`。');
+    }
+    lines.push('解释器：`python`/`python3`、`node`/`nodejs`、`sh`/`bash`（Windows 上 `sh` 需本机有 Git Bash 等）。', '可执行文件：用绝对路径或相对于 cwd（Windows `.exe`/`.bat`/`.cmd`；Unix 二进制需可执行或用 `sh`）。', '`execute_command` 的 cwd 是用户目录。技能包只读。包内任意文件用 `EAP_SKILL_DIR` 加相对路径（不限 `scripts/`）。读到的 SKILL.md 里像脚本的相对路径已展开为绝对路径。不要把 cwd 设成技能目录。相对写出在用户目录。');
+    return lines;
+}
+export function resolveShellSpawn(command, platform = process.platform) {
+    if (platform === 'win32') {
+        const file = process.env.ComSpec?.trim() || 'cmd.exe';
+        return {
+            file,
+            args: ['/d', '/s', '/c', `"${command}"`],
+            shellName: 'cmd.exe',
+            windowsVerbatimArguments: true,
+            windowsHide: true,
+        };
+    }
+    return {
+        file: '/bin/sh',
+        args: ['-c', command],
+        shellName: '/bin/sh',
+    };
+}
+export function spawnOptionsFor(shell) {
+    return {
+        windowsHide: shell.windowsHide,
+        windowsVerbatimArguments: shell.windowsVerbatimArguments,
+    };
+}
+function isExecutableFile(candidate) {
+    try {
+        return statSync(candidate).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function pathSearchDirs(extraDirs = []) {
+    const fromEnv = (process.env.PATH ?? '')
+        .split(path.delimiter)
+        .map((dir) => dir.replace(/^"|"$/g, '').trim())
+        .filter((dir) => dir && path.basename(dir) !== SHIM_DIR_NAME);
+    const out = [];
+    for (const dir of [...extraDirs, ...fromEnv]) {
+        if (/WindowsApps/i.test(dir))
+            continue;
+        if (!out.includes(dir))
+            out.push(dir);
+    }
+    return out;
+}
+export function findOnPath(names, extraDirs = []) {
+    const pathext = process.platform === 'win32'
+        ? (process.env.PATHEXT ?? '.EXE;.CMD;.BAT').split(';').filter(Boolean)
+        : [];
+    for (const dir of pathSearchDirs(extraDirs)) {
+        for (const name of names) {
+            const candidates = [path.join(dir, name)];
+            if (process.platform === 'win32' && !path.extname(name)) {
+                for (const ext of pathext) {
+                    candidates.push(path.join(dir, name + ext));
+                }
+            }
+            for (const candidate of candidates) {
+                if (isExecutableFile(candidate))
+                    return candidate;
+            }
+        }
+    }
+    return undefined;
+}
+function gitBashDirs() {
+    if (process.platform !== 'win32')
+        return [];
+    const dirs = [];
+    for (const key of ['ProgramFiles', 'ProgramFiles(x86)', 'LOCALAPPDATA']) {
+        const root = process.env[key];
+        if (root)
+            dirs.push(path.join(root, 'Git', 'bin'));
+    }
+    return dirs;
+}
+const INTERPRETER_FAMILIES = [
+    {
+        shimNames: ['python', 'python3'],
+        searchNames: process.platform === 'win32'
+            ? ['python.exe', 'python3.exe', 'python', 'python3', 'py.exe']
+            : ['python3', 'python'],
+    },
+    {
+        shimNames: ['node', 'nodejs'],
+        searchNames: process.platform === 'win32' ? ['node.exe', 'nodejs.exe', 'node', 'nodejs'] : ['node', 'nodejs'],
+    },
+    {
+        shimNames: ['sh', 'bash'],
+        searchNames: process.platform === 'win32' ? ['bash.exe', 'sh.exe', 'bash', 'sh'] : ['bash', 'sh'],
+        extraSearchDirs: gitBashDirs,
+    },
+];
+export function findPythonInterpreter() {
+    return findOnPath(INTERPRETER_FAMILIES[0].searchNames);
+}
+export function findNodeInterpreter() {
+    return findOnPath(INTERPRETER_FAMILIES[1].searchNames);
+}
+function shimBody(interpreter, extraArgs) {
+    if (process.platform === 'win32') {
+        return `@echo off\r\n"${interpreter}"${extraArgs} %*\r\n`;
+    }
+    return extraArgs
+        ? `#!/bin/sh\nexec "${interpreter}"${extraArgs} "$@"\n`
+        : `#!/bin/sh\nexec "${interpreter}" "$@"\n`;
+}
+function extraArgsFor(interpreter) {
+    const base = path.basename(interpreter).toLowerCase();
+    return base === 'py.exe' || base === 'py' ? ' -3' : '';
+}
+function writeShim(shimDir, name, interpreter, extraArgs) {
+    const body = shimBody(interpreter, extraArgs);
+    if (process.platform === 'win32') {
+        writeFileSync(path.join(shimDir, `${name}.cmd`), body);
+        return;
+    }
+    const target = path.join(shimDir, name);
+    writeFileSync(target, body, { mode: 0o755 });
+    chmodSync(target, 0o755);
+}
+/** 在写根建立 python/node/sh shim。本机一个都没有则返回 undefined。 */
+export function ensureInterpreterShims(workdir) {
+    const shimDir = path.join(workdir, SHIM_DIR_NAME);
+    mkdirSync(shimDir, { recursive: true });
+    let wrote = false;
+    for (const family of INTERPRETER_FAMILIES) {
+        const found = findOnPath(family.searchNames, family.extraSearchDirs?.() ?? []);
+        if (!found)
+            continue;
+        wrote = true;
+        const extra = extraArgsFor(found);
+        for (const name of family.shimNames) {
+            writeShim(shimDir, name, found, extra);
+        }
+    }
+    return wrote ? shimDir : undefined;
+}
+/** @deprecated 使用 ensureInterpreterShims */
+export function ensurePythonShims(workdir) {
+    return ensureInterpreterShims(workdir);
+}
+/**
+ * 模型可能从 SKILL.md 抄 `$EAP_SKILL_DIR`（POSIX）或 `%EAP_SKILL_DIR%`（cmd）。
+ * spawn 前替换成绝对路径，不依赖壳去展开。
+ */
+export function substituteSkillDir(command, skillDir) {
+    const dir = skillDir?.trim();
+    if (!dir)
+        return command;
+    return command
+        .replace(/\$\{EAP_SKILL_DIR\}/g, dir)
+        .replace(/\$EAP_SKILL_DIR\b/g, dir)
+        .replace(/%EAP_SKILL_DIR%/gi, dir);
+}
+export function sandboxEnv(workdir, cwd, allowlist, shimDir, skillDir) {
+    const win = process.platform === 'win32';
+    const hostPath = process.env.PATH
+        ?? (win
+            ? (process.env.SystemRoot ? path.join(process.env.SystemRoot, 'System32') : 'C:\\Windows\\System32')
+            : '/usr/bin:/bin:/usr/local/bin');
+    const pathValue = shimDir ? `${shimDir}${path.delimiter}${hostPath}` : hostPath;
+    const env = {
+        PATH: pathValue,
+        LANG: process.env.LANG ?? 'C.UTF-8',
+        LC_ALL: process.env.LC_ALL ?? process.env.LANG ?? 'C.UTF-8',
+        HOME: workdir,
+        USERPROFILE: workdir,
+        TMPDIR: workdir,
+        TMP: workdir,
+        TEMP: workdir,
+        PWD: cwd,
+        PYTHONUTF8: '1',
+        PYTHONIOENCODING: 'utf-8',
+    };
+    if (skillDir?.trim())
+        env.EAP_SKILL_DIR = skillDir.trim();
+    if (win) {
+        env.ComSpec = process.env.ComSpec ?? 'cmd.exe';
+        if (process.env.SystemRoot)
+            env.SystemRoot = process.env.SystemRoot;
+        if (process.env.SYSTEMDRIVE)
+            env.SYSTEMDRIVE = process.env.SYSTEMDRIVE;
+        if (process.env.WINDIR)
+            env.WINDIR = process.env.WINDIR;
+        env.PATHEXT = process.env.PATHEXT ?? '.COM;.EXE;.BAT;.CMD;.VBS;.JS;.WS;.MSC';
+    }
+    const pinned = new Set([
+        'PATH',
+        'HOME',
+        'USERPROFILE',
+        'TMPDIR',
+        'TMP',
+        'TEMP',
+        'PWD',
+        'PYTHONUTF8',
+        'PYTHONIOENCODING',
+        'EAP_SKILL_DIR',
+        'ComSpec',
+        'SystemRoot',
+        'SYSTEMDRIVE',
+        'WINDIR',
+        'PATHEXT',
+    ]);
+    for (const key of allowlist) {
+        if (pinned.has(key))
+            continue;
+        const value = process.env[key];
+        if (value !== undefined)
+            env[key] = value;
+    }
+    return env;
+}
+export function formatSpawnError(err, shellFile) {
+    const code = err.code;
+    if (code === 'ENOENT') {
+        return new Error(`本机没有命令壳（${shellFile}），无法执行 execute_command`);
+    }
+    if (code === 'EACCES') {
+        return new Error(`没有权限启动命令壳（${shellFile}）`);
+    }
+    return err instanceof Error ? err : new Error(String(err));
+}
+export function killProcessTree(child) {
+    const pid = child.pid;
+    if (pid == null) {
+        try {
+            child.kill('SIGKILL');
+        }
+        catch {
+            /* already gone */
+        }
+        return;
+    }
+    if (process.platform === 'win32') {
+        spawnSync('taskkill', ['/pid', String(pid), '/T', '/F'], {
+            stdio: 'ignore',
+            windowsHide: true,
+            timeout: 5_000,
+        });
+        return;
+    }
+    spawnSync('pkill', ['-KILL', '-P', String(pid)], { stdio: 'ignore', timeout: 5_000 });
+    try {
+        child.kill('SIGKILL');
+    }
+    catch {
+        /* already gone */
+    }
+}

package/dist/tool/harness-primitives.d.ts

@@ -2,9 +2,10 @@
  * 平台默认 Harness 原语：read_file / write_file / execute_command。
  *
  * 不写进 agent.manifest.toolsets。同名业务工具优先（问数 file-io 等）。
- * 读：工作目录 + 技能包 + EAP_LOCAL_SKILLS_DIR + FILE_IO_ROOT。
- * 写：仅工作目录，且不跟随符号链接。
- * 命令：cwd 落在 jail 内；环境变量白名单，不继承 process.env。
+ * 写：`users/<userId>/`（含用户自己的 skills）。
+ * 读：写根 + 已装配 `preinstall/tools`、`preinstall/skills`。
+ * 命令：cwd 仅写根。技能包只读，EAP_SKILL_DIR 为整包绝对根（不限 scripts/）。不把预装拷进用户装配槽。
+ * 开发态可选 overlay：`EAP_LOCAL_SKILLS_DIR` / `EAP_LOCAL_TOOLS_DIR`（只读）。
  */
 import type { LoadedToolMap } from './loaded-tool-definition.js';
 import type { IToolExecutor, ToolCallRequest, ToolCallResult } from './tool-executor.interface.js';
@@ -12,18 +13,39 @@ export declare function mergeHarnessPrimitives(loadedTools: LoadedToolMap | unde
 /** 装配点：业务 toolsets + 平台 Harness 原语。 */
 export declare function assembleLoadedTools(loadedTools: LoadedToolMap | undefined): LoadedToolMap | undefined;
 export interface HarnessJailOptions {
+    /** 用户写根；缺省则拒绝 write_file / execute_command */
     workdir?: string;
     extraRoots?: string[];
 }
+/** `{agentDir}/users/<userId>`（写根；含用户 skills） */
+export declare function resolveUserDir(agentDir: string, userId: string): string;
+export declare function collectToolBundlePaths(loadedTools?: LoadedToolMap): string[];
+export declare function resolveJailFromState(state: {
+    agentDir?: unknown;
+    userId?: unknown;
+    executionContext?: {
+        userId?: string | null;
+    };
+    loadedTools?: LoadedToolMap;
+    skillDefinitions?: Record<string, {
+        bundlePath?: string;
+    }>;
+}): HarnessJailOptions;
 export declare function resolveJailRoots(options?: HarnessJailOptions): string[];
+/** 路径落在写根外的 extraRoot 时，返回该 extraRoot。 */
+export declare function extraRootContaining(abs: string, extraRoots: string[], workdir: string): string | undefined;
 export declare function resolveJailedPath(requested: string, roots: string[], opts?: {
     mustExist?: boolean;
+    relativeBase?: string;
 }): string;
 export declare class HarnessPrimitiveExecutor implements IToolExecutor {
     private readonly workdir?;
     private readonly extraRoots?;
     constructor(options?: HarnessJailOptions);
+    private workdirFor;
     private rootsFor;
+    private extraRootsFor;
+    private requireWorkdir;
     execute(request: ToolCallRequest): Promise<ToolCallResult>;
     private readFile;
     private writeFile;