@tagma/sdk 0.6.12 → 0.7.1

package/src/core/preflight.ts

@@ -0,0 +1,89 @@
+import type { PipelineConfig, TaskConfig, DriverPlugin } from '../types';
+import type { Dag } from '../dag';
+import type { PluginRegistry } from '../registry';
+
+function isCommandOnly(
+  task: TaskConfig,
+): task is TaskConfig & { readonly command: string; readonly prompt?: undefined } {
+  return task.command !== undefined && task.prompt === undefined;
+}
+
+/**
+ * Validate that every plugin referenced by the pipeline (drivers,
+ * triggers, completions, middlewares) is registered, and that
+ * `continue_from` is only used between drivers that can hand off via
+ * sessionResume or text-injection. Throws with all errors aggregated
+ * into one message so the caller sees every misconfiguration in a
+ * single pass.
+ */
+export function preflight(
+  config: PipelineConfig,
+  dag: Dag,
+  registry: PluginRegistry,
+): void {
+  const errors: string[] = [];
+
+  for (const [, node] of dag.nodes) {
+    const task = node.task;
+    const track = node.track;
+    const driverName = task.driver ?? track.driver ?? config.driver ?? 'opencode';
+
+    const isCommand = isCommandOnly(task);
+
+    if (!isCommand && !registry.hasHandler('drivers', driverName)) {
+      errors.push(`Task "${node.taskId}": driver "${driverName}" not registered`);
+    }
+
+    if (task.trigger && !registry.hasHandler('triggers', task.trigger.type)) {
+      errors.push(
+        `Task "${node.taskId}": trigger type "${task.trigger.type}" not registered`,
+      );
+    }
+
+    if (task.completion && !registry.hasHandler('completions', task.completion.type)) {
+      errors.push(
+        `Task "${node.taskId}": completion type "${task.completion.type}" not registered`,
+      );
+    }
+
+    const mws = task.middlewares ?? track.middlewares ?? [];
+    for (const mw of mws) {
+      if (!registry.hasHandler('middlewares', mw.type)) {
+        errors.push(
+          `Task "${node.taskId}": middleware type "${mw.type}" not registered`,
+        );
+      }
+    }
+
+    if (task.continue_from && registry.hasHandler('drivers', driverName)) {
+      const driver = registry.getHandler<DriverPlugin>('drivers', driverName);
+      if (!driver.capabilities.sessionResume) {
+        const upstreamId = node.resolvedContinueFrom;
+        if (upstreamId) {
+          const upstream = dag.nodes.get(upstreamId);
+          if (upstream) {
+            const upstreamDriverName =
+              upstream.task.driver ?? upstream.track.driver ?? config.driver ?? 'opencode';
+            const upstreamDriver = registry.hasHandler('drivers', upstreamDriverName)
+              ? registry.getHandler<DriverPlugin>('drivers', upstreamDriverName)
+              : null;
+            const canNormalize = typeof upstreamDriver?.parseResult === 'function';
+
+            if (!canNormalize) {
+              errors.push(
+                `Task "${node.taskId}" uses continue_from: "${task.continue_from}", ` +
+                  `but upstream task "${upstreamId}" its driver ` +
+                  `does not implement parseResult for text-injection handoff. ` +
+                  `Use a driver with parseResult, or remove continue_from.`,
+              );
+            }
+          }
+        }
+      }
+    }
+  }
+
+  if (errors.length > 0) {
+    throw new Error(`Preflight validation failed:\n  - ${errors.join('\n  - ')}`);
+  }
+}

package/src/core/run-context.test.ts

@@ -0,0 +1,244 @@
+import { describe, expect, test } from 'bun:test';
+import { RunContext } from './run-context';
+import { buildDag } from '../dag';
+import type { PipelineConfig, RunEventPayload } from '../types';
+import type { PipelineInfo } from '../hooks';
+
+function makeContext(overrides: Partial<{
+  config: PipelineConfig;
+  onEvent: (e: RunEventPayload) => void;
+}> = {}): { ctx: RunContext; events: RunEventPayload[] } {
+  const config: PipelineConfig = overrides.config ?? {
+    name: 'p',
+    tracks: [
+      {
+        id: 't',
+        name: 'T',
+        tasks: [
+          { id: 'a', name: 'A', command: 'echo a' },
+          { id: 'b', name: 'B', command: 'echo b', depends_on: ['a'] },
+        ],
+      },
+    ],
+  };
+  const events: RunEventPayload[] = [];
+  const onEvent = overrides.onEvent ?? ((e: RunEventPayload) => { events.push(e); });
+  const ctx = new RunContext({
+    runId: 'run_test',
+    dag: buildDag(config),
+    config,
+    workDir: '/tmp/wd',
+    pipelineInfo: { name: config.name, run_id: 'run_test', started_at: '2026-04-26T00:00:00Z' } as PipelineInfo,
+    onEvent,
+  });
+  return { ctx, events };
+}
+
+describe('RunContext constructor', () => {
+  test('initializes one idle state per dag node', () => {
+    const { ctx } = makeContext();
+    expect(ctx.states.size).toBe(2);
+    expect(ctx.states.get('t.a')!.status).toBe('idle');
+    expect(ctx.states.get('t.b')!.status).toBe('idle');
+  });
+
+  test('initializes all state maps as empty', () => {
+    const { ctx } = makeContext();
+    expect(ctx.sessionMap.size).toBe(0);
+    expect(ctx.normalizedMap.size).toBe(0);
+    expect(ctx.outputValuesMap.size).toBe(0);
+    expect(ctx.bindingDataMap.size).toBe(0);
+    expect(ctx.resolvedInputsMap.size).toBe(0);
+  });
+
+  test('computes directDownstreams reverse adjacency from dag', () => {
+    const { ctx } = makeContext();
+    expect([...ctx.directDownstreams.get('t.a')!]).toEqual(['t.b']);
+    expect([...ctx.directDownstreams.get('t.b')!]).toEqual([]);
+  });
+
+  test('starts with abortReason null and a fresh AbortController', () => {
+    const { ctx } = makeContext();
+    expect(ctx.abortReason).toBeNull();
+    expect(ctx.abortController.signal.aborted).toBe(false);
+  });
+});
+
+describe('RunContext.emit', () => {
+  test('forwards events to onEvent', () => {
+    const { ctx, events } = makeContext();
+    ctx.emit({ type: 'run_end', runId: 'run_test', success: true, abortReason: null });
+    expect(events).toHaveLength(1);
+    expect(events[0]).toEqual({ type: 'run_end', runId: 'run_test', success: true, abortReason: null });
+  });
+
+  test('is a no-op when onEvent is undefined', () => {
+    const config: PipelineConfig = {
+      name: 'p',
+      tracks: [{ id: 't', name: 'T', tasks: [{ id: 'a', name: 'A', command: 'echo a' }] }],
+    };
+    const ctx = new RunContext({
+      runId: 'run_test',
+      dag: buildDag(config),
+      config,
+      workDir: '/tmp/wd',
+      pipelineInfo: { name: 'p', run_id: 'run_test', started_at: 'now' } as PipelineInfo,
+    });
+    expect(() => ctx.emit({ type: 'run_end', runId: 'run_test', success: true, abortReason: null })).not.toThrow();
+  });
+});
+
+describe('RunContext.setTaskStatus', () => {
+  test('transitions a non-terminal task and emits task_update', () => {
+    const { ctx, events } = makeContext();
+    ctx.setTaskStatus('t.a', 'waiting');
+    expect(ctx.states.get('t.a')!.status).toBe('waiting');
+    expect(events).toHaveLength(1);
+    expect(events[0].type).toBe('task_update');
+    if (events[0].type === 'task_update') {
+      expect(events[0].taskId).toBe('t.a');
+      expect(events[0].status).toBe('waiting');
+    }
+  });
+
+  test('refuses to re-transition a terminal task (terminal lock)', () => {
+    const { ctx, events } = makeContext();
+    ctx.setTaskStatus('t.a', 'success');
+    events.length = 0;
+    ctx.setTaskStatus('t.a', 'failed');
+    expect(ctx.states.get('t.a')!.status).toBe('success');
+    expect(events).toHaveLength(0);
+  });
+
+  test('echoes resolvedInputs and outputs from the maps in the emitted event', () => {
+    const { ctx, events } = makeContext();
+    ctx.resolvedInputsMap.set('t.a', { x: 1 });
+    ctx.outputValuesMap.set('t.a', { y: 2 });
+    ctx.setTaskStatus('t.a', 'running');
+    if (events[0].type === 'task_update') {
+      expect(events[0].inputs).toEqual({ x: 1 });
+      expect(events[0].outputs).toEqual({ y: 2 });
+    } else {
+      throw new Error('expected task_update');
+    }
+  });
+});
+
+describe('RunContext.getOnFailure', () => {
+  test('returns the track-level on_failure setting', () => {
+    const config: PipelineConfig = {
+      name: 'p',
+      tracks: [
+        {
+          id: 't',
+          name: 'T',
+          on_failure: 'stop_all',
+          tasks: [{ id: 'a', name: 'A', command: 'echo a' }],
+        },
+      ],
+    };
+    const { ctx } = makeContext({ config });
+    expect(ctx.getOnFailure('t.a')).toBe('stop_all');
+  });
+
+  test('defaults to skip_downstream when track does not specify', () => {
+    const { ctx } = makeContext();
+    expect(ctx.getOnFailure('t.a')).toBe('skip_downstream');
+  });
+});
+
+describe('RunContext.isDependencySatisfied', () => {
+  test('returns satisfied for success', () => {
+    const { ctx } = makeContext();
+    ctx.states.get('t.a')!.status = 'success';
+    expect(ctx.isDependencySatisfied('t.a')).toBe('satisfied');
+  });
+
+  test('returns skip for skipped', () => {
+    const { ctx } = makeContext();
+    ctx.states.get('t.a')!.status = 'skipped';
+    expect(ctx.isDependencySatisfied('t.a')).toBe('skip');
+  });
+
+  test('returns skip for failed under default policy, satisfied under ignore', () => {
+    const cfgSkip: PipelineConfig = {
+      name: 'p',
+      tracks: [{ id: 't', name: 'T', tasks: [{ id: 'a', name: 'A', command: 'echo a' }] }],
+    };
+    const cfgIgnore: PipelineConfig = {
+      name: 'p',
+      tracks: [
+        {
+          id: 't',
+          name: 'T',
+          on_failure: 'ignore',
+          tasks: [{ id: 'a', name: 'A', command: 'echo a' }],
+        },
+      ],
+    };
+    const a = makeContext({ config: cfgSkip }).ctx;
+    a.states.get('t.a')!.status = 'failed';
+    expect(a.isDependencySatisfied('t.a')).toBe('skip');
+
+    const b = makeContext({ config: cfgIgnore }).ctx;
+    b.states.get('t.a')!.status = 'failed';
+    expect(b.isDependencySatisfied('t.a')).toBe('satisfied');
+  });
+
+  test('returns unsatisfied for non-terminal statuses', () => {
+    const { ctx } = makeContext();
+    ctx.states.get('t.a')!.status = 'running';
+    expect(ctx.isDependencySatisfied('t.a')).toBe('unsatisfied');
+  });
+});
+
+describe('RunContext.applyStopAll', () => {
+  test('aborts the controller, sets abortReason, marks waiting tasks as skipped', () => {
+    const { ctx } = makeContext();
+    ctx.states.get('t.a')!.status = 'waiting';
+    ctx.states.get('t.b')!.status = 'waiting';
+    ctx.applyStopAll();
+    expect(ctx.abortReason).toBe('stop_all');
+    expect(ctx.abortController.signal.aborted).toBe(true);
+    expect(ctx.states.get('t.a')!.status).toBe('skipped');
+    expect(ctx.states.get('t.b')!.status).toBe('skipped');
+  });
+
+  test('does not overwrite an existing abortReason', () => {
+    const { ctx } = makeContext();
+    ctx.abortReason = 'timeout';
+    ctx.applyStopAll();
+    expect(ctx.abortReason).toBe('timeout');
+    expect(ctx.abortController.signal.aborted).toBe(true);
+  });
+
+  test('leaves running and terminal tasks alone', () => {
+    const { ctx } = makeContext();
+    ctx.states.get('t.a')!.status = 'running';
+    ctx.states.get('t.b')!.status = 'success';
+    ctx.applyStopAll();
+    expect(ctx.states.get('t.a')!.status).toBe('running');
+    expect(ctx.states.get('t.b')!.status).toBe('success');
+  });
+});
+
+describe('RunContext.buildTaskInfoObj / trackInfoOf', () => {
+  test('buildTaskInfoObj reports type=command for command tasks', () => {
+    const { ctx } = makeContext();
+    expect(ctx.buildTaskInfoObj('t.a').type).toBe('command');
+  });
+
+  test('buildTaskInfoObj reports type=ai for prompt tasks', () => {
+    const config: PipelineConfig = {
+      name: 'p',
+      tracks: [{ id: 't', name: 'T', tasks: [{ id: 'a', name: 'A', prompt: 'hi' }] }],
+    };
+    const { ctx } = makeContext({ config });
+    expect(ctx.buildTaskInfoObj('t.a').type).toBe('ai');
+  });
+
+  test('trackInfoOf returns the track id and name', () => {
+    const { ctx } = makeContext();
+    expect(ctx.trackInfoOf('t.a')).toEqual({ id: 't', name: 'T' });
+  });
+});

package/src/core/run-context.ts

@@ -0,0 +1,207 @@
+import type {
+  AbortReason,
+  OnFailure,
+  Permissions,
+  PipelineConfig,
+  RunEventPayload,
+  TaskConfig,
+  TaskState,
+  TaskStatus,
+} from '../types';
+import type { Dag } from '../dag';
+import type { UpstreamBindingData } from '../ports';
+import {
+  executeHook,
+  buildTaskContext,
+  type PipelineInfo,
+  type TaskInfo,
+  type TrackInfo,
+} from '../hooks';
+import { isTerminal } from './run-state';
+import { nowISO } from '../utils';
+
+function isPromptTaskConfig(
+  task: TaskConfig,
+): task is TaskConfig & { readonly prompt: string; readonly command?: undefined } {
+  return task.prompt !== undefined && task.command === undefined;
+}
+
+export interface RunContextOptions {
+  readonly runId: string;
+  readonly dag: Dag;
+  readonly config: PipelineConfig;
+  readonly workDir: string;
+  readonly pipelineInfo: PipelineInfo;
+  readonly onEvent?: (event: RunEventPayload) => void;
+}
+
+/**
+ * Per-run state container. Owns the maps and abort tracking that
+ * `runPipeline` previously held as closure locals, plus the small
+ * methods that read/write that state. Scheduler, dataflow, and
+ * task-executor extractions in later phases pass `ctx` instead of
+ * relying on closure capture.
+ */
+export class RunContext {
+  readonly runId: string;
+  readonly dag: Dag;
+  readonly config: PipelineConfig;
+  readonly workDir: string;
+  readonly pipelineInfo: PipelineInfo;
+  readonly onEvent?: (event: RunEventPayload) => void;
+
+  readonly states = new Map<string, TaskState>();
+  readonly sessionMap = new Map<string, string>();
+  readonly normalizedMap = new Map<string, string>();
+  readonly outputValuesMap = new Map<string, Readonly<Record<string, unknown>>>();
+  readonly bindingDataMap = new Map<string, UpstreamBindingData>();
+  readonly resolvedInputsMap = new Map<string, Readonly<Record<string, unknown>>>();
+  readonly directDownstreams: Map<string, string[]>;
+  readonly abortController = new AbortController();
+  abortReason: AbortReason | null = null;
+
+  constructor(options: RunContextOptions) {
+    this.runId = options.runId;
+    this.dag = options.dag;
+    this.config = options.config;
+    this.workDir = options.workDir;
+    this.pipelineInfo = options.pipelineInfo;
+    this.onEvent = options.onEvent;
+
+    for (const [id, node] of this.dag.nodes) {
+      this.states.set(id, {
+        config: node.task,
+        trackConfig: node.track,
+        status: 'idle',
+        result: null,
+        startedAt: null,
+        finishedAt: null,
+      });
+    }
+
+    this.directDownstreams = new Map<string, string[]>();
+    for (const [id] of this.dag.nodes) this.directDownstreams.set(id, []);
+    for (const [id, node] of this.dag.nodes) {
+      for (const upstream of node.dependsOn) {
+        const list = this.directDownstreams.get(upstream);
+        if (list) list.push(id);
+      }
+    }
+  }
+
+  emit(event: RunEventPayload): void {
+    this.onEvent?.(event);
+  }
+
+  setTaskStatus(taskId: string, newStatus: TaskStatus): void {
+    const state = this.states.get(taskId)!;
+    // Terminal lock: once a task reaches a terminal state it must not be
+    // re-transitioned. This prevents stop_all from marking running tasks as
+    // skipped and then having their in-flight processTask promise overwrite
+    // that with success/failed, producing an invalid double transition.
+    if (isTerminal(state.status)) return;
+    state.status = newStatus;
+    const result = state.result;
+    const cfg = state.config;
+    this.emit({
+      type: 'task_update',
+      runId: this.runId,
+      taskId,
+      status: newStatus,
+      startedAt: state.startedAt ?? undefined,
+      finishedAt: state.finishedAt ?? undefined,
+      durationMs: result?.durationMs,
+      exitCode: result?.exitCode,
+      stdout: result?.stdout,
+      stderr: result?.stderr,
+      stdoutPath: result?.stdoutPath ?? null,
+      stderrPath: result?.stderrPath ?? null,
+      stdoutBytes: result?.stdoutBytes ?? null,
+      stderrBytes: result?.stderrBytes ?? null,
+      sessionId: result?.sessionId ?? null,
+      normalizedOutput: result?.normalizedOutput ?? null,
+      inputs: this.resolvedInputsMap.get(taskId) ?? null,
+      outputs: this.outputValuesMap.get(taskId) ?? null,
+      resolvedDriver: cfg.driver ?? null,
+      resolvedModel: cfg.model ?? null,
+      resolvedPermissions: (cfg.permissions as Permissions | undefined) ?? null,
+    });
+  }
+
+  getOnFailure(taskId: string): OnFailure {
+    return this.dag.nodes.get(taskId)?.track.on_failure ?? 'skip_downstream';
+  }
+
+  isDependencySatisfied(depId: string): 'satisfied' | 'unsatisfied' | 'skip' {
+    const depState = this.states.get(depId);
+    if (!depState) return 'skip';
+    switch (depState.status) {
+      case 'success':
+        return 'satisfied';
+      case 'skipped':
+        return 'skip';
+      case 'failed':
+      case 'timeout':
+      case 'blocked':
+        return this.getOnFailure(depId) === 'ignore' ? 'satisfied' : 'skip';
+      default:
+        return 'unsatisfied';
+    }
+  }
+
+  /**
+   * H3: stop_all marks every still-waiting task across every track as
+   * skipped and aborts in-flight tasks via the shared signal. The
+   * terminal lock in setTaskStatus prevents any later re-transition
+   * should a completed running task try to overwrite the skipped state.
+   */
+  applyStopAll(): void {
+    if (this.abortReason === null) this.abortReason = 'stop_all';
+    this.abortController.abort();
+    for (const [id, state] of this.states) {
+      if (state.status === 'waiting') {
+        state.finishedAt = nowISO();
+        this.setTaskStatus(id, 'skipped');
+      }
+    }
+  }
+
+  buildTaskInfoObj(taskId: string): TaskInfo {
+    const state = this.states.get(taskId)!;
+    return {
+      id: taskId,
+      name: state.config.name,
+      type: isPromptTaskConfig(state.config) ? 'ai' : 'command',
+      status: state.status,
+      exit_code: state.result?.exitCode ?? null,
+      duration_ms: state.result?.durationMs ?? null,
+      stderr_path: state.result?.stderrPath ?? null,
+      session_id: state.result?.sessionId ?? null,
+      started_at: state.startedAt,
+      finished_at: state.finishedAt,
+    };
+  }
+
+  trackInfoOf(taskId: string): TrackInfo {
+    const node = this.dag.nodes.get(taskId)!;
+    return { id: node.track.id, name: node.track.name };
+  }
+
+  async fireHook(
+    taskId: string,
+    event: 'task_success' | 'task_failure',
+  ): Promise<void> {
+    await executeHook(
+      this.config.hooks,
+      event,
+      buildTaskContext(
+        event,
+        this.pipelineInfo,
+        this.trackInfoOf(taskId),
+        this.buildTaskInfoObj(taskId),
+      ),
+      this.workDir,
+      this.abortController.signal,
+    );
+  }
+}

package/src/core/run-state.test.ts

@@ -0,0 +1,98 @@
+import { describe, expect, test } from 'bun:test';
+import {
+  isTerminal,
+  freezeStates,
+  summarizeStates,
+  toRunTaskState,
+} from './run-state';
+import type { TaskState, TaskStatus } from '../types';
+
+describe('isTerminal', () => {
+  test('returns true for terminal statuses', () => {
+    expect(isTerminal('success')).toBe(true);
+    expect(isTerminal('failed')).toBe(true);
+    expect(isTerminal('timeout')).toBe(true);
+    expect(isTerminal('skipped')).toBe(true);
+    expect(isTerminal('blocked')).toBe(true);
+  });
+  test('returns false for non-terminal statuses', () => {
+    expect(isTerminal('idle')).toBe(false);
+    expect(isTerminal('waiting')).toBe(false);
+    expect(isTerminal('running')).toBe(false);
+  });
+});
+
+function makeState(status: TaskStatus, opts: Partial<TaskState> = {}): TaskState {
+  return {
+    config: { id: 't', name: 't' } as TaskState['config'],
+    trackConfig: { id: 'tr', name: 'tr', tasks: [] } as TaskState['trackConfig'],
+    status,
+    result: null,
+    startedAt: null,
+    finishedAt: null,
+    ...opts,
+  };
+}
+
+describe('freezeStates', () => {
+  test('produces a deep copy that survives source mutation', () => {
+    const src = new Map<string, TaskState>();
+    src.set('a', makeState('success'));
+    const frozen = freezeStates(src);
+    src.get('a')!.status = 'failed';
+    expect(frozen.get('a')!.status).toBe('success');
+  });
+
+  test('copies result object so mutation does not bleed through', () => {
+    const src = new Map<string, TaskState>();
+    src.set('a', makeState('success', {
+      result: {
+        exitCode: 0,
+        stdout: 'x',
+        stderr: '',
+        stdoutPath: null,
+        stderrPath: null,
+        durationMs: 1,
+        sessionId: null,
+        normalizedOutput: null,
+        outputs: null,
+      } as TaskState['result'],
+    }));
+    const frozen = freezeStates(src);
+    src.get('a')!.result!.stdout = 'mutated';
+    expect(frozen.get('a')!.result!.stdout).toBe('x');
+  });
+});
+
+describe('summarizeStates', () => {
+  test('counts each terminal status into its own bucket', () => {
+    const m = new Map<string, TaskState>();
+    m.set('a', makeState('success'));
+    m.set('b', makeState('failed'));
+    m.set('c', makeState('skipped'));
+    m.set('d', makeState('timeout'));
+    m.set('e', makeState('blocked'));
+    m.set('f', makeState('running'));
+    expect(summarizeStates(m)).toEqual({
+      total: 6,
+      success: 1,
+      failed: 1,
+      skipped: 1,
+      timeout: 1,
+      blocked: 1,
+    });
+  });
+});
+
+describe('toRunTaskState', () => {
+  test('projects null result onto wire shape with empty stdout/stderr', () => {
+    const wire = toRunTaskState('t1', 'trk', 'Task 1', makeState('idle'));
+    expect(wire.taskId).toBe('t1');
+    expect(wire.trackId).toBe('trk');
+    expect(wire.status).toBe('idle');
+    expect(wire.stdout).toBe('');
+    expect(wire.stderr).toBe('');
+    expect(wire.exitCode).toBeNull();
+    expect(wire.logs).toEqual([]);
+  });
+});