maestro-flow 0.1.4 → 0.2.0

package/dashboard/dist-server/src/coordinator/graph-loader.js

@@ -0,0 +1,227 @@
+// ---------------------------------------------------------------------------
+// Graph Loader — loads, validates, and caches ChainGraph JSON files.
+// ---------------------------------------------------------------------------
+import { readFileSync, statSync, readdirSync } from 'node:fs';
+import { readFile, stat } from 'node:fs/promises';
+import { join, relative, sep } from 'node:path';
+// ---------------------------------------------------------------------------
+// Error
+// ---------------------------------------------------------------------------
+export class GraphValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'GraphValidationError';
+    }
+}
+// ---------------------------------------------------------------------------
+// Validation helpers
+// ---------------------------------------------------------------------------
+const REQUIRED_FIELDS = ['id', 'name', 'version', 'entry', 'nodes'];
+function validateGraph(raw, filePath) {
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+        throw new GraphValidationError(`Invalid graph structure in ${filePath}: expected an object`);
+    }
+    const obj = raw;
+    for (const field of REQUIRED_FIELDS) {
+        if (!(field in obj) || obj[field] === undefined) {
+            throw new GraphValidationError(`Missing required field "${field}" in ${filePath}`);
+        }
+    }
+    if (typeof obj.nodes !== 'object' || obj.nodes === null || Array.isArray(obj.nodes)) {
+        throw new GraphValidationError(`"nodes" must be an object in ${filePath}`);
+    }
+    const nodes = obj.nodes;
+    const nodeIds = new Set(Object.keys(nodes));
+    // entry must exist
+    const entry = obj.entry;
+    if (!nodeIds.has(entry)) {
+        throw new GraphValidationError(`Entry node "${entry}" not found in nodes of ${filePath}`);
+    }
+    // Validate all node references
+    for (const [nodeId, node] of Object.entries(nodes)) {
+        if (node === null || typeof node !== 'object')
+            continue;
+        const n = node;
+        validateNodeRefs(nodeId, n, nodeIds, filePath);
+        validateNodeOutputContract(nodeId, n, filePath);
+    }
+    return raw;
+}
+function validateNodeOutputContract(nodeId, node, filePath) {
+    if (node.type !== 'command')
+        return;
+    if (typeof node.cmd !== 'string' || node.cmd.trim().length === 0) {
+        throw new GraphValidationError(`Command node "${nodeId}" has empty "cmd" in ${filePath}`);
+    }
+    const extract = node.extract;
+    if (!extract || typeof extract !== 'object' || Array.isArray(extract))
+        return;
+    for (const [ruleId, rawRule] of Object.entries(extract)) {
+        if (!rawRule || typeof rawRule !== 'object' || Array.isArray(rawRule)) {
+            throw new GraphValidationError(`Command node "${nodeId}" has invalid extract rule "${ruleId}" in ${filePath}`);
+        }
+        const rule = rawRule;
+        if (!rule.target || rule.target.trim().length === 0) {
+            throw new GraphValidationError(`Command node "${nodeId}" extract rule "${ruleId}" has empty target in ${filePath}`);
+        }
+        if (!rule.pattern || rule.pattern.trim().length === 0) {
+            throw new GraphValidationError(`Command node "${nodeId}" extract rule "${ruleId}" has empty pattern in ${filePath}`);
+        }
+        if (rule.strategy === 'json_path') {
+            throw new GraphValidationError(`Command node "${nodeId}" extract rule "${ruleId}" uses unsupported strategy "json_path" in ${filePath}`);
+        }
+        if (rule.strategy === 'regex') {
+            try {
+                new RegExp(rule.pattern);
+            }
+            catch {
+                throw new GraphValidationError(`Command node "${nodeId}" extract rule "${ruleId}" has invalid regex pattern in ${filePath}`);
+            }
+            if (!rule.pattern.includes('(')) {
+                throw new GraphValidationError(`Command node "${nodeId}" extract rule "${ruleId}" regex must include a capture group in ${filePath}`);
+            }
+        }
+    }
+}
+function validateNodeRefs(nodeId, node, nodeIds, filePath) {
+    const check = (field, target) => {
+        if (!nodeIds.has(target)) {
+            throw new GraphValidationError(`Node "${nodeId}" references non-existent node "${target}" via "${field}" in ${filePath}`);
+        }
+    };
+    // next (command, join, eval)
+    if (typeof node.next === 'string')
+        check('next', node.next);
+    // on_failure (command)
+    if (typeof node.on_failure === 'string')
+        check('on_failure', node.on_failure);
+    // on_pass / on_fail (gate)
+    if (typeof node.on_pass === 'string')
+        check('on_pass', node.on_pass);
+    if (typeof node.on_fail === 'string')
+        check('on_fail', node.on_fail);
+    // edges[].target (decision)
+    if (Array.isArray(node.edges)) {
+        for (const edge of node.edges) {
+            if (edge && typeof edge === 'object' && typeof edge.target === 'string') {
+                check('edges[].target', edge.target);
+            }
+        }
+    }
+    // branches + join (fork)
+    if (Array.isArray(node.branches)) {
+        for (const branch of node.branches) {
+            if (typeof branch === 'string')
+                check('branches[]', branch);
+        }
+    }
+    if (node.type === 'fork' && typeof node.join === 'string') {
+        check('join', node.join);
+    }
+}
+// ---------------------------------------------------------------------------
+// GraphLoader
+// ---------------------------------------------------------------------------
+export class GraphLoader {
+    chainsRoot;
+    cache = new Map();
+    constructor(chainsRoot) {
+        this.chainsRoot = chainsRoot;
+    }
+    async load(graphId) {
+        const filePath = this.resolvePath(graphId);
+        // Check mtime for cache
+        let fileStat;
+        try {
+            fileStat = await stat(filePath);
+        }
+        catch {
+            throw new GraphValidationError(`Graph file not found: ${filePath}`);
+        }
+        const mtime = fileStat.mtimeMs;
+        const cached = this.cache.get(filePath);
+        if (cached && cached.mtime === mtime) {
+            return cached.graph;
+        }
+        let content;
+        try {
+            content = await readFile(filePath, 'utf-8');
+        }
+        catch {
+            throw new GraphValidationError(`Failed to read graph file: ${filePath}`);
+        }
+        const graph = this.parseAndValidate(content, filePath);
+        this.cache.set(filePath, { graph, mtime });
+        return graph;
+    }
+    loadSync(graphId) {
+        const filePath = this.resolvePath(graphId);
+        let fileStat;
+        try {
+            fileStat = statSync(filePath);
+        }
+        catch {
+            throw new GraphValidationError(`Graph file not found: ${filePath}`);
+        }
+        const mtime = fileStat.mtimeMs;
+        const cached = this.cache.get(filePath);
+        if (cached && cached.mtime === mtime) {
+            return cached.graph;
+        }
+        let content;
+        try {
+            content = readFileSync(filePath, 'utf-8');
+        }
+        catch {
+            throw new GraphValidationError(`Failed to read graph file: ${filePath}`);
+        }
+        const graph = this.parseAndValidate(content, filePath);
+        this.cache.set(filePath, { graph, mtime });
+        return graph;
+    }
+    listAll() {
+        const results = [];
+        this.walkDir(this.chainsRoot, results);
+        return results.sort();
+    }
+    // -------------------------------------------------------------------------
+    // Private
+    // -------------------------------------------------------------------------
+    resolvePath(graphId) {
+        return join(this.chainsRoot, `${graphId}.json`);
+    }
+    parseAndValidate(content, filePath) {
+        let raw;
+        try {
+            raw = JSON.parse(content);
+        }
+        catch {
+            throw new GraphValidationError(`Invalid JSON in ${filePath}`);
+        }
+        return validateGraph(raw, filePath);
+    }
+    walkDir(dir, results) {
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (entry.name.startsWith('_'))
+                continue;
+            const fullPath = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                this.walkDir(fullPath, results);
+            }
+            else if (entry.isFile() && entry.name.endsWith('.json')) {
+                const rel = relative(this.chainsRoot, fullPath);
+                // Convert to forward-slash graph ID without .json
+                const graphId = rel.replace(/\.json$/, '').split(sep).join('/');
+                results.push(graphId);
+            }
+        }
+    }
+}
+//# sourceMappingURL=graph-loader.js.map

package/dashboard/dist-server/src/coordinator/graph-loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-loader.js","sourceRoot":"","sources":["../../../../src/coordinator/graph-loader.ts"],"names":[],"mappings":"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"}

package/dashboard/dist-server/src/coordinator/graph-types.d.ts

@@ -0,0 +1,335 @@
+export interface ChainGraph {
+    $schema?: string;
+    id: string;
+    name: string;
+    description?: string;
+    version: string;
+    tags?: string[];
+    entry: string;
+    inputs?: Record<string, GraphInput>;
+    nodes: Record<string, GraphNode>;
+    defaults?: GraphDefaults;
+}
+export interface GraphInput {
+    type: 'string' | 'number' | 'boolean';
+    required?: boolean;
+    default?: string | number | boolean;
+    description?: string;
+}
+export interface GraphDefaults {
+    timeout_ms?: number;
+    analyze?: boolean;
+    max_visits?: number;
+    auto_flag?: string;
+    retry?: RetryPolicy;
+    auto_continue_on_failure?: boolean;
+}
+export type GraphNode = CommandNode | DecisionNode | GateNode | ForkNode | JoinNode | EvalNode | TerminalNode;
+export interface CommandNode {
+    type: 'command';
+    cmd: string;
+    args?: string;
+    description?: string;
+    auto_flag?: string;
+    next: string;
+    on_failure?: string;
+    max_visits?: number;
+    timeout_ms?: number;
+    analyze?: boolean;
+    retry?: RetryPolicy;
+    auto_continue_on_failure?: boolean;
+    extract?: Record<string, ExtractionRule>;
+}
+export interface RetryPolicy {
+    max_attempts?: number;
+    base_backoff_ms?: number;
+    max_backoff_ms?: number;
+}
+export interface ExtractionRule {
+    strategy: 'regex' | 'json_path' | 'line_match';
+    pattern: string;
+    target: string;
+}
+export interface DecisionNode {
+    type: 'decision';
+    strategy?: 'expr' | 'llm';
+    eval?: string;
+    prompt?: string;
+    context_keys?: string[];
+    edges: DecisionEdge[];
+}
+export interface DecisionEdge {
+    value?: string | number | boolean;
+    match?: string;
+    label?: string;
+    default?: boolean;
+    target: string;
+    description?: string;
+}
+export interface GateNode {
+    type: 'gate';
+    condition: string;
+    on_pass: string;
+    on_fail: string;
+    wait?: boolean;
+    wait_message?: string;
+}
+export interface ForkNode {
+    type: 'fork';
+    branches: string[];
+    join: string;
+}
+export interface JoinNode {
+    type: 'join';
+    strategy: 'all' | 'any' | 'majority';
+    next: string;
+    merge?: 'concat' | 'last' | 'best_score';
+}
+export interface EvalNode {
+    type: 'eval';
+    set: Record<string, string>;
+    next: string;
+}
+export interface TerminalNode {
+    type: 'terminal';
+    status: 'success' | 'failure' | 'paused' | 'delegate';
+    delegate_graph?: string;
+    delegate_inputs?: Record<string, string>;
+    summary?: string;
+}
+export type WalkerStatus = 'running' | 'waiting_command' | 'waiting_gate' | 'waiting_fork' | 'step_paused' | 'paused' | 'completed' | 'failed';
+export interface WalkerState {
+    session_id: string;
+    graph_id: string;
+    current_node: string;
+    status: WalkerStatus;
+    context: WalkerContext;
+    history: HistoryEntry[];
+    fork_state: Record<string, ForkBranchState> | null;
+    delegate_stack: DelegateFrame[];
+    created_at: string;
+    updated_at: string;
+    tool: string;
+    auto_mode: boolean;
+    step_mode: boolean;
+    intent: string;
+    recovery?: RecoveryState;
+}
+export interface WalkerContext {
+    inputs: Record<string, unknown>;
+    project: ProjectSnapshot;
+    result: Record<string, unknown> | null;
+    analysis: Record<string, unknown> | null;
+    visits: Record<string, number>;
+    var: Record<string, unknown>;
+}
+export interface ProjectSnapshot {
+    initialized: boolean;
+    current_phase: number | null;
+    phase_status: string;
+    artifacts: Record<string, boolean>;
+    execution: {
+        tasks_completed: number;
+        tasks_total: number;
+    };
+    verification_status: string;
+    review_verdict: string | null;
+    uat_status: string;
+    phases_total: number;
+    phases_completed: number;
+    accumulated_context: unknown | null;
+}
+export interface HistoryEntry {
+    node_id: string;
+    node_type: string;
+    entered_at: string;
+    exited_at?: string;
+    outcome?: 'success' | 'failure' | 'skipped';
+    exec_id?: string;
+    quality_score?: number;
+    summary?: string;
+    retry_count?: number;
+    error_message?: string;
+}
+export interface RecoveryState {
+    total_retries: number;
+    total_failures: number;
+    auto_skips: number;
+    consecutive_failures: number;
+    last_error: string | null;
+}
+export interface ForkBranchState {
+    branches: Record<string, 'pending' | 'running' | 'completed' | 'failed'>;
+    join_node: string;
+    results: Record<string, unknown>;
+}
+export interface DelegateFrame {
+    parent_graph_id: string;
+    parent_node_id: string;
+    return_inputs: Record<string, unknown>;
+}
+export type AgentType = 'claude-code' | 'claude' | 'codex' | 'gemini' | 'qwen' | 'opencode';
+export interface ExecuteRequest {
+    prompt: string;
+    agent_type: AgentType;
+    work_dir: string;
+    approval_mode: 'suggest' | 'auto';
+    timeout_ms: number;
+    node_id: string;
+    cmd: string;
+}
+export interface ExecuteResult {
+    success: boolean;
+    raw_output: string;
+    exec_id: string;
+    duration_ms: number;
+    process_id?: string;
+}
+export interface CommandExecutor {
+    execute(request: ExecuteRequest): Promise<ExecuteResult>;
+    abort(): Promise<void>;
+}
+export interface AssembleRequest {
+    node: CommandNode;
+    node_id: string;
+    session_id: string;
+    context: WalkerContext;
+    graph: {
+        id: string;
+        name: string;
+    };
+    command_index: number;
+    command_total: number;
+    auto_mode: boolean;
+    previous_command?: {
+        node_id: string;
+        cmd: string;
+        outcome: 'success' | 'failure';
+        summary?: string;
+    };
+}
+export interface PromptAssembler {
+    assemble(request: AssembleRequest): Promise<string>;
+}
+export interface ExprEvaluator {
+    resolve(expr: string, ctx: WalkerContext): unknown;
+    evaluate(expr: string, ctx: WalkerContext): boolean;
+    match(edge: DecisionEdge, resolvedValue: unknown, ctx: WalkerContext): boolean;
+}
+export interface ParsedResult {
+    structured: {
+        status: 'SUCCESS' | 'FAILURE';
+        phase: string | null;
+        verification_status: string | null;
+        review_verdict: string | null;
+        uat_status: string | null;
+        artifacts: string[];
+        summary: string;
+        [key: string]: unknown;
+    };
+}
+export interface OutputParser {
+    parse(rawOutput: string, node: CommandNode): ParsedResult;
+}
+export interface AnalysisResult {
+    quality_score: number;
+    issues: string[];
+    next_step_hints: {
+        prompt_additions?: string;
+        cautions?: string[];
+        context_to_carry?: string;
+    };
+}
+export interface StepAnalyzer {
+    analyze(node: CommandNode, rawOutput: string, ctx: WalkerContext, prevCmd?: AssembleRequest['previous_command']): Promise<AnalysisResult>;
+}
+export interface LLMDecisionRequest {
+    node_id: string;
+    prompt: string;
+    valid_targets: string[];
+}
+export interface LLMDecisionResult {
+    target: string;
+    reasoning: string;
+}
+export interface LLMDecider {
+    decide(req: LLMDecisionRequest): Promise<LLMDecisionResult | null>;
+}
+export type CoordinateEvent = {
+    type: 'walker:started';
+    session_id: string;
+    graph_id: string;
+    intent: string;
+} | {
+    type: 'walker:node_enter';
+    session_id: string;
+    node_id: string;
+    node_type: string;
+} | {
+    type: 'walker:node_exit';
+    session_id: string;
+    node_id: string;
+    outcome: string;
+} | {
+    type: 'walker:decision';
+    session_id: string;
+    node_id: string;
+    resolved_value: unknown;
+    target: string;
+} | {
+    type: 'walker:command';
+    session_id: string;
+    node_id: string;
+    cmd: string;
+    status: 'spawned' | 'completed' | 'failed';
+} | {
+    type: 'walker:delegate';
+    session_id: string;
+    from_graph: string;
+    to_graph: string;
+} | {
+    type: 'walker:fork_start';
+    session_id: string;
+    node_id: string;
+    branches: string[];
+} | {
+    type: 'walker:branch_complete';
+    session_id: string;
+    node_id: string;
+    branch_id: string;
+    success: boolean;
+} | {
+    type: 'walker:join_complete';
+    session_id: string;
+    node_id: string;
+    strategy: string;
+    success: boolean;
+} | {
+    type: 'walker:completed';
+    session_id: string;
+    status: 'success' | 'failure';
+    history_summary: string[];
+} | {
+    type: 'walker:error';
+    session_id: string;
+    error: string;
+};
+export interface WalkerEventEmitter {
+    emit(event: CoordinateEvent): void;
+}
+export interface IntentPattern {
+    type: string;
+    regex: string;
+    flags?: string;
+    route: IntentRoute;
+}
+export interface IntentRoute {
+    graph?: string;
+    strategy?: 'state_router';
+}
+export interface IntentMap {
+    $schema?: string;
+    version: string;
+    patterns: IntentPattern[];
+    fallback: IntentRoute;
+}

package/dashboard/dist-server/src/coordinator/graph-types.js

@@ -0,0 +1,6 @@
+// ---------------------------------------------------------------------------
+// Graph Coordinator — Type Definitions
+// Pure types, zero runtime. All graph/walker/executor/assembler interfaces.
+// ---------------------------------------------------------------------------
+export {};
+//# sourceMappingURL=graph-types.js.map

package/dashboard/dist-server/src/coordinator/graph-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-types.js","sourceRoot":"","sources":["../../../../src/coordinator/graph-types.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,uCAAuC;AACvC,4EAA4E;AAC5E,8EAA8E"}

package/dashboard/dist-server/src/coordinator/graph-walker.d.ts

@@ -0,0 +1,62 @@
+import type { ChainGraph, WalkerState, CommandExecutor, PromptAssembler, ExprEvaluator, OutputParser, StepAnalyzer, WalkerEventEmitter, LLMDecider } from './graph-types.js';
+import type { GraphLoader } from './graph-loader.js';
+import type { ParallelCommandExecutor } from './parallel-executor.js';
+export interface StartOptions {
+    tool: string;
+    autoMode: boolean;
+    dryRun?: boolean;
+    stepMode?: boolean;
+    workflowRoot: string;
+    inputs?: Record<string, unknown>;
+}
+export declare class GraphWalker {
+    private readonly loader;
+    private readonly assembler;
+    private readonly executor;
+    private readonly analyzer;
+    private readonly outputParser;
+    private readonly evaluator;
+    private readonly emitter?;
+    private readonly sessionDir?;
+    private readonly parallelExecutor?;
+    private readonly llmDecider?;
+    private activeState;
+    constructor(loader: GraphLoader, assembler: PromptAssembler, executor: CommandExecutor, analyzer: StepAnalyzer | null, outputParser: OutputParser, evaluator: ExprEvaluator, emitter?: WalkerEventEmitter | undefined, sessionDir?: string | undefined, parallelExecutor?: ParallelCommandExecutor | undefined, llmDecider?: (LLMDecider | null) | undefined);
+    start(graphId: string, intent: string, options: StartOptions): Promise<WalkerState>;
+    resume(sessionId?: string): Promise<WalkerState>;
+    /** Load session state without executing — for status queries. */
+    getState(sessionId?: string): WalkerState;
+    /** Continue a step_paused session — execute next command node, then pause again. */
+    next(sessionId?: string): Promise<WalkerState>;
+    stop(): Promise<void>;
+    walkGraph(state: WalkerState, graph: ChainGraph): Promise<WalkerState>;
+    private walk;
+    private handleCommand;
+    private handleDecision;
+    private askLLMDecider;
+    private buildDecisionPrompt;
+    private filterContextByKeys;
+    private handleGate;
+    private handleEval;
+    private handleFork;
+    private handleJoin;
+    private handleTerminal;
+    private countCommandNodes;
+    private countCommandsBefore;
+    private findPreviousCommand;
+    private setContextValue;
+    private resolveTemplate;
+    private buildInitialContext;
+    private reportPathFor;
+    private clearNodeReport;
+    private loadNodeResult;
+    private save;
+    private loadState;
+    private dryRunWalk;
+    private emit;
+    private ensureRecovery;
+    private resolveRetryPolicy;
+    private executeWithRetry;
+    private shouldAutoContinue;
+    private buildFailureSummary;
+}