@ai-setting/roy-agent-cli 1.3.15 → 1.3.16

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

@@ -0,0 +1,123 @@
+import { z } from 'zod';
+import type { EventBus } from '../engine/event-bus';
+import type { SessionComponent } from '../../session/session-component';
+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;
+    /** @deprecated No-op: workflow always waits for completion */
+    sync?: boolean;
+}
+export interface RunResult {
+    runId: string;
+    /** Session ID (workflow_{runId} format) - useful for CLI resume */
+    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;
+    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;
+    /**
+     * 请求用户输入
+     *
+     * 调用此方法会抛出 AskUserError，引擎捕获后会暂停 workflow
+     *
+     * @param query - 向用户询问的问题
+     * @throws AskUserError - 总是抛出此异常
+     */
+    askUser(query: string): never;
+}
+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'];
+}): NodeExecutionContext;
+//# sourceMappingURL=run.d.ts.map

package/dist/core/src/env/workflow/types/run.js

@@ -0,0 +1,23 @@
+import { z } from 'zod';
+import { AskUserError } from "./workflow-message.js";
+// ==================== 状态枚举 ====================
+export const RunStatusSchema = z.enum([
+    'idle', 'running', 'paused', 'stopped', 'completed', 'failed'
+]);
+export const NodeStatusSchema = z.enum([
+    'pending', 'scheduled', 'started', 'running', 'completed', 'failed', 'skipped'
+]);
+// ==================== Context Factory ====================
+/**
+ * 创建 NodeExecutionContext
+ */
+export function createNodeExecutionContext(params) {
+    return {
+        ...params,
+        askUser: (query) => {
+            throw new AskUserError(params.runId, params.sessionId, params.nodeId, 'unknown', // nodeType 会在外层设置
+            query);
+        },
+    };
+}
+//# sourceMappingURL=run.js.map

package/dist/core/src/env/workflow/types/run.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=run.test.d.ts.map

package/dist/core/src/env/workflow/types/run.test.js

@@ -0,0 +1,381 @@
+import { describe, it, expect } from 'vitest';
+import { z } from 'zod';
+describe('Run Types', () => {
+    describe('RunStatus', () => {
+        it('should accept all valid run statuses', () => {
+            const validStatuses = ['idle', 'running', 'paused', 'stopped', 'completed', 'failed'];
+            const schema = z.enum(['idle', 'running', 'paused', 'stopped', 'completed', 'failed']);
+            for (const status of validStatuses) {
+                expect(() => schema.parse(status)).not.toThrow();
+            }
+        });
+        it('should reject invalid run status', () => {
+            const schema = z.enum(['idle', 'running', 'paused', 'stopped', 'completed', 'failed']);
+            expect(() => schema.parse('invalid')).toThrow();
+            expect(() => schema.parse('pending')).toThrow();
+            expect(() => schema.parse('')).toThrow();
+        });
+    });
+    describe('NodeStatus', () => {
+        it('should accept all valid node statuses', () => {
+            const validStatuses = ['pending', 'scheduled', 'started', 'running', 'completed', 'failed', 'skipped'];
+            const schema = z.enum(['pending', 'scheduled', 'started', 'running', 'completed', 'failed', 'skipped']);
+            for (const status of validStatuses) {
+                expect(() => schema.parse(status)).not.toThrow();
+            }
+        });
+        it('should reject invalid node status', () => {
+            const schema = z.enum(['pending', 'scheduled', 'started', 'running', 'completed', 'failed', 'skipped']);
+            expect(() => schema.parse('invalid')).toThrow();
+            expect(() => schema.parse('idle')).toThrow();
+        });
+    });
+    describe('WorkflowRun', () => {
+        it('should accept minimal workflow run', () => {
+            const run = {
+                id: 'run_123',
+                workflowId: 'wf_456',
+                workflowName: 'test-workflow',
+                status: 'idle',
+                debugMode: false,
+            };
+            expect(run.id).toBe('run_123');
+            expect(run.workflowId).toBe('wf_456');
+            expect(run.status).toBe('idle');
+        });
+        it('should accept full workflow run', () => {
+            const run = {
+                id: 'run_123',
+                workflowId: 'wf_456',
+                workflowName: 'test-workflow',
+                status: 'completed',
+                input: { param1: 'value1' },
+                output: { result: 'success' },
+                error: undefined,
+                startedAt: new Date('2024-01-01T10:00:00Z'),
+                completedAt: new Date('2024-01-01T10:05:00Z'),
+                durationMs: 300000,
+                debugMode: true,
+                parentRunId: 'run_000',
+            };
+            expect(run.id).toBe('run_123');
+            expect(run.status).toBe('completed');
+            expect(run.input).toEqual({ param1: 'value1' });
+            expect(run.output).toEqual({ result: 'success' });
+            expect(run.startedAt).toBeInstanceOf(Date);
+            expect(run.durationMs).toBe(300000);
+            expect(run.debugMode).toBe(true);
+            expect(run.parentRunId).toBe('run_000');
+        });
+        it('should accept running state workflow run', () => {
+            const run = {
+                id: 'run_123',
+                workflowId: 'wf_456',
+                workflowName: 'test-workflow',
+                status: 'running',
+                startedAt: new Date(),
+                debugMode: false,
+            };
+            expect(run.status).toBe('running');
+            expect(run.startedAt).toBeInstanceOf(Date);
+        });
+        it('should accept paused state workflow run', () => {
+            const run = {
+                id: 'run_123',
+                workflowId: 'wf_456',
+                workflowName: 'test-workflow',
+                status: 'paused',
+                startedAt: new Date(),
+                pausedAt: new Date(),
+                debugMode: false,
+            };
+            expect(run.status).toBe('paused');
+            expect(run.pausedAt).toBeInstanceOf(Date);
+        });
+        it('should accept failed state workflow run', () => {
+            const run = {
+                id: 'run_123',
+                workflowId: 'wf_456',
+                workflowName: 'test-workflow',
+                status: 'failed',
+                error: 'Node execution failed: tool not found',
+                startedAt: new Date(),
+                completedAt: new Date(),
+                durationMs: 5000,
+                debugMode: false,
+            };
+            expect(run.status).toBe('failed');
+            expect(run.error).toBe('Node execution failed: tool not found');
+            expect(run.durationMs).toBe(5000);
+        });
+    });
+    describe('NodeRun', () => {
+        it('should accept minimal node run', () => {
+            const nodeRun = {
+                id: 'nr_123',
+                runId: 'run_456',
+                nodeId: 'node1',
+                nodeType: 'tool',
+                status: 'pending',
+                retryCount: 0,
+            };
+            expect(nodeRun.id).toBe('nr_123');
+            expect(nodeRun.nodeId).toBe('node1');
+            expect(nodeRun.status).toBe('pending');
+            expect(nodeRun.retryCount).toBe(0);
+        });
+        it('should accept full node run', () => {
+            const nodeRun = {
+                id: 'nr_123',
+                runId: 'run_456',
+                nodeId: 'node1',
+                nodeType: 'tool',
+                status: 'completed',
+                input: { operation: 'add', a: 1, b: 2 },
+                output: { result: 3 },
+                error: undefined,
+                startedAt: new Date('2024-01-01T10:00:00Z'),
+                completedAt: new Date('2024-01-01T10:00:01Z'),
+                durationMs: 1000,
+                retryCount: 0,
+            };
+            expect(nodeRun.status).toBe('completed');
+            expect(nodeRun.input).toEqual({ operation: 'add', a: 1, b: 2 });
+            expect(nodeRun.output).toEqual({ result: 3 });
+            expect(nodeRun.durationMs).toBe(1000);
+        });
+        it('should accept failed node run with error', () => {
+            const nodeRun = {
+                id: 'nr_123',
+                runId: 'run_456',
+                nodeId: 'node1',
+                nodeType: 'tool',
+                status: 'failed',
+                input: { tool: 'nonexistent' },
+                error: 'Tool not found: nonexistent',
+                startedAt: new Date(),
+                completedAt: new Date(),
+                durationMs: 100,
+                retryCount: 3,
+            };
+            expect(nodeRun.status).toBe('failed');
+            expect(nodeRun.error).toBe('Tool not found: nonexistent');
+            expect(nodeRun.retryCount).toBe(3);
+        });
+        it('should accept running node run', () => {
+            const nodeRun = {
+                id: 'nr_123',
+                runId: 'run_456',
+                nodeId: 'node1',
+                nodeType: 'agent',
+                status: 'running',
+                input: { prompt: 'Do something' },
+                startedAt: new Date(),
+                retryCount: 0,
+            };
+            expect(nodeRun.status).toBe('running');
+            expect(nodeRun.startedAt).toBeInstanceOf(Date);
+        });
+        it('should accept skipped node run', () => {
+            const nodeRun = {
+                id: 'nr_123',
+                runId: 'run_456',
+                nodeId: 'node1',
+                nodeType: 'tool',
+                status: 'skipped',
+                reason: 'Previous dependency failed',
+                retryCount: 0,
+            };
+            expect(nodeRun.status).toBe('skipped');
+        });
+        it('should accept scheduled node run', () => {
+            const nodeRun = {
+                id: 'nr_123',
+                runId: 'run_456',
+                nodeId: 'node1',
+                nodeType: 'tool',
+                status: 'scheduled',
+                retryCount: 0,
+            };
+            expect(nodeRun.status).toBe('scheduled');
+        });
+    });
+    describe('RunOptions', () => {
+        it('should accept minimal run options', () => {
+            const options = {};
+            expect(options).toEqual({});
+        });
+        it('should accept full run options', () => {
+            const options = {
+                input: { key: 'value' },
+                sync: true,
+                debug: true,
+                parallelLimit: 5,
+                timeout: 300000,
+            };
+            expect(options.input).toEqual({ key: 'value' });
+            expect(options.sync).toBe(true);
+            expect(options.debug).toBe(true);
+            expect(options.parallelLimit).toBe(5);
+            expect(options.timeout).toBe(300000);
+        });
+        it('should accept null parallelLimit for unlimited', () => {
+            const options = {
+                parallelLimit: null,
+            };
+            expect(options.parallelLimit).toBeNull();
+        });
+        it('should accept null timeout for no timeout', () => {
+            const options = {
+                timeout: null,
+            };
+            expect(options.timeout).toBeNull();
+        });
+        it('should accept undefined input', () => {
+            const options = {
+                input: undefined,
+                sync: false,
+            };
+            expect(options.input).toBeUndefined();
+            expect(options.sync).toBe(false);
+        });
+    });
+    describe('RunResult', () => {
+        it('should accept successful run result', () => {
+            const result = {
+                runId: 'run_123',
+                status: 'completed',
+                output: { result: 'success' },
+                durationMs: 5000,
+            };
+            expect(result.runId).toBe('run_123');
+            expect(result.status).toBe('completed');
+            expect(result.output).toEqual({ result: 'success' });
+            expect(result.durationMs).toBe(5000);
+        });
+        it('should accept failed run result', () => {
+            const result = {
+                runId: 'run_123',
+                status: 'failed',
+                error: 'Workflow execution failed',
+                durationMs: 5000,
+            };
+            expect(result.status).toBe('failed');
+            expect(result.error).toBe('Workflow execution failed');
+        });
+        it('should accept running run result', () => {
+            const result = {
+                runId: 'run_123',
+                status: 'running',
+            };
+            expect(result.status).toBe('running');
+            expect(result.output).toBeUndefined();
+            expect(result.error).toBeUndefined();
+        });
+    });
+    describe('NodeExecutionContext', () => {
+        it('should accept valid execution context', () => {
+            const context = {
+                runId: 'run_123',
+                workflowName: 'test-workflow',
+                nodeId: 'node1',
+                input: { param: 'value' },
+                previousOutputs: new Map([['prev_node', { result: 42 }]]),
+                config: { tool: 'calculator' },
+                debug: false,
+                eventBus: {
+                    publish: () => { },
+                },
+            };
+            expect(context.runId).toBe('run_123');
+            expect(context.nodeId).toBe('node1');
+            expect(context.previousOutputs).toBeInstanceOf(Map);
+            expect(context.config).toEqual({ tool: 'calculator' });
+            expect(context.debug).toBe(false);
+        });
+        it('should accept empty previousOutputs', () => {
+            const context = {
+                runId: 'run_123',
+                workflowName: 'test-workflow',
+                nodeId: 'node1',
+                input: {},
+                previousOutputs: new Map(),
+                config: {},
+                debug: false,
+                eventBus: {},
+            };
+            expect(context.previousOutputs.size).toBe(0);
+        });
+        it('should accept context with multiple previous outputs', () => {
+            const context = {
+                runId: 'run_123',
+                workflowName: 'test-workflow',
+                nodeId: 'node3',
+                input: {},
+                previousOutputs: new Map([
+                    ['node1', { result: 'step1' }],
+                    ['node2', { result: 'step2' }],
+                ]),
+                config: {},
+                debug: false,
+                eventBus: {},
+            };
+            expect(context.previousOutputs.size).toBe(2);
+            expect(context.previousOutputs.get('node1')).toEqual({ result: 'step1' });
+            expect(context.previousOutputs.get('node2')).toEqual({ result: 'step2' });
+        });
+        it('should accept debug mode context', () => {
+            const context = {
+                runId: 'run_123',
+                workflowName: 'test-workflow',
+                nodeId: 'node1',
+                input: {},
+                previousOutputs: new Map(),
+                config: {},
+                debug: true,
+                eventBus: {},
+            };
+            expect(context.debug).toBe(true);
+        });
+    });
+    describe('NodeExecutionResult', () => {
+        it('should accept successful execution result', () => {
+            const result = {
+                output: { result: 'success', data: [1, 2, 3] },
+                error: undefined,
+                durationMs: 1500,
+            };
+            expect(result.output).toEqual({ result: 'success', data: [1, 2, 3] });
+            expect(result.error).toBeUndefined();
+            expect(result.durationMs).toBe(1500);
+        });
+        it('should accept failed execution result', () => {
+            const error = new Error('Execution failed');
+            const result = {
+                output: undefined,
+                error,
+                durationMs: 500,
+            };
+            expect(result.output).toBeUndefined();
+            expect(result.error).toBe(error);
+            expect(result.error.message).toBe('Execution failed');
+            expect(result.durationMs).toBe(500);
+        });
+        it('should accept result with complex output', () => {
+            const result = {
+                output: {
+                    files: [
+                        { name: 'file1.txt', size: 1024 },
+                        { name: 'file2.txt', size: 2048 },
+                    ],
+                    summary: { total: 2, totalSize: 3072 },
+                },
+                error: undefined,
+                durationMs: 3000,
+            };
+            expect(result.output.files).toHaveLength(2);
+            expect(result.output.summary.total).toBe(2);
+        });
+    });
+});
+//# sourceMappingURL=run.test.js.map

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

@@ -0,0 +1,58 @@
+/**
+ * @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;
+    readonly timestamp: number;
+    readonly type = "ask-user";
+    readonly name = "AskUserError";
+    constructor(runId: string, sessionId: string, nodeId: string, nodeType: string, query: string, agentSessionId?: string, timestamp?: number);
+    /**
+     * 转换为 WorkflowAskUserEvent
+     */
+    toEvent(): WorkflowAskUserEvent;
+}
+//# sourceMappingURL=workflow-hil.d.ts.map

package/dist/core/src/env/workflow/types/workflow-hil.js

@@ -0,0 +1,76 @@
+/**
+ * @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
+ */
+/**
+ * 创建 NodeInterruptEvent
+ */
+export function createNodeInterruptEvent(runId, nodeId, nodeType, query, agentSessionId) {
+    return {
+        type: 'node.interrupt',
+        run_id: runId,
+        timestamp: Date.now(),
+        node_id: nodeId,
+        node_type: nodeType,
+        query,
+        ...(agentSessionId ? { agent_session_id: agentSessionId } : {}),
+    };
+}
+/**
+ * 创建 WorkflowAskUserEvent
+ */
+export function createWorkflowAskUserEvent(runId, sessionId, nodeId, nodeType, query) {
+    return {
+        type: 'workflow.ask-user',
+        run_id: runId,
+        timestamp: Date.now(),
+        session_id: sessionId,
+        node_id: nodeId,
+        node_type: nodeType,
+        query,
+    };
+}
+// ==================== AskUserError ====================
+/**
+ * AskUserError - 当节点调用 askUser() 时抛出
+ */
+export class AskUserError extends Error {
+    runId;
+    sessionId;
+    nodeId;
+    nodeType;
+    query;
+    agentSessionId;
+    timestamp;
+    type = 'ask-user';
+    name = 'AskUserError';
+    constructor(runId, sessionId, nodeId, nodeType, query, agentSessionId, timestamp = Date.now()) {
+        super(`[${nodeType}:${nodeId}] Ask user: ${query}`);
+        this.runId = runId;
+        this.sessionId = sessionId;
+        this.nodeId = nodeId;
+        this.nodeType = nodeType;
+        this.query = query;
+        this.agentSessionId = agentSessionId;
+        this.timestamp = timestamp;
+    }
+    /**
+     * 转换为 WorkflowAskUserEvent
+     */
+    toEvent() {
+        return {
+            type: 'workflow.ask-user',
+            run_id: this.runId,
+            timestamp: this.timestamp,
+            session_id: this.sessionId,
+            node_id: this.nodeId,
+            node_type: this.nodeType,
+            query: this.query,
+        };
+    }
+}
+//# sourceMappingURL=workflow-hil.js.map