@gt-fe/eap-runtime 0.0.20 → 0.0.22

package/dist/common/types.js

@@ -7,7 +7,7 @@
  */
 /** RuntimeConfig 默认值 */
 export const DEFAULT_RUNTIME_CONFIG = {
-    tokenDetail: 'summary',
+    tokenDetail: 'detail',
     timeout: 60000,
     maxIterations: 10,
     heartbeatInterval: 30000,

package/dist/execution/index.d.ts

@@ -0,0 +1,2 @@
+export { decideBeforeModel, decideBeforeTool, type AfterModelInterceptor, type AfterToolInterceptor, type BeforeModelInput, type BeforeModelInterceptor, type BeforeToolInterceptor, type ExecutionInterceptors, type ModelInterceptorDecision, type ToolInterceptorDecision, } from './interceptors.js';
+export { sandboxFromJail, type ISandbox, type IApproval } from './ports.js';

package/dist/execution/index.js

@@ -0,0 +1,2 @@
+export { decideBeforeModel, decideBeforeTool, } from './interceptors.js';
+export { sandboxFromJail } from './ports.js';

package/dist/execution/interceptors.d.ts

@@ -0,0 +1,40 @@
+/**
+ * 执行拦截：Tool / LLM 调用前可拒绝，默认无注入则与未装配时相同。
+ * 不是规格 R13 Hook，不做插件发现、不读项目 hook 目录。
+ */
+import type { ExecutionContext } from '@gt-fe/eap-contracts';
+import type { GraphMessage } from '../graph/contracts/executable-graph.js';
+import type { LLMNodeConfig, LLMResponse } from '../graph/nodes/llm-node.js';
+import type { ToolCallRequest, ToolCallResult } from '../tool/tool-executor.interface.js';
+export type ToolInterceptorDecision = {
+    action: 'allow';
+} | {
+    action: 'deny';
+    reason: string;
+} | {
+    action: 'ask';
+};
+export type BeforeToolInterceptor = (request: ToolCallRequest, ctx?: ExecutionContext) => Promise<ToolInterceptorDecision | void> | ToolInterceptorDecision | void;
+export type AfterToolInterceptor = (request: ToolCallRequest, result: ToolCallResult) => Promise<void> | void;
+export interface BeforeModelInput {
+    messages: GraphMessage[];
+    config: LLMNodeConfig;
+    nodeId: string;
+}
+export type ModelInterceptorDecision = {
+    action: 'allow';
+    messages?: GraphMessage[];
+} | {
+    action: 'deny';
+    reason: string;
+};
+export type BeforeModelInterceptor = (input: BeforeModelInput) => Promise<ModelInterceptorDecision | void> | ModelInterceptorDecision | void;
+export type AfterModelInterceptor = (input: BeforeModelInput, response: LLMResponse) => Promise<void> | void;
+export interface ExecutionInterceptors {
+    beforeTool?: BeforeToolInterceptor;
+    afterTool?: AfterToolInterceptor;
+    beforeModel?: BeforeModelInterceptor;
+    afterModel?: AfterModelInterceptor;
+}
+export declare function decideBeforeTool(interceptor: BeforeToolInterceptor | undefined, request: ToolCallRequest, ctx?: ExecutionContext): Promise<ToolInterceptorDecision>;
+export declare function decideBeforeModel(interceptor: BeforeModelInterceptor | undefined, input: BeforeModelInput): Promise<ModelInterceptorDecision>;

package/dist/execution/interceptors.js

@@ -0,0 +1,23 @@
+/**
+ * 执行拦截：Tool / LLM 调用前可拒绝，默认无注入则与未装配时相同。
+ * 不是规格 R13 Hook，不做插件发现、不读项目 hook 目录。
+ */
+export async function decideBeforeTool(interceptor, request, ctx) {
+    if (!interceptor)
+        return { action: 'allow' };
+    const raw = await interceptor(request, ctx);
+    if (!raw || raw.action === 'allow')
+        return { action: 'allow' };
+    if (raw.action === 'ask')
+        return { action: 'ask' };
+    return { action: 'deny', reason: raw.reason || '拦截拒绝' };
+}
+export async function decideBeforeModel(interceptor, input) {
+    if (!interceptor)
+        return { action: 'allow' };
+    const raw = await interceptor(input);
+    if (!raw || raw.action === 'allow') {
+        return { action: 'allow', messages: raw && raw.action === 'allow' ? raw.messages : undefined };
+    }
+    return { action: 'deny', reason: raw.reason || '拦截拒绝' };
+}

package/dist/execution/ports.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 执行口类型：不另起引擎，也不改现有调用路径。
+ * ISandbox 描述 jail 根目录；execute_command 仍走 harness jail，未经过本接口。
+ * IApproval 即 HitlHandler；确认仍走 require_confirmation。
+ * OS 级沙箱见 TODO-skill-fs FS-2。
+ */
+import type { HitlHandler } from '../graph/hitl/hitl-handler.js';
+/** 命令路径约束。默认：用户目录读写 + 技能包只读。 */
+export interface ISandbox {
+    allowedWriteRoots: string[];
+    allowedReadRoots: string[];
+}
+export declare function sandboxFromJail(jail: {
+    writeRoot: string;
+    extraRoots?: string[];
+}): ISandbox;
+/** 人工确认。默认实现是 HitlHandler + require_confirmation。 */
+export type IApproval = HitlHandler;

package/dist/execution/ports.js

@@ -0,0 +1,13 @@
+/**
+ * 执行口类型：不另起引擎，也不改现有调用路径。
+ * ISandbox 描述 jail 根目录；execute_command 仍走 harness jail，未经过本接口。
+ * IApproval 即 HitlHandler；确认仍走 require_confirmation。
+ * OS 级沙箱见 TODO-skill-fs FS-2。
+ */
+export function sandboxFromJail(jail) {
+    const extra = jail.extraRoots ?? [];
+    return {
+        allowedWriteRoots: [jail.writeRoot],
+        allowedReadRoots: [jail.writeRoot, ...extra],
+    };
+}

package/dist/governance/audit-reporter.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 权限拒绝审计。未注入则只抛错（A-4）。上报失败不挡执行。
+ */
+export interface PermissionDenialAudit {
+    kind: 'tool' | 'skill';
+    resourceId: string;
+    reason: string;
+    userId?: string | null;
+    correlationId?: string;
+}
+export interface IAuditReporter {
+    recordDenial(event: PermissionDenialAudit): Promise<void>;
+}
+export declare function reportPermissionDenial(reporter: IAuditReporter | undefined, event: PermissionDenialAudit): Promise<void>;

package/dist/governance/audit-reporter.js

@@ -0,0 +1,18 @@
+/**
+ * 权限拒绝审计。未注入则只抛错（A-4）。上报失败不挡执行。
+ */
+import { emitRuntimeLog } from '../common/logger.js';
+export async function reportPermissionDenial(reporter, event) {
+    if (!reporter)
+        return;
+    try {
+        await reporter.recordDenial(event);
+    }
+    catch (err) {
+        emitRuntimeLog('warn', 'runtime.audit', 'permission denial audit failed', {
+            event: 'runtime.audit.denial_failed',
+            resourceId: event.resourceId,
+            error: err instanceof Error ? err.message : String(err),
+        });
+    }
+}

package/dist/governance/index.d.ts

@@ -5,3 +5,5 @@ export type { CallerType, ExecutionContext, GovernancePermissionCheckParams, Gov
 export type { IGovernanceClient } from './governance-client.js';
 export { HttpGovernanceClient, AllowAllGovernanceClient, resolveExecutionContext, } from './governance-client.js';
 export { assertToolPermission, assertSkillPermission, permissionMessage, PermissionDeniedError, GovernanceUnavailableError, } from './permission-guard.js';
+export type { IAuditReporter, PermissionDenialAudit } from './audit-reporter.js';
+export { reportPermissionDenial } from './audit-reporter.js';

package/dist/governance/index.js

@@ -3,3 +3,4 @@
  */
 export { HttpGovernanceClient, AllowAllGovernanceClient, resolveExecutionContext, } from './governance-client.js';
 export { assertToolPermission, assertSkillPermission, permissionMessage, PermissionDeniedError, GovernanceUnavailableError, } from './permission-guard.js';
+export { reportPermissionDenial } from './audit-reporter.js';

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-checkpointer.d.ts

@@ -29,6 +29,7 @@ export declare class LangGraphCheckpointer extends BaseCheckpointSaver {
     putWrites(config: RunnableConfig, writes: PendingWrite[], taskId: string): Promise<void>;
     list(config: RunnableConfig, options?: ListOptions): AsyncIterableIterator<CheckpointTuple>;
     private extractThreadId;
+    private extractCheckpointNs;
     private checkpointDataToTuple;
     /**
      * 优先还原 put() 时写入的 engineSnapshot；旧数据兜底补齐 pending_sends=[]。
@@ -37,4 +38,14 @@ export declare class LangGraphCheckpointer extends BaseCheckpointSaver {
     private checkpointToData;
     private extractExtraState;
 }
+/**
+ * ICheckpointSaver 仍按一个 threadId 分槽。
+ * 父图 ns 为空，槽位=threadId（HITL/多轮仍等于 sessionId）。
+ * 子图 ns 非空，槽位=threadId#ns，不覆盖父 latest。
+ */
+export declare function checkpointStorageThreadId(threadId: string, checkpointNs?: string): string;
+/** 在上一份路径后追加当前节点 id；空 id 或与末项相同则不追加。 */
+export declare function nextHistoryPath(previous: string[] | undefined, currentNodeId: string): string[];
+/** 优先用图状态 channel；旧 checkpoint 没有该 channel 时退回按 currentNode 追加。 */
+export declare function historyPathFromChannel(channel: unknown, previousHistoryPath: string[] | undefined, currentNodeId: string): string[];
 export {};

package/dist/graph/adapters/langgraph-checkpointer.js

@@ -33,7 +33,7 @@ export class LangGraphCheckpointer extends BaseCheckpointSaver {
             data = await this.saver.loadByCheckpointId(checkpointId);
         }
         else {
-            data = await this.saver.load(threadId);
+            data = await this.saver.load(checkpointStorageThreadId(threadId, this.extractCheckpointNs(config)));
         }
         if (!data) {
             return undefined;
@@ -42,8 +42,10 @@ export class LangGraphCheckpointer extends BaseCheckpointSaver {
     }
     async put(config, checkpoint, metadata, _newVersions) {
         const threadId = this.extractThreadId(config) ?? `thread-${Date.now()}`;
-        const data = this.checkpointToData(threadId, checkpoint, metadata);
-        await this.saver.save(threadId, stripCheckpointCollectors(data));
+        const storageThreadId = checkpointStorageThreadId(threadId, this.extractCheckpointNs(config));
+        const previous = await this.saver.load(storageThreadId);
+        const data = this.checkpointToData(storageThreadId, checkpoint, previous?.historyPath);
+        await this.saver.save(storageThreadId, stripCheckpointCollectors(data));
         await notifyCheckpointRef(data);
         return {
             ...config,
@@ -80,7 +82,7 @@ export class LangGraphCheckpointer extends BaseCheckpointSaver {
         if (!threadId) {
             return;
         }
-        let checkpoints = await this.saver.list(threadId);
+        let checkpoints = await this.saver.list(checkpointStorageThreadId(threadId, this.extractCheckpointNs(config)));
         checkpoints.sort((a, b) => new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime());
         if (options?.before) {
             const beforeId = options.before.configurable?.['checkpoint_id'];
@@ -101,6 +103,9 @@ export class LangGraphCheckpointer extends BaseCheckpointSaver {
     extractThreadId(config) {
         return config.configurable?.['thread_id'];
     }
+    extractCheckpointNs(config) {
+        return String(config.configurable?.['checkpoint_ns'] ?? '').trim();
+    }
     checkpointDataToTuple(data, config) {
         const checkpoint = this.restoreLangGraphCheckpoint(data);
         const metadata = {
@@ -112,7 +117,7 @@ export class LangGraphCheckpointer extends BaseCheckpointSaver {
             ...config,
             configurable: {
                 ...config.configurable,
-                thread_id: data.threadId,
+                thread_id: this.extractThreadId(config) ?? data.threadId,
                 checkpoint_id: data.checkpointId,
             },
         };
@@ -162,20 +167,20 @@ export class LangGraphCheckpointer extends BaseCheckpointSaver {
             channel_values: {
                 messages: data.state.messages ?? [],
                 currentNode: data.currentNodeId,
+                historyPath: data.historyPath ?? [],
                 ...this.extractExtraState(data),
             },
-            channel_versions: { messages: 1, currentNode: 1 },
+            channel_versions: { messages: 1, currentNode: 1, historyPath: 1 },
             versions_seen: {},
             pending_sends: [],
         };
     }
-    checkpointToData(threadId, checkpoint, metadata) {
+    checkpointToData(threadId, checkpoint, previousHistoryPath) {
         const messages = Array.isArray(checkpoint.channel_values['messages'])
             ? checkpoint.channel_values['messages']
             : [];
         const currentNodeId = checkpoint.channel_values['currentNode'] ?? '';
-        const step = Number.isFinite(metadata.step) ? Math.max(0, Math.min(metadata.step, 1000)) : 0;
-        const historyPath = Array.from({ length: step }, () => 'node');
+        const historyPath = historyPathFromChannel(checkpoint.channel_values['historyPath'], previousHistoryPath, currentNodeId);
         const raw = checkpoint;
         return {
             checkpointId: checkpoint.id,
@@ -211,3 +216,37 @@ export class LangGraphCheckpointer extends BaseCheckpointSaver {
         return rest;
     }
 }
+/**
+ * ICheckpointSaver 仍按一个 threadId 分槽。
+ * 父图 ns 为空，槽位=threadId（HITL/多轮仍等于 sessionId）。
+ * 子图 ns 非空，槽位=threadId#ns，不覆盖父 latest。
+ */
+export function checkpointStorageThreadId(threadId, checkpointNs) {
+    const ns = (checkpointNs ?? '').trim().replace(/[/\\]/g, '_');
+    if (!ns)
+        return threadId;
+    return `${threadId}#${ns}`;
+}
+/** 在上一份路径后追加当前节点 id；空 id 或与末项相同则不追加。 */
+export function nextHistoryPath(previous, currentNodeId) {
+    const path = Array.isArray(previous) ? [...previous] : [];
+    const id = currentNodeId.trim();
+    if (!id)
+        return path;
+    if (path[path.length - 1] === id)
+        return path;
+    path.push(id);
+    if (path.length > 1000)
+        return path.slice(path.length - 1000);
+    return path;
+}
+/** 优先用图状态 channel；旧 checkpoint 没有该 channel 时退回按 currentNode 追加。 */
+export function historyPathFromChannel(channel, previousHistoryPath, currentNodeId) {
+    if (Array.isArray(channel) && channel.length > 0) {
+        const path = channel.filter((id) => typeof id === 'string' && id.trim().length > 0);
+        if (path.length > 0) {
+            return path.length > 1000 ? path.slice(path.length - 1000) : path;
+        }
+    }
+    return nextHistoryPath(previousHistoryPath, currentNodeId);
+}

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

@@ -12,11 +12,19 @@ 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;
+/**
+ * LangGraph `recursionLimit` 计 superstep（每进一个节点 +1），不是 ReAct 圈数。
+ * 图上 `config.maxIterations` 优先；缺省 {@link DEFAULT_GRAPH_RECURSION_LIMIT}。
+ */
+/** 并行节点各自返回 [id] 时合并进同一路径；末项相同不重复。 */
+export declare function mergeHistoryPath(current: unknown, update: unknown): string[];
 /**
  * LangGraphAdapter — 基于 @langchain/langgraph 的 IStateGraphEngine 实现
  *
@@ -26,6 +34,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 +51,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）。
@@ -103,29 +118,25 @@ export declare class LangGraphAdapter implements IStateGraphEngine {
      * 本方法无 DSL，无法编译出可用 `_engineInstance`。
      */
     restore(checkpointData: CheckpointData): Promise<ExecutableGraph>;
+    private checkpointConfigurable;
     /**
      * 根据节点类型创建对应的执行函数
      */
     private createNodeFunction;
+    private createNodeFunctionBody;
     private createSkillBindNodeFunction;
     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 +184,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 序列