@tagma/sdk 0.2.8 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tagma/sdk",
-  "version": "0.2.8",
+  "version": "0.3.0",
   "license": "MIT",
   "repository": {
     "type": "git",

package/src/engine.ts

@@ -19,6 +19,26 @@ import {
 import { Logger, tailLines, clip, type LogLevel } from './logger';
 import { InMemoryApprovalGateway, type ApprovalGateway } from './approval';
 
+// ═══ A7: Typed trigger errors ═══
+// Replace string-matching on error messages with structured error types so
+// coincidental substrings don't cause misclassification.
+
+export class TriggerBlockedError extends Error {
+  readonly code = 'TRIGGER_BLOCKED' as const;
+  constructor(message: string) {
+    super(message);
+    this.name = 'TriggerBlockedError';
+  }
+}
+
+export class TriggerTimeoutError extends Error {
+  readonly code = 'TRIGGER_TIMEOUT' as const;
+  constructor(message: string) {
+    super(message);
+    this.name = 'TriggerTimeoutError';
+  }
+}
+
 // ═══ Preflight Validation ═══
 
 function preflight(config: PipelineConfig, dag: Dag): void {
@@ -420,20 +440,32 @@ export async function runPipeline(
         });
         log.debug(`[task:${taskId}]`, `trigger fired`);
       } catch (err: unknown) {
-        const msg = err instanceof Error ? err.message : String(err);
         // If pipeline was aborted while we were still waiting for the trigger,
         // this task never entered running state → skipped, not timeout.
         state.finishedAt = nowISO();
         if (pipelineAborted) {
           setTaskStatus(taskId, 'skipped');
-        } else if (msg.includes('rejected') || msg.includes('denied')) {
+        } else if (err instanceof TriggerBlockedError) {
           setTaskStatus(taskId, 'blocked');       // user/policy rejection
-        } else if (msg.includes('timeout')) {
+        } else if (err instanceof TriggerTimeoutError) {
           setTaskStatus(taskId, 'timeout');       // genuine trigger wait timeout
         } else {
-          setTaskStatus(taskId, 'failed');        // plugin error, watcher crash, etc.
+          // A7 fallback: also check message strings for backward-compat with
+          // third-party trigger plugins that don't throw typed errors yet.
+          const msg = err instanceof Error ? err.message : String(err);
+          if (msg.includes('rejected') || msg.includes('denied')) {
+            setTaskStatus(taskId, 'blocked');
+          } else if (msg.includes('timeout')) {
+            setTaskStatus(taskId, 'timeout');
+          } else {
+            setTaskStatus(taskId, 'failed');      // plugin error, watcher crash, etc.
+          }
+        }
+        try {
+          await fireHook(taskId, 'task_failure');
+        } catch (hookErr) {
+          log.error(`[task:${taskId}]`, `hook execution failed: ${hookErr instanceof Error ? hookErr.message : String(hookErr)}`);
         }
-        await fireHook(taskId, 'task_failure');
         return;
       }
     }
@@ -448,7 +480,11 @@ export async function runPipeline(
     if (!hookResult.allowed) {
       state.finishedAt = nowISO();
       setTaskStatus(taskId, 'blocked');
-      await fireHook(taskId, 'task_failure');
+      try {
+        await fireHook(taskId, 'task_failure');
+      } catch (hookErr) {
+        log.error(`[task:${taskId}]`, `hook execution failed: ${hookErr instanceof Error ? hookErr.message : String(hookErr)}`);
+      }
       return;
     }
 
@@ -628,7 +664,11 @@ export async function runPipeline(
 
     // 7. Fire hooks
     const finalStatus: TaskStatus = state.status;
-    await fireHook(taskId, finalStatus === 'success' ? 'task_success' : 'task_failure');
+    try {
+      await fireHook(taskId, finalStatus === 'success' ? 'task_success' : 'task_failure');
+    } catch (hookErr) {
+      log.error(`[task:${taskId}]`, `hook execution failed: ${hookErr instanceof Error ? hookErr.message : String(hookErr)}`);
+    }
 
     // 8. Handle stop_all for failure states
     if (finalStatus !== 'success' && getOnFailure(taskId) === 'stop_all') {

package/src/hooks.ts

@@ -79,6 +79,9 @@ async function runSingleHook(
     }
 
     return exitCode;
+  } catch (err) {
+    console.error(`[hook: ${command}] spawn error: ${err instanceof Error ? err.message : String(err)}`);
+    return -1;
   } finally {
     if (timer) clearTimeout(timer);
     if (signal) signal.removeEventListener('abort', onAbort);

package/src/schema.ts

@@ -216,6 +216,32 @@ function expandTemplateTask(
 // ═══ Config Inheritance Resolution ═══
 
 export function resolveConfig(raw: RawPipelineConfig, workDir: string): PipelineConfig {
+  // Build qualified ID set for resolving bare continue_from references
+  const allQualifiedIds = new Set<string>();
+  for (const t of raw.tracks) {
+    if (!t.id) continue;
+    for (const tk of t.tasks ?? []) {
+      if (tk.id) allQualifiedIds.add(`${t.id}.${tk.id}`);
+    }
+  }
+
+  function qualifyContinueFrom(ref: string, trackId: string): string {
+    // Already qualified
+    if (allQualifiedIds.has(ref)) return ref;
+    // Same-track shorthand
+    const sameTrack = `${trackId}.${ref}`;
+    if (allQualifiedIds.has(sameTrack)) return sameTrack;
+    // Cross-track bare lookup — must be unambiguous
+    let match: string | null = null;
+    for (const qid of allQualifiedIds) {
+      if (qid.endsWith(`.${ref}`)) {
+        if (match !== null) return ref; // ambiguous — leave as-is
+        match = qid;
+      }
+    }
+    return match ?? ref; // not found — leave as-is (validated elsewhere)
+  }
+
   const tracks: TrackConfig[] = raw.tracks.map(rawTrack => {
     const trackDriver = rawTrack.driver ?? raw.driver;
     // validatePath enforces no .. traversal and no absolute paths escaping workDir.
@@ -232,7 +258,9 @@ export function resolveConfig(raw: RawPipelineConfig, workDir: string): Pipeline
         command: rawTask.command,
         depends_on: rawTask.depends_on,
         trigger: rawTask.trigger,
-        continue_from: rawTask.continue_from,
+        continue_from: rawTask.continue_from
+          ? qualifyContinueFrom(rawTask.continue_from, rawTrack.id)
+          : undefined,
         output: rawTask.output,
         // Inheritance: Task > Track
         model_tier: rawTask.model_tier ?? rawTrack.model_tier ?? 'medium',

package/src/sdk.ts

@@ -4,7 +4,7 @@
 // The CLI (src/index.ts in the CLI project) also imports from here.
 
 // ── Core engine ──
-export { runPipeline } from './engine';
+export { runPipeline, TriggerBlockedError, TriggerTimeoutError } from './engine';
 export type { EngineResult, RunPipelineOptions, PipelineEvent } from './engine';
 
 // ── Pipeline runner (multi-pipeline lifecycle management) ──

package/src/triggers/file.ts

@@ -3,6 +3,7 @@ import { resolve, dirname } from 'path';
 import { mkdir } from 'fs/promises';
 import type { TriggerPlugin, TriggerContext } from '../types';
 import { parseDuration, validatePath } from '../utils';
+import { TriggerTimeoutError } from '../engine';
 
 const IS_WINDOWS = process.platform === 'win32';
 
@@ -118,7 +119,7 @@ export const FileTrigger: TriggerPlugin = {
         timer = setTimeout(() => {
           if (settled) return;
           cleanup();
-          reject(new Error(`file trigger timeout: ${filePath} did not appear within ${config.timeout}`));
+          reject(new TriggerTimeoutError(`file trigger timeout: ${filePath} did not appear within ${config.timeout}`));
         }, timeoutMs);
       }
 

package/src/triggers/manual.ts

@@ -1,5 +1,6 @@
 import type { TriggerPlugin, TriggerContext } from '../types';
 import { parseDuration } from '../utils';
+import { TriggerBlockedError, TriggerTimeoutError } from '../engine';
 
 export const ManualTrigger: TriggerPlugin = {
   name: 'manual',
@@ -66,14 +67,15 @@ export const ManualTrigger: TriggerPlugin = {
       case 'approved':
         return { confirmed: true, approvalId: decision.approvalId, actor: decision.actor };
       case 'rejected':
-        throw new Error(
+        // A7: Use typed error for proper classification in the engine.
+        throw new TriggerBlockedError(
           `Manual trigger rejected by ${decision.actor ?? 'user'}` +
             (decision.reason ? `: ${decision.reason}` : ''),
         );
       case 'timeout':
-        throw new Error(`Manual trigger timeout: ${decision.reason ?? 'no decision made'}`);
+        throw new TriggerTimeoutError(`Manual trigger timeout: ${decision.reason ?? 'no decision made'}`);
       case 'aborted':
-        throw new Error(`Manual trigger aborted: ${decision.reason ?? 'pipeline aborted'}`);
+        throw new TriggerBlockedError(`Manual trigger aborted: ${decision.reason ?? 'pipeline aborted'}`);
     }
   },
 };

package/src/validate-raw.ts

@@ -8,6 +8,14 @@
 
 import type { RawPipelineConfig } from './types';
 
+const DURATION_RE = /^(\d*\.?\d+)\s*(s|m|h|d)$/;
+function isValidDuration(input: string): boolean {
+  return DURATION_RE.test(input.trim());
+}
+
+const VALID_ON_FAILURE = new Set(['skip_downstream', 'stop_all', 'ignore']);
+const VALID_MODEL_TIERS = new Set(['low', 'medium', 'high']);
+
 export interface ValidationError {
   /** JSONPath-style location, e.g. "tracks[0].tasks[1].prompt" */
   path: string;
@@ -57,16 +65,27 @@ export function validateRaw(config: RawPipelineConfig): ValidationError[] {
   }
 
   // ── Per-track validation ──
+  const seenTrackIds = new Set<string>();
   for (let ti = 0; ti < config.tracks.length; ti++) {
     const track = config.tracks[ti];
     const trackPath = `tracks[${ti}]`;
 
     if (!track.id?.trim()) {
       errors.push({ path: `${trackPath}.id`, message: 'Track id is required' });
+    } else if (seenTrackIds.has(track.id)) {
+      errors.push({ path: `${trackPath}.id`, message: `Duplicate track id "${track.id}"` });
+    } else {
+      seenTrackIds.add(track.id);
     }
     if (!track.name?.trim()) {
       errors.push({ path: `${trackPath}.name`, message: 'Track name is required' });
     }
+    if (track.on_failure && !VALID_ON_FAILURE.has(track.on_failure)) {
+      errors.push({ path: `${trackPath}.on_failure`, message: `Invalid on_failure value "${track.on_failure}". Expected "skip_downstream", "stop_all", or "ignore".` });
+    }
+    if (track.model_tier && !VALID_MODEL_TIERS.has(track.model_tier)) {
+      errors.push({ path: `${trackPath}.model_tier`, message: `Invalid model_tier "${track.model_tier}". Expected "low", "medium", or "high".` });
+    }
 
     if (!track.tasks || track.tasks.length === 0) {
       errors.push({ path: `${trackPath}.tasks`, message: `Track "${track.id || ti}": must have at least one task` });
@@ -108,6 +127,14 @@ export function validateRaw(config: RawPipelineConfig): ValidationError[] {
         });
       }
 
+      // ── Field-level validations ──
+      if (task.timeout && !isValidDuration(task.timeout)) {
+        errors.push({ path: `${taskPath}.timeout`, message: `Invalid duration format "${task.timeout}". Expected e.g. "30s", "5m", "1h".` });
+      }
+      if (task.model_tier && !VALID_MODEL_TIERS.has(task.model_tier)) {
+        errors.push({ path: `${taskPath}.model_tier`, message: `Invalid model_tier "${task.model_tier}". Expected "low", "medium", or "high".` });
+      }
+
       // ── depends_on reference checks ──
       if (task.depends_on && task.depends_on.length > 0) {
         for (const dep of task.depends_on) {
@@ -139,6 +166,13 @@ export function validateRaw(config: RawPipelineConfig): ValidationError[] {
             path: `${taskPath}.continue_from`,
             message: `Task "${task.id}": continue_from "${task.continue_from}" is ambiguous — multiple tracks have a task with this id. Use the fully-qualified form "trackId.${task.continue_from}".`,
           });
+        } else if (!task.depends_on || !task.depends_on.some(dep =>
+          resolveDepRef(dep, track.id, allQualified, bareToQualified) === resolved
+        )) {
+          errors.push({
+            path: `${taskPath}.continue_from`,
+            message: `Task "${task.id}": continue_from "${task.continue_from}" should also be listed in depends_on to ensure ordering`,
+          });
         }
       }
     }