@ai-setting/roy-agent-cli 1.0.0

package/src/commands/workflow/commands/run.ts

@@ -0,0 +1,398 @@
+/**
+ * @fileoverview Workflow Run Command
+ * 
+ * Run a workflow from file or by name
+ * 
+ * Workflow execution model:
+ * - run starts the workflow
+ * - if ask_user is triggered, workflow stops with status='paused'
+ * - resume with: workflow run -s <sessionId> --input "response"
+ * 
+ * OpenTelemetry W3C TraceContext Support:
+ * - Supports TRACEPARENT environment variable for trace context propagation
+ * - When running via bash tool from interactive mode, TRACEPARENT is passed
+ * - The traceId and parentSpanId are extracted from TRACEPARENT
+ */
+
+import { CommandModule } from 'yargs';
+import { EnvironmentService } from '../../../services/environment.service';
+import { OutputService } from '../../../services/output.service';
+import { renderRunResult } from '../renderers';
+import chalk from 'chalk';
+import fs from 'fs';
+import path from 'path';
+import YAML from 'yaml';
+import type { WorkflowService } from '@ai-setting/roy-agent-core/env/workflow/service';
+import type { WorkflowDefinition } from '@ai-setting/roy-agent-core/env/workflow/types';
+import { getTracerProvider, propagation, wrapFunction } from '@ai-setting/roy-agent-core';
+
+export interface WorkflowRunOptions {
+  identifier: string;
+  debug?: boolean;
+  input?: string;
+  parallelLimit?: number;
+  timeout?: number;
+  watch?: boolean;
+  file?: boolean;
+  name?: string;
+  registerOnly?: boolean;
+  config?: string;
+  /** Resume from existing session */
+  sessionId?: string;
+}
+
+/**
+ * WorkflowRunCommand - Run a workflow
+ * 
+ * Supports two modes:
+ * 1. Run by name: `roy workflow run my-workflow`
+ * 2. Run from file: `roy workflow run workflow.yaml --file`
+ *    - Optionally register with custom name: `roy workflow run workflow.yaml --file --name my-workflow`
+ *    - Register only without running: `roy workflow run workflow.yaml --file --register-only`
+ * 
+ * Resume paused workflow:
+ * `roy workflow run -s <sessionId> --input "user response"`
+ */
+
+/**
+ * Run workflow implementation
+ */
+const runWorkflow = wrapFunction(
+  async function runWorkflowImpl(args: WorkflowRunOptions): Promise<void> {
+    const output = new OutputService();
+    const envService = new EnvironmentService(output);
+
+    // ========================================================================
+    // Initialize OpenTelemetry Trace Context from Environment Variable
+    // 
+    // When running via bash tool from interactive mode, the TRACEPARENT is passed
+    // as environment variable. We initialize the OTel tracer here so that spans
+    // in workflow execution are associated with the parent trace.
+    // ========================================================================
+    
+    // 优先使用 W3C TraceContext (TRACEPARENT)
+    const traceparent = process.env.TRACEPARENT;
+    let traceId: string | undefined;
+    let parentSpanId: string | undefined;
+    
+    if (traceparent) {
+      const extracted = propagation.extract(process.env as Record<string, string | undefined>);
+      if (extracted) {
+        traceId = extracted.traceId;
+        parentSpanId = extracted.spanId; // 发送方 span ID 作为新 span 的 parentSpanId
+      }
+    }
+    
+    // 回退到旧的 TRACE_ID 环境变量（向后兼容）
+    if (!traceId) {
+      traceId = process.env.TRACE_ID;
+      parentSpanId = process.env.PARENT_SPAN_ID;
+    }
+    
+    output.info(`[OTel Trace] TRACEPARENT=${traceparent || 'none'}, traceId=${traceId}, parentSpanId=${parentSpanId}`);
+    
+    // 初始化 OTel tracer 并创建 span
+    let workflowSpan: any = undefined;
+    try {
+      const provider = getTracerProvider();
+      await provider.initialize();
+      const tracer = provider.getTracer('roy-tracer');
+      
+      // 获取恢复后的上下文（用于调试）
+      const restoredContext = tracer.getCurrentContext();
+      output.info(`[OTel Trace] Restored context: ${JSON.stringify(restoredContext)}`);
+      
+      // 从环境变量恢复上下文后创建 span
+      // 注意：调用 getTracer 时会触发 restoreFromEnv，但不会自动创建 span
+      // 需要手动调用 startSpan 来创建新的 span
+      workflowSpan = tracer.startSpan("workflow.run", {
+        attributes: {
+          'workflow.name': args.identifier,
+          'workflow.file': args.file || false,
+          'source': 'workflow-cli',
+          'workflow.parentSpanId': parentSpanId || 'none',
+        },
+      });
+      
+      output.info(`[OTel Trace] Started span: ${workflowSpan.spanContext.spanId}, traceId: ${workflowSpan.spanContext.traceId}, parentSpanId: ${workflowSpan.spanContext.parentSpanId || 'root'}`);
+    } catch (error) {
+      output.warn(`[OTel Trace] Failed to initialize tracer: ${error}`);
+    }
+
+    try {
+      await envService.create({ configPath: args.config });
+      const env = envService.getEnvironment();
+      if (!env) {
+        output.error("Failed to create environment");
+        process.exit(1);
+      }
+      const workflowComponent = env.getComponent('workflow');
+
+      if (!workflowComponent) {
+        output.error('WorkflowComponent not available');
+        process.exit(1);
+      }
+
+      // 获取 WorkflowService
+      const service = (workflowComponent as any).workflowService as WorkflowService;
+      
+      if (!service) {
+        output.error('WorkflowService not initialized. Please run "roy workflow init" first.');
+        process.exit(1);
+      }
+
+      // Parse input
+      let input: Record<string, any> = {};
+      if (args.input) {
+        try {
+          input = JSON.parse(args.input);
+        } catch {
+          output.error('Invalid JSON in --input option');
+          process.exit(1);
+        }
+      }
+
+      // Prepare run options
+      const runOptions: any = {
+        debug: args.debug,
+        parallelLimit: args.parallelLimit,
+        timeout: args.timeout,
+      };
+
+      // Handle session resume (-s sessionId)
+      if (args.sessionId) {
+        // Resume from existing session using unified run()
+        // Session ID format is workflow_{runId}, but user provides runId
+        const sessionId = args.sessionId.startsWith('workflow_') 
+          ? args.sessionId 
+          : `workflow_${args.sessionId}`;
+        
+        output.log(chalk.blue(`🔄 Resuming workflow from session: ${sessionId}`));
+        
+        // Get session to verify it's a workflow session
+        const sessionComponent = (workflowComponent as any).sessionComponent;
+        if (!sessionComponent) {
+          output.error('SessionComponent not available');
+          process.exit(1);
+        }
+        
+        const session = await sessionComponent.get(sessionId);
+        if (!session) {
+          output.error(`Session not found: ${sessionId}`);
+          process.exit(1);
+        }
+        
+        const metadata = session.metadata;
+        if (metadata?.type !== 'workflow') {
+          output.error(`Session is not a workflow session: ${sessionId}`);
+          process.exit(1);
+        }
+        
+        // Get workflow from session metadata to create engine
+        const workflowName = metadata.workflowName;
+        if (!workflowName) {
+          output.error('Workflow name not found in session metadata');
+          process.exit(1);
+        }
+        
+        const workflow = service.getWorkflowByName(workflowName);
+        if (!workflow) {
+          output.error(`Workflow not found: ${workflowName}`);
+          process.exit(1);
+        }
+        
+        // Create engine and use unified run()
+        // The engine's run(sessionId) will detect session exists and infer resume point
+        // input is used as userResponse when resuming from ask_user interrupt
+        const engine = (service as any).engineFactory(workflow);
+        const result = await engine.run(sessionId, {
+          input: args.input || undefined,
+        });
+        
+        output.log(renderRunResult({
+          runId: sessionId,
+          status: result.status,
+          output: result.output,
+          error: result.error,
+          durationMs: result.durationMs,
+        }));
+        
+        // 结束 OTel span
+        if (workflowSpan) {
+          workflowSpan.end();
+        }
+        
+        await envService.dispose();
+        process.exit(0);
+      }
+
+      // Determine if identifier is a file or workflow name
+      const isFile = args.file || 
+        args.identifier.endsWith('.yaml') || 
+        args.identifier.endsWith('.yml') || 
+        args.identifier.endsWith('.json');
+
+      if (isFile) {
+        // Run from file - first register, then run
+        const filePath = path.resolve(args.identifier);
+        if (!fs.existsSync(filePath)) {
+          output.error(`File not found: ${filePath}`);
+          process.exit(1);
+        }
+
+        const content = fs.readFileSync(filePath, 'utf-8');
+        
+        // 解析 YAML 或 JSON 文件
+        let definition: WorkflowDefinition;
+        if (filePath.endsWith('.json')) {
+          definition = JSON.parse(content);
+        } else {
+          definition = YAML.parse(content);
+        }
+
+        // 如果指定了 --name，覆盖定义中的名称
+        const registrationName = args.name || definition.name;
+        if (args.name) {
+          definition = { ...definition, name: args.name };
+        }
+
+        // 注册 workflow
+        const workflow = await service.createWorkflow(definition, { force: true });
+        output.log(chalk.blue(`📝 Registering workflow: ${registrationName}`));
+        output.log(chalk.green(`✅ Workflow registered: ${workflow.name} (${workflow.id})`));
+
+        // 如果是 --register-only 模式，只注册不运行
+        if (args.registerOnly) {
+          output.log(chalk.gray('ℹ️  Use --register-only, skipping execution'));
+          // 结束 OTel span
+          if (workflowSpan) {
+            workflowSpan.end();
+          }
+          await envService.dispose();
+          process.exit(0);
+        }
+
+        // 运行 workflow
+        output.log(chalk.blue(`🚀 Running workflow: ${workflow.name}`));
+        const result = await service.runWorkflow(definition, input, runOptions);
+        
+        // Output result
+        output.log(renderRunResult({
+          runId: result.runId,
+          status: result.status,
+          output: result.output,
+          error: result.error,
+          durationMs: result.durationMs,
+        }));
+        
+        // If paused, show resume hint
+        if (result.status === 'paused') {
+          output.log(chalk.gray(`\n💡 Use "roy workflow run -s ${result.runId}" to resume`));
+        }
+      } else {
+        // Run by name
+        output.log(chalk.blue(`🚀 Running workflow: ${args.identifier}`));
+        const result = await service.runWorkflow(args.identifier, input, runOptions);
+        
+        // Output result
+        output.log(renderRunResult({
+          runId: result.runId,
+          status: result.status,
+          output: result.output,
+          error: result.error,
+          durationMs: result.durationMs,
+        }));
+        
+        // If paused, show resume hint
+        if (result.status === 'paused') {
+          output.log(chalk.gray(`\n💡 Use "roy workflow run -s ${result.runId}" to resume`));
+        }
+      }
+      
+      // 结束 OTel span
+      if (workflowSpan) {
+        workflowSpan.end();
+      }
+      
+      await envService.dispose();
+      process.exit(0);
+    } catch (error) {
+      // 结束 OTel span（带错误）
+      if (workflowSpan) {
+        workflowSpan.end(undefined, error instanceof Error ? error : new Error(String(error)));
+      }
+      output.error(`Failed to run workflow: ${error}`);
+      await envService.dispose();
+      process.exit(1);
+    }
+  },
+  "workflow.cli.run",
+  { recordParams: true, recordResult: true, log: true }
+);
+
+export const WorkflowRunCommand: CommandModule<object, WorkflowRunOptions> = {
+  command: 'run <identifier>',
+  describe: '运行 Workflow (支持从文件或名称运行)',
+
+  builder: (yargs) =>
+    yargs
+      .positional('identifier', {
+        describe: 'Workflow 名称或定义文件路径',
+        type: 'string',
+        demandOption: true,
+      })
+      .option('debug', {
+        alias: 'd',
+        describe: 'Debug 模式',
+        type: 'boolean',
+        default: false,
+      })
+      .option('input', {
+        alias: 'i',
+        describe: '输入参数 (JSON 格式)',
+        type: 'string',
+      })
+      .option('parallel-limit', {
+        describe: '并行限制',
+        type: 'number',
+      })
+      .option('timeout', {
+        alias: 't',
+        describe: '超时时间 (毫秒)',
+        type: 'number',
+      })
+      .option('watch', {
+        alias: 'w',
+        describe: '实时显示执行进度',
+        type: 'boolean',
+        default: false,
+      })
+      .option('file', {
+        alias: 'f',
+        describe: 'identifier 是文件路径，自动注册后运行',
+        type: 'boolean',
+        default: false,
+      })
+      .option('name', {
+        alias: 'n',
+        describe: '注册时的名称（仅 --file 模式有效）',
+        type: 'string',
+      })
+      .option('register-only', {
+        alias: 'r',
+        describe: '只注册不运行（仅 --file 模式有效）',
+        type: 'boolean',
+        default: false,
+      })
+      .option('config', {
+        describe: '配置文件路径',
+        type: 'string',
+      })
+      .option('session-id', {
+        alias: 's',
+        describe: '从已有 session 恢复运行（支持 workflow pause/interrupt 恢复）',
+        type: 'string',
+      }),
+
+  handler: runWorkflow,
+};

package/src/commands/workflow/commands/status.ts

@@ -0,0 +1,147 @@
+/**
+ * @fileoverview Workflow Status Command
+ * 
+ * Get workflow run status
+ */
+
+import { CommandModule } from 'yargs';
+import { EnvironmentService } from '../../../services/environment.service';
+import { OutputService } from '../../../services/output.service';
+import { renderRunDetail } from '../renderers';
+import chalk from 'chalk';
+import type { WorkflowService, SessionInfo } from '@ai-setting/roy-agent-core/env/workflow/service';
+import type { WorkflowRun } from '@ai-setting/roy-agent-core/env/workflow/types';
+
+export interface WorkflowStatusOptions {
+  runId: string;
+  watch?: boolean;
+  interval?: number;
+  config?: string;
+}
+
+/**
+ * WorkflowStatusCommand - Get workflow run status
+ */
+export const WorkflowStatusCommand: CommandModule<object, WorkflowStatusOptions> = {
+  command: 'status <runId>',
+  describe: '查看 Workflow 运行状态',
+
+  builder: (yargs) =>
+    yargs
+      .positional('runId', {
+        describe: 'Run ID',
+        type: 'string',
+        demandOption: true,
+      })
+      .option('watch', {
+        alias: 'w',
+        describe: '持续监控状态',
+        type: 'boolean',
+        default: false,
+      })
+      .option('interval', {
+        alias: 'i',
+        describe: '监控间隔（毫秒）',
+        type: 'number',
+        default: 1000,
+      })
+      .option('config', {
+        describe: '配置文件路径',
+        type: 'string',
+      }),
+
+  async handler(args) {
+    const output = new OutputService();
+    const envService = new EnvironmentService(output);
+
+    try {
+      await envService.create({ configPath: args.config });
+      const env = envService.getEnvironment();
+      if (!env) {
+        output.error("Failed to create environment");
+        process.exit(1);
+      }
+      const workflowComponent = env.getComponent('workflow') as any;
+
+      if (!workflowComponent) {
+        output.error('WorkflowComponent not available');
+        process.exit(1);
+      }
+
+      const service = workflowComponent.getService() as WorkflowService;
+
+      if (args.watch) {
+        // Watch mode
+        let lastStatus = '';
+        while (true) {
+          const session: SessionInfo | null = await service.getSession(args.runId);
+          if (!session) {
+            output.error(`Run not found: ${args.runId}`);
+            process.exit(1);
+          }
+
+          const metadata = session.metadata;
+          const status = metadata.status;
+
+          if (status !== lastStatus) {
+            const run: WorkflowRun = {
+              id: session.id,
+              workflowId: (metadata as any).workflowId || '',
+              workflowName: metadata.workflowName,
+              status,
+              startedAt: session.createdAt,
+              debugMode: false,
+            };
+            output.log(renderRunDetail(run));
+            lastStatus = status;
+          }
+
+          // Check if terminal state
+          if (['completed', 'failed', 'stopped'].includes(status)) {
+            break;
+          }
+
+          // Wait for next check
+          await new Promise(resolve => setTimeout(resolve, args.interval));
+        }
+      } else {
+        // Single status check
+        const session: SessionInfo | null = await service.getSession(args.runId);
+        if (!session) {
+          output.error(`Run not found: ${args.runId}`);
+          process.exit(1);
+        }
+
+        const metadata = session.metadata;
+        const status = metadata.status;
+
+        const run: WorkflowRun = {
+          id: session.id,
+          workflowId: (metadata as any).workflowId || '',
+          workflowName: metadata.workflowName,
+          status,
+          startedAt: session.createdAt,
+          debugMode: false,
+        };
+        output.log(renderRunDetail(run));
+
+        // Show status emoji
+        const statusEmoji: Record<string, string> = {
+          idle: '⏸️',
+          running: '🔄',
+          paused: '⏸️',
+          completed: '✅',
+          failed: '❌',
+          stopped: '⏹️',
+        };
+        const emoji = statusEmoji[status] || '❓';
+        output.log(chalk.bold(`\n${emoji} Status: ${status.toUpperCase()}`));
+      }
+    } catch (error) {
+      output.error(`Failed to get workflow status: ${error}`);
+      process.exit(1);
+    } finally {
+      await envService.dispose();
+    }
+  },
+};

package/src/commands/workflow/commands/stop.ts

@@ -0,0 +1,91 @@
+/**
+ * @fileoverview Workflow Stop Command
+ * 
+ * Stop a running or paused workflow
+ */
+
+import { CommandModule } from 'yargs';
+import { EnvironmentService } from '../../../services/environment.service';
+import { OutputService } from '../../../services/output.service';
+import chalk from 'chalk';
+import type { WorkflowService, SessionInfo } from '@ai-setting/roy-agent-core/env/workflow/service';
+import { wrapFunction } from '@ai-setting/roy-agent-core';
+
+export interface WorkflowStopOptions {
+  runId: string;
+  config?: string;
+}
+
+/**
+ * Stop workflow implementation
+ */
+const stopWorkflow = wrapFunction(
+  async function stopWorkflowImpl(args: WorkflowStopOptions): Promise<void> {
+  const output = new OutputService();
+  const envService = new EnvironmentService(output);
+
+  try {
+    await envService.create({ configPath: args.config });
+    const env = envService.getEnvironment();
+    if (!env) {
+      output.error("Failed to create environment");
+      process.exit(1);
+    }
+    const workflowComponent = env.getComponent('workflow') as any;
+
+    if (!workflowComponent) {
+      output.error('WorkflowComponent not available');
+      process.exit(1);
+    }
+
+    const service = workflowComponent.getService() as WorkflowService;
+
+    // Check if run exists
+    const session: SessionInfo | null = await service.getSession(args.runId);
+    if (!session) {
+      output.error(`Run not found: ${args.runId}`);
+      process.exit(1);
+    }
+
+    const metadata = session.metadata;
+    if (!['running', 'paused'].includes(metadata.status)) {
+      output.error(`Cannot stop run in status: ${metadata.status}`);
+      process.exit(1);
+    }
+
+    // Stop the run
+    await service.stopRun(args.runId);
+
+    output.log(chalk.red(`\n⏹️  Workflow stopped: ${args.runId}`));
+  } catch (error) {
+    output.error(`Failed to stop workflow: ${error}`);
+    process.exit(1);
+  } finally {
+    await envService.dispose();
+  }
+},
+  "workflow.cli.stop",
+  { recordParams: true, recordResult: true, log: true }
+);
+
+/**
+ * WorkflowStopCommand - Stop a running or paused workflow
+ */
+export const WorkflowStopCommand: CommandModule<object, WorkflowStopOptions> = {
+  command: 'stop <runId>',
+  describe: '停止运行中的 Workflow',
+
+  builder: (yargs) =>
+    yargs
+      .positional('runId', {
+        describe: 'Run ID',
+        type: 'string',
+        demandOption: true,
+      })
+      .option('config', {
+        describe: '配置文件路径',
+        type: 'string',
+      }),
+
+  handler: stopWorkflow,
+};