@gt-fe/eap-runtime 0.0.8

package/dist/contracts/trace-collector.d.ts

@@ -0,0 +1,211 @@
+/**
+ * Trace 采集器接口
+ *
+ * 由 foundation-service 实现，Runtime 在执行过程中调用此接口推送 Trace 事件。
+ *
+ * 支持双层追踪模型：
+ * - 执行流（ExecutionFlow/ExecutionNode）：智能体内部执行流
+ * - 链路（TraceLink/TraceLinkNode）：跨服务调用链路
+ *
+ * @see foundation-service 实现存储和查询
+ * @see admin-portal 管理页面
+ */
+/**
+ * Trace 事件
+ */
+export interface TraceEvent {
+    /** 事件 ID */
+    id: string;
+    /** 事件类型 */
+    type: string;
+    /** 关联 ID */
+    correlationId: string;
+    /** 任务 ID */
+    taskId: string;
+    /** 会话 ID */
+    sessionId: string;
+    /** 时间戳（ISO 8601 格式，UTC） */
+    timestamp: string;
+    /** 事件负载 */
+    payload: Record<string, unknown>;
+}
+/**
+ * Trace 会话
+ */
+export interface TraceSession {
+    /** 会话 ID */
+    sessionId: string;
+    /** 任务 ID */
+    taskId: string;
+    /** 开始时间（ISO 8601 格式，UTC） */
+    startTime: string;
+    /** 结束时间（ISO 8601 格式，UTC） */
+    endTime?: string;
+    /** 事件列表 */
+    events: TraceEvent[];
+    /** 状态 */
+    status: 'running' | 'completed' | 'failed';
+}
+/**
+ * 执行流事件
+ *
+ * 用于记录智能体内部执行流。
+ */
+export interface ExecutionFlowEvent {
+    /** 与 ExecuteParams.traceId / Foundation traces.id 同值 */
+    traceId: string;
+    /** 历史字段（值为 agentCode；对齐 foundation Trace API 的 agentId 字段） */
+    agentId: string;
+    /** 对外主键（优先写入 Trace） */
+    agentCode?: string;
+    /** 会话 ID */
+    sessionId: string;
+    /** 用户 ID */
+    userId: string;
+    /** 关联 ID */
+    correlationId?: string;
+    /** 调用类型 */
+    callType: 'sync' | 'async' | 'callback' | 'fork';
+    /** 元数据 */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * 执行节点事件
+ *
+ * 用于记录智能体内部执行节点。
+ */
+export interface ExecutionNodeEvent {
+    /** 与 ExecuteParams.traceId / Foundation traces.id 同值 */
+    traceId: string;
+    /** 父节点 ID */
+    parentNodeId?: string;
+    /** 节点名称 */
+    name: string;
+    /** 节点类型 */
+    type: 'start' | 'llm' | 'tool' | 'skill' | 'condition' | 'end';
+    /** 工具运行环境（type=tool） */
+    toolRuntime?: 'local' | 'server' | 'both' | 'mock';
+    /** Agent 对外主键 */
+    agentCode?: string;
+    /** 输入数据 */
+    input?: unknown;
+    /** 扩展元数据（如 skillId） */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * 链路事件
+ *
+ * 用于记录跨服务调用链路。
+ */
+export interface TraceLinkEvent {
+    /** 关联 ID */
+    correlationId: string;
+}
+/**
+ * 链路节点事件
+ *
+ * 用于记录跨服务调用链路节点。
+ */
+export interface TraceLinkNodeEvent {
+    /** 链路 ID */
+    linkId: string;
+    /** 父节点 ID */
+    parentNodeId?: string;
+    /** 服务 ID */
+    serviceId: string;
+    /** 服务名称 */
+    serviceName: string;
+    /** 操作名称 */
+    operation: string;
+    /** 主机地址 */
+    host?: string;
+    /** 端口 */
+    port?: number;
+}
+/**
+ * ITraceCollector — Trace 采集器接口
+ *
+ * 由 foundation-service 实现，Runtime 通过此接口推送事件。
+ * Runtime 在执行过程中调用 collect() 推送 SSE 事件转换的 Trace 事件。
+ */
+export interface ITraceCollector {
+    /**
+     * 收集 Trace 事件
+     *
+     * @param event - Trace 事件
+     */
+    collect(event: TraceEvent): Promise<void>;
+    /**
+     * 开始 Trace 会话
+     *
+     * @param sessionId - 会话 ID
+     * @param taskId - 任务 ID
+     */
+    startSession(sessionId: string, taskId: string): Promise<void>;
+    /**
+     * 结束 Trace 会话
+     *
+     * @param sessionId - 会话 ID
+     * @param status - 会话状态
+     */
+    endSession(sessionId: string, status: 'completed' | 'failed'): Promise<void>;
+    /**
+     * 获取 Trace 会话
+     *
+     * @param sessionId - 会话 ID
+     * @returns Trace 会话
+     */
+    getSession(sessionId: string): Promise<TraceSession | null>;
+    /**
+     * 创建执行流
+     *
+     * @param event - 执行流事件
+     * @returns 执行流 ID
+     */
+    createFlow(event: ExecutionFlowEvent): Promise<string>;
+    /**
+     * 创建执行节点
+     *
+     * @param event - 执行节点事件
+     * @returns 执行节点 ID
+     */
+    createNode(event: ExecutionNodeEvent): Promise<string>;
+    /**
+     * 完成执行节点
+     *
+     * @param nodeId - 节点 ID
+     * @param params - 完成参数
+     */
+    completeNode(nodeId: string, params: {
+        status: 'completed' | 'failed';
+        output?: unknown;
+        error?: string;
+        inputTokens?: number;
+        outputTokens?: number;
+        totalTokens?: number;
+    }): Promise<void>;
+    /**
+     * 创建链路
+     *
+     * @param event - 链路事件
+     * @returns 链路 ID
+     */
+    createLink(event: TraceLinkEvent): Promise<string>;
+    /**
+     * 创建链路节点
+     *
+     * @param event - 链路节点事件
+     * @returns 链路节点 ID
+     */
+    createLinkNode(event: TraceLinkNodeEvent): Promise<string>;
+    /**
+     * 完成链路节点
+     *
+     * @param nodeId - 链路节点 ID
+     * @param params - 完成参数
+     */
+    completeLinkNode(nodeId: string, params: {
+        status: 'completed' | 'failed';
+        error?: string;
+    }): Promise<void>;
+}

package/dist/contracts/trace-collector.js

@@ -0,0 +1,13 @@
+/**
+ * Trace 采集器接口
+ *
+ * 由 foundation-service 实现，Runtime 在执行过程中调用此接口推送 Trace 事件。
+ *
+ * 支持双层追踪模型：
+ * - 执行流（ExecutionFlow/ExecutionNode）：智能体内部执行流
+ * - 链路（TraceLink/TraceLinkNode）：跨服务调用链路
+ *
+ * @see foundation-service 实现存储和查询
+ * @see admin-portal 管理页面
+ */
+export {};

package/dist/governance/governance-client.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 治理服务 HTTP 客户端（06-governance validateToken / checkPermission）
+ */
+import type { ExecutionContext, GovernancePermissionCheckParams, GovernancePermissionCheckResult } from '@gt-fe/eap-contracts';
+export interface HttpGovernanceClientOptions {
+    baseUrl: string;
+    timeout?: number;
+}
+export interface IGovernanceClient {
+    checkPermission(ctx: ExecutionContext, params: GovernancePermissionCheckParams): Promise<GovernancePermissionCheckResult>;
+}
+/**
+ * 通过 foundation-service governance API 校验权限
+ */
+export declare class HttpGovernanceClient implements IGovernanceClient {
+    private readonly baseUrl;
+    private readonly timeout;
+    constructor(options: HttpGovernanceClientOptions);
+    checkPermission(ctx: ExecutionContext, params: GovernancePermissionCheckParams): Promise<GovernancePermissionCheckResult>;
+}
+/** 本地/测试：跳过远程校验 */
+export declare class AllowAllGovernanceClient implements IGovernanceClient {
+    checkPermission(_ctx: ExecutionContext, _params: GovernancePermissionCheckParams): Promise<GovernancePermissionCheckResult>;
+}
+/**
+ * 从 Invoke 请求与 userId 解析 ExecutionContext
+ */
+export declare function resolveExecutionContext(req: {
+    /** @deprecated 使用 agentCode */
+    agentId?: string;
+    agentCode?: string;
+    sessionId?: string;
+    executionContext?: ExecutionContext;
+    userId?: string;
+}, fallbackUserId: string, options?: {
+    correlationId?: string;
+    delegationToken?: string;
+}): ExecutionContext;

package/dist/governance/governance-client.js

@@ -0,0 +1,95 @@
+/**
+ * 治理服务 HTTP 客户端（06-governance validateToken / checkPermission）
+ */
+import { randomUUID } from 'node:crypto';
+/**
+ * 通过 foundation-service governance API 校验权限
+ */
+export class HttpGovernanceClient {
+    baseUrl;
+    timeout;
+    constructor(options) {
+        this.baseUrl = options.baseUrl.replace(/\/+$/, '');
+        this.timeout = options.timeout ?? 10_000;
+    }
+    async checkPermission(ctx, params) {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+        try {
+            const response = await fetch(`${this.baseUrl}/api/v1/governance/check-permission`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    Authorization: `Bearer ${ctx.delegationToken}`,
+                },
+                body: JSON.stringify({
+                    userId: ctx.userId,
+                    callerType: ctx.callerType,
+                    roles: ctx.roles,
+                    permissions: ctx.permissions,
+                    resourceType: params.resourceType,
+                    resourceId: params.resourceId,
+                    action: params.action,
+                    dataScope: params.dataScope,
+                    resourceOwnerId: params.resourceOwnerId,
+                    correlationId: ctx.correlationId,
+                }),
+                signal: controller.signal,
+            });
+            clearTimeout(timeoutId);
+            if (response.status === 503 || response.status >= 500) {
+                return { allowed: false, reason: 'GOVERNANCE_UNAVAILABLE' };
+            }
+            if (!response.ok) {
+                if (response.status === 403) {
+                    try {
+                        const errBody = (await response.json());
+                        const errData = errBody.data ?? errBody;
+                        return { allowed: false, reason: errData.reason ?? 'NO_PERMISSION' };
+                    }
+                    catch {
+                        return { allowed: false, reason: 'NO_PERMISSION' };
+                    }
+                }
+                return { allowed: false, reason: 'NO_PERMISSION' };
+            }
+            const body = (await response.json());
+            const data = body.data ?? body;
+            return {
+                allowed: data.allowed === true,
+                reason: data.allowed ? undefined : (data.reason ?? 'NO_PERMISSION'),
+            };
+        }
+        catch {
+            clearTimeout(timeoutId);
+            return { allowed: false, reason: 'GOVERNANCE_UNAVAILABLE' };
+        }
+    }
+}
+/** 本地/测试：跳过远程校验 */
+export class AllowAllGovernanceClient {
+    async checkPermission(_ctx, _params) {
+        return { allowed: true };
+    }
+}
+/**
+ * 从 Invoke 请求与 userId 解析 ExecutionContext
+ */
+export function resolveExecutionContext(req, fallbackUserId, options) {
+    if (req.executionContext) {
+        return {
+            ...req.executionContext,
+            sessionId: req.executionContext.sessionId ?? req.sessionId,
+        };
+    }
+    const userId = req.userId ?? fallbackUserId;
+    return {
+        userId: userId === 'anonymous' ? null : userId,
+        callerType: 'user',
+        roles: [],
+        permissions: [],
+        delegationToken: options?.delegationToken ?? process.env.EAP_DELEGATION_TOKEN ?? '',
+        correlationId: options?.correlationId ?? randomUUID(),
+        sessionId: req.sessionId,
+    };
+}

package/dist/governance/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 权限校验 — 对齐 06-governance R16.8
+ */
+export type { CallerType, ExecutionContext, GovernancePermissionCheckParams, GovernancePermissionCheckResult, PermissionAction, PermissionDenyReason, PermissionResourceType, } from '@gt-fe/eap-contracts';
+export type { IGovernanceClient } from './governance-client.js';
+export { HttpGovernanceClient, AllowAllGovernanceClient, resolveExecutionContext, } from './governance-client.js';
+export { assertToolPermission, assertSkillPermission, PermissionDeniedError, GovernanceUnavailableError, } from './permission-guard.js';

package/dist/governance/index.js

@@ -0,0 +1,5 @@
+/**
+ * 权限校验 — 对齐 06-governance R16.8
+ */
+export { HttpGovernanceClient, AllowAllGovernanceClient, resolveExecutionContext, } from './governance-client.js';
+export { assertToolPermission, assertSkillPermission, PermissionDeniedError, GovernanceUnavailableError, } from './permission-guard.js';

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

@@ -0,0 +1,19 @@
+/**
+ * 执行期 Tool 权限守卫
+ */
+import type { ExecutionContext, PermissionDenyReason } from '@gt-fe/eap-contracts';
+import type { IGovernanceClient } from './governance-client.js';
+export declare class GovernanceUnavailableError extends Error {
+    readonly reason: PermissionDenyReason;
+    constructor(message?: string);
+}
+export declare class PermissionDeniedError extends Error {
+    readonly reason: PermissionDenyReason;
+    constructor(reason?: PermissionDenyReason, message?: string);
+}
+export declare function assertToolPermission(client: IGovernanceClient | undefined, ctx: ExecutionContext, toolId: string, options?: {
+    dataScope?: 'user-bound' | 'department-bound' | 'global';
+    resourceOwnerId?: string;
+}): Promise<void>;
+/** Skill 激活守卫（04 R15.3） */
+export declare function assertSkillPermission(client: IGovernanceClient | undefined, ctx: ExecutionContext, skillId: string): Promise<void>;

package/dist/governance/permission-guard.js

@@ -0,0 +1,59 @@
+/**
+ * 执行期 Tool 权限守卫
+ */
+export class GovernanceUnavailableError extends Error {
+    reason = 'GOVERNANCE_UNAVAILABLE';
+    constructor(message = 'Governance service unavailable') {
+        super(message);
+        this.name = 'GovernanceUnavailableError';
+    }
+}
+export class PermissionDeniedError extends Error {
+    reason;
+    constructor(reason = 'NO_PERMISSION', message) {
+        super(message ?? reason);
+        this.name = 'PermissionDeniedError';
+        this.reason = reason;
+    }
+}
+export async function assertToolPermission(client, ctx, toolId, options) {
+    if (!client) {
+        return;
+    }
+    if (!ctx.delegationToken && ctx.callerType === 'user') {
+        return;
+    }
+    const result = await client.checkPermission(ctx, {
+        resourceType: 'tool',
+        resourceId: toolId,
+        action: 'execute',
+        dataScope: options?.dataScope,
+        resourceOwnerId: options?.resourceOwnerId,
+    });
+    if (result.reason === 'GOVERNANCE_UNAVAILABLE') {
+        throw new GovernanceUnavailableError();
+    }
+    if (!result.allowed) {
+        throw new PermissionDeniedError(result.reason ?? 'NO_PERMISSION');
+    }
+}
+/** Skill 激活守卫（04 R15.3） */
+export async function assertSkillPermission(client, ctx, skillId) {
+    if (!client || !skillId) {
+        return;
+    }
+    if (!ctx.delegationToken && ctx.callerType === 'user') {
+        return;
+    }
+    const result = await client.checkPermission(ctx, {
+        resourceType: 'skill',
+        resourceId: skillId,
+        action: 'use',
+    });
+    if (result.reason === 'GOVERNANCE_UNAVAILABLE') {
+        throw new GovernanceUnavailableError();
+    }
+    if (!result.allowed) {
+        throw new PermissionDeniedError(result.reason ?? 'NO_PERMISSION');
+    }
+}

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

@@ -0,0 +1,3 @@
+export { LangGraphAdapter } from './langgraph.adapter.js';
+export { LangGraphCheckpointer } from './langgraph-checkpointer.js';
+export { SubGraphCompiler } from './subgraph-compiler.js';

package/dist/graph/adapters/index.js

@@ -0,0 +1,3 @@
+export { LangGraphAdapter } from './langgraph.adapter.js';
+export { LangGraphCheckpointer } from './langgraph-checkpointer.js';
+export { SubGraphCompiler } from './subgraph-compiler.js';

package/dist/graph/adapters/langgraph-checkpointer.d.ts

@@ -0,0 +1,40 @@
+/**
+ * LangGraphCheckpointer — BaseCheckpointSaver 桥接实现
+ *
+ * 将 LangGraph 的 BaseCheckpointSaver 接口委托到平台的 ICheckpointSaver，
+ * 实现 getTuple / put / putWrites / list 与 CheckpointData 之间的数据映射。
+ *
+ * @see design.md §1.4 Checkpoint 集成
+ * @see tasks.md Task 11.5
+ */
+import { BaseCheckpointSaver, type RunnableConfig, type CheckpointTuple, type Checkpoint, type CheckpointMetadata, type ListOptions } from '@langchain/langgraph';
+import type { ICheckpointSaver } from '../../checkpoint/contracts/checkpoint-saver.contract.js';
+/** LangGraph PendingWrite: [channel, value] */
+type PendingWrite = [channel: string, value: unknown];
+/**
+ * LangGraphCheckpointer — 桥接 LangGraph BaseCheckpointSaver → ICheckpointSaver
+ *
+ * intermediate writes（putWrites）先放进程内；checkpoint 快照仍落 ICheckpointSaver。
+ */
+export declare class LangGraphCheckpointer extends BaseCheckpointSaver {
+    private readonly saver;
+    /** threadId|ns|checkpointId → writes */
+    private readonly pendingWrites;
+    constructor(saver: ICheckpointSaver);
+    getTuple(config: RunnableConfig): Promise<CheckpointTuple | undefined>;
+    put(config: RunnableConfig, checkpoint: Checkpoint, metadata: CheckpointMetadata, _newVersions?: Record<string, number | string>): Promise<RunnableConfig>;
+    /**
+     * 存储与 checkpoint 关联的 intermediate writes（LangGraph 0.2+ 必需；缺此方法会报 putWrites is not a function）
+     */
+    putWrites(config: RunnableConfig, writes: PendingWrite[], taskId: string): Promise<void>;
+    list(config: RunnableConfig, options?: ListOptions): AsyncIterableIterator<CheckpointTuple>;
+    private extractThreadId;
+    private checkpointDataToTuple;
+    /**
+     * 优先还原 put() 时写入的 engineSnapshot；旧数据兜底补齐 pending_sends=[]。
+     */
+    private restoreLangGraphCheckpoint;
+    private checkpointToData;
+    private extractExtraState;
+}
+export {};