@gt-fe/eap-runtime 0.0.8

package/dist/graph/retry/node-retry.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Node Retry — 通用节点级重试执行器
+ *
+ * 为 StateGraph 中任意节点提供可配置的重试逻辑：
+ * - 支持 exponential / linear / fixed 退避策略 + jitter
+ * - 支持 AbortSignal（Graph级 timeout 时停止重试）
+ * - 跟踪重试次数供 observability 使用
+ * - 提供 withRetry 高阶函数包装节点函数
+ *
+ * @see design.md Issue#1: 两级重试（节点级 + Graph级 timeout）
+ * @see requirements.md Requirement 1 AC6
+ */
+import type { NodeRetryConfig } from '../contracts/executable-graph.js';
+/**
+ * NodeFunction — StateGraph 节点函数签名
+ *
+ * 接受当前 state 返回更新后的 state（partial 或完整）。
+ */
+export type NodeFunction = (state: Record<string, unknown>) => Promise<Record<string, unknown>>;
+/**
+ * RetryAttemptInfo — 单次重试的观测信息
+ */
+export interface RetryAttemptInfo {
+    /** 第几次尝试（从 1 开始，首次执行=1） */
+    attempt: number;
+    /** 本次等待的退避延迟（毫秒） */
+    delayMs: number;
+    /** 本次失败的错误 */
+    error: Error;
+    /** 时间戳 (ISO 8601) */
+    timestamp: string;
+}
+/**
+ * RetryResult — 重试执行结果（含观测数据）
+ */
+export interface RetryResult<T> {
+    /** 最终执行结果 */
+    result: T;
+    /** 总尝试次数（含首次） */
+    totalAttempts: number;
+    /** 各次重试的详细信息（不含最终成功的那次） */
+    retryAttempts: RetryAttemptInfo[];
+}
+/**
+ * RetryExhaustedError — 重试耗尽错误
+ *
+ * 当所有重试次数用完仍未成功时抛出。
+ */
+export declare class RetryExhaustedError extends Error {
+    /** 总尝试次数（含首次） */
+    readonly attempts: number;
+    /** 最后一次失败的原始错误 */
+    readonly lastError: Error;
+    /** 关联的节点 ID */
+    readonly nodeId: string;
+    /** 各次重试的详细记录 */
+    readonly retryAttempts: RetryAttemptInfo[];
+    constructor(opts: {
+        attempts: number;
+        lastError: Error;
+        nodeId: string;
+        retryAttempts: RetryAttemptInfo[];
+    });
+}
+/** LLM 节点默认重试配置：3 次 + 指数退避 */
+export declare const DEFAULT_LLM_RETRY_CONFIG: Required<NodeRetryConfig>;
+/** 通用节点默认重试配置：1 次 + fixed */
+export declare const DEFAULT_NODE_RETRY_CONFIG: Required<NodeRetryConfig>;
+/**
+ * NodeRetryExecutor — 通用节点重试执行器
+ *
+ * 可包装任意异步函数，提供重试 + 退避 + AbortSignal 支持。
+ */
+export declare class NodeRetryExecutor {
+    private readonly nodeId;
+    private readonly config;
+    constructor(nodeId: string, config?: NodeRetryConfig);
+    /**
+     * executeWithRetry — 带重试的通用异步函数执行
+     *
+     * @param fn - 要执行的异步函数
+     * @param config - 可选覆盖重试配置（不传则使用构造时配置）
+     * @param abortSignal - 可选 AbortSignal，用于 Graph 级 timeout 中断重试
+     * @returns RetryResult 包含结果和观测数据
+     * @throws RetryExhaustedError 当所有重试用尽
+     * @throws Error 当 AbortSignal 中断时抛出原始 abort reason 或 AbortError
+     */
+    executeWithRetry<T>(fn: () => Promise<T>, config?: NodeRetryConfig, abortSignal?: AbortSignal): Promise<RetryResult<T>>;
+    /**
+     * 获取节点 ID
+     */
+    getNodeId(): string;
+    /**
+     * 获取当前配置
+     */
+    getConfig(): Required<NodeRetryConfig>;
+    /**
+     * 计算退避延迟（支持 exponential / linear / fixed + jitter）
+     */
+    private calculateDelay;
+    /**
+     * 可中断的 sleep
+     *
+     * 支持 AbortSignal 提前中断等待。
+     */
+    private sleepWithAbort;
+}
+/**
+ * withRetry — 将节点函数包装为带重试逻辑的版本
+ *
+ * @param nodeId - 节点标识（用于错误报告和 observability）
+ * @param nodeFn - 原始节点函数
+ * @param config - 重试配置
+ * @param abortSignal - 可选 AbortSignal，用于 Graph 级 timeout 中断
+ * @returns 包装后的节点函数，行为与原函数一致但带重试
+ *
+ * @example
+ * ```ts
+ * const retryableLLM = withRetry('llm-node', llmNodeFn, { maxRetries: 3, backoff: { type: 'exponential', baseDelay: 1000, maxDelay: 30000 } });
+ * const result = await retryableLLM(state);
+ * ```
+ */
+export declare function withRetry(nodeId: string, nodeFn: NodeFunction, config: NodeRetryConfig, abortSignal?: AbortSignal): NodeFunction;

package/dist/graph/retry/node-retry.js

@@ -0,0 +1,235 @@
+/**
+ * Node Retry — 通用节点级重试执行器
+ *
+ * 为 StateGraph 中任意节点提供可配置的重试逻辑：
+ * - 支持 exponential / linear / fixed 退避策略 + jitter
+ * - 支持 AbortSignal（Graph级 timeout 时停止重试）
+ * - 跟踪重试次数供 observability 使用
+ * - 提供 withRetry 高阶函数包装节点函数
+ *
+ * @see design.md Issue#1: 两级重试（节点级 + Graph级 timeout）
+ * @see requirements.md Requirement 1 AC6
+ */
+// ─────────────────────────────────────────────
+// Custom Error
+// ─────────────────────────────────────────────
+/**
+ * RetryExhaustedError — 重试耗尽错误
+ *
+ * 当所有重试次数用完仍未成功时抛出。
+ */
+export class RetryExhaustedError extends Error {
+    /** 总尝试次数（含首次） */
+    attempts;
+    /** 最后一次失败的原始错误 */
+    lastError;
+    /** 关联的节点 ID */
+    nodeId;
+    /** 各次重试的详细记录 */
+    retryAttempts;
+    constructor(opts) {
+        super(`Node "${opts.nodeId}" failed after ${opts.attempts} attempts: ${opts.lastError.message}`);
+        this.name = 'RetryExhaustedError';
+        this.attempts = opts.attempts;
+        this.lastError = opts.lastError;
+        this.nodeId = opts.nodeId;
+        this.retryAttempts = opts.retryAttempts;
+    }
+}
+// ─────────────────────────────────────────────
+// Default Config
+// ─────────────────────────────────────────────
+/** LLM 节点默认重试配置：3 次 + 指数退避 */
+export const DEFAULT_LLM_RETRY_CONFIG = {
+    maxRetries: 3,
+    backoff: {
+        type: 'exponential',
+        baseDelay: 1000,
+        maxDelay: 30000,
+        jitter: 0.1,
+    },
+};
+/** 通用节点默认重试配置：1 次 + fixed */
+export const DEFAULT_NODE_RETRY_CONFIG = {
+    maxRetries: 1,
+    backoff: {
+        type: 'fixed',
+        baseDelay: 500,
+        maxDelay: 5000,
+        jitter: 0,
+    },
+};
+// ─────────────────────────────────────────────
+// NodeRetryExecutor
+// ─────────────────────────────────────────────
+/**
+ * NodeRetryExecutor — 通用节点重试执行器
+ *
+ * 可包装任意异步函数，提供重试 + 退避 + AbortSignal 支持。
+ */
+export class NodeRetryExecutor {
+    nodeId;
+    config;
+    constructor(nodeId, config) {
+        this.nodeId = nodeId;
+        this.config = {
+            maxRetries: config?.maxRetries ?? DEFAULT_NODE_RETRY_CONFIG.maxRetries,
+            backoff: config?.backoff ?? DEFAULT_NODE_RETRY_CONFIG.backoff,
+        };
+    }
+    /**
+     * executeWithRetry — 带重试的通用异步函数执行
+     *
+     * @param fn - 要执行的异步函数
+     * @param config - 可选覆盖重试配置（不传则使用构造时配置）
+     * @param abortSignal - 可选 AbortSignal，用于 Graph 级 timeout 中断重试
+     * @returns RetryResult 包含结果和观测数据
+     * @throws RetryExhaustedError 当所有重试用尽
+     * @throws Error 当 AbortSignal 中断时抛出原始 abort reason 或 AbortError
+     */
+    async executeWithRetry(fn, config, abortSignal) {
+        const effectiveConfig = {
+            maxRetries: config?.maxRetries ?? this.config.maxRetries,
+            backoff: config?.backoff ?? this.config.backoff,
+        };
+        const retryAttempts = [];
+        let lastError;
+        const totalTries = effectiveConfig.maxRetries + 1; // 首次 + 重试次数
+        for (let attempt = 1; attempt <= totalTries; attempt++) {
+            // 检查 AbortSignal
+            if (abortSignal?.aborted) {
+                throw abortSignal.reason instanceof Error
+                    ? abortSignal.reason
+                    : new Error(abortSignal.reason?.toString() ?? 'Aborted');
+            }
+            try {
+                const result = await fn();
+                return {
+                    result,
+                    totalAttempts: attempt,
+                    retryAttempts,
+                };
+            }
+            catch (error) {
+                lastError = error instanceof Error ? error : new Error(String(error));
+                // 最后一次尝试不再退避
+                if (attempt < totalTries) {
+                    const delayMs = this.calculateDelay(attempt - 1, effectiveConfig.backoff);
+                    retryAttempts.push({
+                        attempt,
+                        delayMs,
+                        error: lastError,
+                        timestamp: new Date().toISOString(),
+                    });
+                    // 带 AbortSignal 的 sleep
+                    await this.sleepWithAbort(delayMs, abortSignal);
+                }
+            }
+        }
+        // 所有重试耗尽
+        throw new RetryExhaustedError({
+            attempts: totalTries,
+            lastError: lastError,
+            nodeId: this.nodeId,
+            retryAttempts,
+        });
+    }
+    /**
+     * 获取节点 ID
+     */
+    getNodeId() {
+        return this.nodeId;
+    }
+    /**
+     * 获取当前配置
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+    // ─────────────────────────────────────────────
+    // Private
+    // ─────────────────────────────────────────────
+    /**
+     * 计算退避延迟（支持 exponential / linear / fixed + jitter）
+     */
+    calculateDelay(retryIndex, backoff) {
+        let delay;
+        switch (backoff.type) {
+            case 'exponential':
+                delay = backoff.baseDelay * Math.pow(2, retryIndex);
+                break;
+            case 'linear':
+                delay = backoff.baseDelay * (retryIndex + 1);
+                break;
+            case 'fixed':
+                delay = backoff.baseDelay;
+                break;
+            default:
+                delay = backoff.baseDelay;
+        }
+        // 限制最大延迟
+        delay = Math.min(delay, backoff.maxDelay);
+        // 应用 jitter
+        if (backoff.jitter && backoff.jitter > 0) {
+            const jitterRange = delay * backoff.jitter;
+            delay += Math.random() * jitterRange * 2 - jitterRange;
+            delay = Math.max(0, delay);
+        }
+        return Math.round(delay);
+    }
+    /**
+     * 可中断的 sleep
+     *
+     * 支持 AbortSignal 提前中断等待。
+     */
+    sleepWithAbort(ms, abortSignal) {
+        if (!abortSignal) {
+            return new Promise((resolve) => setTimeout(resolve, ms));
+        }
+        return new Promise((resolve, reject) => {
+            if (abortSignal.aborted) {
+                reject(abortSignal.reason instanceof Error
+                    ? abortSignal.reason
+                    : new Error(abortSignal.reason?.toString() ?? 'Aborted'));
+                return;
+            }
+            const timer = setTimeout(() => {
+                abortSignal.removeEventListener('abort', onAbort);
+                resolve();
+            }, ms);
+            function onAbort() {
+                clearTimeout(timer);
+                reject(abortSignal.reason instanceof Error
+                    ? abortSignal.reason
+                    : new Error(abortSignal.reason?.toString() ?? 'Aborted'));
+            }
+            abortSignal.addEventListener('abort', onAbort, { once: true });
+        });
+    }
+}
+// ─────────────────────────────────────────────
+// withRetry — 高阶包装函数
+// ─────────────────────────────────────────────
+/**
+ * withRetry — 将节点函数包装为带重试逻辑的版本
+ *
+ * @param nodeId - 节点标识（用于错误报告和 observability）
+ * @param nodeFn - 原始节点函数
+ * @param config - 重试配置
+ * @param abortSignal - 可选 AbortSignal，用于 Graph 级 timeout 中断
+ * @returns 包装后的节点函数，行为与原函数一致但带重试
+ *
+ * @example
+ * ```ts
+ * const retryableLLM = withRetry('llm-node', llmNodeFn, { maxRetries: 3, backoff: { type: 'exponential', baseDelay: 1000, maxDelay: 30000 } });
+ * const result = await retryableLLM(state);
+ * ```
+ */
+export function withRetry(nodeId, nodeFn, config, abortSignal) {
+    const executor = new NodeRetryExecutor(nodeId, config);
+    return async (state) => {
+        const { result } = await executor.executeWithRetry(() => nodeFn(state), undefined, // 使用 executor 自身的配置
+        abortSignal);
+        return result;
+    };
+}

package/dist/graph/skill-audit-recorder.d.ts

@@ -0,0 +1,126 @@
+/**
+ * SkillAuditRecorder — Skill 调用台账（RT-6）
+ *
+ * 记录每次 Skill（子图）激活的审计明细，供后续分析与看板使用。
+ * Runtime 负责写入；Gateway 看不到 Skill 调用。
+ *
+ * @see docs/status/module-status-and-backlog.md RT-6
+ */
+/**
+ * Skill 调用审计记录
+ */
+export interface SkillInvocationRecord {
+    /** 记录唯一 ID */
+    id: string;
+    /** Skill ID（子图标识） */
+    skillId: string;
+    /** Skill 名称 */
+    skillName?: string;
+    /** @deprecated 使用 agentCode；仅作历史记录查询兜底 */
+    agentId?: string;
+    /** 调用方 Agent Code */
+    agentCode?: string;
+    /** 调用用户 ID */
+    userId: string;
+    /** 所属 Task ID */
+    taskId?: string;
+    /** 链路关联 ID */
+    correlationId?: string;
+    /** 调用开始时间 (ISO 8601) */
+    startedAt: string;
+    /** 调用结束时间 (ISO 8601) */
+    completedAt?: string;
+    /** 执行耗时（毫秒） */
+    durationMs?: number;
+    /** 调用结果 */
+    status: 'success' | 'failed' | 'denied' | 'timeout';
+    /** 失败原因 */
+    errorMessage?: string;
+    /** Token 消耗（子图级别汇总） */
+    tokenUsage?: {
+        input: number;
+        output: number;
+        total: number;
+    };
+    /** 额外元数据 */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * ISkillAuditStore — Skill 审计存储接口
+ *
+ * 默认实现为内存存储；生产环境应接入 PG 或外部审计服务。
+ */
+export interface ISkillAuditStore {
+    /** 写入审计记录 */
+    write(record: SkillInvocationRecord): Promise<void>;
+    /** 按 Skill ID 查询记录 */
+    queryBySkill(skillId: string, limit?: number): Promise<SkillInvocationRecord[]>;
+    /** 按 Agent Code 查询记录 */
+    queryByAgent(agentCode: string, limit?: number): Promise<SkillInvocationRecord[]>;
+    /** 查询最近 N 条记录 */
+    queryRecent(limit?: number): Promise<SkillInvocationRecord[]>;
+}
+/**
+ * InMemorySkillAuditStore — 内存 Skill 审计存储（开发/测试用）
+ */
+export declare class InMemorySkillAuditStore implements ISkillAuditStore {
+    private readonly records;
+    private readonly maxRecords;
+    constructor(maxRecords?: number);
+    write(record: SkillInvocationRecord): Promise<void>;
+    queryBySkill(skillId: string, limit?: number): Promise<SkillInvocationRecord[]>;
+    queryByAgent(agentCode: string, limit?: number): Promise<SkillInvocationRecord[]>;
+    queryRecent(limit?: number): Promise<SkillInvocationRecord[]>;
+}
+/**
+ * SkillAuditRecorder — Skill 调用审计记录器
+ *
+ * 在 SubGraphCompiler 执行 Skill 子图时调用，
+ * 记录每次激活的完整审计信息。
+ */
+export declare class SkillAuditRecorder {
+    private readonly store;
+    constructor(store?: ISkillAuditStore);
+    /**
+     * 开始记录一次 Skill 调用
+     *
+     * 返回一个 recorder context，调用方在 Skill 完成/失败后调用 finish()
+     */
+    startInvocation(params: {
+        skillId: string;
+        skillName?: string;
+        agentCode?: string;
+        userId: string;
+        taskId?: string;
+        correlationId?: string;
+        metadata?: Record<string, unknown>;
+    }): SkillInvocationContext;
+    /**
+     * 获取底层存储（供查询使用）
+     */
+    getStore(): ISkillAuditStore;
+}
+/**
+ * SkillInvocationContext — 单次 Skill 调用的审计上下文
+ */
+export declare class SkillInvocationContext {
+    private readonly record;
+    private readonly store;
+    constructor(store: ISkillAuditStore, record: SkillInvocationRecord);
+    /**
+     * 完成调用并写入审计记录
+     */
+    finish(result: {
+        status?: 'success' | 'failed' | 'denied' | 'timeout';
+        errorMessage?: string;
+        tokenUsage?: {
+            input: number;
+            output: number;
+            total: number;
+        };
+    }): Promise<SkillInvocationRecord>;
+    /**
+     * 获取记录 ID
+     */
+    getId(): string;
+}

package/dist/graph/skill-audit-recorder.js

@@ -0,0 +1,114 @@
+/**
+ * SkillAuditRecorder — Skill 调用台账（RT-6）
+ *
+ * 记录每次 Skill（子图）激活的审计明细，供后续分析与看板使用。
+ * Runtime 负责写入；Gateway 看不到 Skill 调用。
+ *
+ * @see docs/status/module-status-and-backlog.md RT-6
+ */
+/**
+ * InMemorySkillAuditStore — 内存 Skill 审计存储（开发/测试用）
+ */
+export class InMemorySkillAuditStore {
+    records = [];
+    maxRecords;
+    constructor(maxRecords = 10000) {
+        this.maxRecords = maxRecords;
+    }
+    async write(record) {
+        this.records.push(record);
+        // 超过上限时移除最早的记录
+        if (this.records.length > this.maxRecords) {
+            this.records.splice(0, this.records.length - this.maxRecords);
+        }
+    }
+    async queryBySkill(skillId, limit = 100) {
+        return this.records
+            .filter((r) => r.skillId === skillId)
+            .slice(-limit)
+            .reverse();
+    }
+    async queryByAgent(agentCode, limit = 100) {
+        return this.records
+            .filter((r) => r.agentCode === agentCode || r.agentId === agentCode)
+            .slice(-limit)
+            .reverse();
+    }
+    async queryRecent(limit = 50) {
+        return this.records.slice(-limit).reverse();
+    }
+}
+/**
+ * SkillAuditRecorder — Skill 调用审计记录器
+ *
+ * 在 SubGraphCompiler 执行 Skill 子图时调用，
+ * 记录每次激活的完整审计信息。
+ */
+export class SkillAuditRecorder {
+    store;
+    constructor(store) {
+        this.store = store ?? new InMemorySkillAuditStore();
+    }
+    /**
+     * 开始记录一次 Skill 调用
+     *
+     * 返回一个 recorder context，调用方在 Skill 完成/失败后调用 finish()
+     */
+    startInvocation(params) {
+        const id = `skill-inv-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+        const startedAt = new Date().toISOString();
+        return new SkillInvocationContext(this.store, {
+            id,
+            skillId: params.skillId,
+            skillName: params.skillName,
+            agentCode: params.agentCode,
+            userId: params.userId,
+            taskId: params.taskId,
+            correlationId: params.correlationId,
+            startedAt,
+            status: 'success',
+            metadata: params.metadata,
+        });
+    }
+    /**
+     * 获取底层存储（供查询使用）
+     */
+    getStore() {
+        return this.store;
+    }
+}
+/**
+ * SkillInvocationContext — 单次 Skill 调用的审计上下文
+ */
+export class SkillInvocationContext {
+    record;
+    store;
+    constructor(store, record) {
+        this.store = store;
+        this.record = record;
+    }
+    /**
+     * 完成调用并写入审计记录
+     */
+    async finish(result) {
+        const completedAt = new Date().toISOString();
+        const startedMs = new Date(this.record.startedAt).getTime();
+        const durationMs = Date.now() - startedMs;
+        const finalRecord = {
+            ...this.record,
+            completedAt,
+            durationMs,
+            status: result.status ?? 'success',
+            errorMessage: result.errorMessage,
+            tokenUsage: result.tokenUsage,
+        };
+        await this.store.write(finalRecord);
+        return finalRecord;
+    }
+    /**
+     * 获取记录 ID
+     */
+    getId() {
+        return this.record.id;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+export * from './graph/index.js';
+export * from './checkpoint/index.js';
+export * from './task/index.js';
+export * from './runtime/index.js';
+export * from './session/index.js';
+export * from './sse/index.js';
+export * from './token/index.js';
+export * from './tool/index.js';
+/**
+ * dev-only HTTP 适配层（`EAP_DEV_HTTP=1`）；生产请内嵌 AgentRuntime + Hosting HTTP
+ * @internal
+ */
+export * from './api/index.js';
+export * from './memory/index.js';
+export * from './common/index.js';
+export * from './registry/index.js';
+export * from './providers/index.js';
+export type { ITraceCollector, TraceEvent, TraceSession, ExecutionFlowEvent, ExecutionNodeEvent, TraceLinkEvent, TraceLinkNodeEvent, } from './contracts/trace-collector.js';
+export type { ExecutionContext, CallerType, GovernancePermissionCheckParams, GovernancePermissionCheckResult, PermissionDenyReason, } from '@gt-fe/eap-contracts';
+export { HttpGovernanceClient, AllowAllGovernanceClient, resolveExecutionContext, assertToolPermission, assertSkillPermission, PermissionDeniedError, GovernanceUnavailableError, } from './governance/index.js';
+export type { IGovernanceClient } from './governance/index.js';

package/dist/index.js

@@ -0,0 +1,32 @@
+// @eap/runtime — Enterprise Agent Platform 运行时核心引擎
+// 所有子模块的统一入口
+// Graph Engine
+export * from './graph/index.js';
+// Checkpoint & State
+export * from './checkpoint/index.js';
+// Task Management
+export * from './task/index.js';
+// AgentRuntime SDK facade（Hosting / eap dev 内嵌入口）
+export * from './runtime/index.js';
+// Session & Messages
+export * from './session/index.js';
+// SSE Streaming
+export * from './sse/index.js';
+// Token Budget & Stats
+export * from './token/index.js';
+// Tool Orchestration
+export * from './tool/index.js';
+/**
+ * dev-only HTTP 适配层（`EAP_DEV_HTTP=1`）；生产请内嵌 AgentRuntime + Hosting HTTP
+ * @internal
+ */
+export * from './api/index.js';
+// Memory (P2)
+export * from './memory/index.js';
+// Common Types（不含 @internal 并发/队列模块）
+export * from './common/index.js';
+// Registry integration
+export * from './registry/index.js';
+// LLM Providers
+export * from './providers/index.js';
+export { HttpGovernanceClient, AllowAllGovernanceClient, resolveExecutionContext, assertToolPermission, assertSkillPermission, PermissionDeniedError, GovernanceUnavailableError, } from './governance/index.js';