Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated

Checkpoint: File edits

rUvbcebeaeddc44
diff --git a/v3/@claude-flow/cli/src/services/headless-worker-executor.ts b/v3/@claude-flow/cli/src/services/headless-worker-executor.ts
new file mode 100644
index 0000000000..94d097205c
--- /dev/null
+++ b/v3/@claude-flow/cli/src/services/headless-worker-executor.ts
@@ -0,0 +1,644 @@
+/**
+ * Headless Worker Executor
+ * Enables workers to invoke Claude Code in headless mode with configurable sandbox profiles.
+ *
+ * Based on ADR-019 (Headless Runtime Package) and ADR-020 (Headless Worker Integration)
+ */
+
+import { spawn, execSync, type ChildProcess } from 'child_process';
+import { EventEmitter } from 'events';
+import { existsSync, readFileSync, readdirSync, statSync } from 'fs';
+import { join, relative } from 'path';
+import type { WorkerType } from './worker-daemon.js';
+
+// Headless worker types - workers that can use Claude Code AI
+export type HeadlessWorkerType =
+ | 'audit'
+ | 'optimize'
+ | 'testgaps'
+ | 'document'
+ | 'ultralearn'
+ | 'refactor'
+ | 'deepdive'
+ | 'predict';
+
+// Local worker types - workers that run locally without AI
+export type LocalWorkerType =
+ | 'map'
+ | 'consolidate'
+ | 'benchmark'
+ | 'preload';
+
+// Array of headless worker types for runtime checking
+export const HEADLESS_WORKERS: HeadlessWorkerType[] = [
+ 'audit',
+ 'optimize',
+ 'testgaps',
+ 'document',
+ 'ultralearn',
+ 'refactor',
+ 'deepdive',
+ 'predict',
+];
+
+// Sandbox modes
+export type SandboxMode = 'strict' | 'permissive' | 'disabled';
+
+// Model types
+export type ModelType = 'sonnet' | 'opus' | 'haiku';
+
+/**
+ * Headless worker configuration
+ */
+export interface HeadlessWorkerConfig {
+ type: HeadlessWorkerType;
+
+ // Prompt template for Claude Code
+ promptTemplate: string;
+
+ // Sandbox profile
+ sandbox: SandboxMode;
+
+ // Model to use (default: sonnet)
+ model?: ModelType;
+
+ // Max output tokens
+ maxOutputTokens?: number;
+
+ // Timeout in ms (default: 5 minutes)
+ timeoutMs?: number;
+
+ // File patterns to include as context
+ contextPatterns?: string[];
+
+ // Output parsing format
+ outputFormat?: 'text' | 'json' | 'markdown';
+}
+
+/**
+ * Execution result from headless worker
+ */
+export interface HeadlessExecutionResult {
+ success: boolean;
+ output: string;
+ parsedOutput?: unknown;
+ durationMs: number;
+ tokensUsed?: number;
+ model: string;
+ sandboxMode: SandboxMode;
+ workerType: HeadlessWorkerType;
+}
+
+/**
+ * Default headless worker configurations based on ADR-020
+ */
+export const HEADLESS_WORKER_CONFIGS: Record<HeadlessWorkerType, HeadlessWorkerConfig> = {
+ audit: {
+ type: 'audit',
+ promptTemplate: `Analyze this codebase for security vulnerabilities:
+- Check for hardcoded secrets (API keys, passwords)
+- Identify SQL injection risks
+- Find XSS vulnerabilities
+- Check for insecure dependencies
+- Identify authentication/authorization issues
+
+Provide a JSON report with:
+{
+ "vulnerabilities": [{ "severity": "high|medium|low", "file": "...", "line": N, "description": "..." }],
+ "riskScore": 0-100,
+ "recommendations": ["..."]
+}`,
+ sandbox: 'strict',
+ model: 'haiku',
+ outputFormat: 'json',
+ contextPatterns: ['**/*.ts', '**/*.js', '**/.env*', '**/package.json'],
+ timeoutMs: 5 * 60 * 1000,
+ },
+
+ optimize: {
+ type: 'optimize',
+ promptTemplate: `Analyze this codebase for performance optimizations:
+- Identify N+1 query patterns
+- Find unnecessary re-renders in React
+- Suggest caching opportunities
+- Identify memory leaks
+- Find redundant computations
+
+Provide actionable suggestions with code examples.`,
+ sandbox: 'permissive',
+ model: 'sonnet',
+ outputFormat: 'markdown',
+ contextPatterns: ['src/**/*.ts', 'src/**/*.tsx'],
+ timeoutMs: 10 * 60 * 1000,
+ },
+
+ testgaps: {
+ type: 'testgaps',
+ promptTemplate: `Analyze test coverage and identify gaps:
+- Find untested functions and classes
+- Identify edge cases not covered
+- Suggest new test scenarios
+- Check for missing error handling tests
+- Identify integration test gaps
+
+For each gap, provide a test skeleton.`,
+ sandbox: 'permissive',
+ model: 'sonnet',
+ outputFormat: 'markdown',
+ contextPatterns: ['src/**/*.ts', 'tests/**/*.ts', '__tests__/**/*.ts'],
+ timeoutMs: 10 * 60 * 1000,
+ },
+
+ document: {
+ type: 'document',
+ promptTemplate: `Generate documentation for undocumented code:
+- Add JSDoc comments to functions
+- Create README sections for modules
+- Document API endpoints
+- Add inline comments for complex logic
+- Generate usage examples
+
+Focus on public APIs and exported functions.`,
+ sandbox: 'permissive',
+ model: 'haiku',
+ outputFormat: 'markdown',
+ contextPatterns: ['src/**/*.ts'],
+ timeoutMs: 10 * 60 * 1000,
+ },
+
+ ultralearn: {
+ type: 'ultralearn',
+ promptTemplate: `Deeply analyze this codebase to learn:
+- Architectural patterns used
+- Coding conventions
+- Domain-specific terminology
+- Common patterns and idioms
+- Team preferences
+
+Store insights for future context.`,
+ sandbox: 'strict',
+ model: 'opus',
+ outputFormat: 'json',
+ contextPatterns: ['**/*.ts', '**/CLAUDE.md', '**/README.md'],
+ timeoutMs: 15 * 60 * 1000,
+ },
+
+ refactor: {
+ type: 'refactor',
+ promptTemplate: `Suggest refactoring opportunities:
+- Identify code duplication
+- Suggest better abstractions
+- Find opportunities for design patterns
+- Identify overly complex functions
+- Suggest module reorganization
+
+Provide before/after code examples.`,
+ sandbox: 'permissive',
+ model: 'sonnet',
+ outputFormat: 'markdown',
+ contextPatterns: ['src/**/*.ts'],
+ timeoutMs: 10 * 60 * 1000,
+ },
+
+ deepdive: {
+ type: 'deepdive',
+ promptTemplate: `Perform deep analysis of this codebase:
+- Understand data flow
+- Map dependencies
+- Identify architectural issues
+- Find potential bugs
+- Analyze error handling
+
+Provide comprehensive report.`,
+ sandbox: 'strict',
+ model: 'opus',
+ outputFormat: 'markdown',
+ contextPatterns: ['src/**/*.ts'],
+ timeoutMs: 15 * 60 * 1000,
+ },
+
+ predict: {
+ type: 'predict',
+ promptTemplate: `Based on recent activity, predict what the developer needs:
+- Files likely to be edited next
+- Tests that should be run
+- Documentation to reference
+- Dependencies to check
+
+Provide preload suggestions in JSON format:
+{
+ "filesToPreload": ["..."],
+ "testsToRun": ["..."],
+ "docsToReference": ["..."]
+}`,
+ sandbox: 'strict',
+ model: 'haiku',
+ outputFormat: 'json',
+ contextPatterns: ['.claude-flow/metrics/*.json'],
+ timeoutMs: 2 * 60 * 1000,
+ },
+};
+
+/**
+ * Check if a worker type is a headless worker
+ */
+export function isHeadlessWorker(type: WorkerType): type is HeadlessWorkerType {
+ return HEADLESS_WORKERS.includes(type as HeadlessWorkerType);
+}
+
+/**
+ * HeadlessWorkerExecutor - Executes workers using Claude Code in headless mode
+ */
+export class HeadlessWorkerExecutor extends EventEmitter {
+ private projectRoot: string;
+ private maxConcurrent: number;
+ private activeProcesses: Map<string, ChildProcess> = new Map();
+ private claudeCodeAvailable: boolean | null = null;
+
+ constructor(projectRoot: string, options?: { maxConcurrent?: number }) {
+ super();
+ this.projectRoot = projectRoot;
+ this.maxConcurrent = options?.maxConcurrent ?? 2;
+ }
+
+ /**
+ * Check if Claude Code CLI is available
+ */
+ async isAvailable(): Promise<boolean> {
+ if (this.claudeCodeAvailable !== null) {
+ return this.claudeCodeAvailable;
+ }
+
+ try {
+ execSync('claude --version', { stdio: 'pipe', timeout: 5000 });
+ this.claudeCodeAvailable = true;
+ this.emit('availability:checked', { available: true });
+ return true;
+ } catch {
+ this.claudeCodeAvailable = false;
+ this.emit('availability:checked', { available: false });
+ return false;
+ }
+ }
+
+ /**
+ * Execute a headless worker
+ */
+ async execute(workerType: HeadlessWorkerType): Promise<HeadlessExecutionResult> {
+ const config = HEADLESS_WORKER_CONFIGS[workerType];
+ if (!config) {
+ throw new Error(`Unknown headless worker type: ${workerType}`);
+ }
+
+ const startTime = Date.now();
+ const executionId = `${workerType}_${Date.now()}`;
+
+ this.emit('execution:start', {
+ executionId,
+ workerType,
+ config
+ });
+
+ try {
+ // Check availability
+ const available = await this.isAvailable();
+ if (!available) {
+ throw new Error('Claude Code CLI not available');
+ }
+
+ // Build context from file patterns
+ const context = await this.buildContext(config.contextPatterns || []);
+
+ // Build the full prompt
+ const fullPrompt = this.buildPrompt(config.promptTemplate, context);
+
+ // Execute Claude Code headlessly
+ const result = await this.executeClaudeCode(fullPrompt, {
+ sandbox: config.sandbox,
+ model: config.model || 'sonnet',
+ timeoutMs: config.timeoutMs || 300000,
+ executionId,
+ });
+
+ // Parse output if JSON expected
+ let parsedOutput: unknown;
+ if (config.outputFormat === 'json' && result.output) {
+ try {
+ // Try to extract JSON from the output
+ const jsonMatch = result.output.match(/\{[\s\S]*\}/);
+ if (jsonMatch) {
+ parsedOutput = JSON.parse(jsonMatch[0]);
+ }
+ } catch {
+ // Keep raw output if parsing fails
+ }
+ }
+
+ const executionResult: HeadlessExecutionResult = {
+ success: result.success,
+ output: result.output,
+ parsedOutput,
+ durationMs: Date.now() - startTime,
+ tokensUsed: result.tokensUsed,
+ model: config.model || 'sonnet',
+ sandboxMode: config.sandbox,
+ workerType,
+ };
+
+ this.emit('execution:complete', {
+ executionId,
+ result: executionResult
+ });
+
+ return executionResult;
+ } catch (error) {
+ const errorResult: HeadlessExecutionResult = {
+ success: false,
+ output: error instanceof Error ? error.message : String(error),
+ durationMs: Date.now() - startTime,
+ model: config.model || 'sonnet',
+ sandboxMode: config.sandbox,
+ workerType,
+ };
+
+ this.emit('execution:error', {
+ executionId,
+ error: error instanceof Error ? error.message : String(error),
+ result: errorResult
+ });
+
+ throw error;
+ } finally {
+ this.activeProcesses.delete(executionId);
+ }
+ }
+
+ /**
+ * Build context from file patterns
+ */
+ private async buildContext(patterns: string[]): Promise<string> {
+ if (patterns.length === 0) return '';
+
+ const files: string[] = [];
+
+ for (const pattern of patterns) {
+ const matches = this.simpleGlob(pattern);
+ files.push(...matches);
+ }
+
+ // Limit to reasonable context size
+ const maxFiles = 20;
+ const maxCharsPerFile = 5000;
+ const selectedFiles = [...new Set(files)].slice(0, maxFiles);
+
+ const contextParts: string[] = [];
+ for (const file of selectedFiles) {
+ try {
+ const fullPath = join(this.projectRoot, file);
+ if (existsSync(fullPath)) {
+ const content = readFileSync(fullPath, 'utf-8');
+ const truncated = content.slice(0, maxCharsPerFile);
+ const suffix = content.length > maxCharsPerFile ? '\n... (truncated)' : '';
+ contextParts.push(`--- ${file} ---\n${truncated}${suffix}`);
+ }
+ } catch {
+ // Skip unreadable files
+ }
+ }
+
+ return contextParts.join('\n\n');
+ }
+
+ /**
+ * Simple glob implementation for file matching
+ */
+ private simpleGlob(pattern: string): string[] {
+ const results: string[] = [];
+
+ // Handle simple patterns
+ if (!pattern.includes('*')) {
+ const fullPath = join(this.projectRoot, pattern);
+ if (existsSync(fullPath)) {
+ results.push(pattern);
+ }
+ return results;
+ }
+
+ // Handle recursive patterns like **/*.ts
+ const parts = pattern.split('/');
+ const hasRecursive = parts.includes('**');
+
+ const scanDir = (dir: string, remainingParts: string[]): void => {
+ if (remainingParts.length === 0) return;
+
+ try {
+ const entries = readdirSync(join(this.projectRoot, dir), { withFileTypes: true });
+ const currentPart = remainingParts[0];
+ const isLastPart = remainingParts.length === 1;
+
+ for (const entry of entries) {
+ const entryPath = dir ? `${dir}/${entry.name}` : entry.name;
+
+ if (currentPart === '**') {
+ // Recursive - match this level and descend
+ if (entry.isDirectory()) {
+ scanDir(entryPath, remainingParts); // Keep ** for deeper levels
+ scanDir(entryPath, remainingParts.slice(1)); // Try next pattern part
+ } else if (entry.isFile() && remainingParts.length > 1) {
+ // Check if file matches next pattern
+ const nextPart = remainingParts[1];
+ if (this.matchesPattern(entry.name, nextPart)) {
+ results.push(entryPath);
+ }
+ }
+ } else if (this.matchesPattern(entry.name, currentPart)) {
+ if (isLastPart && entry.isFile()) {
+ results.push(entryPath);
+ } else if (!isLastPart && entry.isDirectory()) {
+ scanDir(entryPath, remainingParts.slice(1));
+ }
+ }
+ }
+ } catch {
+ // Skip unreadable directories
+ }
+ };
+
+ scanDir('', parts);
+ return results.slice(0, 100); // Limit results
+ }
+
+ /**
+ * Match filename against a simple pattern
+ */
+ private matchesPattern(name: string, pattern: string): boolean {
+ if (pattern === '*') return true;
+ if (pattern === '**') return true;
+
+ // Handle *.ext patterns
+ if (pattern.startsWith('*.')) {
+ const ext = pattern.slice(1);
+ return name.endsWith(ext);
+ }
+
+ // Handle prefix* patterns
+ if (pattern.endsWith('*')) {
+ const prefix = pattern.slice(0, -1);
+ return name.startsWith(prefix);
+ }
+
+ // Exact match
+ return name === pattern;
+ }
+
+ /**
+ * Build full prompt with context
+ */
+ private buildPrompt(template: string, context: string): string {
+ if (!context) {
+ return template;
+ }
+
+ return `${template}
+
+## Codebase Context
+
+${context}
+
+## Instructions
+
+Analyze the above codebase context and provide your response following the format specified in the task.`;
+ }
+
+ /**
+ * Execute Claude Code in headless mode
+ */
+ private async executeClaudeCode(
+ prompt: string,
+ options: {
+ sandbox: SandboxMode;
+ model: ModelType;
+ timeoutMs: number;
+ executionId: string;
+ }
+ ): Promise<{ success: boolean; output: string; tokensUsed?: number }> {
+ return new Promise((resolve, reject) => {
+ // Map model names to API model IDs
+ const modelMap: Record<ModelType, string> = {
+ sonnet: 'claude-sonnet-4-20250514',
+ opus: 'claude-opus-4-20250514',
+ haiku: 'claude-haiku-4-20250514',
+ };
+
+ const env: Record<string, string> = {
+ ...process.env as Record<string, string>,
+ CLAUDE_CODE_HEADLESS: 'true',
+ CLAUDE_CODE_SANDBOX_MODE: options.sandbox,
+ };
+
+ // Set model if specified
+ if (options.model) {
+ env.ANTHROPIC_MODEL = modelMap[options.model];
+ }
+
+ // Spawn claude CLI process
+ const child = spawn('claude', ['--print', prompt], {
+ cwd: this.projectRoot,
+ env,
+ timeout: options.timeoutMs,
+ stdio: ['pipe', 'pipe', 'pipe'],
+ });
+
+ this.activeProcesses.set(options.executionId, child);
+
+ let stdout = '';
+ let stderr = '';
+
+ child.stdout?.on('data', (data: Buffer) => {
+ const chunk = data.toString();
+ stdout += chunk;
+ this.emit('output', {
+ executionId: options.executionId,
+ type: 'stdout',
+ data: chunk
+ });
+ });
+
+ child.stderr?.on('data', (data: Buffer) => {
+ const chunk = data.toString();
+ stderr += chunk;
+ this.emit('output', {
+ executionId: options.executionId,
+ type: 'stderr',
+ data: chunk
+ });
+ });
+
+ child.on('close', (code: number | null) => {
+ this.activeProcesses.delete(options.executionId);
+ resolve({
+ success: code === 0,
+ output: stdout || stderr,
+ });
+ });
+
+ child.on('error', (error: Error) => {
+ this.activeProcesses.delete(options.executionId);
+ reject(error);
+ });
+
+ // Setup timeout
+ const timeoutId = setTimeout(() => {
+ if (this.activeProcesses.has(options.executionId)) {
+ child.kill('SIGTERM');
+ reject(new Error(`Execution timed out after ${options.timeoutMs}ms`));
+ }
+ }, options.timeoutMs);
+
+ child.on('close', () => {
+ clearTimeout(timeoutId);
+ });
+ });
+ }
+
+ /**
+ * Cancel a running execution
+ */
+ cancel(executionId: string): boolean {
+ const process = this.activeProcesses.get(executionId);
+ if (process) {
+ process.kill('SIGTERM');
+ this.activeProcesses.delete(executionId);
+ this.emit('execution:cancelled', { executionId });
+ return true;
+ }
+ return false;
+ }
+
+ /**
+ * Get number of active executions
+ */
+ getActiveCount(): number {
+ return this.activeProcesses.size;
+ }
+
+ /**
+ * Cancel all running executions
+ */
+ cancelAll(): void {
+ for (const [id, process] of this.activeProcesses) {
+ process.kill('SIGTERM');
+ this.emit('execution:cancelled', { executionId: id });
+ }
+ this.activeProcesses.clear();
+ }
+
+ /**
+ * Get worker configuration
+ */
+ getConfig(workerType: HeadlessWorkerType): HeadlessWorkerConfig | undefined {
+ return HEADLESS_WORKER_CONFIGS[workerType];
+ }
+}
+
+export default HeadlessWorkerExecutor;