@gt-fe/eap-runtime 0.0.10 → 0.0.11

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;