@ai-setting/roy-agent-core 1.7.52 → 1.7.53

package/dist/env/types.d.ts

@@ -0,0 +1,184 @@
+/**
+ * @fileoverview Environment types and interfaces
+ *
+ * 定义 Environment 的核心类型，包括：
+ * - Environment 配置
+ * - EnvEvent 事件类型
+ */
+/**
+ * Environment Config
+ */
+export interface EnvironmentConfig {
+    /** 环境名称 */
+    name: string;
+    /** 环境版本 */
+    version: string;
+    /** 是否启用 */
+    enabled: boolean;
+}
+/**
+ * BaseEnvironment 配置
+ */
+export interface BaseEnvironmentConfig {
+    /** 环境名称 */
+    name?: string;
+    /** 环境版本 */
+    version?: string;
+    /** 是否启用 */
+    enabled?: boolean;
+}
+/**
+ * EnvEvent 元信息
+ */
+export interface EnvEventMetadata {
+    /** 触发事件的 session ID */
+    trigger_session_id?: string;
+    /** 触发事件的 agent ID */
+    trigger_agent_id?: string;
+    /** Agent 名称 */
+    trigger_agent_name?: string;
+    /** 环境名称 */
+    env_name?: string;
+    /** 事件来源（如 "event-source"） */
+    source?: string;
+    /**
+     * Task #4042 (ESPlugin v2 Phase 2)：trigger event ID
+     *
+     * 当 event 是由 delegate_task sub-agent 完成触发的 notify event 时，
+     * 此字段指向触发整个 delegate_task 调用的原始 event（由 EventStore
+     * insertTriggerEvent 返回）。下游 consumer 用此 ID 反查 EventStore
+     * 拿到原始 chatId / messageId 等 ES info。
+     *
+     * 不存在时：notify event 由非 ES 触发的场景，consumer 应 fallback 到
+     * lastReplyChannel / metadata.replyChannel。
+     */
+    triggerEventId?: string;
+    /** 事件源 ID */
+    sourceId?: string;
+    /** 反馈通道（用于事件处理完成后回复） */
+    replyChannel?: {
+        /** 渠道类型，如 lark-cli, bounty-im */
+        type: string;
+        /** 发送目标的 app ID */
+        appId?: string;
+        /** 发送目标的会话 ID */
+        chatId?: string;
+        /** 原始消息 ID（用于回复） */
+        messageId?: string;
+        /** 原始回复指令 */
+        rawCommand?: string;
+        /** 其他自定义参数 */
+        params?: Record<string, unknown>;
+    };
+    /** 启用的插件列表（用于 pluginEnabled 构建） */
+    plugins?: string[];
+    /** 其他元数据 */
+    [key: string]: unknown;
+}
+/**
+ * EnvEvent
+ *
+ * 统一的事件机制，用于：
+ * - Stream 事件（stream.start, stream.text, stream.completed 等）
+ * - 工具调用事件（tool.call, tool.result 等）
+ * - 会话事件（session.created, session.updated 等）
+ * - Agent 事件（agent.thinking, agent.acting 等）
+ */
+export interface EnvEvent<T = unknown> {
+    /** 事件 ID */
+    id: string;
+    /** 事件类型 */
+    type: string;
+    /** 时间戳 */
+    timestamp: number;
+    /** 元信息 */
+    metadata: EnvEventMetadata;
+    /** 事件负载 */
+    payload: T;
+}
+/**
+ * EnvEvent Handler
+ */
+export type EnvEventHandler = (event: EnvEvent) => void | Promise<void>;
+/**
+ * EnvEvent 创建参数（部分属性，可选）
+ *
+ * 用于 pushEnvEvent 方法，允许传入部分属性，自动补全必填字段
+ */
+export interface EnvEventInput {
+    /** 事件类型（必填） */
+    type: string;
+    /** 事件 ID（可选，自动生成） */
+    id?: string;
+    /** 时间戳（可选，自动生成） */
+    timestamp?: number;
+    /** 元信息（可选，自动创建） */
+    metadata?: EnvEventMetadata;
+    /** 事件负载（可选） */
+    payload?: unknown;
+}
+/**
+ * Action 类型
+ */
+export interface Action {
+    /** Action 类型 */
+    type: string;
+    /** Action 参数 */
+    params?: Record<string, unknown>;
+}
+/**
+ * Tool Result
+ */
+export interface ToolResult {
+    /** 是否成功 */
+    success: boolean;
+    /** 输出内容 */
+    output: string | Record<string, unknown>;
+    /** 错误信息 */
+    error?: string;
+}
+/**
+ * Context
+ */
+export interface Context {
+    /** 会话 ID */
+    sessionId?: string;
+    /** 用户 ID */
+    userId?: string;
+    /** 工作目录 */
+    workdir?: string;
+    /** 中断信号 */
+    abort?: AbortSignal;
+    /** 元数据 */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Session Hook 上下文
+ */
+export interface SessionHookContext {
+    /** Session 对象 */
+    session?: {
+        id: string;
+        title?: string;
+        metadata?: Record<string, unknown>;
+    };
+    /** 操作选项 */
+    options?: Record<string, unknown>;
+}
+/**
+ * Log Context（日志上下文）
+ */
+export interface LogContext {
+    /** 日志级别 */
+    level: string;
+    /** 日志类别 */
+    category: string;
+    /** 日志消息 */
+    message: string;
+    /** 时间戳 */
+    timestamp: number;
+    /** 调用位置 */
+    callerLocation?: string;
+    /** 其他元数据 */
+    [key: string]: unknown;
+}

package/dist/env/workflow/decorators/decorator-node.d.ts

@@ -0,0 +1,76 @@
+/**
+ * DecoratorNode - 执行装饰器类方法的节点
+ *
+ * 实现 Node 接口，用于执行使用 @Workflow/@NodeAs 装饰的类方法
+ */
+import type { Node, NodeDefinition, NodeExecutionContext, NodeExecutionResult } from '../types';
+/**
+ * DecoratorNode 节点配置
+ */
+export interface DecoratorNodeConfig extends NodeDefinition {
+    config: {
+        /** 方法名称 */
+        _methodName: string;
+        /** 类实例 */
+        _instance: any;
+        /** 用户自定义配置 */
+        [key: string]: unknown;
+    };
+}
+/**
+ * DecoratorNode - 执行装饰器类方法的节点
+ *
+ * 用于执行使用 @Workflow/@NodeAs 装饰器定义的类方法
+ *
+ * @example
+ * ```typescript
+ * const definition: DecoratorNodeConfig = {
+ *   id: 'myNode',
+ *   type: 'decorator',
+ *   config: {
+ *     _methodName: 'myMethod',
+ *     _instance: myWorkflowInstance,
+ *   }
+ * };
+ *
+ * const node = new DecoratorNode(definition);
+ * const result = await node.execute(context);
+ * ```
+ */
+export declare class DecoratorNode implements Node {
+    readonly type = "decorator";
+    readonly id: string;
+    private readonly methodName;
+    private readonly instance;
+    private readonly dependsOn;
+    private readonly timeout?;
+    private readonly retryConfig?;
+    constructor(definition: NodeDefinition);
+    /**
+     * 执行装饰器方法
+     */
+    execute(context: NodeExecutionContext): Promise<NodeExecutionResult>;
+    /**
+     * 准备输入参数
+     *
+     * 根据依赖的节点 ID，从 nodeOutputs 中提取对应的输出
+     * 返回格式: { [depNodeId]: depOutput }
+     */
+    private prepareInput;
+    /**
+     * 带重试的执行
+     */
+    private executeWithRetry;
+    /**
+     * 带超时的执行
+     */
+    private executeWithTimeout;
+    /**
+     * 计算退避延迟
+     */
+    private calculateBackoff;
+    /**
+     * 睡眠
+     */
+    private sleep;
+}

package/dist/env/workflow/decorators/edge.d.ts

@@ -0,0 +1,42 @@
+/**
+ * @Edge 和 @WorkflowEdges 装饰器
+ *
+ * 用于显式声明节点之间的边关系
+ */
+import 'reflect-metadata';
+import type { EdgeMetadata, EdgeOptions } from '../types/decorators-types';
+/**
+ * 声明一条边 (from -> to)
+ *
+ * 这是一个方法装饰器，用于在方法上声明边关系
+ *
+ * @param from - 起始节点 ID
+ * @param to - 目标节点 ID
+ *
+ * @example
+ * ```typescript
+ * @Edge('nodeA', 'nodeB')
+ * static __edge_nodeA_to_nodeB__ = null;
+ * ```
+ */
+export declare function Edge(from: string, to: string): MethodDecorator;
+/**
+ * 类级别装饰器，声明多条边
+ *
+ * @param edges - 边数组
+ *
+ * @example
+ * ```typescript
+ * @WorkflowEdges([
+ *   { from: 'A', to: 'B' },
+ *   { from: 'B', to: 'C' }
+ * ])
+ * @Workflow({ name: 'test' })
+ * class TestWorkflow { }
+ * ```
+ */
+export declare function WorkflowEdges(edges: EdgeOptions[]): ClassDecorator;
+/**
+ * 获取类上的所有边元数据
+ */
+export declare function getEdgeMetadatas(target: Function): EdgeMetadata[];

package/dist/env/workflow/decorators/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @fileoverview Workflow Decorators Index
+ *
+ * 导出所有装饰器相关的 API
+ */
+export { Workflow, getWorkflowMetadata } from './workflow';
+export { NodeAs, getNodeMetadatas } from './node-as';
+export { Edge, WorkflowEdges, getEdgeMetadatas } from './edge';
+export { DecoratorNode } from './decorator-node';
+export type { DecoratorNodeConfig } from './decorator-node';
+export { WorkflowConverter } from '../extractor/workflow-converter';
+export { createWorkflowFromClass } from '../utils/create-workflow';
+export type { WorkflowOptions, NodeAsOptions, EdgeOptions, WorkflowMetadata, NodeMetadata, EdgeMetadata, ValidationResult, ConvertedWorkflowDefinition, ConvertedNodeDefinition, } from '../types/decorators-types';

package/dist/env/workflow/decorators/node-as.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @NodeAs 装饰器
+ *
+ * 用于将类方法声明为 Workflow 的 Node
+ */
+import 'reflect-metadata';
+import type { NodeAsOptions, NodeMetadata } from '../types/decorators-types';
+/**
+ * 将方法声明为 Workflow 的 Node
+ *
+ * @param options - Node 配置选项
+ *
+ * @example
+ * ```typescript
+ * @Workflow({ name: 'my-workflow', entry: 'fetch' })
+ * class MyWorkflow {
+ *   @NodeAs({
+ *     nodeId: 'fetch',
+ *     nodeType: 'tool',
+ *     config: { tool: 'web_search' }
+ *   })
+ *   async fetch(input: { query: string }) {
+ *     return { data: [] };
+ *   }
+ *
+ *   @NodeAs({
+ *     nodeId: 'process',
+ *     dependsOn: 'fetch'
+ *   })
+ *   async process(input: { data: any }) {
+ *     return { result: {} };
+ *   }
+ * }
+ * ```
+ */
+export declare function NodeAs(options?: NodeAsOptions): MethodDecorator;
+/**
+ * 获取类上所有方法的 Node 元数据
+ */
+export declare function getNodeMetadatas(target: Object): NodeMetadata[];

package/dist/env/workflow/decorators/workflow.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @Workflow 装饰器
+ *
+ * 用于声明一个类为 Workflow 类
+ */
+import 'reflect-metadata';
+import type { WorkflowOptions, WorkflowMetadata } from '../types/decorators-types';
+/**
+ * 声明一个类为 Workflow 类
+ *
+ * @param options - Workflow 配置选项
+ *
+ * @example
+ * ```typescript
+ * @Workflow({
+ *   name: 'my-workflow',
+ *   version: '1.0',
+ *   entry: 'start'
+ * })
+ * class MyWorkflow {
+ *   @NodeAs({ nodeId: 'start' })
+ *   async start() { }
+ * }
+ * ```
+ */
+export declare function Workflow(options: WorkflowOptions): ClassDecorator;
+/**
+ * 获取类上的 Workflow 元数据
+ */
+export declare function getWorkflowMetadata(target: Function): WorkflowMetadata | undefined;

package/dist/env/workflow/engine/dag-manager.d.ts

@@ -0,0 +1,176 @@
+import type { WorkflowDefinition, NodeDefinition, WorkflowDefinitionExtended, LoopGuardConfig } from '../types';
+import type { EdgeDefinition } from '../types/edge';
+/**
+ * DAG Analysis Result
+ */
+export interface DAGAnalysis {
+    /** 入口节点（无依赖） */
+    entryNodes: string[];
+    /** 出口节点（无下游） */
+    exitNodes: string[];
+    /** 按层级组织的节点，用于并行执行 */
+    levels: string[][];
+    /** 每个节点的依赖 */
+    dependencies: Map<string, string[]>;
+    /** 每个节点的下游 */
+    dependents: Map<string, string[]>;
+    /** 关键路径 */
+    criticalPath: string[];
+}
+/**
+ * DAG Manager
+ *
+ * Manages Directed Acyclic Graph (DAG) operations for workflow execution.
+ * Provides analysis, topological sorting, and validation of workflow structures.
+ *
+ * Supports two modes:
+ * - DAG mode (default): enforces acyclic graph, throws on cycles
+ * - Loop mode (allowCycles=true): allows cycles for workflow loops
+ */
+export declare class DAGManager {
+    private workflow;
+    private nodeMap;
+    private extendedDefinition;
+    private cachedAnalysis;
+    /** Allow cycles in the workflow (for loop/cycle support) */
+    private allowCycles;
+    /**
+     * @param workflow - The workflow definition
+     * @param options - Options
+     * @param options.allowCycles - If true, allows cycles in the workflow (for loop support)
+     */
+    constructor(workflow: WorkflowDefinition, options?: {
+        allowCycles?: boolean;
+    });
+    /**
+     * Get extended workflow definition with computed properties
+     */
+    getExtendedDefinition(): WorkflowDefinitionExtended;
+    /**
+     * Analyze the DAG structure
+     */
+    analyze(): DAGAnalysis;
+    /**
+     * Build a map of node dependencies
+     */
+    private buildDependenciesMap;
+    /**
+     * Check if 'target' is reachable from 'source' by following existing dependencies (BFS).
+     */
+    private isReachable;
+    /**
+     * Build a map of node dependents (reverse of dependencies)
+     */
+    private buildDependentsMap;
+    /**
+     * Find entry nodes (nodes with no dependencies)
+     */
+    private findEntryNodes;
+    /**
+     * Find exit nodes (nodes with no dependents)
+     */
+    private findExitNodes;
+    /**
+     * Compute levels for parallel execution
+     * Nodes at the same level can be executed in parallel
+     */
+    private computeLevels;
+    /**
+     * Find critical path (longest path through the DAG)
+     */
+    private findCriticalPath;
+    /**
+     * Get topological order using Kahn's algorithm
+     */
+    getTopologicalOrder(): string[];
+    /**
+     * Get nodes that are ready to execute (dependencies met and not completed)
+     */
+    getReadyNodes(completedNodes: Set<string>): string[];
+    /**
+     * Check if all dependencies for a node are completed
+     * Uses the computed dependency map (which includes edges-derived dependencies)
+     */
+    areDependenciesMet(nodeId: string, completedNodes: Set<string>): boolean;
+    /**
+     * Check if the workflow contains a cycle
+     */
+    isCyclic(): boolean;
+    /**
+     * Internal topological sort that detects cycles
+     */
+    private getTopologicalOrderInternal;
+    /**
+     * Validate the workflow
+     * @param options - Validation options
+     * @param options.skipCycleCheck - Skip cycle detection (used when allowCycles is enabled)
+     */
+    validate(options?: {
+        skipCycleCheck?: boolean;
+    }): {
+        valid: boolean;
+        errors: string[];
+    };
+    /**
+     * Add a new node to the workflow dynamically
+     *
+     * @param node - The node definition to add
+     * @throws Error if a node with the same ID already exists
+     * @throws Error if the node depends on a non-existent node
+     * @throws Error if adding this node would create a cycle
+     */
+    addNode(node: NodeDefinition): void;
+    /**
+     * Remove a node from the workflow dynamically
+     *
+     * @param nodeId - The ID of the node to remove
+     * @throws Error if the node doesn't exist
+     * @throws Error if other nodes depend on this node
+     */
+    removeNode(nodeId: string): void;
+    /**
+     * Get direct dependents of a node (nodes that depend on this node)
+     */
+    getDependents(nodeId: string): string[];
+    /**
+     * Get downstream nodes on paths from `fromNodeId` toward `untilNodeId` (inclusive).
+     * Used to cascade-reset completed nodes when a back-edge re-enters `fromNodeId`.
+     */
+    getDownstreamUntil(fromNodeId: string, untilNodeId: string): string[];
+    /**
+     * Get the workflow definition (current state)
+     */
+    getDefinition(): WorkflowDefinition;
+    /**
+     * Get a node by ID
+     */
+    getNode(nodeId: string): NodeDefinition | undefined;
+    /**
+     * Get the loop_guard config block for a node, or undefined if the node
+     * has none. The returned object is the normalized LoopGuardConfig
+     * (defaults already applied) that the engine can consume directly.
+     *
+     * Task #2283 — engine-side back-edge progress guard.
+     *
+     * Defensive contract: if `config.loop_guard` is missing, malformed, or
+     * fails LoopGuardConfigSchema.safeParse, this method returns undefined
+     * rather than throwing. Callers can therefore use a simple `if (guard)`
+     * check to opt into the guard logic without try/catch.
+     */
+    getLoopGuard(nodeId: string): LoopGuardConfig | undefined;
+    /**
+     * Get all node IDs
+     */
+    getNodeIds(): string[];
+    /**
+     * Get the number of nodes in the workflow
+     */
+    getNodeCount(): number;
+    /**
+     * Build explicit edges from nodes with inline condition
+     * Also derives implicit edges from depends_on if not already defined
+     * @param explicitEdges - Array of explicit edge definitions from workflow
+     * @returns Combined array of explicit and derived edges
+     */
+    buildEdges(explicitEdges?: EdgeDefinition[]): EdgeDefinition[];
+}