cli4ai 0.8.0

package/src/core/routine-engine.ts

@@ -0,0 +1,725 @@
+/**
+ * Structured routine runner (v1).
+ */
+
+import { readFileSync } from 'fs';
+import { spawn } from 'child_process';
+import { executeTool, ExecuteToolError } from './execute.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';
+
+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;
+}
+
+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>;
+  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)}`);
+  }
+
+  let data: unknown;
+  try {
+    data = JSON.parse(content);
+  } catch {
+    throw new RoutineParseError(path, 'Invalid JSON');
+  }
+
+  return validateRoutineDefinition(data, path);
+}
+
+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 });
+  }
+
+  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.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 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 capture = step.capture ?? 'text';
+
+      try {
+        const execRes = await executeTool({
+          packageName: pkg,
+          command: cmd,
+          args,
+          cwd: invocationDir,
+          env,
+          stdin,
+          capture: 'pipe',
+          timeoutMs: step.timeout,
+          teeStderr: true
+        });
+
+        const res: StepRunResult = {
+          id: step.id,
+          type: step.type,
+          status: execRes.exitCode === 0 ? 'success' : 'failed',
+          exitCode: execRes.exitCode,
+          durationMs: execRes.durationMs,
+          stdout: execRes.stdout,
+          stderr: execRes.stderr
+        };
+
+        if (capture === 'json') {
+          try {
+            res.json = execRes.stdout ? JSON.parse(execRes.stdout) : null;
+          } catch {
+            throw new RoutineTemplateError(`JSON parse error in step "${step.id}": stdout is not valid JSON`, {
+              step: step.id,
+              stdout: (execRes.stdout ?? '').slice(0, 200)
+            });
+          }
+        }
+
+        stepsById[step.id] = res;
+        steps.push(res);
+
+        if (execRes.exitCode !== 0 && !step.continueOnError) {
+          return finalizeFailure(def, ctxVars, steps, Date.now() - startTime, execRes.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 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
+  };
+}