cli4ai 1.2.4 → 1.2.6

package/dist/core/routine-engine.js

@@ -3,8 +3,20 @@
  */
 import { readFileSync } from 'fs';
 import { spawn } from 'child_process';
-import { parse as parseYaml } from 'yaml';
+import { platform } from 'os';
+import { EventEmitter } from 'events';
+import { createInterface } from 'readline';
+import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
+const isWindows = platform() === 'win32';
 import { executeTool, ExecuteToolError } from './execute.js';
+// ═══════════════════════════════════════════════════════════════════════════
+// ROUTINE EVENTS
+// ═══════════════════════════════════════════════════════════════════════════
+/**
+ * Event emitter for routine execution events.
+ * Used by the dashboard for real-time updates.
+ */
+export const routineEvents = new EventEmitter();
 import { remoteRunTool, RemoteConnectionError, RemoteApiError } from './remote-client.js';
 import { getRemote } from './remotes.js';
 export class RoutineParseError extends Error {
@@ -50,6 +62,15 @@ export function loadRoutineDefinition(path) {
     }
     return validateRoutineDefinition(data, path);
 }
+/**
+ * Serialize a routine definition to YAML or JSON string.
+ */
+export function serializeRoutineDefinition(def, format = 'yaml') {
+    if (format === 'json') {
+        return JSON.stringify(def, null, 2);
+    }
+    return stringifyYaml(def, { indent: 2 });
+}
 const INTERVAL_PATTERN = /^(\d+)(s|m|h|d)$/;
 /**
  * Validate a schedule configuration.
@@ -112,111 +133,197 @@ export function validateScheduleConfig(schedule, source) {
     }
     return s;
 }
-function validateRoutineDefinition(value, source) {
-    if (!value || typeof value !== 'object') {
-        throw new RoutineValidationError('Routine must be an object', { source });
+// ═══════════════════════════════════════════════════════════════════════════
+// TYPE GUARDS
+// ═══════════════════════════════════════════════════════════════════════════
+export function isParallelGroup(entry) {
+    return (entry !== null &&
+        typeof entry === 'object' &&
+        'parallel' in entry &&
+        Array.isArray(entry.parallel));
+}
+export function isTryBlock(entry) {
+    return (entry !== null &&
+        typeof entry === 'object' &&
+        'try' in entry &&
+        Array.isArray(entry.try));
+}
+function isRegularStep(entry) {
+    return (entry !== null &&
+        typeof entry === 'object' &&
+        'type' in entry &&
+        'id' in entry);
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// STEP VALIDATION HELPER
+// ═══════════════════════════════════════════════════════════════════════════
+function validateSingleStep(s, ids, source, context) {
+    const contextPrefix = context ? `${context} ` : '';
+    if (typeof s.id !== 'string' || s.id.length === 0) {
+        throw new RoutineValidationError(`${contextPrefix}Step missing "id"`, { source });
     }
-    const obj = value;
-    if (obj.version !== 1) {
-        throw new RoutineValidationError('Invalid or missing "version" (must be 1)', { source, got: obj.version });
+    if (ids.has(s.id)) {
+        throw new RoutineValidationError(`Duplicate step id: ${s.id}`, { source, id: s.id });
     }
-    if (typeof obj.name !== 'string' || obj.name.length === 0) {
-        throw new RoutineValidationError('Invalid or missing "name"', { source, got: obj.name });
+    ids.add(s.id);
+    if (typeof s.type !== 'string' || !['cli4ai', 'set', 'exec'].includes(s.type)) {
+        throw new RoutineValidationError(`Invalid step type for "${s.id}"`, { source, id: s.id, got: s.type });
     }
-    // Validate schedule if present
-    if (obj.schedule !== undefined) {
-        validateScheduleConfig(obj.schedule, source);
+    if (s.timeout !== undefined && typeof s.timeout !== 'number') {
+        throw new RoutineValidationError(`Invalid timeout for "${s.id}" (must be number ms)`, { source, id: s.id, got: s.timeout });
     }
-    if (!Array.isArray(obj.steps)) {
-        throw new RoutineValidationError('Invalid or missing "steps" (must be an array)', { source });
+    if (s.continueOnError !== undefined && typeof s.continueOnError !== 'boolean') {
+        throw new RoutineValidationError(`Invalid continueOnError for "${s.id}" (must be boolean)`, { source, id: s.id, got: s.continueOnError });
     }
-    const steps = obj.steps;
-    const ids = new Set();
-    for (const [idx, step] of steps.entries()) {
-        if (!step || typeof step !== 'object') {
-            throw new RoutineValidationError('Invalid step (must be an object)', { source, index: idx });
+    if (s.type === 'cli4ai') {
+        if (typeof s.package !== 'string' || s.package.length === 0) {
+            throw new RoutineValidationError(`Step "${s.id}" missing "package"`, { source, id: s.id });
+        }
+        if (s.command !== undefined && typeof s.command !== 'string') {
+            throw new RoutineValidationError(`Step "${s.id}" has invalid "command"`, { source, id: s.id });
         }
-        const s = step;
-        if (typeof s.id !== 'string' || s.id.length === 0) {
-            throw new RoutineValidationError('Step missing "id"', { source, index: idx });
+        if (s.args !== undefined && (!Array.isArray(s.args) || s.args.some(a => typeof a !== 'string'))) {
+            throw new RoutineValidationError(`Step "${s.id}" has invalid "args" (must be string array)`, { source, id: s.id });
+        }
+        if (s.env !== undefined) {
+            if (typeof s.env !== 'object' || s.env === null) {
+                throw new RoutineValidationError(`Step "${s.id}" has invalid "env" (must be object)`, { source, id: s.id });
+            }
+            for (const [k, v] of Object.entries(s.env)) {
+                if (typeof v !== 'string') {
+                    throw new RoutineValidationError(`Step "${s.id}" env.${k} must be a string template`, { source, id: s.id });
+                }
+            }
         }
-        if (ids.has(s.id)) {
-            throw new RoutineValidationError(`Duplicate step id: ${s.id}`, { source, id: s.id });
+        if (s.stdin !== undefined && typeof s.stdin !== 'string') {
+            throw new RoutineValidationError(`Step "${s.id}" has invalid "stdin"`, { source, id: s.id });
         }
-        ids.add(s.id);
-        if (typeof s.type !== 'string' || !['cli4ai', 'set', 'exec'].includes(s.type)) {
-            throw new RoutineValidationError(`Invalid step type for "${s.id}"`, { source, id: s.id, got: s.type });
+        if (s.capture !== undefined && !['inherit', 'text', 'json'].includes(String(s.capture))) {
+            throw new RoutineValidationError(`Step "${s.id}" has invalid "capture"`, { source, id: s.id, got: s.capture });
         }
-        if (s.timeout !== undefined && typeof s.timeout !== 'number') {
-            throw new RoutineValidationError(`Invalid timeout for "${s.id}" (must be number ms)`, { source, id: s.id, got: s.timeout });
+        if (s.remote !== undefined && typeof s.remote !== 'string') {
+            throw new RoutineValidationError(`Step "${s.id}" has invalid "remote" (must be string)`, { source, id: s.id, got: s.remote });
         }
-        if (s.continueOnError !== undefined && typeof s.continueOnError !== 'boolean') {
-            throw new RoutineValidationError(`Invalid continueOnError for "${s.id}" (must be boolean)`, { source, id: s.id, got: s.continueOnError });
+    }
+    if (s.type === 'set') {
+        if (typeof s.vars !== 'object' || s.vars === null) {
+            throw new RoutineValidationError(`Step "${s.id}" missing "vars"`, { source, id: s.id });
         }
-        if (s.type === 'cli4ai') {
-            if (typeof s.package !== 'string' || s.package.length === 0) {
-                throw new RoutineValidationError(`Step "${s.id}" missing "package"`, { source, id: s.id });
-            }
-            if (s.command !== undefined && typeof s.command !== 'string') {
-                throw new RoutineValidationError(`Step "${s.id}" has invalid "command"`, { source, id: s.id });
+        for (const [k, v] of Object.entries(s.vars)) {
+            if (typeof v !== 'string') {
+                throw new RoutineValidationError(`Step "${s.id}" vars.${k} must be a string template`, { source, id: s.id });
             }
-            if (s.args !== undefined && (!Array.isArray(s.args) || s.args.some(a => typeof a !== 'string'))) {
-                throw new RoutineValidationError(`Step "${s.id}" has invalid "args" (must be string array)`, { source, id: s.id });
+        }
+    }
+    if (s.type === 'exec') {
+        if (typeof s.cmd !== 'string' || s.cmd.length === 0) {
+            throw new RoutineValidationError(`Step "${s.id}" missing "cmd"`, { source, id: s.id });
+        }
+        if (s.args !== undefined && (!Array.isArray(s.args) || s.args.some(a => typeof a !== 'string'))) {
+            throw new RoutineValidationError(`Step "${s.id}" has invalid "args" (must be string array)`, { source, id: s.id });
+        }
+        if (s.env !== undefined) {
+            if (typeof s.env !== 'object' || s.env === null) {
+                throw new RoutineValidationError(`Step "${s.id}" has invalid "env" (must be object)`, { source, id: s.id });
             }
-            if (s.env !== undefined) {
-                if (typeof s.env !== 'object' || s.env === null) {
-                    throw new RoutineValidationError(`Step "${s.id}" has invalid "env" (must be object)`, { source, id: s.id });
-                }
-                for (const [k, v] of Object.entries(s.env)) {
-                    if (typeof v !== 'string') {
-                        throw new RoutineValidationError(`Step "${s.id}" env.${k} must be a string template`, { source, id: s.id });
-                    }
+            for (const [k, v] of Object.entries(s.env)) {
+                if (typeof v !== 'string') {
+                    throw new RoutineValidationError(`Step "${s.id}" env.${k} must be a string template`, { source, id: s.id });
                 }
             }
-            if (s.stdin !== undefined && typeof s.stdin !== 'string') {
-                throw new RoutineValidationError(`Step "${s.id}" has invalid "stdin"`, { source, id: s.id });
-            }
-            if (s.capture !== undefined && !['inherit', 'text', 'json'].includes(String(s.capture))) {
-                throw new RoutineValidationError(`Step "${s.id}" has invalid "capture"`, { source, id: s.id, got: s.capture });
+        }
+        if (s.stdin !== undefined && typeof s.stdin !== 'string') {
+            throw new RoutineValidationError(`Step "${s.id}" has invalid "stdin"`, { source, id: s.id });
+        }
+        if (s.capture !== undefined && !['text', 'json'].includes(String(s.capture))) {
+            throw new RoutineValidationError(`Step "${s.id}" has invalid "capture"`, { source, id: s.id, got: s.capture });
+        }
+    }
+}
+function validateStepEntry(entry, ids, source, index) {
+    if (!entry || typeof entry !== 'object') {
+        throw new RoutineValidationError('Invalid step entry (must be an object)', { source, index });
+    }
+    // Check if it's a parallel group
+    if (isParallelGroup(entry)) {
+        const pg = entry;
+        if (pg.parallel.length < 1) {
+            throw new RoutineValidationError('Parallel group must have at least one step', { source, index });
+        }
+        if (pg.failFast !== undefined && typeof pg.failFast !== 'boolean') {
+            throw new RoutineValidationError('Parallel group "failFast" must be a boolean', { source, index, got: pg.failFast });
+        }
+        for (const step of pg.parallel) {
+            if (!step || typeof step !== 'object') {
+                throw new RoutineValidationError('Invalid step in parallel group', { source, index });
             }
-            if (s.remote !== undefined && typeof s.remote !== 'string') {
-                throw new RoutineValidationError(`Step "${s.id}" has invalid "remote" (must be string)`, { source, id: s.id, got: s.remote });
+            const s = step;
+            // Validate that parallel steps are not 'set' type (race condition)
+            if (s.type === 'set') {
+                throw new RoutineValidationError(`Step "${s.id}" of type "set" cannot be in a parallel group (race condition)`, { source, id: String(s.id) });
             }
+            validateSingleStep(s, ids, source, 'parallel');
         }
-        if (s.type === 'set') {
-            if (typeof s.vars !== 'object' || s.vars === null) {
-                throw new RoutineValidationError(`Step "${s.id}" missing "vars"`, { source, id: s.id });
+        return;
+    }
+    // Check if it's a try block
+    if (isTryBlock(entry)) {
+        const tb = entry;
+        if (tb.try.length < 1) {
+            throw new RoutineValidationError('Try block must have at least one step', { source, index });
+        }
+        for (const step of tb.try) {
+            if (!step || typeof step !== 'object') {
+                throw new RoutineValidationError('Invalid step in try block', { source, index });
             }
-            for (const [k, v] of Object.entries(s.vars)) {
-                if (typeof v !== 'string') {
-                    throw new RoutineValidationError(`Step "${s.id}" vars.${k} must be a string template`, { source, id: s.id });
+            validateSingleStep(step, ids, source, 'try');
+        }
+        if (tb.catch) {
+            for (const step of tb.catch) {
+                if (!step || typeof step !== 'object') {
+                    throw new RoutineValidationError('Invalid step in catch block', { source, index });
                 }
+                validateSingleStep(step, ids, source, 'catch');
             }
         }
-        if (s.type === 'exec') {
-            if (typeof s.cmd !== 'string' || s.cmd.length === 0) {
-                throw new RoutineValidationError(`Step "${s.id}" missing "cmd"`, { source, id: s.id });
-            }
-            if (s.args !== undefined && (!Array.isArray(s.args) || s.args.some(a => typeof a !== 'string'))) {
-                throw new RoutineValidationError(`Step "${s.id}" has invalid "args" (must be string array)`, { source, id: s.id });
-            }
-            if (s.env !== undefined) {
-                if (typeof s.env !== 'object' || s.env === null) {
-                    throw new RoutineValidationError(`Step "${s.id}" has invalid "env" (must be object)`, { source, id: s.id });
-                }
-                for (const [k, v] of Object.entries(s.env)) {
-                    if (typeof v !== 'string') {
-                        throw new RoutineValidationError(`Step "${s.id}" env.${k} must be a string template`, { source, id: s.id });
-                    }
+        if (tb.finally) {
+            for (const step of tb.finally) {
+                if (!step || typeof step !== 'object') {
+                    throw new RoutineValidationError('Invalid step in finally block', { source, index });
                 }
-            }
-            if (s.stdin !== undefined && typeof s.stdin !== 'string') {
-                throw new RoutineValidationError(`Step "${s.id}" has invalid "stdin"`, { source, id: s.id });
-            }
-            if (s.capture !== undefined && !['text', 'json'].includes(String(s.capture))) {
-                throw new RoutineValidationError(`Step "${s.id}" has invalid "capture"`, { source, id: s.id, got: s.capture });
+                validateSingleStep(step, ids, source, 'finally');
             }
         }
+        return;
+    }
+    // Regular step
+    if (!isRegularStep(entry)) {
+        throw new RoutineValidationError('Invalid step entry (must have type and id, or be parallel/try block)', { source, index });
+    }
+    validateSingleStep(entry, ids, source);
+}
+function validateRoutineDefinition(value, source) {
+    if (!value || typeof value !== 'object') {
+        throw new RoutineValidationError('Routine must be an object', { source });
+    }
+    const obj = value;
+    if (obj.version !== 1) {
+        throw new RoutineValidationError('Invalid or missing "version" (must be 1)', { source, got: obj.version });
+    }
+    if (typeof obj.name !== 'string' || obj.name.length === 0) {
+        throw new RoutineValidationError('Invalid or missing "name"', { source, got: obj.name });
+    }
+    // Validate schedule if present
+    if (obj.schedule !== undefined) {
+        validateScheduleConfig(obj.schedule, source);
+    }
+    if (!Array.isArray(obj.steps)) {
+        throw new RoutineValidationError('Invalid or missing "steps" (must be an array)', { source });
+    }
+    const steps = obj.steps;
+    const ids = new Set();
+    for (const [idx, entry] of steps.entries()) {
+        validateStepEntry(entry, ids, source, idx);
     }
     return obj;
 }
@@ -358,8 +465,9 @@ function collectStream(stream) {
         stream.on('end', () => resolve(Buffer.concat(chunks).toString('utf-8')));
     });
 }
-async function runExecStep(step, ctx, invocationDir) {
+async function runExecStep(step, ctx, invocationDir, callbacks = {}) {
     const startTime = Date.now();
+    const { onStdoutLine, onStderrLine } = callbacks;
     const cmd = renderScalarString(step.cmd, ctx, { stepId: step.id, field: 'cmd' });
     const args = renderStringArray(step.args, ctx, { stepId: step.id, field: 'args' });
     const env = renderEnv(step.env, ctx, { stepId: step.id, field: 'env' });
@@ -367,6 +475,7 @@ async function runExecStep(step, ctx, invocationDir) {
     const child = spawn(cmd, args, {
         cwd: invocationDir,
         stdio: ['pipe', 'pipe', 'pipe'],
+        shell: isWindows,
         env: {
             ...process.env,
             ...(env ?? {})
@@ -377,10 +486,30 @@ async function runExecStep(step, ctx, invocationDir) {
     }
     if (child.stdin)
         child.stdin.end();
-    const stdoutPromise = child.stdout ? collectStream(child.stdout) : Promise.resolve('');
-    const stderrPromise = child.stderr ? collectStream(child.stderr) : Promise.resolve('');
+    // Use line-by-line streaming for callbacks
+    const stdoutLines = [];
+    const stderrLines = [];
+    const readlineInterfaces = [];
+    if (child.stdout) {
+        const rl = createInterface({ input: child.stdout, crlfDelay: Infinity });
+        readlineInterfaces.push(rl);
+        rl.on('line', (line) => {
+            stdoutLines.push(line);
+            if (onStdoutLine) {
+                onStdoutLine(line);
+            }
+        });
+    }
     if (child.stderr) {
-        child.stderr.on('data', (chunk) => process.stderr.write(chunk));
+        const rl = createInterface({ input: child.stderr, crlfDelay: Infinity });
+        readlineInterfaces.push(rl);
+        rl.on('line', (line) => {
+            stderrLines.push(line);
+            process.stderr.write(line + '\n');
+            if (onStderrLine) {
+                onStderrLine(line);
+            }
+        });
     }
     let timeout;
     if (step.timeout && step.timeout > 0) {
@@ -398,13 +527,18 @@ async function runExecStep(step, ctx, invocationDir) {
         }, step.timeout);
     }
     const exitCode = await new Promise((resolve, reject) => {
-        child.on('close', (code) => resolve(code ?? 0));
-        child.on('error', (err) => reject(new ExecuteToolError('API_ERROR', `Failed to execute: ${err.message}`)));
+        child.once('close', (code) => resolve(code ?? 0));
+        child.once('error', (err) => reject(new ExecuteToolError('API_ERROR', `Failed to execute: ${err.message}`)));
     }).finally(() => {
         if (timeout)
             clearTimeout(timeout);
+        // Close all readline interfaces
+        for (const rl of readlineInterfaces) {
+            rl.close();
+        }
     });
-    const [stdout, stderr] = await Promise.all([stdoutPromise, stderrPromise]);
+    const stdout = stdoutLines.length > 0 ? stdoutLines.join('\n') + '\n' : '';
+    const stderr = stderrLines.length > 0 ? stderrLines.join('\n') + '\n' : '';
     const capture = step.capture ?? 'text';
     let json;
     if (capture === 'json') {
@@ -442,7 +576,7 @@ export async function dryRunRoutine(def, vars, invocationDir) {
         steps: {}
     };
     const steps = [];
-    for (const step of def.steps) {
+    function dryRunSingleStep(step) {
         if (step.type === 'set') {
             const renderedVars = {};
             for (const [k, v] of Object.entries(step.vars)) {
@@ -451,8 +585,7 @@ export async function dryRunRoutine(def, vars, invocationDir) {
             // Apply to context for subsequent steps
             for (const [k, v] of Object.entries(renderedVars))
                 ctxVars[k] = v;
-            steps.push({ id: step.id, type: step.type, rendered: { vars: renderedVars } });
-            continue;
+            return { id: step.id, type: step.type, rendered: { vars: renderedVars } };
         }
         if (step.type === 'cli4ai') {
             const rendered = {
@@ -463,8 +596,7 @@ export async function dryRunRoutine(def, vars, invocationDir) {
                 stdin: step.stdin ? renderString(step.stdin, ctx, { stepId: step.id, field: 'stdin', strict: false }) : undefined,
                 timeout: step.timeout
             };
-            steps.push({ id: step.id, type: step.type, rendered });
-            continue;
+            return { id: step.id, type: step.type, rendered };
         }
         if (step.type === 'exec') {
             const rendered = {
@@ -474,9 +606,38 @@ export async function dryRunRoutine(def, vars, invocationDir) {
                 stdin: step.stdin ? renderString(step.stdin, ctx, { stepId: step.id, field: 'stdin', strict: false }) : undefined,
                 timeout: step.timeout
             };
-            steps.push({ id: step.id, type: step.type, rendered });
+            return { id: step.id, type: step.type, rendered };
+        }
+        // Exhaustive check - this should never be reached
+        const _exhaustive = step;
+        throw new Error(`Unknown step type: ${_exhaustive.type}`);
+    }
+    for (const entry of def.steps) {
+        // Handle parallel groups
+        if (isParallelGroup(entry)) {
+            const parallelSteps = entry.parallel.map(s => dryRunSingleStep(s));
+            steps.push({
+                type: 'parallel',
+                steps: parallelSteps,
+                failFast: entry.failFast
+            });
             continue;
         }
+        // Handle try blocks
+        if (isTryBlock(entry)) {
+            const trySteps = entry.try.map(s => dryRunSingleStep(s));
+            const catchSteps = entry.catch?.map(s => dryRunSingleStep(s));
+            const finallySteps = entry.finally?.map(s => dryRunSingleStep(s));
+            steps.push({
+                type: 'try',
+                try: trySteps,
+                catch: catchSteps,
+                finally: finallySteps
+            });
+            continue;
+        }
+        // Regular step
+        steps.push(dryRunSingleStep(entry));
     }
     const result = def.result !== undefined ? renderTemplateValue(def.result, ctx, { field: 'result', strict: false }) : undefined;
     return {
@@ -487,150 +648,279 @@ export async function dryRunRoutine(def, vars, invocationDir) {
         result
     };
 }
-export async function runRoutine(def, vars, invocationDir) {
+async function executeSingleStep(step, execCtx) {
+    const { ctx, ctxVars, stepsById, invocationDir, onStdoutLine, onStderrLine, onStepStart, onStepFinish } = execCtx;
+    // Notify step start
+    if (onStepStart) {
+        onStepStart(step.id, step.type);
+    }
+    if (step.type === 'set') {
+        const assigned = {};
+        for (const [k, v] of Object.entries(step.vars)) {
+            assigned[k] = renderTemplateString(v, ctx, { stepId: step.id, field: `vars.${k}` });
+        }
+        for (const [k, v] of Object.entries(assigned))
+            ctxVars[k] = v;
+        const res = {
+            id: step.id,
+            type: step.type,
+            status: 'success',
+            exitCode: 0,
+            durationMs: 0,
+            json: assigned
+        };
+        stepsById[step.id] = res;
+        if (onStepFinish) {
+            onStepFinish(res);
+        }
+        return res;
+    }
+    if (step.type === 'exec') {
+        const res = await runExecStep(step, ctx, invocationDir, {
+            onStdoutLine: onStdoutLine ? (line) => onStdoutLine(step.id, line) : undefined,
+            onStderrLine: onStderrLine ? (line) => onStderrLine(step.id, line) : undefined,
+        });
+        stepsById[step.id] = res;
+        if (onStepFinish) {
+            onStepFinish(res);
+        }
+        return res;
+    }
+    if (step.type === 'cli4ai') {
+        const pkg = renderScalarString(step.package, ctx, { stepId: step.id, field: 'package' });
+        const cmd = step.command !== undefined ? renderScalarString(step.command, ctx, { stepId: step.id, field: 'command' }) : undefined;
+        const args = renderStringArray(step.args, ctx, { stepId: step.id, field: 'args' });
+        const env = renderEnv(step.env, ctx, { stepId: step.id, field: 'env' });
+        const stdin = step.stdin !== undefined ? renderString(step.stdin, ctx, { stepId: step.id, field: 'stdin' }) : undefined;
+        const remoteName = step.remote !== undefined ? renderScalarString(step.remote, ctx, { stepId: step.id, field: 'remote' }) : undefined;
+        const capture = step.capture ?? 'text';
+        let execResult;
+        if (remoteName) {
+            const remote = getRemote(remoteName);
+            if (!remote) {
+                throw new ExecuteToolError('NOT_FOUND', `Remote "${remoteName}" not found`, {
+                    step: step.id,
+                    hint: 'Use "cli4ai remotes add <name> <url>" to configure a remote'
+                });
+            }
+            const remoteRes = await remoteRunTool(remoteName, {
+                package: pkg,
+                command: cmd,
+                args,
+                env: Object.keys(env).length > 0 ? env : undefined,
+                stdin,
+                timeout: step.timeout
+            });
+            execResult = {
+                exitCode: remoteRes.exitCode,
+                durationMs: remoteRes.durationMs,
+                stdout: remoteRes.stdout,
+                stderr: remoteRes.stderr
+            };
+            if (remoteRes.stderr) {
+                process.stderr.write(remoteRes.stderr);
+            }
+            if (remoteRes.error && !remoteRes.success) {
+                throw new ExecuteToolError(remoteRes.error.code, remoteRes.error.message, remoteRes.error.details);
+            }
+        }
+        else {
+            const localRes = await executeTool({
+                packageName: pkg,
+                command: cmd,
+                args,
+                cwd: invocationDir,
+                env,
+                stdin,
+                capture: 'pipe',
+                timeoutMs: step.timeout,
+                teeStderr: true,
+                onStdoutLine: onStdoutLine ? (line) => onStdoutLine(step.id, line) : undefined,
+                onStderrLine: onStderrLine ? (line) => onStderrLine(step.id, line) : undefined,
+            });
+            execResult = {
+                exitCode: localRes.exitCode,
+                durationMs: localRes.durationMs,
+                stdout: localRes.stdout,
+                stderr: localRes.stderr
+            };
+        }
+        const res = {
+            id: step.id,
+            type: step.type,
+            status: execResult.exitCode === 0 ? 'success' : 'failed',
+            exitCode: execResult.exitCode,
+            durationMs: execResult.durationMs,
+            stdout: execResult.stdout,
+            stderr: execResult.stderr
+        };
+        if (capture === 'json') {
+            try {
+                res.json = execResult.stdout ? JSON.parse(execResult.stdout) : null;
+            }
+            catch {
+                throw new RoutineTemplateError(`JSON parse error in step "${step.id}": stdout is not valid JSON`, {
+                    step: step.id,
+                    stdout: (execResult.stdout ?? '').slice(0, 200)
+                });
+            }
+        }
+        stepsById[step.id] = res;
+        if (onStepFinish) {
+            onStepFinish(res);
+        }
+        return res;
+    }
+    throw new Error(`Unknown step type: ${step.type}`);
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// PARALLEL EXECUTION
+// ═══════════════════════════════════════════════════════════════════════════
+async function runParallelGroup(group, execCtx) {
     const startTime = Date.now();
-    const ctxVars = {};
-    for (const [k, v] of Object.entries(def.vars ?? {})) {
-        if (v.default !== undefined)
-            ctxVars[k] = v.default;
+    const failFast = group.failFast !== false; // default true
+    // Run all steps in parallel
+    const promises = group.parallel.map(async (step) => {
+        try {
+            return await executeSingleStep(step, execCtx);
+        }
+        catch (err) {
+            const error = normalizeError(err);
+            const res = {
+                id: step.id,
+                type: step.type,
+                status: 'failed',
+                exitCode: 1,
+                error
+            };
+            execCtx.stepsById[step.id] = res;
+            return res;
+        }
+    });
+    // Wait for all to complete (always use allSettled for consistent behavior)
+    const settled = await Promise.allSettled(promises);
+    const results = [];
+    let failed = false;
+    for (const outcome of settled) {
+        if (outcome.status === 'fulfilled') {
+            results.push(outcome.value);
+            if (outcome.value.status === 'failed') {
+                failed = true;
+            }
+        }
+        else {
+            // This shouldn't happen since we catch errors above, but handle it
+            failed = true;
+        }
     }
-    for (const [k, v] of Object.entries(vars))
-        ctxVars[k] = v;
-    const stepsById = {};
-    const ctx = {
-        vars: ctxVars,
-        steps: stepsById
-    };
-    const steps = [];
-    for (const step of def.steps) {
-        if (step.type === 'set') {
-            const assigned = {};
-            for (const [k, v] of Object.entries(step.vars)) {
-                assigned[k] = renderTemplateString(v, ctx, { stepId: step.id, field: `vars.${k}` });
+    // Add results to the steps array
+    for (const res of results) {
+        execCtx.steps.push(res);
+    }
+    return { results, failed };
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// TRY/CATCH EXECUTION
+// ═══════════════════════════════════════════════════════════════════════════
+async function runTryBlock(block, execCtx) {
+    const { ctx, stepsById, steps } = execCtx;
+    const results = [];
+    let failed = false;
+    let caught = false;
+    let errorContext;
+    // Execute try steps
+    for (const step of block.try) {
+        try {
+            const res = await executeSingleStep(step, execCtx);
+            results.push(res);
+            steps.push(res);
+            if (res.status === 'failed') {
+                failed = true;
+                errorContext = {
+                    stepId: step.id,
+                    stepType: step.type,
+                    code: res.error?.code ?? 'EXIT_CODE',
+                    message: res.error?.message ?? `Step "${step.id}" failed with exit code ${res.exitCode}`,
+                    exitCode: res.exitCode,
+                    stdout: res.stdout,
+                    stderr: res.stderr
+                };
+                // Mark as caught since we have a catch block
+                if (block.catch) {
+                    res.status = 'caught';
+                    caught = true;
+                }
+                break;
             }
-            for (const [k, v] of Object.entries(assigned))
-                ctxVars[k] = v;
+        }
+        catch (err) {
+            const error = normalizeError(err);
             const res = {
                 id: step.id,
                 type: step.type,
-                status: 'success',
-                exitCode: 0,
-                durationMs: 0,
-                json: assigned
+                status: block.catch ? 'caught' : 'failed',
+                exitCode: 1,
+                error
             };
             stepsById[step.id] = res;
+            results.push(res);
             steps.push(res);
-            continue;
+            failed = true;
+            if (block.catch) {
+                caught = true;
+            }
+            errorContext = {
+                stepId: step.id,
+                stepType: step.type,
+                code: error.code,
+                message: error.message,
+                exitCode: 1
+            };
+            break;
         }
-        if (step.type === 'exec') {
+    }
+    // Execute catch steps if there was an error and we have a catch block
+    if (failed && block.catch && errorContext) {
+        // Add error context to the template context
+        const catchCtx = { ...ctx, error: errorContext };
+        for (const step of block.catch) {
             try {
-                const res = await runExecStep(step, ctx, invocationDir);
-                stepsById[step.id] = res;
+                // Create a modified exec context with the error context
+                const catchExecCtx = {
+                    ...execCtx,
+                    ctx: catchCtx
+                };
+                const res = await executeSingleStep(step, catchExecCtx);
+                results.push(res);
                 steps.push(res);
-                if (res.exitCode !== 0 && !step.continueOnError) {
-                    return finalizeFailure(def, ctxVars, steps, Date.now() - startTime, res.exitCode ?? 1);
+                if (res.status === 'failed' && !step.continueOnError) {
+                    // Catch block itself failed
+                    break;
                 }
-                continue;
             }
             catch (err) {
                 const error = normalizeError(err);
-                const res = { id: step.id, type: step.type, status: 'failed', exitCode: 1, error };
-                stepsById[step.id] = res;
-                steps.push(res);
-                if (!step.continueOnError) {
-                    return finalizeFailure(def, ctxVars, steps, Date.now() - startTime, 1);
-                }
-                continue;
-            }
-        }
-        if (step.type === 'cli4ai') {
-            const pkg = renderScalarString(step.package, ctx, { stepId: step.id, field: 'package' });
-            const cmd = step.command !== undefined ? renderScalarString(step.command, ctx, { stepId: step.id, field: 'command' }) : undefined;
-            const args = renderStringArray(step.args, ctx, { stepId: step.id, field: 'args' });
-            const env = renderEnv(step.env, ctx, { stepId: step.id, field: 'env' });
-            const stdin = step.stdin !== undefined ? renderString(step.stdin, ctx, { stepId: step.id, field: 'stdin' }) : undefined;
-            const remoteName = step.remote !== undefined ? renderScalarString(step.remote, ctx, { stepId: step.id, field: 'remote' }) : undefined;
-            const capture = step.capture ?? 'text';
-            try {
-                let execResult;
-                if (remoteName) {
-                    // Remote execution
-                    const remote = getRemote(remoteName);
-                    if (!remote) {
-                        throw new ExecuteToolError('NOT_FOUND', `Remote "${remoteName}" not found`, {
-                            step: step.id,
-                            hint: 'Use "cli4ai remotes add <name> <url>" to configure a remote'
-                        });
-                    }
-                    const remoteRes = await remoteRunTool(remoteName, {
-                        package: pkg,
-                        command: cmd,
-                        args,
-                        env: Object.keys(env).length > 0 ? env : undefined,
-                        stdin,
-                        timeout: step.timeout
-                    });
-                    execResult = {
-                        exitCode: remoteRes.exitCode,
-                        durationMs: remoteRes.durationMs,
-                        stdout: remoteRes.stdout,
-                        stderr: remoteRes.stderr
-                    };
-                    // Log stderr from remote
-                    if (remoteRes.stderr) {
-                        process.stderr.write(remoteRes.stderr);
-                    }
-                    // Handle remote-level errors
-                    if (remoteRes.error && !remoteRes.success) {
-                        throw new ExecuteToolError(remoteRes.error.code, remoteRes.error.message, remoteRes.error.details);
-                    }
-                }
-                else {
-                    // Local execution
-                    const localRes = await executeTool({
-                        packageName: pkg,
-                        command: cmd,
-                        args,
-                        cwd: invocationDir,
-                        env,
-                        stdin,
-                        capture: 'pipe',
-                        timeoutMs: step.timeout,
-                        teeStderr: true
-                    });
-                    execResult = {
-                        exitCode: localRes.exitCode,
-                        durationMs: localRes.durationMs,
-                        stdout: localRes.stdout,
-                        stderr: localRes.stderr
-                    };
-                }
                 const res = {
                     id: step.id,
                     type: step.type,
-                    status: execResult.exitCode === 0 ? 'success' : 'failed',
-                    exitCode: execResult.exitCode,
-                    durationMs: execResult.durationMs,
-                    stdout: execResult.stdout,
-                    stderr: execResult.stderr
+                    status: 'failed',
+                    exitCode: 1,
+                    error
                 };
-                if (capture === 'json') {
-                    try {
-                        res.json = execResult.stdout ? JSON.parse(execResult.stdout) : null;
-                    }
-                    catch {
-                        throw new RoutineTemplateError(`JSON parse error in step "${step.id}": stdout is not valid JSON`, {
-                            step: step.id,
-                            stdout: (execResult.stdout ?? '').slice(0, 200)
-                        });
-                    }
-                }
                 stepsById[step.id] = res;
+                results.push(res);
+                steps.push(res);
+                break;
+            }
+        }
+    }
+    // Execute finally steps (always)
+    if (block.finally) {
+        for (const step of block.finally) {
+            try {
+                const res = await executeSingleStep(step, execCtx);
+                results.push(res);
                 steps.push(res);
-                if (execResult.exitCode !== 0 && !step.continueOnError) {
-                    return finalizeFailure(def, ctxVars, steps, Date.now() - startTime, execResult.exitCode);
-                }
-                continue;
             }
             catch (err) {
                 const error = normalizeError(err);
@@ -638,15 +928,82 @@ export async function runRoutine(def, vars, invocationDir) {
                     id: step.id,
                     type: step.type,
                     status: 'failed',
-                    exitCode: error.code === 'INTEGRITY_ERROR' ? 1 : 1,
+                    exitCode: 1,
                     error
                 };
                 stepsById[step.id] = res;
+                results.push(res);
                 steps.push(res);
-                if (!step.continueOnError) {
-                    return finalizeFailure(def, ctxVars, steps, Date.now() - startTime, 1);
-                }
-                continue;
+            }
+        }
+    }
+    // If error was caught, we don't propagate failure
+    return { results, failed: failed && !caught, caught };
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// MAIN ROUTINE RUNNER
+// ═══════════════════════════════════════════════════════════════════════════
+export async function runRoutine(def, vars, invocationDir) {
+    const startTime = Date.now();
+    const ctxVars = {};
+    for (const [k, v] of Object.entries(def.vars ?? {})) {
+        if (v.default !== undefined)
+            ctxVars[k] = v.default;
+    }
+    for (const [k, v] of Object.entries(vars))
+        ctxVars[k] = v;
+    const stepsById = {};
+    const ctx = {
+        vars: ctxVars,
+        steps: stepsById
+    };
+    const steps = [];
+    const execCtx = {
+        ctx,
+        ctxVars,
+        stepsById,
+        steps,
+        invocationDir
+    };
+    for (const entry of def.steps) {
+        // Handle parallel groups
+        if (isParallelGroup(entry)) {
+            const { failed } = await runParallelGroup(entry, execCtx);
+            if (failed && (entry.failFast !== false)) {
+                return finalizeFailure(def, ctxVars, steps, Date.now() - startTime, 1);
+            }
+            continue;
+        }
+        // Handle try/catch blocks
+        if (isTryBlock(entry)) {
+            const { failed } = await runTryBlock(entry, execCtx);
+            if (failed) {
+                return finalizeFailure(def, ctxVars, steps, Date.now() - startTime, 1);
+            }
+            continue;
+        }
+        // Regular step
+        const step = entry;
+        try {
+            const res = await executeSingleStep(step, execCtx);
+            steps.push(res);
+            if (res.status === 'failed' && !step.continueOnError) {
+                return finalizeFailure(def, ctxVars, steps, Date.now() - startTime, res.exitCode ?? 1);
+            }
+        }
+        catch (err) {
+            const error = normalizeError(err);
+            const res = {
+                id: step.id,
+                type: step.type,
+                status: 'failed',
+                exitCode: 1,
+                error
+            };
+            stepsById[step.id] = res;
+            steps.push(res);
+            if (!step.continueOnError) {
+                return finalizeFailure(def, ctxVars, steps, Date.now() - startTime, 1);
             }
         }
     }
@@ -697,3 +1054,194 @@ function finalizeFailure(def, vars, steps, durationMs, exitCode) {
         steps
     };
 }
+// ═══════════════════════════════════════════════════════════════════════════
+// TRACKED ROUTINE RUNNER (for dashboard)
+// ═══════════════════════════════════════════════════════════════════════════
+import { randomUUID } from 'crypto';
+/**
+ * Run a routine with event emissions for real-time tracking.
+ * Emits events: run:started, run:log, run:step, run:finished
+ */
+export async function runRoutineTracked(def, vars, invocationDir, options = {}) {
+    const runId = options.runId ?? randomUUID();
+    const triggerType = options.triggerType ?? 'manual';
+    const startTime = Date.now();
+    // Emit run started event
+    routineEvents.emit('run:started', {
+        runId,
+        routineName: def.name,
+        triggerType,
+    });
+    // Set up context variables
+    const ctxVars = {};
+    for (const [k, v] of Object.entries(def.vars ?? {})) {
+        if (v.default !== undefined)
+            ctxVars[k] = v.default;
+    }
+    for (const [k, v] of Object.entries(vars))
+        ctxVars[k] = v;
+    const stepsById = {};
+    const ctx = {
+        vars: ctxVars,
+        steps: stepsById
+    };
+    const steps = [];
+    // Create execution context with live event callbacks
+    const execCtx = {
+        ctx,
+        ctxVars,
+        stepsById,
+        steps,
+        invocationDir,
+        // Emit log events for each output line
+        onStdoutLine: (stepId, line) => {
+            routineEvents.emit('run:log', {
+                runId,
+                stream: 'stdout',
+                line,
+                stepId,
+            });
+        },
+        onStderrLine: (stepId, line) => {
+            routineEvents.emit('run:log', {
+                runId,
+                stream: 'stderr',
+                line,
+                stepId,
+            });
+        },
+        // Emit step start event
+        onStepStart: (stepId, stepType) => {
+            routineEvents.emit('run:step', {
+                runId,
+                stepId,
+                stepType,
+                status: 'running',
+            });
+        },
+        // Emit step finish event
+        onStepFinish: (result) => {
+            routineEvents.emit('run:step', {
+                runId,
+                stepId: result.id,
+                stepType: result.type,
+                status: result.status,
+                exitCode: result.exitCode,
+                durationMs: result.durationMs,
+                stdout: result.stdout,
+                stderr: result.stderr,
+            });
+        },
+    };
+    try {
+        // Execute steps inline (similar to runRoutine but with callbacks)
+        for (const entry of def.steps) {
+            // Handle parallel groups
+            if (isParallelGroup(entry)) {
+                const { failed } = await runParallelGroup(entry, execCtx);
+                if (failed && (entry.failFast !== false)) {
+                    const result = finalizeFailure(def, ctxVars, steps, Date.now() - startTime, 1);
+                    routineEvents.emit('run:finished', {
+                        runId,
+                        status: result.status,
+                        exitCode: result.exitCode,
+                        durationMs: result.durationMs,
+                    });
+                    return { ...result, runId };
+                }
+                continue;
+            }
+            // Handle try/catch blocks
+            if (isTryBlock(entry)) {
+                const { failed } = await runTryBlock(entry, execCtx);
+                if (failed) {
+                    const result = finalizeFailure(def, ctxVars, steps, Date.now() - startTime, 1);
+                    routineEvents.emit('run:finished', {
+                        runId,
+                        status: result.status,
+                        exitCode: result.exitCode,
+                        durationMs: result.durationMs,
+                    });
+                    return { ...result, runId };
+                }
+                continue;
+            }
+            // Regular step
+            const step = entry;
+            try {
+                const res = await executeSingleStep(step, execCtx);
+                steps.push(res);
+                if (res.status === 'failed' && !step.continueOnError) {
+                    const result = finalizeFailure(def, ctxVars, steps, Date.now() - startTime, res.exitCode ?? 1);
+                    routineEvents.emit('run:finished', {
+                        runId,
+                        status: result.status,
+                        exitCode: result.exitCode,
+                        durationMs: result.durationMs,
+                    });
+                    return { ...result, runId };
+                }
+            }
+            catch (err) {
+                const error = normalizeError(err);
+                const res = {
+                    id: step.id,
+                    type: step.type,
+                    status: 'failed',
+                    exitCode: 1,
+                    error
+                };
+                stepsById[step.id] = res;
+                steps.push(res);
+                // Emit step finish event for error
+                routineEvents.emit('run:step', {
+                    runId,
+                    stepId: step.id,
+                    stepType: step.type,
+                    status: 'failed',
+                    exitCode: 1,
+                });
+                if (!step.continueOnError) {
+                    const result = finalizeFailure(def, ctxVars, steps, Date.now() - startTime, 1);
+                    routineEvents.emit('run:finished', {
+                        runId,
+                        status: result.status,
+                        exitCode: result.exitCode,
+                        durationMs: result.durationMs,
+                    });
+                    return { ...result, runId };
+                }
+            }
+        }
+        const resultValue = def.result !== undefined ? renderTemplateValue(def.result, ctx, { field: 'result' }) : undefined;
+        const result = {
+            routine: def.name,
+            version: def.version,
+            status: 'success',
+            exitCode: 0,
+            durationMs: Date.now() - startTime,
+            vars: ctxVars,
+            steps,
+            result: resultValue
+        };
+        // Emit run finished event
+        routineEvents.emit('run:finished', {
+            runId,
+            status: result.status,
+            exitCode: result.exitCode,
+            durationMs: result.durationMs,
+        });
+        return { ...result, runId };
+    }
+    catch (err) {
+        const durationMs = Date.now() - startTime;
+        // Emit failure event
+        routineEvents.emit('run:finished', {
+            runId,
+            status: 'failed',
+            exitCode: 1,
+            durationMs,
+        });
+        throw err;
+    }
+}