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

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

@@ -0,0 +1,375 @@
+/**
+ * @fileoverview WorkflowEngine - Session-based workflow execution engine
+ *
+ * 统一的 run() 方法同时支持：
+ * - 初次运行：session 不存在 → 创建 session，从 entry node 开始
+ * - 中断恢复：session 存在 + 有消息 → 从消息推断下一个节点继续执行
+ *
+ * Session 通过 workflow.node.* 消息记录节点执行状态
+ *
+ * @version v3.0 (移除 resume() 方法，统一使用 run())
+ */
+import { EventEmitter } from 'events';
+import type { WorkflowDefinition, Workflow, RunOptions, RunResult, RunStatus } from '../types/index';
+import { NodeRegistry } from './node-registry';
+import type { SessionComponent } from '../../session/session-component';
+/**
+ * Agent Session Recovery Info
+ */
+export interface AgentSessionRecoveryInfo {
+    nodeId: string;
+    agentSessionId: string;
+}
+/**
+ * Options for creating WorkflowEngine via static factory
+ */
+export interface WorkflowEngineCreateOptions {
+    env?: {
+        getComponent<T>(name: string): T | undefined;
+    };
+    toolRegistry?: any;
+    skillRegistry?: any;
+    workflowRunner?: any;
+    sessionComponent?: SessionComponent;
+    /** Repository for loading workflow definitions during resume */
+    workflowRepository?: WorkflowRepository;
+}
+/**
+ * Workflow Repository interface (abstraction)
+ */
+export interface WorkflowRepository {
+    getById(id: string): Workflow | null;
+    getByName(name: string): Workflow | null;
+}
+/**
+ * WorkflowEngine Configuration
+ */
+export interface WorkflowEngineConfig {
+    parallelLimit: number | null;
+    timeout: number | null;
+    debug: boolean;
+    /** Strict mode: fail on unresolved templates instead of warning */
+    strict: boolean;
+    /** Maximum iterations to prevent infinite loops (default: 100) */
+    maxIterations: number;
+    /** Global workflow input for condition evaluation (P0-3 fix) */
+    workflowInput?: Record<string, unknown>;
+    /** Enable loop mode to allow re-entry of completed nodes (P0-1 fix) */
+    loopEnabled?: boolean;
+    /**
+     * Per-node runtime overrides.
+     *
+     * Task #1974 — Workflow Node-Level Config + Resume + Stop. Set by
+     * `engine.initializeSessionState` from `RunOptions.nodeConfig`. Used
+     * by `buildNodeContext` to shallow-merge into each node's effective
+     * config (input wins over nodeDef.config).
+     *
+     * Always present (defaults to `{}`); engine treats `undefined` and
+     * `{}` identically.
+     */
+    nodeConfig?: Record<string, Record<string, unknown>>;
+}
+/**
+ * WorkflowEngine
+ *
+ * Session-based workflow execution engine.
+ * Uses Session to manage workflow run state and node execution history.
+ */
+export declare class WorkflowEngine extends EventEmitter {
+    /** 活跃的 session 状态，key 为 sessionId */
+    private activeSessions;
+    /** Session ID 计数器 */
+    private sessionIdCounter;
+    /** Session component */
+    private sessionComponent?;
+    /** Node registry */
+    private nodeRegistry;
+    /** Workflow repository for loading definitions during resume */
+    private workflowRepository?;
+    /**
+     * Create a new WorkflowEngine
+     */
+    constructor(nodeRegistry: NodeRegistry, sessionComponent?: SessionComponent, workflowRepository?: WorkflowRepository);
+    /**
+     * Create a WorkflowEngine with automatic AgentComponent integration
+     */
+    static create(options: WorkflowEngineCreateOptions): Promise<WorkflowEngine>;
+    /**
+     * Generate a unique run ID
+     */
+    private generateRunId;
+    /**
+     * Get session ID for a run.
+     *
+     * Task #1837: now an identity function — runId already has the
+     * `workflow_` prefix, so sessionId equals runId exactly. The legacy
+     * `\`workflow_${runId}\`` mapping is collapsed.
+     *
+     * Kept as a public method for backward compatibility with external
+     * callers that may still derive sessionId from runId.
+     */
+    getSessionId(runId: string): string;
+    /**
+     * Extract runId from sessionId.
+     *
+     * Task #1837: sessionId IS the runId (no prefix to strip). Returns the
+     * input verbatim. Existing callers (event emission, pause/stop) still
+     * work because they don't care about the prefix format — they just
+     * need a unique identifier for the workflow run.
+     */
+    private getRunIdFromSessionId;
+    /**
+     * Create a new workflow session
+     *
+     * @param workflow - Workflow definition or entity
+     * @param options - Optional configuration
+     * @returns Promise resolving to sessionId (format: workflow_{runId})
+     */
+    createSession(workflow: Workflow | WorkflowDefinition, options?: RunOptions): Promise<string>;
+    /**
+     * Run a workflow by sessionId (unified entry point)
+     *
+     * This method supports both:
+     * 1. First run: session doesn't exist → create session, start from entry node
+     * 2. Resume: session exists with messages → infer next node from messages
+     *
+     * @param sessionId - Session ID (format: workflow_{runId} or any string)
+     * @param options - Optional configuration
+     * @returns Promise resolving to RunResult
+     */
+    run(sessionId: string, options?: RunOptions & {
+        workflowId?: string;
+    }): Promise<RunResult>;
+    /**
+     * Initialize session state
+     */
+    private initializeSessionState;
+    /**
+     * Run with resume point
+     *
+     * Simplified logic:
+     * - input is passed directly to execution (string or object)
+     * - For resume with ask_user, the input should contain userQuery
+     * - agentSessionId comes from session messages via resumePoint
+     */
+    private runWithResume;
+    /**
+     * Convenience method to run a workflow directly
+     */
+    runWorkflow(workflow: Workflow | WorkflowDefinition, options?: RunOptions): Promise<RunResult>;
+    /**
+     * Pause a running workflow
+     */
+    pause(sessionId: string): Promise<void>;
+    /**
+     * Stop a running or paused workflow.
+     *
+     * Task #2275: now structured through `RuntimeCancellationScope` so that:
+     *   - The session's `completedPromise` is resolved with `{status:'stopped'}`
+     *     once tracked cleanup settles, NOT just metadata update.
+     *   - `force=true` escalates to the scope's force level and fires any
+     *     registered force handlers (e.g. process kill paths).
+     *   - Cooperative runners listening to the scope signal will abort.
+     *   - The legacy `abortController` is also aborted for backward compat.
+     *
+     * The function is idempotent — calling it twice (or stop+stop(force))
+     * coalesces into a single transition.
+     */
+    stop(sessionId: string, reason?: string, options?: {
+        force?: boolean;
+    }): Promise<void>;
+    /**
+     * Get session status
+     */
+    getSessionStatus(sessionId: string): RunStatus | null;
+    /**
+     * Task #2275 — propagate a workflow stop to each actual child agent
+     * session record. The previous engine.stop only updated the workflow
+     * session's `agentSessions[]` references, leaving child session
+     * metadata.status stale (a gap visible in `sessions list --graph`
+     * where the user saw `agent_plan_*` and `agent_init-task_*` still
+     * listed without a stopped status after the workflow was stopped).
+     *
+     * Behavior:
+     *   - Iterates ALL sessions whose parentSessionId matches this
+     *     workflow session (not just refs in metadata.agentSessions, so
+     *     children created in the brief window between schedule and stop
+     *     are also caught).
+     *   - For each child session:
+     *     - Skip if status is already terminal (completed/failed/stopped)
+     *     - Update metadata.status = "stopped", append stop reason
+     *   - Errors are isolated per child — one failure does not block siblings
+     *   - No-op when sessionComponent is missing or workflow has no children
+     *
+     * Idempotency: a second invocation only touches children that are
+     * still non-terminal, so double-stop is safe.
+     */
+    private propagateStopToChildSessions;
+    /**
+     * Check if session is active
+     */
+    isSessionActive(sessionId: string): boolean;
+    /**
+     * Setup event handlers for a run
+     */
+    private setupEventHandlers;
+    /**
+     * Main scheduling loop
+     */
+    private scheduleAndExecute;
+    /**
+     * Wait for next node event
+     *
+     * Optimization: When there are running nodes, use pure event-driven waiting
+     * (no polling). When there are only pending nodes (dependencies not yet met),
+     * use a small timeout to re-check scheduling conditions.
+     */
+    private waitForNextNodeEvent;
+    /**
+     * Start execution of a single node
+     */
+    private startNode;
+    /**
+     * Write workflow.node.start message
+     */
+    private writeNodeStart;
+    /**
+     * Resume execution of a paused node
+     *
+     * Simplified logic:
+     * - Load agent session from agentSessionId
+     * - Pass userQuery from input to agentNode
+     * - No complex userResponse distinction
+     */
+    private resumeNode;
+    /**
+     * Pre-execute validation
+     * Validates node configuration before execution
+     * Checks for unresolved templates and throws in strict mode
+     */
+    private preExecuteValidation;
+    /**
+     * Validate node configuration and execute it
+     * Common method used by both startNode and resumeNode
+     */
+    private validateAndExecute;
+    /**
+     * Loop-guard check for a single back-edge re-entry.
+     *
+     * Task #2283 — engine-side progress guard. Reads the node's
+     * `config.loop_guard` and decides whether the upcoming re-entry would
+     * be a no-progress attempt. If the no-progress counter reaches
+     * `max_consecutive_no_progress`, the function returns
+     * `{ trip: true, failMessage }` so the caller can short-circuit the
+     * agent and inject a fail output.
+     *
+     * Behavior matrix for the `value_unchanged` type:
+     *   - previous_value === current_value (after JSON.stringify)
+     *       → increment counter; if >= maxAllowed → trip; else allow
+     *   - previous_value !== current_value
+     *       → reset counter to 0; allow
+     *   - previous_value is undefined (first run for this node)
+     *       → first re-entry: count this as a "change" (we don't know the
+     *         prior state); allow
+     *   - current_signal_command fails to execute
+     *       → allow (defensive: don't false-positive on transient shell errors)
+     *
+     * The counter is persisted in `sessionState.loopGuardCounters`
+     * (Task #2286 fix — dedicated map, independent of `nodeOutputs`).
+     *
+     * Earlier versions stored the counter under the well-known key
+     * `_loop_guard_consecutive_<nodeId>` directly on the node's prior
+     * output map. That broke once `max_consecutive_no_progress >= 2`,
+     * because the next agent run overwrote the whole output via
+     * `sessionState.nodeOutputs.set(nodeId, result.output)`, clobbering
+     * the counter on every back-edge. The dedicated map survives agent
+     * output writes because nothing else mutates it.
+     *
+     * The caller MUST pass a `templateResolver` whose previousOutputs
+     * already include the pre-cascade-reset snapshot for `reEntryId`.
+     * The post-reset state would otherwise resolve `{{nodes.<reEntryId>.*}}`
+     * to undefined.
+     */
+    private checkLoopGuardWithSnapshot;
+    /**
+     * Evaluate conditional edges after a node completes and start matching targets.
+     *
+     * IMPORTANT: For conditional edge workflows to work correctly:
+     * 1. All non-entry nodes MUST specify depends_on for their expected upstream node(s)
+     * 2. edges.when acts as a gate AFTER depends_on is satisfied
+     * 3. If depends_on is empty, the node will be scheduled at start regardless of edges
+     */
+    private processConditionalEdgesAfterCompletion;
+    /**
+     * Build node execution context (renamed from createExecutionContext)
+     *
+     * @param sessionState - Active session state
+     * @param nodeId - Node ID to create context for
+     * @param globalInput - Global workflow input
+     */
+    /**
+     * 安全取 DAG 节点总数（供 hook payload 用）。
+     *
+     * ★ 2026-10-16 独立 review P0：hook payload 的构造**绝不能**让 engine 抛错。
+     *   原实现直接写 `sessionState.dagManager.getNodeCount()`，而 legacy 测试 fixture
+     *   会直接 cast 构造 ActiveSessionState（可能没有 dagManager）→
+     *   `TypeError: undefined is not an object`。
+     *
+     *   致命点：该异常发生在 **HookManager 之前**（还在构造 payload），所以
+     *   "hook 抛错由 safeExecute 隔离"这条保护**完全救不了** —— 异常是 engine 自己
+     *   抛的，会连带吞掉 `resolveCompleted` / agentSessions 传播 / 原始 error。
+     *   实测它打红了 7 条既有测试
+     *   （engine-fail-agentsessions ×4、engine-node-completed-agentsessions ×3）。
+     *
+     *   兜底返回 undefined：hook 消费方（如通知插件）本就把 totalNodes 当可选。
+     */
+    private safeNodeCount;
+    private buildNodeContext;
+    /**
+     * Check if workflow is complete and finalize
+     */
+    private checkAndFinalize;
+    /**
+     * Complete a workflow successfully.
+     *
+     * === RunResult Output Behavior ===
+     *
+     * 1. ALL node outputs (intermediate + exit) are included in the final
+     *    RunResult.output as { nodeId: output, ... }. The shape stays
+     *    consistent regardless of how many nodes or exit points a
+     *    workflow has.
+     *
+     * 2. The same all-node-outputs map is also stored in session metadata
+     *    for debugging/reference.
+     *
+     * 3. Intermediate node outputs are additionally recorded in session
+     *    messages via workflow.node.end messages written by
+     *    executor.writeNodeEnd().
+     *
+     * 4. Consumers can always access a node's output via
+     *    result.output[nodeId], including agents that need to chain state
+     *    across pause/resume cycles (see agent-resume-history.test.ts,
+     *    dual-agent-resume-userquery.test.ts).
+     */
+    private completeWorkflow;
+    /**
+     * Fail a workflow
+     */
+    private failWorkflow;
+    /**
+     * Cleanup session resources
+     */
+    private cleanupSession;
+    /**
+     * Wait for a run to complete
+     */
+    private waitForCompletion;
+    /**
+     * Get session metadata
+     */
+    private getSessionMetadata;
+    /**
+     * Find workflow definition from repository
+     */
+    private findDefinitionForWorkflow;
+}

package/dist/env/workflow/engine/event-bus.d.ts

@@ -0,0 +1,54 @@
+import type { WorkflowEvent } from '../types/event';
+export type EventHandler = (event: WorkflowEvent) => void | Promise<void>;
+/**
+ * EventBus for workflow events.
+ * Custom event bus implementation with support for wildcard subscriptions.
+ */
+export declare class EventBus {
+    private handlers;
+    private wildcardHandlers;
+    constructor();
+    /**
+     * Subscribe to a specific event type.
+     * @returns Unsubscribe function
+     */
+    on(eventType: string, handler: EventHandler): () => void;
+    /**
+     * Subscribe to an event type only once (auto-unsubscribe after first call).
+     * @returns Unsubscribe function
+     */
+    once(eventType: string, handler: EventHandler): () => void;
+    /**
+     * Unsubscribe from an event type.
+     */
+    off(eventType: string, handler: EventHandler): void;
+    /**
+     * Subscribe to all events (wildcard subscription).
+     * @returns Unsubscribe function
+     */
+    onAny(handler: EventHandler): () => void;
+    /**
+     * Publish an event to all subscribers.
+     * Handler errors are caught and do not crash the bus.
+     *
+     * @param event - The event to publish
+     * @param waitForHandlers - If true, waits for all async handlers to complete (default: false)
+     */
+    publish(event: WorkflowEvent, waitForHandlers?: boolean): Promise<void>;
+    /**
+     * Execute a handler safely, catching any errors.
+     */
+    private executeHandler;
+    /**
+     * Clear all subscriptions.
+     */
+    clear(): void;
+    /**
+     * Get statistics about the event bus.
+     */
+    getStats(): {
+        eventTypes: number;
+        wildcardHandlers: number;
+        totalHandlers: number;
+    };
+}

package/dist/env/workflow/engine/executor.d.ts

@@ -0,0 +1,122 @@
+/**
+ * @fileoverview Executor - Executes nodes in a workflow
+ *
+ * The Executor is responsible for:
+ * - Executing individual nodes
+ * - Handling retries
+ * - Managing timeouts
+ * - Tracking execution state
+ */
+import type { NodeDefinition, RetryConfig, NodeExecutionContext, NodeExecutionResult } from '../types/index';
+import { EventBus } from './event-bus';
+import { NodeRegistry } from './node-registry';
+import type { SessionComponent } from '../../session/session-component';
+/**
+ * Executor Options
+ */
+export interface ExecutorOptions {
+    /** Global timeout for node execution (ms). null = no timeout */
+    globalTimeout: number | null;
+    /** Global retry configuration */
+    globalRetry: RetryConfig | null;
+    /** Debug mode */
+    debug: boolean;
+}
+/**
+ * Executor
+ *
+ * Executes nodes in a workflow with support for:
+ * - Timeout handling
+ * - Retry with configurable backoff
+ * - Error propagation
+ * - Session message writing
+ * - AskUserError handling
+ *
+ * @example
+ * ```typescript
+ * const executor = new Executor(nodeRegistry, eventBus, {
+ *   globalTimeout: 60000,
+ *   globalRetry: { max_attempts: 3, backoff: 'exponential', initial_delay: 1000 },
+ *   debug: false
+ * });
+ *
+ * const result = await executor.executeNode(nodeDefinition, context);
+ * ```
+ */
+export declare class Executor {
+    private nodeRegistry;
+    private eventBus;
+    private options;
+    private sessionComponent?;
+    private abortControllers;
+    constructor(nodeRegistry: NodeRegistry, eventBus: EventBus, options: ExecutorOptions, sessionComponent?: SessionComponent | undefined);
+    /**
+     * Execute a node with timeout and retry handling
+     */
+    executeNode(definition: NodeDefinition, context: NodeExecutionContext): Promise<NodeExecutionResult>;
+    /**
+     * Execute node with timeout handling
+     *
+     * Task #1976: when the timeout fires, also abort the controller so the
+     * node has a chance to react via its AbortSignal — instead of being
+     * silently orphaned (the bug this method was leaking).
+     */
+    private executeWithTimeout;
+    /**
+     * Execute node with retry handling
+     */
+    private executeWithRetry;
+    /**
+     * Cancel execution of a specific node
+     */
+    cancelNode(nodeId: string): void;
+    /**
+     * Cancel all running nodes
+     */
+    cancelAll(): void;
+    /**
+     * Combine two abort signals.
+     *
+     * Task #2291 P0-1 / P1-3:
+     *   Replaced the addEventListener-based composition with `AbortSignal.any`
+     *   which (a) preserves the abort reason from the firing input and
+     *   (b) aborts synchronously when any input is already aborted.
+     */
+    private combineAbortSignals;
+    /**
+     * Sleep for specified milliseconds, with optional signal-aware abort
+     * (Task #2275). When `signal` is provided, the returned Promise rejects
+     * with `signal.reason` if the signal aborts before the timer fires,
+     * and the underlying setTimeout is cleared (no leftover timer).
+     */
+    private sleep;
+    /**
+     * Write workflow.node.start message
+     * 对应 tool-call，节点开始执行
+     */
+    writeNodeStart(sessionId: string, nodeId: string, nodeType: string, input: unknown, agentSessionId?: string): Promise<void>;
+    /**
+     * Patch agentSessionId onto the latest workflow.node.start for a node (P1).
+     */
+    attachAgentSessionToLastStart(sessionId: string, nodeId: string, agentSessionId: string): Promise<void>;
+    /**
+     * Create a meaningful content summary for call message
+     */
+    private summarizeCall;
+    /**
+     * Write workflow.node.interrupt message
+     */
+    writeNodeInterrupt(sessionId: string, nodeId: string, nodeType: string, query: string, agentSessionId?: string): Promise<void>;
+    /**
+     * Write workflow.node.end message (对应 tool-result)
+     */
+    writeNodeEnd(sessionId: string, nodeId: string, nodeType: string, output: unknown, error: string | undefined, durationMs: number, agentSessionId?: string): Promise<void>;
+    /**
+     * Create a meaningful content summary for result display
+     */
+    private summarizeResult;
+    /**
+     * Write workflow.node.resume message
+     */
+    writeNodeResume(sessionId: string, nodeId: string, nodeType: string, response: string, agentSessionId?: string): Promise<void>;
+}

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

@@ -0,0 +1,15 @@
+/**
+ * @fileoverview Engine exports
+ */
+export type { NodeExecutionContext, RunOptions, RunResult, RunStatus, NodeStatus, } from '../types/index';
+export { EventBus } from './event-bus';
+export { DAGManager } from './dag-manager';
+export type { DAGAnalysis } from './dag-manager';
+export { Scheduler } from './scheduler';
+export type { SchedulerOptions, SchedulerState } from './scheduler';
+export { Executor } from './executor';
+export type { ExecutorOptions } from './executor';
+export { WorkflowEngine } from './engine';
+export type { WorkflowEngineConfig, WorkflowEngineCreateOptions, WorkflowRepository } from './engine';
+export { NodeRegistry } from './node-registry';
+export type { NodeContext, NodeFactory } from './node-registry';