@tagma/sdk 0.6.12 → 0.7.1

package/dist/yaml.js

@@ -0,0 +1,3 @@
+export { parseYaml, resolveConfig, loadPipeline, serializePipeline, deresolvePipeline, validateConfig, } from './schema';
+export { compileYamlContent } from './yaml-compiler';
+//# sourceMappingURL=yaml.js.map

package/dist/yaml.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"yaml.js","sourceRoot":"","sources":["../src/yaml.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,SAAS,EACT,aAAa,EACb,YAAY,EACZ,iBAAiB,EACjB,iBAAiB,EACjB,cAAc,GACf,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tagma/sdk",
-  "version": "0.6.12",
+  "version": "0.7.1",
   "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",
@@ -47,7 +92,7 @@
     "release:publish": "bun scripts/release.ts --publish"
   },
   "dependencies": {
-    "@tagma/types": "0.4.8",
+    "@tagma/types": "0.4.9",
     "js-yaml": "^4.1.0",
     "chokidar": "^4.0.0"
   }

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,166 @@
+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 typed outputs for command tasks', () => {
+    const config: PipelineConfig = {
+      name: 'p',
+      tracks: [
+        {
+          id: 't',
+          name: 'T',
+          tasks: [
+            {
+              id: 'cmd',
+              name: 'Cmd',
+              command: 'echo',
+              outputs: { 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',
+              outputs: { 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',
+              outputs: { city: { type: 'string' } },
+            },
+            {
+              id: 'b',
+              name: 'B',
+              command: 'echo',
+              outputs: { 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('extracts typed binding outputs', () => {
+    const config: PipelineConfig = {
+      name: 'p',
+      tracks: [
+        {
+          id: 't',
+          name: 'T',
+          tasks: [
+            {
+              id: 'cmd',
+              name: 'Cmd',
+              command: 'echo',
+              outputs: { city: { type: 'string' }, raw: { from: 'stdout' } },
+            },
+          ],
+        },
+      ],
+    };
+    const ctx = makeContext(config);
+    const node = ctx.dag.nodes.get('t.cmd')!;
+    const extracted = extractSuccessfulOutputs({
+      task: node.task,
+      effectivePorts: undefined,
+      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,161 @@
+import type {
+  PortDef,
+  TaskConfig,
+  TaskInputBindings,
+  TaskOutputBindings,
+  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;
+}
+
+function inputBindingsToPorts(bindings: TaskInputBindings | undefined): PortDef[] | undefined {
+  if (!bindings || Object.keys(bindings).length === 0) return undefined;
+  return Object.entries(bindings).map(([name, binding]) => ({
+    name,
+    type: binding.type ?? 'json',
+    ...(binding.description ? { description: binding.description } : {}),
+    ...(binding.required !== undefined ? { required: binding.required } : {}),
+    ...(binding.default !== undefined ? { default: binding.default } : {}),
+    ...(binding.enum ? { enum: [...binding.enum] } : {}),
+    ...(binding.from ? { from: binding.from } : {}),
+  }));
+}
+
+function outputBindingsToPorts(bindings: TaskOutputBindings | undefined): PortDef[] | undefined {
+  if (!bindings || Object.keys(bindings).length === 0) return undefined;
+  return Object.entries(bindings).map(([name, binding]) => ({
+    name,
+    type: binding.type ?? 'json',
+    ...(binding.description ? { description: binding.description } : {}),
+    ...(binding.default !== undefined ? { default: binding.default } : {}),
+    ...(binding.enum ? { enum: [...binding.enum] } : {}),
+  }));
+}
+
+function taskBindingsAsPorts(task: TaskConfig): TaskPorts | undefined {
+  const inputs = inputBindingsToPorts(task.inputs);
+  const outputs = outputBindingsToPorts(task.outputs);
+  if (!inputs && !outputs) return undefined;
+  return {
+    ...(inputs ? { inputs } : {}),
+    ...(outputs ? { outputs } : {}),
+  };
+}
+
+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: taskBindingsAsPorts(task) };
+  }
+
+  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 ? outputBindingsToPorts(upstream?.task.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 ? inputBindingsToPorts(downstream?.task.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;
+  }
+
+  if ((!task.outputs || Object.keys(task.outputs).length === 0) && effectivePorts?.outputs?.length) {
+    const portExtraction = extractTaskOutputs(
+      effectivePorts,
+      result.stdout,
+      result.normalizedOutput,
+    );
+    extractedOutputs = portExtraction.outputs;
+    return {
+      outputs: extractedOutputs,
+      bindingDiagnostic: bindingExtraction.diagnostic,
+      portDiagnostic: portExtraction.diagnostic,
+    };
+  }
+
+  return {
+    outputs: extractedOutputs,
+    bindingDiagnostic: bindingExtraction.diagnostic,
+    portDiagnostic: null,
+  };
+}

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