@tagma/sdk 0.6.11 → 0.7.0

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([]);
+  });
+});

package/src/core/run-state.ts

@@ -0,0 +1,122 @@
+import type {
+  TaskState,
+  TaskStatus,
+  RunTaskState,
+  Permissions,
+} from '../types';
+
+export function isTerminal(status: TaskStatus): boolean {
+  return (
+    status === 'success' ||
+    status === 'failed' ||
+    status === 'timeout' ||
+    status === 'skipped' ||
+    status === 'blocked'
+  );
+}
+
+/** Return a deep-copied, caller-safe snapshot of the states map. */
+export function freezeStates(
+  states: Map<string, TaskState>,
+): ReadonlyMap<string, TaskState> {
+  const copy = new Map<string, TaskState>();
+  for (const [id, s] of states) {
+    copy.set(id, {
+      config: { ...s.config },
+      trackConfig: { ...s.trackConfig },
+      status: s.status,
+      result: s.result ? { ...s.result } : null,
+      startedAt: s.startedAt,
+      finishedAt: s.finishedAt,
+    });
+  }
+  return copy;
+}
+
+export interface RunSummary {
+  total: number;
+  success: number;
+  failed: number;
+  skipped: number;
+  timeout: number;
+  blocked: number;
+}
+
+/**
+ * Tally terminal task counts. Idle/waiting/running tasks are counted in
+ * `total` but not in any per-status bucket — same semantics as the
+ * original engine.ts summary loop.
+ */
+export function summarizeStates(
+  states: ReadonlyMap<string, TaskState>,
+): RunSummary {
+  const summary: RunSummary = {
+    total: 0,
+    success: 0,
+    failed: 0,
+    skipped: 0,
+    timeout: 0,
+    blocked: 0,
+  };
+  for (const [, state] of states) {
+    summary.total++;
+    switch (state.status) {
+      case 'success':
+        summary.success++;
+        break;
+      case 'failed':
+        summary.failed++;
+        break;
+      case 'skipped':
+        summary.skipped++;
+        break;
+      case 'timeout':
+        summary.timeout++;
+        break;
+      case 'blocked':
+        summary.blocked++;
+        break;
+    }
+  }
+  return summary;
+}
+
+/**
+ * Project the engine's internal TaskState onto the wire RunTaskState
+ * shape. `logs` / `totalLogCount` default to empty — they are populated
+ * on the server side from streamed `task_log` events, not from state.
+ */
+export function toRunTaskState(
+  taskId: string,
+  trackId: string,
+  taskName: string,
+  state: TaskState,
+): RunTaskState {
+  const result = state.result;
+  const cfg = state.config;
+  return {
+    taskId,
+    trackId,
+    taskName,
+    status: state.status,
+    startedAt: state.startedAt,
+    finishedAt: state.finishedAt,
+    durationMs: result?.durationMs ?? null,
+    exitCode: result?.exitCode ?? null,
+    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,
+    resolvedDriver: cfg.driver ?? null,
+    resolvedModel: cfg.model ?? null,
+    resolvedPermissions: (cfg.permissions as Permissions | undefined) ?? null,
+    outputs: result?.outputs ?? null,
+    inputs: null,
+    logs: [],
+    totalLogCount: 0,
+  };
+}

package/src/core/scheduler.test.ts

@@ -0,0 +1,83 @@
+import { describe, expect, test } from 'bun:test';
+import { buildDag } from '../dag';
+import type { PipelineConfig } from '../types';
+import { RunContext } from './run-context';
+import {
+  allTasksTerminal,
+  findLaunchableTasks,
+  skipNonTerminalTasks,
+} from './scheduler';
+
+function makeContext(config: PipelineConfig): RunContext {
+  return new RunContext({
+    runId: 'run_scheduler',
+    dag: buildDag(config),
+    config,
+    workDir: '/tmp/wd',
+    pipelineInfo: {
+      name: config.name,
+      run_id: 'run_scheduler',
+      started_at: '2026-04-26T00:00:00Z',
+    },
+  });
+}
+
+const chainConfig: PipelineConfig = {
+  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'] },
+        { id: 'c', name: 'C', command: 'echo c' },
+      ],
+    },
+  ],
+};
+
+describe('findLaunchableTasks', () => {
+  test('returns waiting roots that are not already running', () => {
+    const ctx = makeContext(chainConfig);
+    for (const state of ctx.states.values()) state.status = 'waiting';
+
+    expect(findLaunchableTasks(ctx, new Set())).toEqual(['t.a', 't.c']);
+    expect(findLaunchableTasks(ctx, new Set(['t.a']))).toEqual(['t.c']);
+  });
+
+  test('returns dependents only after dependencies are terminal', () => {
+    const ctx = makeContext(chainConfig);
+    for (const state of ctx.states.values()) state.status = 'waiting';
+
+    expect(findLaunchableTasks(ctx, new Set())).not.toContain('t.b');
+    ctx.states.get('t.a')!.status = 'success';
+    expect(findLaunchableTasks(ctx, new Set())).toContain('t.b');
+  });
+});
+
+describe('allTasksTerminal', () => {
+  test('returns true only when every task is terminal', () => {
+    const ctx = makeContext(chainConfig);
+    for (const state of ctx.states.values()) state.status = 'success';
+    expect(allTasksTerminal(ctx)).toBe(true);
+    ctx.states.get('t.b')!.status = 'waiting';
+    expect(allTasksTerminal(ctx)).toBe(false);
+  });
+});
+
+describe('skipNonTerminalTasks', () => {
+  test('marks every non-terminal task as skipped and leaves terminal tasks alone', () => {
+    const ctx = makeContext(chainConfig);
+    ctx.states.get('t.a')!.status = 'success';
+    ctx.states.get('t.b')!.status = 'waiting';
+    ctx.states.get('t.c')!.status = 'running';
+
+    skipNonTerminalTasks(ctx, '2026-04-26T01:00:00Z');
+
+    expect(ctx.states.get('t.a')!.status).toBe('success');
+    expect(ctx.states.get('t.b')!.status).toBe('skipped');
+    expect(ctx.states.get('t.b')!.finishedAt).toBe('2026-04-26T01:00:00Z');
+    expect(ctx.states.get('t.c')!.status).toBe('skipped');
+  });
+});

package/src/core/scheduler.ts

@@ -0,0 +1,42 @@
+import type { RunContext } from './run-context';
+import { isTerminal } from './run-state';
+import { nowISO } from '../utils';
+
+/**
+ * Return waiting tasks whose dependency states are terminal and which are not
+ * already in flight. The caller owns actually launching them.
+ */
+export function findLaunchableTasks(
+  ctx: RunContext,
+  runningTaskIds: ReadonlySet<string>,
+): string[] {
+  const launchable: string[] = [];
+  for (const [id, state] of ctx.states) {
+    if (state.status !== 'waiting' || runningTaskIds.has(id)) continue;
+    const node = ctx.dag.nodes.get(id)!;
+    const allDepsTerminal =
+      node.dependsOn.length === 0 ||
+      node.dependsOn.every((depId) => isTerminal(ctx.states.get(depId)!.status));
+    if (allDepsTerminal) launchable.push(id);
+  }
+  return launchable;
+}
+
+export function allTasksTerminal(ctx: RunContext): boolean {
+  return [...ctx.states.values()].every((state) => isTerminal(state.status));
+}
+
+/**
+ * Abort cleanup helper: after in-flight tasks settle, any remaining
+ * non-terminal tasks are waiting/idle tasks that were never started.
+ */
+export function skipNonTerminalTasks(
+  ctx: RunContext,
+  finishedAt = nowISO(),
+): void {
+  for (const [id, state] of ctx.states) {
+    if (isTerminal(state.status)) continue;
+    state.finishedAt = finishedAt;
+    ctx.setTaskStatus(id, 'skipped');
+  }
+}