cli4ai 1.2.0 → 1.2.1

package/dist/core/routine-engine.js

@@ -0,0 +1,699 @@
+/**
+ * Structured routine runner (v1).
+ */
+import { readFileSync } from 'fs';
+import { spawn } from 'child_process';
+import { parse as parseYaml } from 'yaml';
+import { executeTool, ExecuteToolError } from './execute.js';
+import { remoteRunTool, RemoteConnectionError, RemoteApiError } from './remote-client.js';
+import { getRemote } from './remotes.js';
+export class RoutineParseError extends Error {
+    path;
+    constructor(path, message) {
+        super(message);
+        this.path = path;
+        this.name = 'RoutineParseError';
+    }
+}
+export class RoutineValidationError extends Error {
+    details;
+    constructor(message, details) {
+        super(message);
+        this.details = details;
+        this.name = 'RoutineValidationError';
+    }
+}
+export class RoutineTemplateError extends Error {
+    details;
+    constructor(message, details) {
+        super(message);
+        this.details = details;
+        this.name = 'RoutineTemplateError';
+    }
+}
+export function loadRoutineDefinition(path) {
+    let content;
+    try {
+        content = readFileSync(path, 'utf-8');
+    }
+    catch (err) {
+        throw new RoutineParseError(path, `Failed to read: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const isYaml = path.endsWith('.yaml') || path.endsWith('.yml');
+    let data;
+    try {
+        data = isYaml ? parseYaml(content) : JSON.parse(content);
+    }
+    catch (err) {
+        const format = isYaml ? 'YAML' : 'JSON';
+        throw new RoutineParseError(path, `Invalid ${format}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    return validateRoutineDefinition(data, path);
+}
+const INTERVAL_PATTERN = /^(\d+)(s|m|h|d)$/;
+/**
+ * Validate a schedule configuration.
+ * Exported for use by scheduler and tests.
+ */
+export function validateScheduleConfig(schedule, source) {
+    if (!schedule || typeof schedule !== 'object') {
+        throw new RoutineValidationError('Schedule must be an object', { source });
+    }
+    const s = schedule;
+    // Must have either cron or interval (or both)
+    if (s.cron === undefined && s.interval === undefined) {
+        throw new RoutineValidationError('Schedule must have "cron" or "interval"', { source });
+    }
+    // Validate cron (basic format check - full validation happens at runtime with cron-parser)
+    if (s.cron !== undefined) {
+        if (typeof s.cron !== 'string' || s.cron.trim().length === 0) {
+            throw new RoutineValidationError('Schedule "cron" must be a non-empty string', { source, got: s.cron });
+        }
+        // Basic cron format: should have 5 space-separated parts
+        const parts = s.cron.trim().split(/\s+/);
+        if (parts.length < 5 || parts.length > 6) {
+            throw new RoutineValidationError('Schedule "cron" must have 5 or 6 fields', { source, got: s.cron });
+        }
+    }
+    // Validate interval
+    if (s.interval !== undefined) {
+        if (typeof s.interval !== 'string') {
+            throw new RoutineValidationError('Schedule "interval" must be a string', { source, got: s.interval });
+        }
+        if (!INTERVAL_PATTERN.test(s.interval)) {
+            throw new RoutineValidationError('Schedule "interval" must be like "30s", "5m", "1h", or "1d"', { source, got: s.interval });
+        }
+    }
+    // Validate timezone (just check it's a string - actual validation happens at runtime)
+    if (s.timezone !== undefined && typeof s.timezone !== 'string') {
+        throw new RoutineValidationError('Schedule "timezone" must be a string', { source, got: s.timezone });
+    }
+    // Validate enabled
+    if (s.enabled !== undefined && typeof s.enabled !== 'boolean') {
+        throw new RoutineValidationError('Schedule "enabled" must be a boolean', { source, got: s.enabled });
+    }
+    // Validate retries
+    if (s.retries !== undefined) {
+        if (typeof s.retries !== 'number' || !Number.isInteger(s.retries) || s.retries < 0) {
+            throw new RoutineValidationError('Schedule "retries" must be a non-negative integer', { source, got: s.retries });
+        }
+    }
+    // Validate retryDelayMs
+    if (s.retryDelayMs !== undefined) {
+        if (typeof s.retryDelayMs !== 'number' || !Number.isInteger(s.retryDelayMs) || s.retryDelayMs < 0) {
+            throw new RoutineValidationError('Schedule "retryDelayMs" must be a non-negative integer', { source, got: s.retryDelayMs });
+        }
+    }
+    // Validate concurrency
+    if (s.concurrency !== undefined) {
+        if (s.concurrency !== 'skip' && s.concurrency !== 'queue') {
+            throw new RoutineValidationError('Schedule "concurrency" must be "skip" or "queue"', { source, got: s.concurrency });
+        }
+    }
+    return s;
+}
+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, step] of steps.entries()) {
+        if (!step || typeof step !== 'object') {
+            throw new RoutineValidationError('Invalid step (must be an object)', { source, index: idx });
+        }
+        const s = step;
+        if (typeof s.id !== 'string' || s.id.length === 0) {
+            throw new RoutineValidationError('Step missing "id"', { source, index: idx });
+        }
+        if (ids.has(s.id)) {
+            throw new RoutineValidationError(`Duplicate step id: ${s.id}`, { 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.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.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 === '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 });
+            }
+            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 (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.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.type === 'set') {
+            if (typeof s.vars !== 'object' || s.vars === null) {
+                throw new RoutineValidationError(`Step "${s.id}" missing "vars"`, { 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.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 (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 });
+            }
+        }
+    }
+    return obj;
+}
+function getPath(root, segments) {
+    let current = root;
+    for (const seg of segments) {
+        if (current === null || current === undefined)
+            return undefined;
+        if (Array.isArray(current)) {
+            const idx = Number(seg);
+            if (!Number.isInteger(idx))
+                return undefined;
+            current = current[idx];
+            continue;
+        }
+        if (typeof current !== 'object')
+            return undefined;
+        current = current[seg];
+    }
+    return current;
+}
+function renderTemplateString(template, ctx, meta) {
+    const regex = /\{\{\s*([^}]+?)\s*\}\}/g;
+    const matches = [...template.matchAll(regex)];
+    if (matches.length === 0)
+        return template;
+    const resolveExpr = (expr) => {
+        const parts = expr.split('.').map(s => s.trim()).filter(Boolean);
+        const value = getPath(ctx, parts);
+        if (value === undefined) {
+            if (meta.strict === false) {
+                return `{{${expr}}}`;
+            }
+            throw new RoutineTemplateError(`Template error${meta.stepId ? ` in step "${meta.stepId}"` : ''}: path "${expr}" not found`, {
+                step: meta.stepId,
+                field: meta.field,
+                path: expr
+            });
+        }
+        return value;
+    };
+    // If the template is exactly a single {{expr}}, return the raw value.
+    if (matches.length === 1 && matches[0].index === 0 && matches[0][0].length === template.length) {
+        return resolveExpr(matches[0][1]);
+    }
+    let out = '';
+    let lastIndex = 0;
+    for (const m of matches) {
+        const full = m[0];
+        const expr = m[1];
+        const idx = m.index ?? 0;
+        out += template.slice(lastIndex, idx);
+        const value = resolveExpr(expr);
+        if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+            out += String(value);
+        }
+        else {
+            out += JSON.stringify(value);
+        }
+        lastIndex = idx + full.length;
+    }
+    out += template.slice(lastIndex);
+    return out;
+}
+function renderString(value, ctx, meta) {
+    const rendered = renderTemplateString(value, ctx, meta);
+    if (rendered === undefined || rendered === null) {
+        throw new RoutineTemplateError(`Template error${meta.stepId ? ` in step "${meta.stepId}"` : ''}: "${value}" resolved to empty`, {
+            step: meta.stepId,
+            field: meta.field
+        });
+    }
+    if (typeof rendered === 'string')
+        return rendered;
+    if (typeof rendered === 'number' || typeof rendered === 'boolean')
+        return String(rendered);
+    try {
+        return JSON.stringify(rendered);
+    }
+    catch {
+        throw new RoutineTemplateError(`Template error${meta.stepId ? ` in step "${meta.stepId}"` : ''}: "${value}" resolved to non-serializable value`, {
+            step: meta.stepId,
+            field: meta.field
+        });
+    }
+}
+function renderScalarString(value, ctx, meta) {
+    const rendered = renderTemplateString(value, ctx, meta);
+    if (rendered === undefined || rendered === null) {
+        throw new RoutineTemplateError(`Template error${meta.stepId ? ` in step "${meta.stepId}"` : ''}: "${value}" resolved to empty`, {
+            step: meta.stepId,
+            field: meta.field
+        });
+    }
+    if (typeof rendered === 'string' || typeof rendered === 'number' || typeof rendered === 'boolean') {
+        return String(rendered);
+    }
+    throw new RoutineTemplateError(`Template error${meta.stepId ? ` in step "${meta.stepId}"` : ''}: "${value}" did not resolve to a string`, {
+        step: meta.stepId,
+        field: meta.field,
+        gotType: Array.isArray(rendered) ? 'array' : typeof rendered
+    });
+}
+function renderStringArray(values, ctx, meta) {
+    if (!values)
+        return [];
+    return values.map((v, i) => renderString(v, ctx, { ...meta, field: `${meta.field ?? 'args'}.${i}` }));
+}
+function renderEnv(env, ctx, meta) {
+    if (!env)
+        return {};
+    const out = {};
+    for (const [k, v] of Object.entries(env)) {
+        out[k] = renderString(v, ctx, { ...meta, field: `${meta.field ?? 'env'}.${k}` });
+    }
+    return out;
+}
+function renderTemplateValue(value, ctx, meta) {
+    if (typeof value === 'string') {
+        return renderTemplateString(value, ctx, meta);
+    }
+    if (Array.isArray(value)) {
+        return value.map((item, idx) => renderTemplateValue(item, ctx, { ...meta, field: `${meta.field ?? 'value'}.${idx}` }));
+    }
+    if (value && typeof value === 'object') {
+        const out = {};
+        for (const [k, v] of Object.entries(value)) {
+            out[k] = renderTemplateValue(v, ctx, { ...meta, field: `${meta.field ?? 'value'}.${k}` });
+        }
+        return out;
+    }
+    return value;
+}
+function collectStream(stream) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        stream.on('data', (chunk) => chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk))));
+        stream.on('error', reject);
+        stream.on('end', () => resolve(Buffer.concat(chunks).toString('utf-8')));
+    });
+}
+async function runExecStep(step, ctx, invocationDir) {
+    const startTime = Date.now();
+    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' });
+    const stdin = step.stdin !== undefined ? renderString(step.stdin, ctx, { stepId: step.id, field: 'stdin' }) : undefined;
+    const child = spawn(cmd, args, {
+        cwd: invocationDir,
+        stdio: ['pipe', 'pipe', 'pipe'],
+        env: {
+            ...process.env,
+            ...(env ?? {})
+        }
+    });
+    if (stdin !== undefined && child.stdin) {
+        child.stdin.write(stdin);
+    }
+    if (child.stdin)
+        child.stdin.end();
+    const stdoutPromise = child.stdout ? collectStream(child.stdout) : Promise.resolve('');
+    const stderrPromise = child.stderr ? collectStream(child.stderr) : Promise.resolve('');
+    if (child.stderr) {
+        child.stderr.on('data', (chunk) => process.stderr.write(chunk));
+    }
+    let timeout;
+    if (step.timeout && step.timeout > 0) {
+        timeout = setTimeout(() => {
+            try {
+                child.kill('SIGTERM');
+            }
+            catch { }
+            setTimeout(() => {
+                try {
+                    child.kill('SIGKILL');
+                }
+                catch { }
+            }, 250);
+        }, 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}`)));
+    }).finally(() => {
+        if (timeout)
+            clearTimeout(timeout);
+    });
+    const [stdout, stderr] = await Promise.all([stdoutPromise, stderrPromise]);
+    const capture = step.capture ?? 'text';
+    let json;
+    if (capture === 'json') {
+        try {
+            json = JSON.parse(stdout);
+        }
+        catch {
+            throw new RoutineTemplateError(`JSON parse error in step "${step.id}": stdout is not valid JSON`, {
+                step: step.id,
+                stdout: stdout.slice(0, 200)
+            });
+        }
+    }
+    return {
+        id: step.id,
+        type: step.type,
+        status: exitCode === 0 ? 'success' : 'failed',
+        exitCode,
+        durationMs: Date.now() - startTime,
+        stdout,
+        stderr,
+        json
+    };
+}
+export async function dryRunRoutine(def, vars, invocationDir) {
+    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 ctx = {
+        vars: ctxVars,
+        steps: {}
+    };
+    const steps = [];
+    for (const step of def.steps) {
+        if (step.type === 'set') {
+            const renderedVars = {};
+            for (const [k, v] of Object.entries(step.vars)) {
+                renderedVars[k] = renderTemplateString(v, ctx, { stepId: step.id, field: `vars.${k}`, strict: false });
+            }
+            // 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;
+        }
+        if (step.type === 'cli4ai') {
+            const rendered = {
+                package: renderScalarString(step.package, ctx, { stepId: step.id, field: 'package', strict: false }),
+                command: step.command ? renderScalarString(step.command, ctx, { stepId: step.id, field: 'command', strict: false }) : undefined,
+                args: renderStringArray(step.args, ctx, { stepId: step.id, field: 'args', strict: false }),
+                env: renderEnv(step.env, ctx, { stepId: step.id, field: 'env', strict: false }),
+                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;
+        }
+        if (step.type === 'exec') {
+            const rendered = {
+                cmd: renderScalarString(step.cmd, ctx, { stepId: step.id, field: 'cmd', strict: false }),
+                args: renderStringArray(step.args, ctx, { stepId: step.id, field: 'args', strict: false }),
+                env: renderEnv(step.env, ctx, { stepId: step.id, field: 'env', strict: false }),
+                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;
+        }
+    }
+    const result = def.result !== undefined ? renderTemplateValue(def.result, ctx, { field: 'result', strict: false }) : undefined;
+    return {
+        routine: def.name,
+        version: def.version,
+        vars: ctxVars,
+        steps,
+        result
+    };
+}
+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 = [];
+    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}` });
+            }
+            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;
+            steps.push(res);
+            continue;
+        }
+        if (step.type === 'exec') {
+            try {
+                const res = await runExecStep(step, ctx, invocationDir);
+                stepsById[step.id] = res;
+                steps.push(res);
+                if (res.exitCode !== 0 && !step.continueOnError) {
+                    return finalizeFailure(def, ctxVars, steps, Date.now() - startTime, res.exitCode ?? 1);
+                }
+                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
+                };
+                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;
+                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);
+                const res = {
+                    id: step.id,
+                    type: step.type,
+                    status: 'failed',
+                    exitCode: error.code === 'INTEGRITY_ERROR' ? 1 : 1,
+                    error
+                };
+                stepsById[step.id] = res;
+                steps.push(res);
+                if (!step.continueOnError) {
+                    return finalizeFailure(def, ctxVars, steps, Date.now() - startTime, 1);
+                }
+                continue;
+            }
+        }
+    }
+    const result = def.result !== undefined ? renderTemplateValue(def.result, ctx, { field: 'result' }) : undefined;
+    return {
+        routine: def.name,
+        version: def.version,
+        status: 'success',
+        exitCode: 0,
+        durationMs: Date.now() - startTime,
+        vars: ctxVars,
+        steps,
+        result
+    };
+}
+function normalizeError(err) {
+    if (err instanceof ExecuteToolError) {
+        return { code: err.code, message: err.message, details: err.details };
+    }
+    if (err instanceof RemoteConnectionError) {
+        return { code: 'NETWORK_ERROR', message: err.message, details: { remote: err.remoteName, url: err.url } };
+    }
+    if (err instanceof RemoteApiError) {
+        return { code: err.code, message: err.message, details: err.details };
+    }
+    if (err instanceof RoutineTemplateError) {
+        return { code: 'INVALID_INPUT', message: err.message, details: err.details };
+    }
+    if (err instanceof RoutineValidationError) {
+        return { code: 'INVALID_INPUT', message: err.message, details: err.details };
+    }
+    if (err instanceof RoutineParseError) {
+        return { code: 'PARSE_ERROR', message: err.message, details: { path: err.path } };
+    }
+    if (err instanceof Error) {
+        return { code: 'API_ERROR', message: err.message };
+    }
+    return { code: 'API_ERROR', message: String(err) };
+}
+function finalizeFailure(def, vars, steps, durationMs, exitCode) {
+    return {
+        routine: def.name,
+        version: def.version,
+        status: 'failed',
+        exitCode,
+        durationMs,
+        vars,
+        steps
+    };
+}