@gt-fe/eap-runtime 0.0.8

package/dist/common/health.d.ts

@@ -0,0 +1,40 @@
+/**
+ * RuntimeHealthInfo — Runtime 依赖健康状态
+ *
+ * 供宿主服务（Hosting/CLI）调用，组装 /health 响应。
+ * Runtime 作为库不直接暴露 HTTP 端点，只提供状态查询方法。
+ */
+export interface RuntimeHealthInfo {
+    /** Checkpoint 存储连接状态 */
+    checkpoint: 'connected' | 'disconnected';
+    /** Redis 连接状态 */
+    redis: 'connected' | 'disconnected' | 'not_configured';
+    /** 消息队列连接状态 */
+    mq: 'connected' | 'disconnected' | 'not_configured';
+}
+export interface HealthCheckDeps {
+    /** 检查 Checkpoint 存储是否可用 */
+    checkCheckpoint?: () => Promise<boolean>;
+    /** 检查 Redis 是否可用 */
+    checkRedis?: () => Promise<boolean>;
+    /** 检查消息队列是否可用 */
+    checkMq?: () => Promise<boolean>;
+}
+/**
+ * 获取 Runtime 依赖健康状态
+ *
+ * @param deps - 各依赖的健康检查函数（未提供则标记 not_configured）
+ * @returns RuntimeHealthInfo
+ *
+ * @example
+ * ```typescript
+ * import { getHealthInfo } from '@eap/runtime';
+ *
+ * const health = await getHealthInfo({
+ *   checkCheckpoint: () => pgPool.query('SELECT 1').then(() => true).catch(() => false),
+ *   checkRedis: () => redis.ping().then(() => true).catch(() => false),
+ * });
+ * // { checkpoint: 'connected', redis: 'connected', mq: 'not_configured' }
+ * ```
+ */
+export declare function getHealthInfo(deps?: HealthCheckDeps): Promise<RuntimeHealthInfo>;

package/dist/common/health.js

@@ -0,0 +1,37 @@
+/**
+ * RuntimeHealthInfo — Runtime 依赖健康状态
+ *
+ * 供宿主服务（Hosting/CLI）调用，组装 /health 响应。
+ * Runtime 作为库不直接暴露 HTTP 端点，只提供状态查询方法。
+ */
+/**
+ * 获取 Runtime 依赖健康状态
+ *
+ * @param deps - 各依赖的健康检查函数（未提供则标记 not_configured）
+ * @returns RuntimeHealthInfo
+ *
+ * @example
+ * ```typescript
+ * import { getHealthInfo } from '@eap/runtime';
+ *
+ * const health = await getHealthInfo({
+ *   checkCheckpoint: () => pgPool.query('SELECT 1').then(() => true).catch(() => false),
+ *   checkRedis: () => redis.ping().then(() => true).catch(() => false),
+ * });
+ * // { checkpoint: 'connected', redis: 'connected', mq: 'not_configured' }
+ * ```
+ */
+export async function getHealthInfo(deps = {}) {
+    const [checkpoint, redis, mq] = await Promise.all([
+        deps.checkCheckpoint
+            ? deps.checkCheckpoint().then((ok) => ok ? 'connected' : 'disconnected').catch(() => 'disconnected')
+            : Promise.resolve('disconnected'),
+        deps.checkRedis
+            ? deps.checkRedis().then((ok) => ok ? 'connected' : 'disconnected').catch(() => 'disconnected')
+            : Promise.resolve('not_configured'),
+        deps.checkMq
+            ? deps.checkMq().then((ok) => ok ? 'connected' : 'disconnected').catch(() => 'disconnected')
+            : Promise.resolve('not_configured'),
+    ]);
+    return { checkpoint, redis, mq };
+}

package/dist/common/index.d.ts

@@ -0,0 +1,5 @@
+export * from './types.js';
+export * from './logger.js';
+export * from './health.js';
+export * from './agent-code.js';
+export * from './trace-id.js';

package/dist/common/index.js

@@ -0,0 +1,5 @@
+export * from './types.js';
+export * from './logger.js';
+export * from './health.js';
+export * from './agent-code.js';
+export * from './trace-id.js';

package/dist/common/logger.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 结构化日志接口 — A2
+ */
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+export interface LogEntry {
+    level: LogLevel;
+    timestamp: string;
+    module: string;
+    message: string;
+    context?: Record<string, unknown>;
+    error?: Error;
+}
+export interface ILogger {
+    debug(message: string, context?: Record<string, unknown>): void;
+    info(message: string, context?: Record<string, unknown>): void;
+    warn(message: string, context?: Record<string, unknown>): void;
+    error(message: string, context?: Record<string, unknown>): void;
+}
+export declare class ConsoleLogger implements ILogger {
+    private readonly module;
+    constructor(module: string);
+    debug(message: string, context?: Record<string, unknown>): void;
+    info(message: string, context?: Record<string, unknown>): void;
+    warn(message: string, context?: Record<string, unknown>): void;
+    error(message: string, context?: Record<string, unknown>): void;
+    private log;
+}
+/** ponytail: 空实现，测试用 */
+export declare class NoopLogger implements ILogger {
+    debug(): void;
+    info(): void;
+    warn(): void;
+    error(): void;
+}

package/dist/common/logger.js

@@ -0,0 +1,38 @@
+/**
+ * 结构化日志接口 — A2
+ */
+export class ConsoleLogger {
+    module;
+    constructor(module) {
+        this.module = module;
+    }
+    debug(message, context) {
+        this.log('debug', message, context);
+    }
+    info(message, context) {
+        this.log('info', message, context);
+    }
+    warn(message, context) {
+        this.log('warn', message, context);
+    }
+    error(message, context) {
+        this.log('error', message, context);
+    }
+    log(level, message, context) {
+        const entry = {
+            level,
+            timestamp: new Date().toISOString(),
+            module: this.module,
+            message,
+            ...(context && { context }),
+        };
+        console[level](JSON.stringify(entry));
+    }
+}
+/** ponytail: 空实现，测试用 */
+export class NoopLogger {
+    debug() { }
+    info() { }
+    warn() { }
+    error() { }
+}

package/dist/common/queue-consumer.d.ts

@@ -0,0 +1,125 @@
+/**
+ * RabbitMQ 队列消费者
+ *
+ * 从 RabbitMQ 队列中消费任务消息，分发给 Graph 引擎处理。
+ * 通过 channel.prefetch(n) 控制并发：
+ * - 最多同时处理 n 条未 ack 的消息
+ * - 超出 prefetch 限制的消息留在 RabbitMQ Queue 中排队等待
+ * - 不丢弃任何请求
+ *
+ * 整体 QPS = Pod 数 × prefetch
+ *
+ * @see Requirement 14 AC2: 系统通过消息消费者 prefetch 参数控制单 Agent 实例的并发上限
+ * @see Requirement 14 AC3: 并发请求数超过 prefetch 限制时，系统将超出请求放入 Queue 排队等待，不丢弃请求
+ */
+import type { Connection } from 'amqplib';
+/**
+ * 任务消息体 — 从 RabbitMQ 队列中消费到的任务负载
+ */
+export interface TaskMessage {
+    /** 任务唯一标识 */
+    taskId: string;
+    /** 目标 Agent（值为 agentCode；字段名保留 agentId 兼容存量消息） */
+    agentId: string;
+    /** 会话 ID */
+    sessionId: string;
+    /** 发起请求的用户 ID */
+    userId: string;
+    /** 用户输入内容 */
+    input: string;
+    /** 可选的执行配置 */
+    config?: Record<string, unknown>;
+}
+/**
+ * 任务处理器 — 接收解析后的 TaskMessage，分发给 Graph 引擎执行
+ *
+ * 处理成功则 resolve，失败则 reject（消费者据此决定 ack/nack）。
+ */
+export type TaskHandler = (message: TaskMessage) => Promise<void>;
+/**
+ * QueueConsumer 配置选项
+ */
+export interface QueueConsumerOptions {
+    /** 队列名称 */
+    queueName: string;
+    /** prefetch 数量 — 单实例最大并发消息处理数，默认 5 */
+    prefetch?: number;
+    /** 队列是否持久化，默认 true */
+    durable?: boolean;
+    /** 是否自动确认（不推荐生产使用），默认 false */
+    noAck?: boolean;
+}
+/**
+ * RabbitMQ 队列消费者
+ *
+ * 核心设计：利用 RabbitMQ channel.prefetch 机制实现队列式溢出控制。
+ * - consumer.prefetch(5) → 该 Channel 上最多持有 5 条未 ack 消息
+ * - 第 6 条及后续消息自动留在 RabbitMQ Queue 中排队
+ * - 只有当某条消息被 ack/nack 后，RabbitMQ 才推送下一条
+ * - 保证不丢弃任何请求（queue-based overflow）
+ *
+ * 使用方式：
+ * ```ts
+ * const consumer = new QueueConsumer(connection, {
+ *   queueName: 'agent.tasks.ai-bi',
+ *   prefetch: 5,
+ * }, async (msg) => {
+ *   await graphEngine.execute(msg);
+ * });
+ *
+ * await consumer.start();
+ * // ... 优雅关闭
+ * await consumer.stop();
+ * ```
+ */
+export declare class QueueConsumer {
+    private readonly connection;
+    private readonly options;
+    private readonly taskHandler;
+    private channel;
+    private consumerTag;
+    private started;
+    /**
+     * @param connection amqplib Connection 实例
+     * @param options 消费者配置
+     * @param taskHandler 任务处理函数 — 接收解析后的消息，分发给 Graph 引擎
+     */
+    constructor(connection: Connection, options: QueueConsumerOptions, taskHandler: TaskHandler);
+    /**
+     * 启动消费者
+     *
+     * 1. 创建 Channel
+     * 2. 设置 prefetch（限制并发）
+     * 3. 声明队列（确保队列存在）
+     * 4. 开始消费消息
+     *
+     * prefetch 机制保证：超出限制的消息留在 RabbitMQ Queue 排队，不丢弃。
+     */
+    start(): Promise<void>;
+    /**
+     * 停止消费者并优雅关闭 Channel
+     *
+     * 1. 取消消费（不再接收新消息）
+     * 2. 关闭 Channel
+     *
+     * 已在处理中的消息不受影响，会正常完成后 ack/nack。
+     */
+    stop(): Promise<void>;
+    /**
+     * 是否正在运行
+     */
+    get isRunning(): boolean;
+    /**
+     * 获取配置的 prefetch 值
+     */
+    get prefetch(): number;
+    /**
+     * 处理单条消息
+     *
+     * - 解析消息体为 TaskMessage
+     * - 调用 taskHandler 执行任务
+     * - 成功 → ack（释放 prefetch 槽位，RabbitMQ 推送下一条）
+     * - 失败 → nack + requeue（消息重新入队，稍后重试）
+     */
+    private handleMessage;
+}

package/dist/common/queue-consumer.js

@@ -0,0 +1,159 @@
+/**
+ * RabbitMQ 队列消费者
+ *
+ * 从 RabbitMQ 队列中消费任务消息，分发给 Graph 引擎处理。
+ * 通过 channel.prefetch(n) 控制并发：
+ * - 最多同时处理 n 条未 ack 的消息
+ * - 超出 prefetch 限制的消息留在 RabbitMQ Queue 中排队等待
+ * - 不丢弃任何请求
+ *
+ * 整体 QPS = Pod 数 × prefetch
+ *
+ * @see Requirement 14 AC2: 系统通过消息消费者 prefetch 参数控制单 Agent 实例的并发上限
+ * @see Requirement 14 AC3: 并发请求数超过 prefetch 限制时，系统将超出请求放入 Queue 排队等待，不丢弃请求
+ */
+// ─────────────────────────────────────────────
+// QueueConsumer
+// ─────────────────────────────────────────────
+/** 默认 prefetch 值 */
+const DEFAULT_PREFETCH = 5;
+/**
+ * RabbitMQ 队列消费者
+ *
+ * 核心设计：利用 RabbitMQ channel.prefetch 机制实现队列式溢出控制。
+ * - consumer.prefetch(5) → 该 Channel 上最多持有 5 条未 ack 消息
+ * - 第 6 条及后续消息自动留在 RabbitMQ Queue 中排队
+ * - 只有当某条消息被 ack/nack 后，RabbitMQ 才推送下一条
+ * - 保证不丢弃任何请求（queue-based overflow）
+ *
+ * 使用方式：
+ * ```ts
+ * const consumer = new QueueConsumer(connection, {
+ *   queueName: 'agent.tasks.ai-bi',
+ *   prefetch: 5,
+ * }, async (msg) => {
+ *   await graphEngine.execute(msg);
+ * });
+ *
+ * await consumer.start();
+ * // ... 优雅关闭
+ * await consumer.stop();
+ * ```
+ */
+export class QueueConsumer {
+    connection;
+    options;
+    taskHandler;
+    channel = null;
+    consumerTag = null;
+    started = false;
+    /**
+     * @param connection amqplib Connection 实例
+     * @param options 消费者配置
+     * @param taskHandler 任务处理函数 — 接收解析后的消息，分发给 Graph 引擎
+     */
+    constructor(connection, options, taskHandler) {
+        this.connection = connection;
+        this.options = {
+            queueName: options.queueName,
+            prefetch: options.prefetch ?? DEFAULT_PREFETCH,
+            durable: options.durable ?? true,
+            noAck: options.noAck ?? false,
+        };
+        this.taskHandler = taskHandler;
+    }
+    /**
+     * 启动消费者
+     *
+     * 1. 创建 Channel
+     * 2. 设置 prefetch（限制并发）
+     * 3. 声明队列（确保队列存在）
+     * 4. 开始消费消息
+     *
+     * prefetch 机制保证：超出限制的消息留在 RabbitMQ Queue 排队，不丢弃。
+     */
+    async start() {
+        if (this.started) {
+            return;
+        }
+        // 1. 创建 Channel
+        this.channel = await this.connection.createChannel();
+        // 2. 设置 prefetch — 核心并发控制
+        // 超出 prefetch 的消息留在 Queue 中排队等待（queue-based overflow）
+        await this.channel.prefetch(this.options.prefetch);
+        // 3. 声明队列（幂等操作，队列已存在则不做修改）
+        await this.channel.assertQueue(this.options.queueName, {
+            durable: this.options.durable,
+        });
+        // 4. 开始消费
+        const { consumerTag } = await this.channel.consume(this.options.queueName, (msg) => this.handleMessage(msg), { noAck: this.options.noAck });
+        this.consumerTag = consumerTag;
+        this.started = true;
+    }
+    /**
+     * 停止消费者并优雅关闭 Channel
+     *
+     * 1. 取消消费（不再接收新消息）
+     * 2. 关闭 Channel
+     *
+     * 已在处理中的消息不受影响，会正常完成后 ack/nack。
+     */
+    async stop() {
+        if (!this.started || !this.channel) {
+            return;
+        }
+        // 取消消费者
+        if (this.consumerTag) {
+            await this.channel.cancel(this.consumerTag);
+            this.consumerTag = null;
+        }
+        // 关闭 Channel
+        await this.channel.close();
+        this.channel = null;
+        this.started = false;
+    }
+    /**
+     * 是否正在运行
+     */
+    get isRunning() {
+        return this.started;
+    }
+    /**
+     * 获取配置的 prefetch 值
+     */
+    get prefetch() {
+        return this.options.prefetch;
+    }
+    // ─── 内部方法 ───────────────────────────────
+    /**
+     * 处理单条消息
+     *
+     * - 解析消息体为 TaskMessage
+     * - 调用 taskHandler 执行任务
+     * - 成功 → ack（释放 prefetch 槽位，RabbitMQ 推送下一条）
+     * - 失败 → nack + requeue（消息重新入队，稍后重试）
+     */
+    async handleMessage(msg) {
+        // RabbitMQ 在 Channel 关闭时会发送 null
+        if (!msg || !this.channel) {
+            return;
+        }
+        try {
+            // 解析消息体
+            const body = msg.content.toString('utf-8');
+            const taskMessage = JSON.parse(body);
+            // 分发给 Graph 引擎处理
+            await this.taskHandler(taskMessage);
+            // 处理成功 → ack，释放 prefetch 槽位
+            if (!this.options.noAck) {
+                this.channel.ack(msg);
+            }
+        }
+        catch {
+            // 处理失败 → nack，requeue=true 让消息重新排队
+            if (!this.options.noAck && this.channel) {
+                this.channel.nack(msg, false, true);
+            }
+        }
+    }
+}

package/dist/common/trace-id.d.ts

@@ -0,0 +1,2 @@
+/** 从请求或 GraphState 读取 `traceId`。 */
+export declare function resolveTraceId(source: object): string | undefined;

package/dist/common/trace-id.js

@@ -0,0 +1,8 @@
+/** 从请求或 GraphState 读取 `traceId`。 */
+export function resolveTraceId(source) {
+    const rec = source;
+    if (typeof rec.traceId === 'string' && rec.traceId.trim()) {
+        return rec.traceId.trim();
+    }
+    return undefined;
+}

package/dist/common/types.d.ts

@@ -0,0 +1,104 @@
+/**
+ * eap-runtime 内部共享类型定义
+ *
+ * 本文件定义 Runtime 模块内部使用的类型，与 @gt-fe/eap-contracts 中的公共协议类型互补但不重复。
+ * - @gt-fe/eap-contracts 定义跨模块的公共协议（如 Task 实体、Session 实体、Agent Manifest）
+ * - 本文件定义 Runtime 执行引擎内部流转的配置、上下文、枚举等
+ */
+/**
+ * Token 统计输出粒度控制
+ * - none: 不输出任何 Token 统计事件
+ * - summary: 仅 Task 结束时输出 stats.token_usage 汇总
+ * - detail: 每次 LLM 调用输出 stats.node_token + 结束时汇总
+ */
+export type TokenDetailLevel = 'none' | 'summary' | 'detail';
+/**
+ * Runtime 执行引擎配置
+ *
+ * 控制单次请求级别的执行行为，来自 invoke/stream 请求体的 config 字段。
+ */
+export interface RuntimeConfig {
+    /** Token 统计输出粒度 */
+    tokenDetail: TokenDetailLevel;
+    /** Task 执行超时时间（毫秒） */
+    timeout: number;
+    /** ReAct 循环最大迭代次数 */
+    maxIterations: number;
+    /** SSE 心跳间隔（毫秒），默认 30000 */
+    heartbeatInterval: number;
+}
+/** RuntimeConfig 默认值 */
+export declare const DEFAULT_RUNTIME_CONFIG: RuntimeConfig;
+/**
+ * 执行上下文 — 贯穿 Graph 执行生命周期（Runtime 内部）
+ *
+ * 平台级 ExecutionContext（@gt-fe/eap-contracts）由 Hosting/eap dev 注入；
+ * 本类型在 Task 创建后组装，供引擎子服务使用。
+ */
+export interface RuntimeRunContext {
+    /** 当前 Task ID */
+    taskId: string;
+    /** 当前 Session ID */
+    sessionId: string;
+    /** 发起请求的用户 ID */
+    userId: string;
+    /** 请求关联 ID（用于分布式追踪） */
+    correlationId: string;
+    /** 目标 Agent（值为 agentCode；字段名保留 agentId 兼容历史调用方） */
+    agentId: string;
+    /** 运行时配置 */
+    config: RuntimeConfig;
+    /** 权限委托令牌（用于 Tool 调用时传递用户权限） */
+    delegationToken?: string;
+}
+/**
+ * Task 执行状态（Runtime 内部使用）
+ *
+ * 状态流转：pending → running → success | failed | timeout | token_exhausted | waiting_hitl
+ *
+ * waiting_hitl：等待人工介入确认，可通过 HITL API 恢复为 running
+ */
+export type TaskStatus = 'pending' | 'running' | 'waiting_hitl' | 'success' | 'failed' | 'timeout' | 'token_exhausted';
+/**
+ * Runtime 执行上下文绑定状态（非平台 Session 生命周期）
+ *
+ * 平台 Session 三态（active/paused/closed）由 Hosting 管理，见 @gt-fe/eap-contracts。
+ * Runtime 仅在引擎内标记执行上下文是否仍可绑定：`active` | `archived`。
+ */
+export type ExecutionSessionBindingStatus = 'active' | 'archived';
+/**
+ * 会话消息角色
+ * - user: 用户输入
+ * - assistant: Agent/LLM 回复
+ * - system: 系统提示词
+ * - tool: Tool 执行结果
+ */
+export type MessageRole = 'user' | 'assistant' | 'system' | 'tool';
+/**
+ * 单次 LLM/Tool 调用的 Token 消耗记录
+ *
+ * 与 @gt-fe/eap-contracts.TokenUsage 的区别：
+ * - contracts 版本是 Task 级聚合结果（含 byNode/byModel）
+ * - 本类型是单次调用粒度的原始记录，用于 Runtime 内部累计和 stats.node_token 事件
+ */
+export interface TokenUsage {
+    /** 输入 Token 数 */
+    input: number;
+    /** 输出 Token 数 */
+    output: number;
+    /** 总 Token 数 (input + output) */
+    total: number;
+    /** 使用的模型标识 */
+    model?: string;
+    /** 产生消耗的节点 ID */
+    nodeId?: string;
+    /** 预估费用（单位：元或美分，由平台配置决定） */
+    costEstimate?: number;
+}
+/**
+ * Token Budget 配额作用域
+ * - task: 单次 Task 执行上限
+ * - session: 同一 Session 的日预算
+ * - agent: 单个 Agent 单次执行 cap
+ */
+export type TokenBudgetScope = 'task' | 'session' | 'agent';

package/dist/common/types.js

@@ -0,0 +1,14 @@
+/**
+ * eap-runtime 内部共享类型定义
+ *
+ * 本文件定义 Runtime 模块内部使用的类型，与 @gt-fe/eap-contracts 中的公共协议类型互补但不重复。
+ * - @gt-fe/eap-contracts 定义跨模块的公共协议（如 Task 实体、Session 实体、Agent Manifest）
+ * - 本文件定义 Runtime 执行引擎内部流转的配置、上下文、枚举等
+ */
+/** RuntimeConfig 默认值 */
+export const DEFAULT_RUNTIME_CONFIG = {
+    tokenDetail: 'summary',
+    timeout: 60000,
+    maxIterations: 10,
+    heartbeatInterval: 30000,
+};

package/dist/contracts/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Contracts — Runtime 接口定义
+ *
+ * Runtime 核心接口，由其他模块实现。
+ * - Trace 采集：由 foundation-service 实现
+ * - 权限校验：由 foundation-service 实现
+ * - LLM 调用：由模型路由模块实现
+ * - 存储接口：由各存储后端实现
+ */
+export type { ITraceCollector, TraceEvent, TraceSession, } from './trace-collector.js';
+export type { IPermissionChecker } from './permission-checker.js';

package/dist/contracts/index.js

@@ -0,0 +1,10 @@
+/**
+ * Contracts — Runtime 接口定义
+ *
+ * Runtime 核心接口，由其他模块实现。
+ * - Trace 采集：由 foundation-service 实现
+ * - 权限校验：由 foundation-service 实现
+ * - LLM 调用：由模型路由模块实现
+ * - 存储接口：由各存储后端实现
+ */
+export {};

package/dist/contracts/permission-checker.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 权限校验器接口（对齐 06-governance R16.8）
+ */
+import type { ExecutionContext, GovernancePermissionCheckParams, GovernancePermissionCheckResult } from '@gt-fe/eap-contracts';
+/**
+ * IPermissionChecker — Runtime 执行期权限校验
+ */
+export interface IPermissionChecker {
+    checkPermission(ctx: ExecutionContext, params: GovernancePermissionCheckParams): Promise<GovernancePermissionCheckResult>;
+}

package/dist/contracts/permission-checker.js

@@ -0,0 +1,4 @@
+/**
+ * 权限校验器接口（对齐 06-governance R16.8）
+ */
+export {};