@gt-fe/eap-runtime 0.0.19 → 0.0.21

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.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）。
@@ -60,6 +69,7 @@ export declare class LangGraphAdapter implements IStateGraphEngine {
      * Tool 节点执行旁路：started → tool.called + tool.progress；
      * completed/error → 对应终态 + tool.progress。同一 toolCallId。
      * 读 SKILL.md / 技能包内文件：成功后再发 skill.loaded / skill.resource_read，同时保留 tool.*。
+     * 读 SKILL.md 另发 skill.started / skill.completed（与 Trace type=skill Span 对齐）；子图内不重复。
      */
     private emitToolExecutionEvents;
     /**
@@ -110,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;
     /**
      * 代码执行节点：在受限沙箱中执行用户代码
      *
@@ -172,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 序列