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

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

@@ -0,0 +1,16 @@
+export * from './edge';
+export * from './workflow';
+export * from './workflow-message';
+export * from './workflow-session';
+export * from './context';
+export * from './workflow-hil';
+export * from './event';
+export * from './run';
+export type { AgentSessionInfo } from './workflow-message';
+export type { AgentSessionRef } from './workflow-session';
+export type { RunStatus, NodeStatus, WorkflowRun, NodeRun, RunOptions, RunResult, NodeExecutionContext, NodeExecutionResult, } from './run';
+export { createNodeExecutionContext } from './run';
+export type { WorkflowDefinition, WorkflowDefinitionExtended, Workflow, WorkflowConfig, WorkflowMetadata, RetryConfig, Node, NodeDefinition, NodeDefinitionSchema, DependsOn, DependsOnSchema, OutputDefinition, OutputDefinitionSchema, InputParameter, WorkflowInputs, } from './workflow';
+export type { TemplateResolver } from '../utils/template-resolver';
+export { WorkflowError, TemplateUnresolvedError, WorkflowValidationError, nodeNotFound, pathNotFound, unresolvedVariable, } from './workflow-error';
+export type { WorkflowErrorContext } from './workflow-error';

package/dist/env/workflow/types/run.d.ts

@@ -0,0 +1,254 @@
+import { z } from 'zod';
+import type { EventBus } from '../engine/event-bus';
+import type { SessionComponent } from '../../session/session-component';
+import type { TemplateResolver } from '../utils/template-resolver';
+export declare const RunStatusSchema: z.ZodEnum<["idle", "running", "paused", "stopped", "completed", "failed"]>;
+export type RunStatus = z.infer<typeof RunStatusSchema>;
+export declare const NodeStatusSchema: z.ZodEnum<["pending", "scheduled", "started", "running", "completed", "failed", "skipped"]>;
+export type NodeStatus = z.infer<typeof NodeStatusSchema>;
+export interface WorkflowRun {
+    id: string;
+    workflowId: string;
+    workflowName: string;
+    status: RunStatus;
+    input?: Record<string, any>;
+    output?: Record<string, any>;
+    error?: string;
+    startedAt?: Date;
+    pausedAt?: Date;
+    resumedAt?: Date;
+    stoppedAt?: Date;
+    completedAt?: Date;
+    durationMs?: number;
+    debugMode: boolean;
+    parentRunId?: string;
+}
+export interface NodeRun {
+    id: string;
+    runId: string;
+    nodeId: string;
+    nodeType: string;
+    status: NodeStatus;
+    input?: any;
+    output?: any;
+    error?: string;
+    startedAt?: Date;
+    completedAt?: Date;
+    durationMs?: number;
+    retryCount: number;
+}
+export interface RunOptions {
+    input?: Record<string, any>;
+    debug?: boolean;
+    parallelLimit?: number | null;
+    timeout?: number | null;
+    /** Strict mode: fail on unresolved templates instead of warning */
+    strict?: boolean;
+    /** Maximum iterations to prevent infinite loops (default: 100) */
+    maxIterations?: number;
+    /** Enable loop mode to allow re-entry of completed nodes (for workflow cycles) */
+    loopEnabled?: boolean;
+    /** Global workflow input for condition evaluation */
+    workflowInput?: Record<string, unknown>;
+    /**
+     * Caller-reserved runId for a fresh workflow run.
+     *
+     * When set, `WorkflowEngine.createSession` uses this runId (instead of
+     * calling `generateRunId()`), so the caller can pre-allocate a runId
+     * that the tool layer surfaces on every termination path (timeout /
+     * abort / error). Task #1837 already established that runId ===
+     * sessionId, and Task #2106 closes the gap where the `workflow_run`
+     * tool's synthesized fallback runId was shape-compatible but not
+     * queryable / stoppable on the engine.
+     *
+     * Contract:
+     *  - Must start with `workflow_` (Task #1837 prefix requirement)
+     *  - Must be unique across all active workflow sessions
+     *  - On the resume path, callers should pass `sessionId` instead
+     *
+     * Task #2106 — required by `workflow_run` tool's reserved-ID contract.
+     */
+    runId?: string;
+    /**
+     * Parent session id — when set, the workflow run session will be created
+     * with `parentSessionId === parentSessionId`. Used by `workflow_run` tool
+     * and `roy-agent workflow run` CLI to track the parent→workflow session
+     * hierarchy for `sessions list --graph` (Task #1739).
+     */
+    parentSessionId?: string | null;
+    /**
+     * Session id to resume — when set, the engine re-enters an existing
+     * workflow session instead of starting a fresh run. Set by the
+     * `workflow_run` tool's `session` field and `roy-agent workflow run --session`
+     * CLI to power workflow-runner re-entry into paused/interrupted workflows.
+     * (Task #1829)
+     */
+    sessionId?: string;
+    /**
+     * Callback fired immediately after the workflow session is created
+     * (or resolved for resume). The sessionId argument is also the
+     * runId (Task #1837: runId == sessionId).
+     *
+     * Use this to capture the runId/sessionId BEFORE execution, so callers
+     * can still reference it when execution later times out, aborts, or
+     * throws. Without this callback, the tool layer has no way to surface
+     * the runId on failure paths (Task #1840).
+     *
+     * The callback must be safe to call: a throwing callback is caught
+     * and logged, but does NOT abort session creation.
+     */
+    onSessionCreated?: (sessionId: string) => void;
+    /**
+     * Per-node runtime config overrides.
+     *
+     * Keyed by `node.id`. Values are shallow-merged into the node's
+     * `nodeDef.config` at buildNodeContext time. Keys present in BOTH
+     * nodeDef.config and nodeConfig[nodeId] are taken from nodeConfig
+     * (input wins). Unknown node IDs are silently ignored.
+     *
+     * Common use cases:
+     * - `timeout`: per-node execution timeout (ms), overrides engine's
+     *   global timeout. Read by AgentNode and ToolNode.
+     * - `maxIterations`: only honored when loopEnabled=true.
+     * - `model`, `allowedTools`, `deniedTools`: forwarded to AgentNode
+     *   via `options.*`.
+     *
+     * Task #1974 — Workflow Node-Level Config + Resume + Stop.
+     * Backward compatible: when omitted (or empty), engine behavior is
+     * unchanged.
+     */
+    nodeConfig?: Record<string, Record<string, unknown>>;
+}
+export interface RunResult {
+    runId: string;
+    /** Session ID — Task #1837: equals runId exactly (no derivation). */
+    sessionId?: string;
+    status: RunStatus;
+    output?: Record<string, any>;
+    error?: string;
+    durationMs?: number;
+    /** Pending node ID (when status is 'paused') */
+    pendingNodeId?: string;
+    /** Query from ask_user (when status is 'paused') */
+    query?: string;
+    /** Agent sub-session ID (for resuming agent nodes) */
+    agentSessionId?: string;
+}
+/**
+ * 节点执行上下文
+ *
+ * 扩展后包含：
+ * - sessionId: Session ID，用于消息持久化
+ * - askUser(): 方法，让节点可以请求用户输入
+ */
+export interface NodeExecutionContext {
+    runId: string;
+    /** Task #1837: sessionId == runId (runId natively carries workflow_ prefix). */
+    sessionId: string;
+    workflowName: string;
+    nodeId: string;
+    input: unknown;
+    previousOutputs: Map<string, unknown>;
+    nodeOutputs: Map<string, unknown>;
+    config: Record<string, unknown>;
+    debug: boolean;
+    eventBus: EventBus;
+    workflowHistory?: Array<{
+        role: 'user' | 'assistant' | 'tool';
+        content: string;
+        toolCallId?: string;
+        toolName?: string;
+        nodeId?: string;
+    }>;
+    sessionComponent?: SessionComponent;
+    agentSessionId?: string;
+    workflowInput?: Record<string, unknown>;
+    templateResolver?: TemplateResolver;
+    /**
+     * Pre-resolved node configuration
+     *
+     * This is the node's config with all template references resolved
+     * using the TemplateResolver. Nodes should use this instead of the
+     * raw `config` to avoid duplicate template resolution.
+     *
+     * Example: A node with config.prompt = "{{nodes.fetch.result}}" will have
+     * resolvedConfig.prompt = "The weather is sunny" after resolution.
+     */
+    resolvedConfig?: Record<string, unknown>;
+    /**
+     * 请求用户输入
+     *
+     * 调用此方法会抛出 AskUserError，引擎捕获后会暂停 workflow
+     *
+     * @param query - 向用户询问的问题
+     * @throws AskUserError - 总是抛出此异常
+     */
+    askUser(query: string): never;
+    /** Patch agent sub-session id onto latest workflow.node.start (agent nodes) */
+    attachAgentSessionToLastStart?(nodeId: string, agentSessionId: string): Promise<void>;
+    /**
+     * Register (or refresh) an agent sub-session entry in the parent workflow
+     * session's `metadata.agentSessions` (Task #4412 C1).
+     *
+     * AgentNode must use this instead of doing its own
+     * `get → push → update` on the parent metadata. That read-modify-write is
+     * unsafe once dispatch is concurrent: N sibling agent nodes all read the
+     * same parent snapshot and each writes back its own array-with-one-extra
+     * entry, so the last writer wins and every sibling's marker is silently
+     * dropped (measured: 4 concurrent agents → only 2 markers survive).
+     *
+     * The engine implements this by routing the mutation through the same
+     * per-session serialization queue it uses for its own metadata writes, so
+     * the whole class of lost updates is closed by construction.
+     *
+     * Optional for backward compatibility with hand-built contexts in tests;
+     * AgentNode falls back to the legacy inline RMW when it is absent.
+     */
+    registerAgentSubSession?(nodeId: string, agentSessionId: string): Promise<void>;
+    /**
+     * Abort signal for this node's execution (Task #1976).
+     *
+     * Populated by the workflow executor from its per-node `AbortController`.
+     * The signal fires when:
+     *   1. The node's timeout elapses (timeoutPromise rejects the race → executor
+     *      calls `this.cancelNode(nodeId)` which triggers this signal).
+     *   2. The user issues `workflow_run_stop` (engine.stop → executor.cancelAll).
+     *   3. The retry path on inner-attempt timeout (existing behavior preserved).
+     *
+     * Nodes SHOULD pass this signal to any long-running async operation they
+     * own (e.g. AgentRunner.run, LLM calls, network requests) so that timeout
+     * truly cancels the underlying work, not just the engine's wait.
+     *
+     * Optional for backward compat — nodes that don't opt in still work
+     * (their execution will be leaked on timeout, which is the bug this field
+     * is designed to fix).
+     */
+    abortSignal?: AbortSignal;
+}
+export interface NodeExecutionResult {
+    success?: boolean;
+    output?: any;
+    error?: string | Error;
+    duration?: number;
+    durationMs?: number;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * 创建 NodeExecutionContext
+ */
+export declare function createNodeExecutionContext(params: {
+    runId: string;
+    workflowName: string;
+    nodeId: string;
+    input: unknown;
+    previousOutputs: Map<string, unknown>;
+    nodeOutputs: Map<string, unknown>;
+    config: Record<string, unknown>;
+    debug: boolean;
+    eventBus: EventBus;
+    sessionId: string;
+    workflowHistory?: NodeExecutionContext['workflowHistory'];
+    workflowInput?: Record<string, unknown>;
+    templateResolver?: TemplateResolver;
+    resolvedConfig?: Record<string, unknown>;
+}): NodeExecutionContext;

package/dist/env/workflow/types/workflow-error.d.ts

@@ -0,0 +1,79 @@
+/**
+ * @fileoverview Workflow Error Types
+ *
+ * Defines error classes for workflow template resolution and validation.
+ */
+import { z } from 'zod';
+/**
+ * Error context schema for structured error data
+ */
+export declare const WorkflowErrorContextSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+export type WorkflowErrorContext = z.infer<typeof WorkflowErrorContextSchema>;
+/**
+ * Base workflow error class
+ */
+export declare class WorkflowError extends Error {
+    readonly context: WorkflowErrorContext;
+    constructor(message: string, context?: WorkflowErrorContext);
+    /**
+     * Convert error to JSON-serializable object
+     */
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Error thrown when template resolution fails due to unresolved templates.
+ *
+ * This error captures the list of unresolved template strings for debugging
+ * and potential user feedback.
+ */
+export declare class TemplateUnresolvedError extends WorkflowError {
+    /**
+     * List of template strings that could not be resolved
+     */
+    readonly unresolved: string[];
+    constructor(message: string, unresolved?: string[], context?: WorkflowErrorContext);
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Error thrown when workflow definition validation fails.
+ *
+ * This includes validation of node configurations, input schemas,
+ * output definitions, and edge connections.
+ */
+export declare class WorkflowValidationError extends WorkflowError {
+    /**
+     * The field or path that failed validation
+     */
+    readonly field: string;
+    /**
+     * The invalid value that was provided
+     */
+    readonly invalidValue: unknown;
+    constructor(message: string, field: string, invalidValue?: unknown);
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Create a TemplateUnresolvedError for when a referenced node is not found.
+ *
+ * @param referencedNodeId - The referenced node ID that was not found
+ * @param unresolved - List of template strings referencing the node
+ * @returns TemplateUnresolvedError instance
+ */
+export declare function nodeNotFound(referencedNodeId: string, unresolved: string[]): TemplateUnresolvedError;
+/**
+ * Create a TemplateUnresolvedError for when a path within a node's output is not found.
+ *
+ * @param referencedNodeId - The referenced node ID
+ * @param path - The path that was not found
+ * @param template - The template string that referenced this path
+ * @returns TemplateUnresolvedError instance
+ */
+export declare function pathNotFound(referencedNodeId: string, path: string, template: string): TemplateUnresolvedError;
+/**
+ * Create a TemplateUnresolvedError for an unresolved variable reference.
+ *
+ * @param template - The unresolved template string
+ * @param path - The path that could not be resolved
+ * @returns TemplateUnresolvedError instance
+ */
+export declare function unresolvedVariable(template: string, path?: string): TemplateUnresolvedError;

package/dist/env/workflow/types/workflow-hil.d.ts

@@ -0,0 +1,57 @@
+/**
+ * @fileoverview Human-in-Loop (HIL) types for workflow
+ *
+ * This module contains types and utilities for human-in-loop functionality:
+ * - NodeInterruptEvent: Event when a node needs human input
+ * - WorkflowAskUserEvent: Event when the workflow needs human confirmation
+ * - AskUserError: Error thrown when a node requests user input
+ */
+import type { BaseEvent } from './event';
+/**
+ * Node 中断事件 - 节点等待用户输入
+ */
+export interface NodeInterruptEvent extends BaseEvent {
+    type: 'node.interrupt';
+    node_id: string;
+    node_type: string;
+    query: string;
+    /** Agent sub-session ID (for agent nodes that need resume) */
+    agent_session_id?: string;
+}
+/**
+ * Workflow Ask User 事件 - Workflow 等待用户输入
+ */
+export interface WorkflowAskUserEvent extends BaseEvent {
+    type: 'workflow.ask-user';
+    session_id: string;
+    node_id: string;
+    node_type: string;
+    query: string;
+}
+/**
+ * 创建 NodeInterruptEvent
+ */
+export declare function createNodeInterruptEvent(runId: string, nodeId: string, nodeType: string, query: string, agentSessionId?: string): NodeInterruptEvent;
+/**
+ * 创建 WorkflowAskUserEvent
+ */
+export declare function createWorkflowAskUserEvent(runId: string, sessionId: string, nodeId: string, nodeType: string, query: string): WorkflowAskUserEvent;
+/**
+ * AskUserError - 当节点调用 askUser() 时抛出
+ */
+export declare class AskUserError extends Error {
+    readonly runId: string;
+    readonly sessionId: string;
+    readonly nodeId: string;
+    readonly nodeType: string;
+    readonly query: string;
+    readonly agentSessionId?: string | undefined;
+    readonly timestamp: number;
+    readonly type = "ask-user";
+    readonly name = "AskUserError";
+    constructor(runId: string, sessionId: string, nodeId: string, nodeType: string, query: string, agentSessionId?: string | undefined, timestamp?: number);
+    /**
+     * 转换为 WorkflowAskUserEvent
+     */
+    toEvent(): WorkflowAskUserEvent;
+}

package/dist/env/workflow/types/workflow-message.d.ts

@@ -0,0 +1,193 @@
+import { z } from 'zod';
+/**
+ * Workflow 节点执行消息角色类型
+ *
+ * 设计原则：
+ * - workflow.node.start: 对应 tool-call，节点开始执行
+ * - workflow.node.interrupt: 节点中断等待用户输入
+ * - workflow.node.end: 对应 tool-result，节点执行结束
+ * - workflow.node.resume: 用户响应后恢复节点执行
+ */
+export declare const WorkflowMessageRoleSchema: z.ZodEnum<["workflow.node.start", "workflow.node.interrupt", "workflow.node.end", "workflow.node.resume"]>;
+export type WorkflowMessageRole = z.infer<typeof WorkflowMessageRoleSchema>;
+/**
+ * workflow.node.start 消息 part
+ * 对应 tool-call，节点开始执行
+ */
+export interface WorkflowNodeStartPart {
+    type: 'workflow-node-start';
+    nodeId: string;
+    nodeType: string;
+    input?: unknown;
+    startTime: number;
+    /** Agent session ID (only for agent nodes) */
+    agentSessionId?: string;
+}
+/**
+ * workflow.node.interrupt 消息 part
+ * 节点中断等待用户输入
+ */
+export interface WorkflowNodeInterruptPart {
+    type: 'workflow-node-interrupt';
+    nodeId: string;
+    nodeType: string;
+    query: string;
+    timestamp: number;
+    /** Agent session ID (only for agent nodes) - 用于恢复 agent 子会话 */
+    agentSessionId?: string;
+}
+/**
+ * workflow.node.end 消息 part
+ * 对应 tool-result，节点执行结束
+ */
+export interface WorkflowNodeEndPart {
+    type: 'workflow-node-end';
+    nodeId: string;
+    nodeType: string;
+    output?: unknown;
+    error?: string;
+    durationMs: number;
+    /** Agent session ID (only for agent nodes) */
+    agentSessionId?: string;
+}
+/**
+ * workflow.node.resume 消息 part
+ * 用户响应后恢复节点执行
+ */
+export interface WorkflowNodeResumePart {
+    type: 'workflow-node-resume';
+    nodeId: string;
+    response: string;
+    timestamp: number;
+    /** Agent session ID (only for agent nodes) */
+    agentSessionId?: string;
+}
+/**
+ * workflow 消息 part 联合类型
+ */
+export type WorkflowMessagePart = WorkflowNodeStartPart | WorkflowNodeInterruptPart | WorkflowNodeEndPart | WorkflowNodeResumePart;
+/**
+ * Workflow Session 元数据（简化版）
+ *
+ * 简化原则：只保留必要字段，其他信息从 messages 推断
+ *
+ * 设计原则（Task #1837）：
+ * - sessionId 直接作为 runId 使用（runId 天然带 workflow_ 前缀）
+ * - Session.metadata.status 跟踪运行状态
+ * - Session.messages 按时间顺序记录节点执行状态
+ * - Next node 从 messages 推断（最后一条消息决定恢复点）
+ */
+export interface WorkflowSessionMetadata {
+    type: 'workflow';
+    /** Used to load workflow definition */
+    workflowId: string;
+    /** Display name */
+    workflowName: string;
+    /** Workflow 版本 (可选) */
+    workflowVersion?: string;
+    /** Execution status */
+    status: 'running' | 'paused' | 'completed' | 'failed' | 'stopped';
+    /** Run id — Task #1837: equals sessionId exactly. Kept for backward compat with older session records. */
+    runId?: string;
+    /** Workflow input (fresh + resume merged) */
+    input?: unknown;
+    /** Timestamps and lifecycle */
+    startedAt?: number;
+    completedAt?: number;
+    failedAt?: number;
+    durationMs?: number;
+    /** Final workflow output summary */
+    output?: Record<string, unknown>;
+    /** Pause/resume hints */
+    pendingNodeId?: string;
+    pauseReason?: 'ask_user' | string;
+    /** Agent sub-session refs */
+    agentSessions?: AgentSessionRef[];
+    /** Allow additional properties for metadata extension */
+    [key: string]: unknown;
+}
+/**
+ * Agent Session 引用（存储在 workflow session metadata 中）
+ */
+export interface AgentSessionRef {
+    nodeId: string;
+    sessionId: string;
+    /**
+     * Agent session 状态
+     * - 'active': 节点正在执行
+     * - 'paused': 节点因 ask_user 中断暂停（可恢复）
+     * - 'completed': 节点成功完成
+     * - 'failed': 节点执行失败
+     * - 'stopped': 节点因 workflow.stop() 强制终止
+     */
+    status: 'active' | 'paused' | 'completed' | 'failed' | 'stopped';
+    createdAt?: number;
+}
+/**
+ * workflow.node.start 消息元数据
+ * 对应 tool-call
+ */
+export interface WorkflowNodeStartMetadata {
+    type: 'workflow.node.start';
+    /** Canonical node id (alias of workflowNodeId) */
+    nodeId: string;
+    workflowNodeId: string;
+    workflowNodeType: string;
+    /** Agent session ID (only for agent nodes) */
+    agentSessionId?: string;
+}
+/**
+ * workflow.node.interrupt 消息元数据
+ */
+export interface WorkflowNodeInterruptMetadata {
+    type: 'workflow.node.interrupt';
+    nodeId: string;
+    workflowNodeId: string;
+    workflowNodeType: string;
+    query: string;
+    /** Agent session ID (only for agent nodes) */
+    agentSessionId?: string;
+    timestamp?: number;
+}
+/**
+ * workflow.node.end 消息元数据
+ * 对应 tool-result
+ */
+export interface WorkflowNodeEndMetadata {
+    type: 'workflow.node.end';
+    nodeId: string;
+    workflowNodeId: string;
+    workflowNodeType: string;
+    success: boolean;
+    agentSessionId?: string;
+}
+/**
+ * workflow.node.resume 消息元数据
+ */
+export interface WorkflowNodeResumeMetadata {
+    type: 'workflow.node.resume';
+    nodeId: string;
+    workflowNodeId: string;
+    workflowNodeType: string;
+    response: string;
+    /** Agent session ID (only for agent nodes) */
+    agentSessionId?: string;
+    timestamp?: number;
+}
+/**
+ * workflow 消息元数据联合类型
+ */
+export type WorkflowMessageMetadata = WorkflowNodeStartMetadata | WorkflowNodeInterruptMetadata | WorkflowNodeEndMetadata | WorkflowNodeResumeMetadata;
+/**
+ * Agent Session 信息（存储在 workflow message metadata 中）
+ */
+export interface AgentSessionInfo {
+    /** Agent session ID */
+    sessionId: string;
+    /** Node ID */
+    nodeId: string;
+    /** 创建时间 */
+    createdAt: number;
+}
+export { AskUserError, createNodeInterruptEvent, createWorkflowAskUserEvent, } from './workflow-hil';
+export type { NodeInterruptEvent, WorkflowAskUserEvent, } from './workflow-hil';

package/dist/env/workflow/types/workflow-session.d.ts

@@ -0,0 +1,17 @@
+import type { WorkflowSessionMetadata } from './workflow-message';
+export type { WorkflowSessionMetadata } from './workflow-message';
+export type { AgentSessionRef } from './workflow-message';
+/**
+ * 检查 SessionMetadata 是否为 Workflow 类型
+ *
+ * 简化验证：只检查必要字段存在性
+ * - type === 'workflow'
+ * - workflowId 存在
+ * - workflowName 存在
+ * - status 存在且为有效值
+ */
+export declare function isWorkflowSessionMetadata(metadata: unknown): metadata is WorkflowSessionMetadata;
+/**
+ * 获取 workflow session 的状态
+ */
+export declare function getWorkflowSessionStatus(metadata: WorkflowSessionMetadata): 'running' | 'paused' | 'completed' | 'failed' | 'stopped';