@gt-fe/eap-runtime 0.0.20 → 0.0.21

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

@@ -10,6 +10,7 @@
 import type { ILocalToolInstallStore, LocalToolInstallRecord } from '@gt-fe/eap-contracts';
 import { type DeploymentContext } from './tool-execution-router.js';
 import type { IToolExecutor } from './tool-executor.interface.js';
+import { type HarnessJailOptions } from './harness-primitives.js';
 export declare class EmptyInstallStore implements ILocalToolInstallStore {
     get(): null;
     listReady(): LocalToolInstallRecord[];
@@ -28,6 +29,11 @@ export interface CreateToolExecutorOptions {
      * 也可用环境变量 EAP_TOOL_GATEWAY_TRANSPORT=http|mcp。
      */
     gatewayTransport?: ToolGatewayTransport;
+    /**
+     * 开发 overlay jail。缺省则在本函数调用时从 process.env 捕获。
+     * SDK createAgent 会在 createDevRuntime 返回后恢复 env，必须在那时之前钉死。
+     */
+    jail?: HarnessJailOptions;
 }
 /**
  * 创建经 ToolExecutionRouter 包装的 IToolExecutor（生产装配入口）

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

@@ -11,7 +11,7 @@ import { HttpToolExecutor } from './http-tool-executor.js';
 import { isAbsoluteHttpUrl, McpToolExecutor } from './mcp-tool-executor.js';
 import { LocalToolExecutor } from './local-tool-executor.js';
 import { ToolExecutionRouter, } from './tool-execution-router.js';
-import { withHarnessPrimitives } from './harness-primitives.js';
+import { captureOverlayJailOptions, withHarnessPrimitives, } from './harness-primitives.js';
 export class EmptyInstallStore {
     get() {
         return null;
@@ -51,8 +51,9 @@ export function createToolExecutor(options) {
     const localExecutor = new LocalToolExecutor({ installStore });
     const deploymentContext = resolveDeploymentContext(options.deploymentContext);
     const hasGateway = isAbsoluteHttpUrl(options.foundationUrl);
+    const jail = options.jail ?? captureOverlayJailOptions();
     if (!hasGateway && (deploymentContext === 'desktop' || deploymentContext === 'dev')) {
-        return withHarnessPrimitives(localExecutor);
+        return withHarnessPrimitives(localExecutor, jail);
     }
     const transport = resolveGatewayTransport(options.gatewayTransport);
     const serverExecutor = createServerExecutor(options.foundationUrl, transport, options.httpTimeout);
@@ -64,5 +65,5 @@ export function createToolExecutor(options) {
         toolTypes: options.toolTypes,
         toolRuntimes: options.toolRuntimes,
         forceToolServer: options.forceToolServer,
-    }));
+    }), jail);
 }

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

@@ -5,7 +5,9 @@
  * 写：`users/<userId>/`（含用户自己的 skills）。
  * 读：写根 + 已装配 `preinstall/tools`、`preinstall/skills`。
  * 命令：cwd 仅写根。技能包只读，EAP_SKILL_DIR 为整包绝对根（不限 scripts/）。不把预装拷进用户装配槽。
- * 开发态可选 overlay：`EAP_LOCAL_SKILLS_DIR` / `EAP_LOCAL_TOOLS_DIR`（只读）。
+ * 开发态 overlay：`EAP_LOCAL_SKILLS_DIR` / `EAP_LOCAL_TOOLS_DIR`（只读）。在 `createDevRuntime` /
+ * `createToolExecutor` 时钉进执行器 extraRoots；SDK `createAgent` 构造完会恢复 process.env，
+ * 请求时不再读这两项。相对 `read_file` 会把 overlay 根下直接子目录里带 SKILL.md 的包纳入唯一命中。
  */
 import type { LoadedToolMap } from './loaded-tool-definition.js';
 import type { IToolExecutor, ToolCallRequest, ToolCallResult } from './tool-executor.interface.js';
@@ -31,6 +33,12 @@ export declare function resolveJailFromState(state: {
         bundlePath?: string;
     }>;
 }): HarnessJailOptions;
+/**
+ * 把开发 overlay 钉进 Harness extraRoots。
+ * SDK `createAgent` 在 createDevRuntime 返回后恢复 process.env，请求时不能再读这两项。
+ */
+export declare function captureOverlayJailOptions(env?: NodeJS.ProcessEnv): Pick<HarnessJailOptions, 'extraRoots'>;
+/** 只认 workdir + extraRoots。开发 overlay 必须由调用方在构造时传入，不在此处读 process.env。 */
 export declare function resolveJailRoots(options?: HarnessJailOptions): string[];
 /** 路径落在写根外的 extraRoot 时，返回该 extraRoot。 */
 export declare function extraRootContaining(abs: string, extraRoots: string[], workdir: string): string | undefined;

package/dist/tool/harness-primitives.js

@@ -5,10 +5,12 @@
  * 写：`users/<userId>/`（含用户自己的 skills）。
  * 读：写根 + 已装配 `preinstall/tools`、`preinstall/skills`。
  * 命令：cwd 仅写根。技能包只读，EAP_SKILL_DIR 为整包绝对根（不限 scripts/）。不把预装拷进用户装配槽。
- * 开发态可选 overlay：`EAP_LOCAL_SKILLS_DIR` / `EAP_LOCAL_TOOLS_DIR`（只读）。
+ * 开发态 overlay：`EAP_LOCAL_SKILLS_DIR` / `EAP_LOCAL_TOOLS_DIR`（只读）。在 `createDevRuntime` /
+ * `createToolExecutor` 时钉进执行器 extraRoots；SDK `createAgent` 构造完会恢复 process.env，
+ * 请求时不再读这两项。相对 `read_file` 会把 overlay 根下直接子目录里带 SKILL.md 的包纳入唯一命中。
  */
 import { spawn } from 'node:child_process';
-import { constants as fsConstants, existsSync, realpathSync } from 'node:fs';
+import { constants as fsConstants, existsSync, readdirSync, 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';
@@ -150,21 +152,29 @@ export function resolveJailFromState(state) {
         extraRoots: scoped,
     };
 }
-function deploymentAllowsLocalOverlay() {
-    const ctx = process.env.EAP_DEPLOYMENT_CONTEXT?.trim();
+function deploymentAllowsLocalOverlay(env = process.env) {
+    const ctx = env.EAP_DEPLOYMENT_CONTEXT?.trim();
     return ctx === 'dev' || ctx === 'desktop';
 }
-function devOverlayRoots() {
-    if (!deploymentAllowsLocalOverlay())
+function overlayRootsFromEnv(env = process.env) {
+    if (!deploymentAllowsLocalOverlay(env))
         return [];
     const extra = [];
     for (const key of ['EAP_LOCAL_SKILLS_DIR', 'EAP_LOCAL_TOOLS_DIR']) {
-        const value = process.env[key]?.trim();
+        const value = env[key]?.trim();
         if (value)
             extra.push(value);
     }
     return extra;
 }
+/**
+ * 把开发 overlay 钉进 Harness extraRoots。
+ * SDK `createAgent` 在 createDevRuntime 返回后恢复 process.env，请求时不能再读这两项。
+ */
+export function captureOverlayJailOptions(env = process.env) {
+    const extraRoots = overlayRootsFromEnv(env);
+    return extraRoots.length > 0 ? { extraRoots } : {};
+}
 function tryRealpath(p) {
     try {
         return realpathSync(p);
@@ -173,11 +183,11 @@ function tryRealpath(p) {
         return undefined;
     }
 }
+/** 只认 workdir + extraRoots。开发 overlay 必须由调用方在构造时传入，不在此处读 process.env。 */
 export function resolveJailRoots(options) {
     const workdir = options?.workdir?.trim() ? path.resolve(options.workdir) : undefined;
     const candidates = [
         ...(workdir ? [workdir] : []),
-        ...devOverlayRoots(),
         ...(options?.extraRoots ?? []),
     ];
     const roots = [];
@@ -257,16 +267,37 @@ function userReadBase(workdir) {
         ? (tryRealpath(path.resolve(workdir)) ?? path.resolve(workdir))
         : undefined;
 }
+function isSkillPackageDir(dir) {
+    return existsSync(path.join(dir, 'SKILL.md')) || existsSync(path.join(dir, 'skill.md'));
+}
 function skillPackageRoots(roots) {
     const out = [];
     const seen = new Set();
+    const add = (dir) => {
+        if (seen.has(dir))
+            return;
+        seen.add(dir);
+        out.push(dir);
+    };
     for (const root of roots) {
         const resolved = path.resolve(root);
-        if (seen.has(resolved))
+        if (isSkillPackageDir(resolved)) {
+            add(resolved);
             continue;
-        seen.add(resolved);
-        if (existsSync(path.join(resolved, 'SKILL.md')) || existsSync(path.join(resolved, 'skill.md'))) {
-            out.push(resolved);
+        }
+        let entries;
+        try {
+            entries = readdirSync(resolved, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const ent of entries) {
+            if (!ent.isDirectory())
+                continue;
+            const child = path.join(resolved, ent.name);
+            if (isSkillPackageDir(child))
+                add(child);
         }
     }
     return out;

package/dist/tool/index.d.ts

@@ -2,6 +2,7 @@ export type { AuthContext, ToolCallRequest, ToolCallResult, LLMToolCall, LLMTool
 export { hydrateMcpTools, isMcpDiscoverStub, needsMcpHydration, parseListedTools, toolsetCodeFromLoaded, toolTraceIdentity, } from './mcp-list.js';
 export { toLoadedToolMap, type LoadedToolDefinition, type LoadedToolMap, type LoadedToolManifestRef, } from './loaded-tool-definition.js';
 export { ToolOrchestrator } from './tool-orchestrator.js';
+export { isRetryableToolFailure, resolveToolRetryConfig, type ToolFailureShape, } from './tool-retry.js';
 export { HttpToolExecutor, type HttpToolExecutorOptions, } from './http-tool-executor.js';
 export { McpToolExecutor, isAbsoluteHttpUrl, type McpToolExecutorOptions, } from './mcp-tool-executor.js';
 export { LocalToolExecutor, isLocalPreferredExecution, resolveCodeExecutionFromRequest } from './local-tool-executor.js';
@@ -12,7 +13,7 @@ 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, resolveUserDir, resolveJailFromState, collectToolBundlePaths, type HarnessJailOptions as BuiltinJailOptions, } from './harness-primitives.js';
+export { assembleLoadedTools, mergeHarnessPrimitives as mergeBuiltinTools, withHarnessPrimitives as withBuiltinTools, HarnessPrimitiveExecutor as BuiltinToolExecutor, resolveUserDir, resolveJailFromState, captureOverlayJailOptions, collectToolBundlePaths, type HarnessJailOptions as BuiltinJailOptions, } from './harness-primitives.js';
 export { resolveShellSpawn, shellNameFor, commandDialectLines, findPythonInterpreter, findNodeInterpreter, ensureInterpreterShims, substituteSkillDir, } from './harness-command.js';
 export { expandSkillScriptRefs, isSkillEntryFile, EAP_SKILL_DIR_ENV, } from './skill-script-refs.js';
 export { ToolResultInjector, type ToolMessage, } from './tool-result-injector.js';

package/dist/tool/index.js

@@ -1,6 +1,7 @@
 export { hydrateMcpTools, isMcpDiscoverStub, needsMcpHydration, parseListedTools, toolsetCodeFromLoaded, toolTraceIdentity, } from './mcp-list.js';
 export { toLoadedToolMap, } from './loaded-tool-definition.js';
 export { ToolOrchestrator } from './tool-orchestrator.js';
+export { isRetryableToolFailure, resolveToolRetryConfig, } from './tool-retry.js';
 export { HttpToolExecutor, } from './http-tool-executor.js';
 export { McpToolExecutor, isAbsoluteHttpUrl, } from './mcp-tool-executor.js';
 export { LocalToolExecutor, isLocalPreferredExecution, resolveCodeExecutionFromRequest } from './local-tool-executor.js';
@@ -11,7 +12,7 @@ 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, resolveUserDir, resolveJailFromState, collectToolBundlePaths, } from './harness-primitives.js';
+export { assembleLoadedTools, mergeHarnessPrimitives as mergeBuiltinTools, withHarnessPrimitives as withBuiltinTools, HarnessPrimitiveExecutor as BuiltinToolExecutor, resolveUserDir, resolveJailFromState, captureOverlayJailOptions, collectToolBundlePaths, } from './harness-primitives.js';
 export { resolveShellSpawn, shellNameFor, commandDialectLines, findPythonInterpreter, findNodeInterpreter, ensureInterpreterShims, substituteSkillDir, } from './harness-command.js';
 export { expandSkillScriptRefs, isSkillEntryFile, EAP_SKILL_DIR_ENV, } from './skill-script-refs.js';
 export { ToolResultInjector, } from './tool-result-injector.js';

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

@@ -61,6 +61,33 @@ export interface ToolCallRequest {
      * 对标 Claude CLAUDE_SKILL_DIR。
      */
     skillDir?: string;
+    /**
+     * 会话级 rag 数据源勾选（数据源 id 列表，tool 节点从 GraphState 转递）。
+     * RagSearchToolExecutor 等检索型装饰器消费；普通工具执行器忽略。
+     */
+    ragSources?: string[];
+    /**
+     * 图声明的 rag 检索面（tool 节点 config.retrievalSources 原样转递，工具形态声明位）。
+     * RagSearchToolExecutor 以其为该请求的数据源目录（覆盖装配期配置）；
+     * 普通工具执行器忽略。
+     */
+    ragSourcesConfig?: import('../graph/nodes/rag/types.js').RagRetrievalSources;
+    /**
+     * 图声明的融合总条数（tool 节点 config.totalK 原样转递，工具形态声明位）。
+     * RagSearchToolExecutor 以其为该请求的 totalK 缺省（调用级 topK 参数仍可覆盖）；
+     * 普通工具执行器忽略。
+     */
+    ragTotalK?: number;
+    /**
+     * 请求级 rag 检索范围（fileIds/dirPaths，tool 节点从 GraphState 转递）。
+     * 与 ragSources 同一消费面。
+     */
+    ragScope?: import('../graph/nodes/rag/types.js').RagScope;
+    /**
+     * 本轮 loadedTools 快照（tool 节点从 GraphState 转递，引用传递零拷贝）。
+     * rag_search 装饰器据此组装内层工具表（含会话勾选后的圈定）；普通执行器忽略。
+     */
+    loadedTools?: import('./loaded-tool-definition.js').LoadedToolMap;
 }
 /**
  * ToolCallResult — Tool 调用结果

package/dist/tool/tool-orchestrator.d.ts

@@ -6,6 +6,7 @@
  */
 import { type ExecutionContext } from '@gt-fe/eap-contracts';
 import type { IGovernanceClient } from '../governance/governance-client.js';
+import type { IAuditReporter } from '../governance/audit-reporter.js';
 export type { AuthContext, ToolCallRequest, ToolCallResult, LLMToolCall, LLMToolCallResponse, IToolExecutor, } from './tool-executor.interface.js';
 import type { AuthContext, ToolCallRequest, ToolCallResult, LLMToolCallResponse, IToolExecutor } from './tool-executor.interface.js';
 /**
@@ -14,7 +15,8 @@ import type { AuthContext, ToolCallRequest, ToolCallResult, LLMToolCallResponse,
 export declare class ToolOrchestrator {
     private readonly toolExecutor;
     private readonly governanceClient?;
-    constructor(toolExecutor: IToolExecutor, governanceClient?: IGovernanceClient | undefined);
+    private readonly auditReporter?;
+    constructor(toolExecutor: IToolExecutor, governanceClient?: IGovernanceClient | undefined, auditReporter?: IAuditReporter | undefined);
     extractToolCalls(llmResponse: LLMToolCallResponse, authContext: AuthContext): ToolCallRequest[];
     executeSingle(request: ToolCallRequest, executionContext?: ExecutionContext): Promise<ToolCallResult>;
     executeAll(requests: ToolCallRequest[], executionContext?: ExecutionContext): Promise<ToolCallResult[]>;

package/dist/tool/tool-orchestrator.js

@@ -12,9 +12,11 @@ import { assertToolPermission, GovernanceUnavailableError, PermissionDeniedError
 export class ToolOrchestrator {
     toolExecutor;
     governanceClient;
-    constructor(toolExecutor, governanceClient) {
+    auditReporter;
+    constructor(toolExecutor, governanceClient, auditReporter) {
         this.toolExecutor = toolExecutor;
         this.governanceClient = governanceClient;
+        this.auditReporter = auditReporter;
     }
     extractToolCalls(llmResponse, authContext) {
         if (!llmResponse.toolCalls || llmResponse.toolCalls.length === 0) {
@@ -37,13 +39,20 @@ export class ToolOrchestrator {
         });
     }
     async executeSingle(request, executionContext) {
-        if (this.governanceClient &&
-            executionContext?.delegationToken &&
-            !isBuiltinToolExecution(request.execution)) {
+        if (this.governanceClient && !isBuiltinToolExecution(request.execution)) {
+            const ctx = executionContext ?? {
+                userId: '',
+                callerType: 'user',
+                roles: [],
+                permissions: [],
+                delegationToken: '',
+                correlationId: request.correlationId ?? '',
+            };
             try {
-                await assertToolPermission(this.governanceClient, executionContext, request.toolName, {
+                await assertToolPermission(this.governanceClient, ctx, request.toolName, {
                     dataScope: request.dataScope ?? 'user-bound',
-                    resourceOwnerId: request.resourceOwnerId ?? executionContext.userId ?? undefined,
+                    resourceOwnerId: request.resourceOwnerId ?? (ctx.userId || undefined),
+                    auditReporter: this.auditReporter,
                 });
             }
             catch (error) {

package/dist/tool/tool-retry.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Tool 单次调用的瞬时失败重试。
+ * 不整段重跑节点 / Skill 子图（会重复 LLM 流式输出）。
+ */
+import type { BackoffStrategy, NodeRetryConfig } from '../graph/contracts/executable-graph.js';
+export interface ToolFailureShape {
+    success: boolean;
+    error?: string;
+    errorCode?: string;
+    retryable?: boolean;
+}
+export declare function isRetryableToolFailure(result: ToolFailureShape): boolean;
+export declare function resolveToolRetryConfig(retry?: NodeRetryConfig): Required<NodeRetryConfig> | undefined;
+export declare function toolRetryDelayMs(attemptIndex: number, backoff: BackoffStrategy): number;
+export declare function sleepToolRetry(ms: number): Promise<void>;

package/dist/tool/tool-retry.js

@@ -0,0 +1,69 @@
+/**
+ * Tool 单次调用的瞬时失败重试。
+ * 不整段重跑节点 / Skill 子图（会重复 LLM 流式输出）。
+ */
+import { DEFAULT_NODE_RETRY_CONFIG } from '../graph/retry/node-retry.js';
+import { isAbortError } from './timeout.js';
+const NON_RETRYABLE_CODES = new Set([
+    'interceptor_denied',
+    'interceptor_ask',
+    'hitl_rejected',
+    'NO_PERMISSION',
+    'DATA_SCOPE_DENIED',
+    'TOOL_NOT_FOUND',
+    'INVALID_ARGUMENTS',
+    'PARAMS_INVALID',
+    'TOOL_TIMEOUT',
+]);
+export function isRetryableToolFailure(result) {
+    if (result.success)
+        return false;
+    if (result.retryable === true)
+        return true;
+    if (result.retryable === false)
+        return false;
+    const code = result.errorCode ?? '';
+    if (NON_RETRYABLE_CODES.has(code))
+        return false;
+    const msg = (result.error ?? '').toLowerCase();
+    if (/timeout after \d+s/.test(msg) || isAbortError(result.error))
+        return false;
+    if (code === 'RATE_LIMITED' || code === 'CIRCUIT_OPEN')
+        return true;
+    return (/(?:^|\D)(429|502|503|504)(?:\D|$)/.test(msg) ||
+        /econnreset|econnrefused|enotfound|etimedout|socket hang up|fetch failed|network error/.test(msg));
+}
+export function resolveToolRetryConfig(retry) {
+    if (!retry || typeof retry.maxRetries !== 'number' || retry.maxRetries <= 0) {
+        return undefined;
+    }
+    return {
+        maxRetries: retry.maxRetries,
+        backoff: retry.backoff ?? DEFAULT_NODE_RETRY_CONFIG.backoff,
+    };
+}
+export function toolRetryDelayMs(attemptIndex, backoff) {
+    let delay;
+    switch (backoff.type) {
+        case 'exponential':
+            delay = backoff.baseDelay * Math.pow(2, attemptIndex);
+            break;
+        case 'linear':
+            delay = backoff.baseDelay * (attemptIndex + 1);
+            break;
+        default:
+            delay = backoff.baseDelay;
+    }
+    delay = Math.min(delay, backoff.maxDelay);
+    if (backoff.jitter && backoff.jitter > 0) {
+        const jitterRange = delay * backoff.jitter;
+        delay += Math.random() * jitterRange * 2 - jitterRange;
+        delay = Math.max(0, delay);
+    }
+    return Math.round(delay);
+}
+export async function sleepToolRetry(ms) {
+    if (ms <= 0)
+        return;
+    await new Promise((resolve) => setTimeout(resolve, ms));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gt-fe/eap-runtime",
-  "version": "0.0.20",
+  "version": "0.0.21",
   "description": "Enterprise Agent Platform — Runtime核心：Graph执行引擎、Task生命周期、Session管理、Checkpoint持久化",
   "type": "module",
   "main": "dist/index.js",
@@ -20,7 +20,7 @@
     "ioredis": "^5.4.0",
     "pg": "^8.13.0",
     "yaml": "^2.6.1",
-    "@gt-fe/eap-contracts": "0.0.11"
+    "@gt-fe/eap-contracts": "0.0.12"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",