cli4ai 1.2.0 → 1.2.2

package/src/core/routine-engine.ts

@@ -1,895 +0,0 @@
-/**
- * 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 {
-  constructor(
-    public path: string,
-    message: string
-  ) {
-    super(message);
-    this.name = 'RoutineParseError';
-  }
-}
-
-export class RoutineValidationError extends Error {
-  constructor(
-    message: string,
-    public details?: Record<string, unknown>
-  ) {
-    super(message);
-    this.name = 'RoutineValidationError';
-  }
-}
-
-export class RoutineTemplateError extends Error {
-  constructor(
-    message: string,
-    public details?: Record<string, unknown>
-  ) {
-    super(message);
-    this.name = 'RoutineTemplateError';
-  }
-}
-
-export type StepCapture = 'inherit' | 'text' | 'json';
-
-// ═══════════════════════════════════════════════════════════════════════════
-// SCHEDULE TYPES
-// ═══════════════════════════════════════════════════════════════════════════
-
-export interface RoutineSchedule {
-  /** Cron expression (e.g., "0 9 * * *" for 9am daily) */
-  cron?: string;
-  /** Simple interval (e.g., "30s", "5m", "1h", "1d") */
-  interval?: string;
-  /** IANA timezone (e.g., "Pacific/Auckland"). Defaults to system timezone */
-  timezone?: string;
-  /** Whether this schedule is active. Defaults to true */
-  enabled?: boolean;
-  /** Number of retry attempts on failure. Defaults to 0 */
-  retries?: number;
-  /** Delay between retries in milliseconds. Defaults to 60000 */
-  retryDelayMs?: number;
-  /** What to do if previous run is still executing. Defaults to 'skip' */
-  concurrency?: 'skip' | 'queue';
-}
-
-export interface RoutineVarDef {
-  default?: string;
-}
-
-export interface RoutineBaseStep {
-  id: string;
-  type: 'cli4ai' | 'set' | 'exec';
-  continueOnError?: boolean;
-  timeout?: number;
-}
-
-export interface RoutineC4aiStep extends RoutineBaseStep {
-  type: 'cli4ai';
-  package: string;
-  command?: string;
-  args?: string[];
-  env?: Record<string, string>;
-  stdin?: string;
-  capture?: StepCapture;
-  /** Name of a configured remote to execute on (optional) */
-  remote?: string;
-}
-
-export interface RoutineSetStep extends RoutineBaseStep {
-  type: 'set';
-  vars: Record<string, string>;
-}
-
-export interface RoutineExecStep extends RoutineBaseStep {
-  type: 'exec';
-  cmd: string;
-  args?: string[];
-  env?: Record<string, string>;
-  stdin?: string;
-  capture?: Exclude<StepCapture, 'inherit'>;
-}
-
-export type RoutineStep = RoutineC4aiStep | RoutineSetStep | RoutineExecStep;
-
-export interface RoutineDefinition {
-  version: 1;
-  name: string;
-  description?: string;
-  mcp?: { expose?: boolean; description?: string };
-  vars?: Record<string, RoutineVarDef>;
-  /** Schedule configuration for automatic execution */
-  schedule?: RoutineSchedule;
-  steps: RoutineStep[];
-  result?: unknown;
-}
-
-export interface StepRunResult {
-  id: string;
-  type: RoutineStep['type'];
-  status: 'success' | 'failed' | 'skipped';
-  exitCode?: number;
-  durationMs?: number;
-  stdout?: string;
-  stderr?: string;
-  json?: unknown;
-  error?: { code: string; message: string; details?: Record<string, unknown> };
-}
-
-export interface RoutineRunSummary {
-  routine: string;
-  version: number;
-  status: 'success' | 'failed';
-  exitCode: number;
-  durationMs: number;
-  vars: Record<string, unknown>;
-  steps: StepRunResult[];
-  result?: unknown;
-}
-
-export interface RoutineDryRunStep {
-  id: string;
-  type: RoutineStep['type'];
-  rendered: Record<string, unknown>;
-}
-
-export interface RoutineDryRunPlan {
-  routine: string;
-  version: number;
-  vars: Record<string, unknown>;
-  steps: RoutineDryRunStep[];
-  result?: unknown;
-}
-
-export function loadRoutineDefinition(path: string): RoutineDefinition {
-  let content: string;
-  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: unknown;
-  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: unknown, source?: string): RoutineSchedule {
-  if (!schedule || typeof schedule !== 'object') {
-    throw new RoutineValidationError('Schedule must be an object', { source });
-  }
-
-  const s = schedule as Record<string, unknown>;
-
-  // 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 as RoutineSchedule;
-}
-
-function validateRoutineDefinition(value: unknown, source?: string): RoutineDefinition {
-  if (!value || typeof value !== 'object') {
-    throw new RoutineValidationError('Routine must be an object', { source });
-  }
-
-  const obj = value as Record<string, unknown>;
-
-  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 as unknown[];
-  const ids = new Set<string>();
-
-  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 as Record<string, unknown>;
-
-    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 as Record<string, unknown>)) {
-          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 as Record<string, unknown>)) {
-        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 as Record<string, unknown>)) {
-          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 as unknown as RoutineDefinition;
-}
-
-function getPath(root: unknown, segments: string[]): unknown {
-  let current: unknown = 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 as Record<string, unknown>)[seg];
-  }
-  return current;
-}
-
-function renderTemplateString(
-  template: string,
-  ctx: Record<string, unknown>,
-  meta: { stepId?: string; field?: string; strict?: boolean }
-): unknown {
-  const regex = /\{\{\s*([^}]+?)\s*\}\}/g;
-  const matches = [...template.matchAll(regex)];
-  if (matches.length === 0) return template;
-
-  const resolveExpr = (expr: string): unknown => {
-    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: string, ctx: Record<string, unknown>, meta: { stepId?: string; field?: string; strict?: boolean }): string {
-  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: string, ctx: Record<string, unknown>, meta: { stepId?: string; field?: string; strict?: boolean }): string {
-  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: string[] | undefined, ctx: Record<string, unknown>, meta: { stepId?: string; field?: string; strict?: boolean }): string[] {
-  if (!values) return [];
-  return values.map((v, i) => renderString(v, ctx, { ...meta, field: `${meta.field ?? 'args'}.${i}` }));
-}
-
-function renderEnv(env: Record<string, string> | undefined, ctx: Record<string, unknown>, meta: { stepId?: string; field?: string; strict?: boolean }): Record<string, string> {
-  if (!env) return {};
-  const out: Record<string, string> = {};
-  for (const [k, v] of Object.entries(env)) {
-    out[k] = renderString(v, ctx, { ...meta, field: `${meta.field ?? 'env'}.${k}` });
-  }
-  return out;
-}
-
-function renderTemplateValue(value: unknown, ctx: Record<string, unknown>, meta: { stepId?: string; field?: string; strict?: boolean }): unknown {
-  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: Record<string, unknown> = {};
-    for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
-      out[k] = renderTemplateValue(v, ctx, { ...meta, field: `${meta.field ?? 'value'}.${k}` });
-    }
-    return out;
-  }
-  return value;
-}
-
-function collectStream(stream: NodeJS.ReadableStream): Promise<string> {
-  return new Promise((resolve, reject) => {
-    const chunks: Buffer[] = [];
-    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: RoutineExecStep, ctx: Record<string, unknown>, invocationDir: string): Promise<StepRunResult> {
-  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: NodeJS.Timeout | undefined;
-  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<number>((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: unknown | undefined;
-  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: RoutineDefinition, vars: Record<string, string>, invocationDir: string): Promise<RoutineDryRunPlan> {
-  const ctxVars: Record<string, unknown> = {};
-
-  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: Record<string, unknown> = {
-    vars: ctxVars,
-    steps: {}
-  };
-
-  const steps: RoutineDryRunStep[] = [];
-
-  for (const step of def.steps) {
-    if (step.type === 'set') {
-      const renderedVars: Record<string, unknown> = {};
-      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: RoutineDefinition, vars: Record<string, string>, invocationDir: string): Promise<RoutineRunSummary> {
-  const startTime = Date.now();
-
-  const ctxVars: Record<string, unknown> = {};
-  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: Record<string, StepRunResult> = {};
-
-  const ctx: Record<string, unknown> = {
-    vars: ctxVars,
-    steps: stepsById
-  };
-
-  const steps: StepRunResult[] = [];
-
-  for (const step of def.steps) {
-    if (step.type === 'set') {
-      const assigned: Record<string, unknown> = {};
-      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: StepRunResult = {
-        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: StepRunResult = { 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: { exitCode: number; durationMs: number; stdout?: string; stderr?: string };
-
-        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: StepRunResult = {
-          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: StepRunResult = {
-          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: unknown): { code: string; message: string; details?: Record<string, unknown> } {
-  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: RoutineDefinition, vars: Record<string, unknown>, steps: StepRunResult[], durationMs: number, exitCode: number): RoutineRunSummary {
-  return {
-    routine: def.name,
-    version: def.version,
-    status: 'failed',
-    exitCode,
-    durationMs,
-    vars,
-    steps
-  };
-}