@tagma/sdk 0.6.12 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tagma/sdk",
-  "version": "0.6.12",
+  "version": "0.7.0",
   "description": "Local AI task orchestration engine — core SDK for tagma pipelines",
   "license": "MIT",
   "repository": {
@@ -12,14 +12,59 @@
   "homepage": "https://github.com/GoTagma/tagma-mono/tree/main/packages/sdk#readme",
   "type": "module",
   "sideEffects": false,
-  "main": "./dist/sdk.js",
-  "module": "./dist/sdk.js",
-  "types": "./dist/sdk.d.ts",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "types": "./dist/sdk.d.ts",
-      "import": "./dist/sdk.js",
-      "default": "./dist/sdk.js"
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./yaml": {
+      "types": "./dist/yaml.d.ts",
+      "import": "./dist/yaml.js",
+      "default": "./dist/yaml.js"
+    },
+    "./config": {
+      "types": "./dist/config.d.ts",
+      "import": "./dist/config.js",
+      "default": "./dist/config.js"
+    },
+    "./plugins": {
+      "types": "./dist/plugins.d.ts",
+      "import": "./dist/plugins.js",
+      "default": "./dist/plugins.js"
+    },
+    "./runner": {
+      "types": "./dist/pipeline-runner.d.ts",
+      "import": "./dist/pipeline-runner.js",
+      "default": "./dist/pipeline-runner.js"
+    },
+    "./logger": {
+      "types": "./dist/logger.d.ts",
+      "import": "./dist/logger.js",
+      "default": "./dist/logger.js"
+    },
+    "./approval": {
+      "types": "./dist/approval.d.ts",
+      "import": "./dist/approval.js",
+      "default": "./dist/approval.js"
+    },
+    "./utils": {
+      "types": "./dist/utils-api.d.ts",
+      "import": "./dist/utils-api.js",
+      "default": "./dist/utils-api.js"
+    },
+    "./adapters/stdin-approval": {
+      "types": "./dist/adapters/stdin-approval.d.ts",
+      "import": "./dist/adapters/stdin-approval.js",
+      "default": "./dist/adapters/stdin-approval.js"
+    },
+    "./adapters/websocket-approval": {
+      "types": "./dist/adapters/websocket-approval.d.ts",
+      "import": "./dist/adapters/websocket-approval.js",
+      "default": "./dist/adapters/websocket-approval.js"
     },
     "./ports": {
       "types": "./dist/ports.d.ts",

package/src/bootstrap.ts

@@ -1,4 +1,4 @@
-import { defaultRegistry, type PluginRegistry } from './registry';
+import type { PluginRegistry } from './registry';
 
 // Built-in Drivers
 // Only opencode is built in. Other drivers (codex, claude-code) ship as
@@ -20,15 +20,15 @@ import { OutputCheckCompletion } from './completions/output-check';
 import { StaticContextMiddleware } from './middlewares/static-context';
 
 /**
- * Register every built-in plugin into `target` (defaults to the process-wide
- * default registry). Multi-tenant hosts instantiate one PluginRegistry per
- * workspace and call this once per instance so each workspace sees the same
- * built-ins without sharing registration state.
+ * Register every built-in plugin into `target`. Hosts instantiate one
+ * PluginRegistry per workspace or SDK instance and call this once per
+ * instance so each workspace sees the same built-ins without sharing
+ * registration state.
  *
  * Built-in handlers are stateless module singletons — registering the same
  * handler object into N registries is cheap and safe; no cloning is needed.
  */
-export function bootstrapBuiltins(target: PluginRegistry = defaultRegistry): void {
+export function bootstrapBuiltins(target: PluginRegistry): void {
   // Drivers
   target.registerPlugin('drivers', 'opencode', OpenCodeDriver);
 

package/src/config.ts

@@ -0,0 +1,26 @@
+export {
+  createEmptyPipeline,
+  setPipelineField,
+  upsertTrack,
+  removeTrack,
+  moveTrack,
+  updateTrack,
+  upsertTask,
+  removeTask,
+  moveTask,
+  transferTask,
+} from './config-ops';
+export { validateRaw } from './validate-raw';
+export type { ValidationError, KnownPluginTypes } from './validate-raw';
+export { buildRawDag } from './dag';
+export type { RawDag, RawDagNode } from './dag';
+export {
+  TASK_ID_RE,
+  isValidTaskId,
+  qualifyTaskId,
+  isQualifiedRef,
+  buildTaskIndex,
+  resolveTaskRef,
+  AMBIGUOUS,
+} from './task-ref';
+export type { TaskIndex, RefResolution } from './task-ref';

package/src/core/dataflow.test.ts

@@ -0,0 +1,167 @@
+import { describe, expect, test } from 'bun:test';
+import { buildDag } from '../dag';
+import type { PipelineConfig, TaskResult } from '../types';
+import { RunContext } from './run-context';
+import {
+  inferEffectivePorts,
+  extractSuccessfulOutputs,
+} from './dataflow';
+
+function makeContext(config: PipelineConfig): RunContext {
+  return new RunContext({
+    runId: 'run_dataflow',
+    dag: buildDag(config),
+    config,
+    workDir: '/tmp/wd',
+    pipelineInfo: {
+      name: config.name,
+      run_id: 'run_dataflow',
+      started_at: '2026-04-26T00:00:00Z',
+    },
+  });
+}
+
+function result(stdout: string, normalizedOutput: string | null = null): TaskResult {
+  return {
+    exitCode: 0,
+    stdout,
+    stderr: '',
+    stdoutPath: null,
+    stderrPath: null,
+    durationMs: 1,
+    sessionId: null,
+    normalizedOutput,
+    failureKind: null,
+  };
+}
+
+describe('inferEffectivePorts', () => {
+  test('returns declared ports for command tasks', () => {
+    const config: PipelineConfig = {
+      name: 'p',
+      tracks: [
+        {
+          id: 't',
+          name: 'T',
+          tasks: [
+            {
+              id: 'cmd',
+              name: 'Cmd',
+              command: 'echo',
+              ports: { outputs: [{ name: 'city', type: 'string' }] },
+            },
+          ],
+        },
+      ],
+    };
+    const ctx = makeContext(config);
+    const inferred = inferEffectivePorts(ctx, 't.cmd');
+    expect(inferred.kind).toBe('ready');
+    if (inferred.kind === 'ready') {
+      expect(inferred.isPromptTask).toBe(false);
+      expect(inferred.effectivePorts?.outputs?.[0]?.name).toBe('city');
+    }
+  });
+
+  test('infers prompt inputs from upstream command outputs', () => {
+    const config: PipelineConfig = {
+      name: 'p',
+      tracks: [
+        {
+          id: 't',
+          name: 'T',
+          tasks: [
+            {
+              id: 'up',
+              name: 'Up',
+              command: 'echo',
+              ports: { outputs: [{ name: 'city', type: 'string' }] },
+            },
+            { id: 'prompt', name: 'Prompt', prompt: 'hi', depends_on: ['up'] },
+          ],
+        },
+      ],
+    };
+    const ctx = makeContext(config);
+    const inferred = inferEffectivePorts(ctx, 't.prompt');
+    expect(inferred.kind).toBe('ready');
+    if (inferred.kind === 'ready') {
+      expect(inferred.isPromptTask).toBe(true);
+      expect(inferred.effectivePorts?.inputs?.[0]?.name).toBe('city');
+    }
+  });
+
+  test('blocks prompt tasks when upstream command outputs are ambiguous', () => {
+    const config: PipelineConfig = {
+      name: 'p',
+      tracks: [
+        {
+          id: 't',
+          name: 'T',
+          tasks: [
+            {
+              id: 'a',
+              name: 'A',
+              command: 'echo',
+              ports: { outputs: [{ name: 'city', type: 'string' }] },
+            },
+            {
+              id: 'b',
+              name: 'B',
+              command: 'echo',
+              ports: { outputs: [{ name: 'city', type: 'string' }] },
+            },
+            {
+              id: 'prompt',
+              name: 'Prompt',
+              prompt: 'hi',
+              depends_on: ['a', 'b'],
+            },
+          ],
+        },
+      ],
+    };
+    const ctx = makeContext(config);
+    const inferred = inferEffectivePorts(ctx, 't.prompt');
+    expect(inferred.kind).toBe('blocked');
+    if (inferred.kind === 'blocked') {
+      expect(inferred.reason).toContain('city');
+    }
+  });
+});
+
+describe('extractSuccessfulOutputs', () => {
+  test('combines lightweight binding outputs with typed port outputs', () => {
+    const config: PipelineConfig = {
+      name: 'p',
+      tracks: [
+        {
+          id: 't',
+          name: 'T',
+          tasks: [
+            {
+              id: 'cmd',
+              name: 'Cmd',
+              command: 'echo',
+              outputs: { raw: { from: 'stdout' } },
+              ports: { outputs: [{ name: 'city', type: 'string' }] },
+            },
+          ],
+        },
+      ],
+    };
+    const ctx = makeContext(config);
+    const node = ctx.dag.nodes.get('t.cmd')!;
+    const extracted = extractSuccessfulOutputs({
+      task: node.task,
+      effectivePorts: node.task.ports,
+      result: result('{"city":"Paris"}'),
+    });
+    expect(extracted.outputs).toEqual({
+      raw: '{"city":"Paris"}',
+      city: 'Paris',
+    });
+    expect(extracted.bindingDiagnostic).toBeNull();
+    expect(extracted.portDiagnostic).toBeNull();
+  });
+});

package/src/core/dataflow.ts

@@ -0,0 +1,118 @@
+import type { TaskConfig, TaskPorts, TaskResult } from '../types';
+import {
+  extractTaskBindingOutputs,
+  extractTaskOutputs,
+  inferPromptPorts,
+} from '../ports';
+import type { RunContext } from './run-context';
+
+function isPromptTaskConfig(
+  task: TaskConfig,
+): task is TaskConfig & { readonly prompt: string; readonly command?: undefined } {
+  return task.prompt !== undefined && task.command === undefined;
+}
+
+function isCommandTaskConfig(
+  task: TaskConfig,
+): task is TaskConfig & { readonly command: string; readonly prompt?: undefined } {
+  return task.command !== undefined && task.prompt === undefined;
+}
+
+export type EffectivePortsResult =
+  | {
+      readonly kind: 'ready';
+      readonly isPromptTask: boolean;
+      readonly effectivePorts: TaskPorts | undefined;
+    }
+  | {
+      readonly kind: 'blocked';
+      readonly reason: string;
+    };
+
+export function inferEffectivePorts(
+  ctx: RunContext,
+  taskId: string,
+): EffectivePortsResult {
+  const node = ctx.dag.nodes.get(taskId)!;
+  const task = node.task;
+  const isPromptTask = isPromptTaskConfig(task);
+
+  if (!isPromptTask) {
+    return { kind: 'ready', isPromptTask: false, effectivePorts: task.ports };
+  }
+
+  const inference = inferPromptPorts({
+    upstreams: node.dependsOn.map((upstreamId) => {
+      const upstream = ctx.dag.nodes.get(upstreamId);
+      const isUpstreamCommand = upstream ? isCommandTaskConfig(upstream.task) : false;
+      return {
+        taskId: upstreamId,
+        outputs: isUpstreamCommand ? upstream?.task.ports?.outputs : undefined,
+      };
+    }),
+    downstreams: (ctx.directDownstreams.get(taskId) ?? []).map((downstreamId) => {
+      const downstream = ctx.dag.nodes.get(downstreamId);
+      const isDownstreamCommand = downstream ? isCommandTaskConfig(downstream.task) : false;
+      return {
+        taskId: downstreamId,
+        inputs: isDownstreamCommand ? downstream?.task.ports?.inputs : undefined,
+      };
+    }),
+  });
+
+  if (inference.inputConflicts.length > 0 || inference.outputConflicts.length > 0) {
+    const lines: string[] = [];
+    for (const conflict of inference.inputConflicts) lines.push(conflict.reason);
+    for (const conflict of inference.outputConflicts) lines.push(conflict.reason);
+    return { kind: 'blocked', reason: lines.join('\n') };
+  }
+
+  return { kind: 'ready', isPromptTask: true, effectivePorts: inference.ports };
+}
+
+export interface ExtractSuccessfulOutputsOptions {
+  readonly task: TaskConfig;
+  readonly effectivePorts: TaskPorts | undefined;
+  readonly result: TaskResult;
+}
+
+export interface ExtractSuccessfulOutputsResult {
+  readonly outputs: Readonly<Record<string, unknown>> | null;
+  readonly bindingDiagnostic: string | null;
+  readonly portDiagnostic: string | null;
+}
+
+export function extractSuccessfulOutputs(
+  options: ExtractSuccessfulOutputsOptions,
+): ExtractSuccessfulOutputsResult {
+  const { task, effectivePorts, result } = options;
+  let extractedOutputs: Readonly<Record<string, unknown>> | null = null;
+
+  const bindingExtraction = extractTaskBindingOutputs(
+    task.outputs,
+    result.stdout,
+    result.stderr,
+    result.normalizedOutput,
+  );
+  if (task.outputs && Object.keys(task.outputs).length > 0) {
+    extractedOutputs = bindingExtraction.outputs;
+  }
+
+  const portExtraction = extractTaskOutputs(
+    effectivePorts,
+    result.stdout,
+    result.normalizedOutput,
+  );
+  if (effectivePorts?.outputs && effectivePorts.outputs.length > 0) {
+    extractedOutputs = {
+      ...(extractedOutputs ?? {}),
+      ...portExtraction.outputs,
+    };
+  }
+
+  return {
+    outputs: extractedOutputs,
+    bindingDiagnostic: bindingExtraction.diagnostic,
+    portDiagnostic: portExtraction.diagnostic,
+  };
+}

package/src/core/log-prune.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, test } from 'bun:test';
+import { mkdtempSync, mkdirSync, readdirSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { pruneLogDirs } from './log-prune';
+
+function fixture(): string {
+  return mkdtempSync(join(tmpdir(), 'tagma-prune-'));
+}
+
+describe('pruneLogDirs', () => {
+  test('returns silently when logsDir does not exist', async () => {
+    const root = fixture();
+    try {
+      await expect(
+        pruneLogDirs(join(root, 'nope'), 5, 'run_live'),
+      ).resolves.toBeUndefined();
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  test('keeps the live run plus (keep-1) most recent historical runs', async () => {
+    const root = fixture();
+    try {
+      for (const id of ['run_001', 'run_002', 'run_003', 'run_004', 'run_005']) {
+        mkdirSync(join(root, id));
+      }
+      await pruneLogDirs(root, 3, 'run_005'); // keep=3 → 1 live + 2 historical
+      expect(readdirSync(root).sort()).toEqual(['run_003', 'run_004', 'run_005']);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  test('never deletes the excluded live runId even if it would be pruned', async () => {
+    const root = fixture();
+    try {
+      for (const id of ['run_001', 'run_002', 'run_003']) mkdirSync(join(root, id));
+      await pruneLogDirs(root, 1, 'run_001');
+      expect(readdirSync(root).sort()).toEqual(['run_001']);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  test('ignores entries that do not look like run dirs', async () => {
+    const root = fixture();
+    try {
+      mkdirSync(join(root, 'run_001'));
+      mkdirSync(join(root, 'not_a_run'));
+      await pruneLogDirs(root, 1, 'run_001');
+      expect(readdirSync(root).sort()).toEqual(['not_a_run', 'run_001']);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+});

package/src/core/log-prune.ts

@@ -0,0 +1,43 @@
+import { readdir, rm } from 'node:fs/promises';
+import { resolve } from 'node:path';
+
+/**
+ * Delete the oldest subdirectories under `logsDir`, keeping only the
+ * most recent `keep` total runs (including the currently-live run
+ * identified by `excludeRunId`). Directories are sorted
+ * lexicographically; because runIds are prefixed with a base-36
+ * timestamp, lexicographic order equals chronological order.
+ *
+ * `excludeRunId` is always skipped from deletion even if it would
+ * otherwise be pruned — this prevents a concurrent run from removing a
+ * live log directory that is still in use.
+ *
+ * The live run occupies one slot out of `keep`, so the maximum number
+ * of *historical* dirs to retain is `keep - 1`.
+ */
+export async function pruneLogDirs(
+  logsDir: string,
+  keep: number,
+  excludeRunId: string,
+): Promise<void> {
+  let entries: string[];
+  try {
+    entries = await readdir(logsDir);
+  } catch {
+    return; // logsDir doesn't exist yet
+  }
+
+  const runDirs = entries
+    .filter((e) => e.startsWith('run_') && e !== excludeRunId)
+    .sort();
+  const historyKeep = Math.max(0, keep - 1);
+  const toDelete = runDirs.slice(0, Math.max(0, runDirs.length - historyKeep));
+
+  await Promise.all(
+    toDelete.map((dir) =>
+      rm(resolve(logsDir, dir), { recursive: true, force: true }).catch(() => {
+        // Ignore deletion errors — stale dirs are better than a crash
+      }),
+    ),
+  );
+}

package/src/core/preflight.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, test } from 'bun:test';
+import { preflight } from './preflight';
+import { buildDag } from '../dag';
+import { PluginRegistry } from '../registry';
+import { bootstrapBuiltins } from '../bootstrap';
+import type { PipelineConfig } from '../types';
+
+function emptyConfig(overrides: Partial<PipelineConfig> = {}): PipelineConfig {
+  return {
+    name: 'p',
+    tracks: [{ id: 't', name: 'T', tasks: [] }],
+    ...overrides,
+  };
+}
+
+describe('preflight', () => {
+  test('throws when a referenced driver is not registered', () => {
+    const reg = new PluginRegistry();
+    const cfg = emptyConfig({
+      tracks: [
+        { id: 't', name: 'T', tasks: [{ id: 'a', name: 'A', prompt: 'hi' }] },
+      ],
+    });
+    expect(() => preflight(cfg, buildDag(cfg), reg)).toThrow(
+      /driver "opencode" not registered/,
+    );
+  });
+
+  test('passes when all referenced plugins are registered', () => {
+    const reg = new PluginRegistry();
+    bootstrapBuiltins(reg);
+    const cfg = emptyConfig({
+      tracks: [
+        { id: 't', name: 'T', tasks: [{ id: 'a', name: 'A', prompt: 'hi' }] },
+      ],
+    });
+    expect(() => preflight(cfg, buildDag(cfg), reg)).not.toThrow();
+  });
+
+  test('skips driver check for command-only tasks', () => {
+    const reg = new PluginRegistry(); // no drivers registered
+    const cfg = emptyConfig({
+      tracks: [
+        { id: 't', name: 'T', tasks: [{ id: 'a', name: 'A', command: 'echo hi' }] },
+      ],
+    });
+    expect(() => preflight(cfg, buildDag(cfg), reg)).not.toThrow();
+  });
+});

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  - ')}`);
+  }
+}