@gt-fe/eap-runtime 0.0.20 → 0.0.21

package/dist/governance/permission-guard.d.ts

@@ -2,7 +2,8 @@
  * 执行期 Tool 权限守卫
  */
 import type { ExecutionContext, PermissionDenyReason } from '@gt-fe/eap-contracts';
-import type { IGovernanceClient } from './governance-client.js';
+import { type IGovernanceClient } from './governance-client.js';
+import { type IAuditReporter } from './audit-reporter.js';
 export declare class GovernanceUnavailableError extends Error {
     readonly reason: PermissionDenyReason;
     constructor(message?: string);
@@ -15,6 +16,9 @@ export declare function permissionMessage(kind: 'tool' | 'skill', reason: Permis
 export declare function assertToolPermission(client: IGovernanceClient | undefined, ctx: ExecutionContext, toolId: string, options?: {
     dataScope?: 'user-bound' | 'department-bound' | 'global';
     resourceOwnerId?: string;
+    auditReporter?: IAuditReporter;
 }): Promise<void>;
 /** Skill 激活守卫（04 R15.3） */
-export declare function assertSkillPermission(client: IGovernanceClient | undefined, ctx: ExecutionContext, skillId: string): Promise<void>;
+export declare function assertSkillPermission(client: IGovernanceClient | undefined, ctx: ExecutionContext, skillId: string, options?: {
+    auditReporter?: IAuditReporter;
+}): Promise<void>;

package/dist/governance/permission-guard.js

@@ -1,6 +1,8 @@
 /**
  * 执行期 Tool 权限守卫
  */
+import { AllowAllGovernanceClient } from './governance-client.js';
+import { reportPermissionDenial } from './audit-reporter.js';
 export class GovernanceUnavailableError extends Error {
     reason = 'GOVERNANCE_UNAVAILABLE';
     constructor(message = '治理服务不可用') {
@@ -27,8 +29,17 @@ export async function assertToolPermission(client, ctx, toolId, options) {
     if (!client) {
         return;
     }
-    if (!ctx.delegationToken && ctx.callerType === 'user') {
-        return;
+    // 会向治理服务校验的客户端无 token 即拒绝。AllowAll 不校验，不要求 token。
+    if (!ctx.delegationToken && !(client instanceof AllowAllGovernanceClient)) {
+        const err = new PermissionDeniedError('NO_PERMISSION', permissionMessage('tool', 'NO_PERMISSION'));
+        await reportPermissionDenial(options?.auditReporter, {
+            kind: 'tool',
+            resourceId: toolId,
+            reason: 'NO_PERMISSION',
+            userId: ctx.userId,
+            correlationId: ctx.correlationId,
+        });
+        throw err;
     }
     const result = await client.checkPermission(ctx, {
         resourceType: 'tool',
@@ -42,16 +53,31 @@ export async function assertToolPermission(client, ctx, toolId, options) {
     }
     if (!result.allowed) {
         const reason = result.reason ?? 'NO_PERMISSION';
+        await reportPermissionDenial(options?.auditReporter, {
+            kind: 'tool',
+            resourceId: toolId,
+            reason,
+            userId: ctx.userId,
+            correlationId: ctx.correlationId,
+        });
         throw new PermissionDeniedError(reason, permissionMessage('tool', reason));
     }
 }
 /** Skill 激活守卫（04 R15.3） */
-export async function assertSkillPermission(client, ctx, skillId) {
+export async function assertSkillPermission(client, ctx, skillId, options) {
     if (!client || !skillId) {
         return;
     }
-    if (!ctx.delegationToken && ctx.callerType === 'user') {
-        return;
+    if (!ctx.delegationToken && !(client instanceof AllowAllGovernanceClient)) {
+        const err = new PermissionDeniedError('NO_PERMISSION', permissionMessage('skill', 'NO_PERMISSION'));
+        await reportPermissionDenial(options?.auditReporter, {
+            kind: 'skill',
+            resourceId: skillId,
+            reason: 'NO_PERMISSION',
+            userId: ctx.userId,
+            correlationId: ctx.correlationId,
+        });
+        throw err;
     }
     const result = await client.checkPermission(ctx, {
         resourceType: 'skill',
@@ -63,6 +89,13 @@ export async function assertSkillPermission(client, ctx, skillId) {
     }
     if (!result.allowed) {
         const reason = result.reason ?? 'NO_PERMISSION';
+        await reportPermissionDenial(options?.auditReporter, {
+            kind: 'skill',
+            resourceId: skillId,
+            reason,
+            userId: ctx.userId,
+            correlationId: ctx.correlationId,
+        });
         throw new PermissionDeniedError(reason, permissionMessage('skill', reason));
     }
 }

package/dist/graph/adapters/graph-nesting.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Skill 子图只允许一层：Agent 图可以有 type=subgraph，子图 DSL 不能再有。
+ * Checkpoint / HITL / Span 未按嵌套设计（B14）。
+ */
+import type { GraphDSL, GraphNode } from '../contracts/executable-graph.js';
+export declare function subgraphNodesOf(dsl: GraphDSL | undefined): GraphNode[];
+/**
+ * Skill 子图（compileSubGraph 入参、父节点内嵌 subgraphDsl、运行时 workflow）不得含 type=subgraph。
+ */
+export declare function assertSkillGraphHasNoSubgraphNodes(dsl: GraphDSL, label?: string): void;
+/** 父图 buildGraph：内嵌 subgraphDsl 在编译父图时就拒绝，不等第一次 invoke。 */
+export declare function assertEmbeddedSubgraphsAreFlat(dsl: GraphDSL): void;

package/dist/graph/adapters/graph-nesting.js

@@ -0,0 +1,29 @@
+/**
+ * Skill 子图只允许一层：Agent 图可以有 type=subgraph，子图 DSL 不能再有。
+ * Checkpoint / HITL / Span 未按嵌套设计（B14）。
+ */
+import { AppError, ErrorCodes } from '@gt-fe/eap-contracts';
+export function subgraphNodesOf(dsl) {
+    return (dsl?.nodes ?? []).filter((node) => node.type === 'subgraph');
+}
+/**
+ * Skill 子图（compileSubGraph 入参、父节点内嵌 subgraphDsl、运行时 workflow）不得含 type=subgraph。
+ */
+export function assertSkillGraphHasNoSubgraphNodes(dsl, label) {
+    const nested = subgraphNodesOf(dsl);
+    if (nested.length === 0)
+        return;
+    const where = label ?? dsl.name ?? 'unnamed';
+    throw new AppError(ErrorCodes.GRAPH_BUILD_FAILED, `Skill 子图不允许再包含 type=subgraph（不支持子图套子图）: ${where} → ${nested.map((n) => n.id).join(', ')}`, { exposeMessage: true });
+}
+/** 父图 buildGraph：内嵌 subgraphDsl 在编译父图时就拒绝，不等第一次 invoke。 */
+export function assertEmbeddedSubgraphsAreFlat(dsl) {
+    for (const node of dsl.nodes ?? []) {
+        if (node.type !== 'subgraph')
+            continue;
+        const nested = node.config?.['subgraphDsl'];
+        if (nested?.nodes?.length) {
+            assertSkillGraphHasNoSubgraphNodes(nested, node.id);
+        }
+    }
+}

package/dist/graph/adapters/index.d.ts

@@ -1,3 +1,5 @@
 export { LangGraphAdapter } from './langgraph.adapter.js';
 export { LangGraphCheckpointer } from './langgraph-checkpointer.js';
 export { SubGraphCompiler } from './subgraph-compiler.js';
+export { assertSkillGraphHasNoSubgraphNodes, assertEmbeddedSubgraphsAreFlat, subgraphNodesOf, } from './graph-nesting.js';
+export { isSkillContextIsolated, isolatedSkillMessages, isolatedSkillOutput, } from './skill-isolate.js';

package/dist/graph/adapters/index.js

@@ -1,3 +1,5 @@
 export { LangGraphAdapter } from './langgraph.adapter.js';
 export { LangGraphCheckpointer } from './langgraph-checkpointer.js';
 export { SubGraphCompiler } from './subgraph-compiler.js';
+export { assertSkillGraphHasNoSubgraphNodes, assertEmbeddedSubgraphsAreFlat, subgraphNodesOf, } from './graph-nesting.js';
+export { isSkillContextIsolated, isolatedSkillMessages, isolatedSkillOutput, } from './skill-isolate.js';

package/dist/graph/adapters/langgraph.adapter.d.ts

@@ -12,9 +12,11 @@ import type { ExecutableGraph, GraphDSL, GraphState, RuntimeEvent, CheckpointDat
 import type { ICheckpointSaver } from '../../checkpoint/contracts/checkpoint-saver.contract.js';
 import type { HitlHandler } from '../hitl/hitl-handler.js';
 import { type ILLMProvider } from '../nodes/llm-node.js';
+import { type RagNodeDeps } from '../nodes/rag/index.js';
 import type { IToolExecutor } from '../../tool/tool-executor.interface.js';
 import type { IGovernanceClient } from '../../governance/governance-client.js';
 import { type ConditionEvaluatorFn } from '../condition-evaluator.js';
+import type { ExecutionInterceptors } from '../../execution/interceptors.js';
 /** 图未写 `config.maxIterations` 时的 recursionLimit。`agent ⇄ tools` 一圈约 2，50 ≈ 24 次工具往返。 */
 export declare const DEFAULT_GRAPH_RECURSION_LIMIT = 50;
 /**
@@ -26,6 +28,7 @@ export declare const DEFAULT_GRAPH_RECURSION_LIMIT = 50;
  * 3. 提供 Checkpoint 提取与恢复能力
  */
 export declare class LangGraphAdapter implements IStateGraphEngine {
+    private readonly auditReporter?;
     private readonly checkpointer;
     private readonly subGraphCompiler;
     private readonly llmProvider;
@@ -42,11 +45,17 @@ export declare class LangGraphAdapter implements IStateGraphEngine {
      */
     private readonly governanceClient?;
     private hitlHandler?;
-    constructor(checkpointSaver?: ICheckpointSaver, llmProvider?: ILLMProvider, toolExecutor?: IToolExecutor, governanceClient?: IGovernanceClient, hitlHandler?: HitlHandler);
+    private readonly ragNodeDeps?;
+    private readonly interceptors?;
+    /** 开发 overlay 根；createDevRuntime 在恢复 process.env 之前钉死 */
+    private overlayExtraRoots;
+    constructor(checkpointSaver?: ICheckpointSaver, llmProvider?: ILLMProvider, toolExecutor?: IToolExecutor, governanceClient?: IGovernanceClient, hitlHandler?: HitlHandler, ragNodeDeps?: RagNodeDeps, interceptors?: ExecutionInterceptors, auditReporter?: import("../../governance/audit-reporter.js").IAuditReporter | undefined);
     /**
      * 注册自定义条件评估函数
      */
     registerConditionEvaluator(name: string, fn: ConditionEvaluatorFn): void;
+    /** SDK 恢复 env 之后仍要把 overlay 算进 LLM jail 根，不能再读 process.env。 */
+    bindOverlayExtraRoots(roots: string[] | undefined): void;
     /**
      * 节点旁路推送 RuntimeEvent（子图 Skill 生命周期、Tool 执行）。
      * 无本次执行流式袋时为空操作（纯 invoke）。
@@ -111,21 +120,15 @@ export declare class LangGraphAdapter implements IStateGraphEngine {
     private buildSkillCatalog;
     private createToolNodeFunction;
     private createLLMNodeFunction;
+    /**
+     * RAG 节点：编译期 fail-fast（deps 缺失），请求级状态经 execute(state) 流转
+     */
+    private createRagNodeFunction;
     /**
      * 子图节点：优先 config.subgraphDsl；否则按 skillId 从 state.skillDefinitions.workflow 解析。
      * 技能正文用短目录 + read_file，不灌 system。
      */
     private createSubGraphNodeFunction;
-    /**
-     * 并行节点：并行执行多个子任务分支
-     *
-     * 支持两种并行模式：
-     * 1. branches 模式：node.branches 列出要并行执行的节点 ID，每个节点的执行函数由 DSL 定义
-     * 2. tasks 模式：node.config.tasks 列出要并行执行的异步任务函数
-     *
-     * 执行结果合并到 state.__parallelResults 中。
-     */
-    private createParallelNodeFunction;
     /**
      * 代码执行节点：在受限沙箱中执行用户代码
      *
@@ -173,6 +176,17 @@ export declare class LangGraphAdapter implements IStateGraphEngine {
      * 否则多轮回放时 DeepSeek thinking 会因缺少 reasoning_content 而 400，
      * tool 消息也会丢掉 tool_call_id。
      */
+    /**
+     * 工具形态检索面白名单（图声明即真相）：tool 节点 config.retrievalSources 声明的
+     * 数据源目录 → 本图工具白名单（声明源解析出的工具 + rag_search）。未声明的检索类
+     * 工具对主 LLM 工具表与执行链整体不可见/不可用；图未声明 = 不收敓名单（通用形态）。
+     *
+     * 约束——单检索面假设：find 只取全图首个带 retrievalSources 的 tool 节点、按它过滤
+     * 全图 loadedTools。多 tool 节点各声明检索面属未支持场景：第二面的工具会被当成
+     * 未声明而过滤，无法各自收敛；如需支持须改为 per-node 收敛（在节点边界分别过滤
+     * loadedTools，而非此处全图一次性收敛）。
+     */
+    private applyDeclaredSearchFace;
     private graphStateToLangGraphInput;
     /**
      * 将 LangGraph updates 模式输出转为平台 RuntimeEvent 序列

package/dist/graph/adapters/langgraph.adapter.js

@@ -11,8 +11,12 @@ import { StateGraph, START, END, } from '@langchain/langgraph';
 import { resolveCheckpointThreadId } from '../../session/persist-turn-messages.js';
 import { LangGraphCheckpointer } from './langgraph-checkpointer.js';
 import { SubGraphCompiler } from './subgraph-compiler.js';
+import { assertEmbeddedSubgraphsAreFlat } from './graph-nesting.js';
+import { isSkillContextIsolated } from './skill-isolate.js';
 import { LLMNode } from '../nodes/llm-node.js';
 import { ToolNode } from '../nodes/tool-node.js';
+import { RagNode, RAG_SEARCH_TOOL_NAME, RagSearchToolExecutor } from '../nodes/rag/index.js';
+import { resolveRagSources, appendSourceCatalog } from '../nodes/rag/tools.js';
 import { ToolOrchestrator } from '../../tool/tool-orchestrator.js';
 import { ToolResultInjector } from '../../tool/tool-result-injector.js';
 import { fileArtifactFromToolOutput } from '../../tool/file-artifact.js';
@@ -33,6 +37,7 @@ import { classifySkillRead } from './skill-read.js';
 import { skillEntryInvocationFromTool } from './skill-entry-span.js';
 import { withGraphSpan } from '../trace-span.js';
 import { executionTraceFromState, getExecutionStream, runWithExecutionTrace, } from '../execution-trace-context.js';
+import { isRetryableToolFailure, resolveToolRetryConfig, sleepToolRetry, toolRetryDelayMs, } from '../../tool/tool-retry.js';
 /** 图未写 `config.maxIterations` 时的 recursionLimit。`agent ⇄ tools` 一圈约 2，50 ≈ 24 次工具往返。 */
 export const DEFAULT_GRAPH_RECURSION_LIMIT = 50;
 /**
@@ -61,6 +66,7 @@ function langGraphRunOptions(dsl, extra) {
  * 3. 提供 Checkpoint 提取与恢复能力
  */
 export class LangGraphAdapter {
+    auditReporter;
     checkpointer;
     subGraphCompiler;
     llmProvider;
@@ -77,17 +83,29 @@ export class LangGraphAdapter {
      */
     governanceClient;
     hitlHandler;
-    constructor(checkpointSaver, llmProvider, toolExecutor, governanceClient, hitlHandler) {
+    ragNodeDeps;
+    interceptors;
+    /** 开发 overlay 根；createDevRuntime 在恢复 process.env 之前钉死 */
+    overlayExtraRoots = [];
+    constructor(checkpointSaver, llmProvider, toolExecutor, governanceClient, hitlHandler, ragNodeDeps, interceptors, auditReporter) {
+        this.auditReporter = auditReporter;
         this.governanceClient = governanceClient;
         this.hitlHandler = hitlHandler;
+        this.ragNodeDeps = ragNodeDeps;
+        this.interceptors = interceptors;
         this.checkpointer = checkpointSaver
             ? new LangGraphCheckpointer(checkpointSaver)
             : undefined;
         this.llmProvider = llmProvider ?? new EchoLLMProvider();
         this.toolExecutor = toolExecutor;
         this.toolOrchestrator = toolExecutor
-            ? new ToolOrchestrator(toolExecutor, governanceClient)
+            ? new ToolOrchestrator(toolExecutor, governanceClient, this.auditReporter)
             : undefined;
+        // rag_search 装饰器注入同款编排器（内层 kb 派发与 tool 节点同一链路；
+        // 装饰器 deps 已显式提供 orchestrator 时不覆盖）
+        if (toolExecutor instanceof RagSearchToolExecutor && this.toolOrchestrator) {
+            toolExecutor.attachToolOrchestrator(this.toolOrchestrator);
+        }
         this.toolResultInjector = new ToolResultInjector();
         this.conditionEvaluator = new ConditionEvaluator();
         this.systemPromptBuilder = new SystemPromptBuilder();
@@ -125,7 +143,7 @@ export class LangGraphAdapter {
             return 'none';
         });
         // 必须在其他依赖初始化后再创建 SubGraphCompiler（它持有 adapter 引用）
-        this.subGraphCompiler = new SubGraphCompiler(this, governanceClient, this.skillAuditRecorder);
+        this.subGraphCompiler = new SubGraphCompiler(this, governanceClient, this.skillAuditRecorder, this.auditReporter);
     }
     /**
      * 注册自定义条件评估函数
@@ -133,6 +151,10 @@ export class LangGraphAdapter {
     registerConditionEvaluator(name, fn) {
         this.conditionEvaluator.register(name, fn);
     }
+    /** SDK 恢复 env 之后仍要把 overlay 算进 LLM jail 根，不能再读 process.env。 */
+    bindOverlayExtraRoots(roots) {
+        this.overlayExtraRoots = (roots ?? []).filter((root) => root.trim());
+    }
     /**
      * 节点旁路推送 RuntimeEvent（子图 Skill 生命周期、Tool 执行）。
      * 无本次执行流式袋时为空操作（纯 invoke）。
@@ -290,7 +312,7 @@ export class LangGraphAdapter {
                     toolName: progress.toolName,
                     ...(progress.toolset ? { toolset: progress.toolset } : {}),
                     error: progress.error ?? 'Unknown error',
-                    willRetry: false,
+                    willRetry: progress.willRetry === true,
                     ...loc,
                 },
             });
@@ -312,6 +334,7 @@ export class LangGraphAdapter {
      */
     async buildGraph(dsl) {
         this.assertShouldContinueTargetsTool(dsl);
+        assertEmbeddedSubgraphsAreFlat(dsl);
         const silentNodeIds = new Set(dsl.nodes
             .filter((node) => node.type === 'llm' && node.config?.['silent'] === true)
             .map((node) => node.id));
@@ -352,6 +375,7 @@ export class LangGraphAdapter {
                 correlationId: ephemeral(''),
                 taskId: ephemeral(''),
                 sessionId: ephemeral(''),
+                skillIsolateContext: ephemeral(undefined),
                 loadedTools: ephemeral(undefined),
                 loadedSkills: ephemeral(undefined),
                 skillDefinitions: ephemeral(undefined),
@@ -364,9 +388,15 @@ export class LangGraphAdapter {
                 agentDir: ephemeral(undefined),
                 executionContext: ephemeral(undefined),
                 forceToolServer: ephemeral(undefined),
+                // 请求级检索范围（前端圈定 fileIds/dirPaths；rag 节点读取，仅本地检索源生效）
+                ragScope: ephemeral(undefined),
+                // 会话级数据源勾选（数据源 id 列表，undefined=全部启用；rag 节点读取）
+                ragSources: ephemeral(undefined),
                 traceCollector: ephemeral(undefined),
                 traceId: ephemeral(undefined),
                 skillSpanId: ephemeral(undefined),
+                toolSpanId: ephemeral(undefined),
+                hitlToolCallId: ephemeral(undefined),
                 lastSpanId: ephemeral(undefined),
                 hitlChoice: ephemeral(undefined),
                 // ── LLM Token 使用量：数组累加器 reducer，每次 LLM 节点追加一条使用明细
@@ -378,7 +408,6 @@ export class LangGraphAdapter {
                     },
                     default: () => [],
                 },
-                __parallelResults: ephemeral(undefined),
                 __codeResult: ephemeral(undefined),
                 __codeError: ephemeral(undefined),
                 __conditionResult: ephemeral(undefined),
@@ -450,7 +479,7 @@ export class LangGraphAdapter {
      */
     async *stream(graph, state) {
         const ref = this.getCompiledRef(graph);
-        const input = this.graphStateToLangGraphInput(state);
+        const input = this.graphStateToLangGraphInput(this.applyDeclaredSearchFace(state, ref.dsl));
         const queue = [];
         const waiter = { fn: null };
         let finished = false;
@@ -523,7 +552,7 @@ export class LangGraphAdapter {
      */
     async invoke(graph, state) {
         const ref = this.getCompiledRef(graph);
-        const input = this.graphStateToLangGraphInput(state);
+        const input = this.graphStateToLangGraphInput(this.applyDeclaredSearchFace(state, ref.dsl));
         const startTime = Date.now();
         const traceCtx = executionTraceFromState(state);
         // 只补 collector/traceId。子图套娃时外层 stream 袋经 ?? 保留。
@@ -651,23 +680,26 @@ export class LangGraphAdapter {
             case 'subgraph':
                 return this.createSubGraphNodeFunction(node);
             case 'human':
-                return async (state) => {
-                    return { currentNode: node.id };
-                };
-            case 'parallel':
-                return this.createParallelNodeFunction(node);
+                throw new AppError(ErrorCodes.GRAPH_BUILD_FAILED, `Graph 节点 "${node.id}" type=human 未实现；人工确认请用 require_confirmation`, { exposeMessage: true });
             case 'code':
                 if (node.config?.['bindSkill'] === true) {
                     return this.createSkillBindNodeFunction(node);
                 }
                 return this.createCodeNodeFunction(node);
-            default:
+            case 'rag':
+                return this.createRagNodeFunction(node);
+            default: {
                 if (node.config?.['bindSkill'] === true) {
                     return this.createSkillBindNodeFunction(node);
                 }
-                return async (state) => {
-                    return { ...state, currentNode: node.id };
-                };
+                const type = String(node.type);
+                if (type === 'start' || type === 'end') {
+                    return async (state) => {
+                        return { ...state, currentNode: node.id };
+                    };
+                }
+                throw new AppError(ErrorCodes.GRAPH_BUILD_FAILED, `Graph 节点 "${node.id}" type=${type} 不是合法类型`, { exposeMessage: true });
+            }
         }
     }
     createSkillBindNodeFunction(node) {
@@ -744,7 +776,7 @@ export class LangGraphAdapter {
                 userId: 'system',
                 delegationToken: '',
                 agentCode: '',
-            }, (progress) => this.emitToolExecutionEvents(progress), this.hitlHandler, node.id);
+            }, (progress) => this.emitToolExecutionEvents(progress), this.hitlHandler, node.id, this.interceptors, node.config?.['retrievalSources'], node.config?.['totalK'], node.retry);
             return (state) => toolNode.execute(state);
         }
         if (this.toolExecutor) {
@@ -767,7 +799,7 @@ export class LangGraphAdapter {
                 const jailExtraRoots = Object.values(skillDefs ?? {})
                     .map((skill) => skill.bundlePath)
                     .filter((p) => Boolean(p));
-                const result = await this.toolExecutor.execute({
+                const request = {
                     toolCallId,
                     toolName,
                     arguments: defaultArgs,
@@ -775,7 +807,25 @@ export class LangGraphAdapter {
                     correlationId,
                     taskId,
                     ...(jailExtraRoots.length > 0 ? { jailExtraRoots } : {}),
-                });
+                };
+                const retry = resolveToolRetryConfig(node.retry);
+                const maxRetries = retry?.maxRetries ?? 0;
+                let result = await this.toolExecutor.execute(request);
+                for (let attempt = 0; !result.success && attempt < maxRetries; attempt++) {
+                    if (!isRetryableToolFailure(result))
+                        break;
+                    this.emitToolExecutionEvents({
+                        toolCallId: result.toolCallId,
+                        toolName: result.toolName,
+                        status: 'error',
+                        arguments: defaultArgs,
+                        error: result.error,
+                        willRetry: true,
+                        node: node.id,
+                    });
+                    await sleepToolRetry(toolRetryDelayMs(attempt, retry.backoff));
+                    result = await this.toolExecutor.execute(request);
+                }
                 const executionTime = Date.now() - startedAt;
                 const skillDirs = Object.values(skillDefs ?? {})
                     .filter((skill) => Boolean(skill.bundlePath))
@@ -787,6 +837,7 @@ export class LangGraphAdapter {
                     arguments: defaultArgs,
                     content: result.content,
                     error: result.error,
+                    willRetry: false,
                     executionTime,
                     node: node.id,
                     ...(skillDirs.length > 0 ? { skillDirs } : {}),
@@ -891,6 +942,9 @@ export class LangGraphAdapter {
                     loadedTools,
                     skillDefinitions: skillDefs,
                 });
+                if (this.overlayExtraRoots.length > 0) {
+                    jail.extraRoots = [...(jail.extraRoots ?? []), ...this.overlayExtraRoots];
+                }
                 const workingDirectory = jail.workdir;
                 const jailRoots = resolveJailRoots(jail);
                 const skillDirs = Object.values(skillDefs ?? {})
@@ -972,7 +1026,7 @@ export class LangGraphAdapter {
                             },
                         });
                     }
-                    : undefined);
+                    : undefined, this.interceptors);
                 const next = await llmNode.execute(state);
                 const hydratedUpdate = loadedTools && loadedTools !== loadedToolsBase ? { loadedTools } : {};
                 if (!silent)
@@ -990,6 +1044,31 @@ export class LangGraphAdapter {
             });
         };
     }
+    /**
+     * RAG 节点：编译期 fail-fast（deps 缺失），请求级状态经 execute(state) 流转
+     */
+    createRagNodeFunction(node) {
+        if (!this.ragNodeDeps) {
+            throw new Error(`图使用了 type:rag 节点 "${node.id}"，但宿主未注入 ragNodeDeps（LangGraphAdapter 第 6 参）`);
+        }
+        const ragNode = new RagNode(node.id, (node.config ?? {}), {
+            ...this.ragNodeDeps,
+            // 未显式提供时复用 adapter 已组装的 orchestrator（§9.3：toolExecutor+governance 透传）
+            toolOrchestrator: this.ragNodeDeps.toolOrchestrator ?? this.toolOrchestrator,
+            // rag.* 事件接 SSE 旁路（请求级执行流存活期间有效；宿主/测试注入的 emitEvent 优先）
+            emitEvent: this.ragNodeDeps.emitEvent ??
+                ((type, payload) => {
+                    this.emitStreamEvent({
+                        type,
+                        taskId: undefined,
+                        correlationId: undefined,
+                        timestamp: new Date().toISOString(),
+                        payload,
+                    });
+                }),
+        });
+        return (state) => ragNode.execute(state);
+    }
     /**
      * 子图节点：优先 config.subgraphDsl；否则按 skillId 从 state.skillDefinitions.workflow 解析。
      * 技能正文用短目录 + read_file，不灌 system。
@@ -1000,7 +1079,10 @@ export class LangGraphAdapter {
             node.config?.['skillId'] ??
             embeddedDsl?.name;
         if (embeddedDsl) {
-            return this.subGraphCompiler.compileSubGraph(embeddedDsl, configuredSkillId);
+            return this.subGraphCompiler.compileSubGraph(embeddedDsl, configuredSkillId, {
+                isolateContext: isSkillContextIsolated(node),
+                parentNodeId: node.id,
+            });
         }
         return async (state) => {
             const skillId = configuredSkillId ??
@@ -1011,70 +1093,13 @@ export class LangGraphAdapter {
             if (!workflow?.nodes?.length) {
                 throw preloadSkillNotFound(`子图节点无法解析 Skill workflow: node=${node.id}, skillId=${skillId ?? '(none)'}`, { nodeId: node.id, skillId });
             }
-            const fn = this.subGraphCompiler.compileSubGraph(workflow, skillId ?? def?.skillId);
+            const fn = this.subGraphCompiler.compileSubGraph(workflow, skillId ?? def?.skillId, {
+                isolateContext: isSkillContextIsolated(node),
+                parentNodeId: node.id,
+            });
             return fn(state);
         };
     }
-    /**
-     * 并行节点：并行执行多个子任务分支
-     *
-     * 支持两种并行模式：
-     * 1. branches 模式：node.branches 列出要并行执行的节点 ID，每个节点的执行函数由 DSL 定义
-     * 2. tasks 模式：node.config.tasks 列出要并行执行的异步任务函数
-     *
-     * 执行结果合并到 state.__parallelResults 中。
-     */
-    createParallelNodeFunction(node) {
-        return async (state) => {
-            const branchNodeIds = node.branches ?? node.config?.['branches'] ?? [];
-            const tasks = node.config?.['tasks'];
-            const results = [];
-            if (tasks?.length) {
-                // tasks 模式：并行执行配置的任务
-                const promises = tasks.map(async (task) => {
-                    try {
-                        // 任务结果由外部注入的 task executor 处理
-                        // 此处仅记录任务 ID，实际执行依赖外部编排
-                        return { branchId: task.id, success: true, result: { taskId: task.id, status: 'dispatched' } };
-                    }
-                    catch (err) {
-                        return {
-                            branchId: task.id,
-                            success: false,
-                            error: err instanceof Error ? err.message : String(err),
-                        };
-                    }
-                });
-                results.push(...await Promise.all(promises));
-            }
-            else if (branchNodeIds.length) {
-                // branches 模式：并行执行分支节点
-                const promises = branchNodeIds.map(async (branchId) => {
-                    try {
-                        // 每个分支节点的实际执行由 LangGraph 编排层驱动
-                        // 并行节点仅负责触发并汇总状态
-                        return { branchId, success: true, result: { dispatched: true } };
-                    }
-                    catch (err) {
-                        return {
-                            branchId,
-                            success: false,
-                            error: err instanceof Error ? err.message : String(err),
-                        };
-                    }
-                });
-                results.push(...await Promise.all(promises));
-            }
-            const allSuccess = results.every((r) => r.success);
-            return {
-                ...state,
-                currentNode: node.id,
-                __parallelResults: results,
-                __parallelAllSuccess: allSuccess,
-                __conditionResult: allSuccess ? 'success' : 'partial_failure',
-            };
-        };
-    }
     /**
      * 代码执行节点：在受限沙箱中执行用户代码
      *
@@ -1250,6 +1275,41 @@ export class LangGraphAdapter {
      * 否则多轮回放时 DeepSeek thinking 会因缺少 reasoning_content 而 400，
      * tool 消息也会丢掉 tool_call_id。
      */
+    /**
+     * 工具形态检索面白名单（图声明即真相）：tool 节点 config.retrievalSources 声明的
+     * 数据源目录 → 本图工具白名单（声明源解析出的工具 + rag_search）。未声明的检索类
+     * 工具对主 LLM 工具表与执行链整体不可见/不可用；图未声明 = 不收敓名单（通用形态）。
+     *
+     * 约束——单检索面假设：find 只取全图首个带 retrievalSources 的 tool 节点、按它过滤
+     * 全图 loadedTools。多 tool 节点各声明检索面属未支持场景：第二面的工具会被当成
+     * 未声明而过滤，无法各自收敛；如需支持须改为 per-node 收敛（在节点边界分别过滤
+     * loadedTools，而非此处全图一次性收敛）。
+     */
+    applyDeclaredSearchFace(state, dsl) {
+        const face = dsl?.nodes?.find((n) => n.type === 'tool' && n.config?.['retrievalSources']);
+        const declaration = face?.config?.['retrievalSources'];
+        const loaded = state.loadedTools;
+        if (!declaration || !loaded || typeof loaded !== 'object')
+            return state;
+        const resolved = resolveRagSources({ retrievalSources: declaration });
+        const allowed = new Set([...(resolved.toolScope ?? []), RAG_SEARCH_TOOL_NAME]);
+        const filtered = {};
+        for (const [name, def] of Object.entries(loaded)) {
+            if (!allowed.has(name))
+                continue;
+            // 数据源目录写进保留工具的 description（幂等）——主 LLM 直调时与 rag 内核
+            // 同一份目录，杜绝瞎猜 datasetCode；内核组表侧 appendSourceCatalog 幂等不重复
+            const catalog = resolved.sourceCatalog[name];
+            if (catalog?.length) {
+                const desc = appendSourceCatalog(def.manifest.description, catalog);
+                filtered[name] = { ...def, manifest: { ...def.manifest, description: desc } };
+            }
+            else {
+                filtered[name] = def;
+            }
+        }
+        return { ...state, loadedTools: filtered };
+    }
     graphStateToLangGraphInput(state) {
         const mapped = (state.messages ?? []).map((msg) => ({
             role: msg.role,