@tagma/sdk 0.7.0 → 0.7.3

package/src/schema-ports.test.ts

@@ -1,19 +1,12 @@
 import { describe, expect, test } from 'bun:test';
 import yaml from 'js-yaml';
 import type { PipelineConfig, RawPipelineConfig } from './types';
-import {
-  deresolvePipeline,
-  parseYaml,
-  resolveConfig,
-  serializePipeline,
-} from './schema';
+import { deresolvePipeline, parseYaml, resolveConfig, serializePipeline } from './schema';
 
 const WORK_DIR = process.platform === 'win32' ? 'D:\\fake-work' : '/fake-work';
 
-// ─── resolveConfig preserves ports ───────────────────────────────────
-
-describe('resolveConfig — ports passthrough', () => {
-  test('raw lightweight bindings survive onto the resolved task', () => {
+describe('schema — unified bindings passthrough', () => {
+  test('typed inputs and outputs survive onto the resolved task', () => {
     const raw: RawPipelineConfig = {
       name: 'p',
       tracks: [
@@ -24,94 +17,19 @@ describe('resolveConfig — ports passthrough', () => {
             {
               id: 'a',
               command: 'echo "{{inputs.city}}"',
-              inputs: {
-                city: { from: 't.plan.outputs.city', required: true },
-              },
-              outputs: {
-                report: { from: 'json.reportPath' },
-              },
+              inputs: { city: { from: 't.plan.outputs.city', type: 'string', required: true } },
+              outputs: { report: { from: 'json.reportPath', type: 'string' } },
             },
           ],
         },
       ],
     };
-    const resolved = resolveConfig(raw, WORK_DIR);
-    const task = resolved.tracks[0]!.tasks[0]!;
+    const task = resolveConfig(raw, WORK_DIR).tracks[0]!.tasks[0]!;
     expect(task.inputs).toEqual(raw.tracks[0]!.tasks[0]!.inputs!);
     expect(task.outputs).toEqual(raw.tracks[0]!.tasks[0]!.outputs!);
   });
 
-  test('raw ports survive onto the resolved task', () => {
-    const raw: RawPipelineConfig = {
-      name: 'p',
-      tracks: [
-        {
-          id: 't',
-          name: 'T',
-          tasks: [
-            {
-              id: 'a',
-              prompt: 'do it',
-              ports: {
-                inputs: [{ name: 'city', type: 'string', required: true }],
-                outputs: [{ name: 'temp', type: 'number', description: 'Celsius' }],
-              },
-            },
-          ],
-        },
-      ],
-    };
-    const resolved = resolveConfig(raw, WORK_DIR);
-    const task = resolved.tracks[0]!.tasks[0]!;
-    expect(task.ports).toBeDefined();
-    expect(task.ports!.inputs).toEqual([
-      { name: 'city', type: 'string', required: true },
-    ]);
-    expect(task.ports!.outputs).toEqual([
-      { name: 'temp', type: 'number', description: 'Celsius' },
-    ]);
-  });
-
-  test('tasks without ports still resolve with ports === undefined', () => {
-    const raw: RawPipelineConfig = {
-      name: 'p',
-      tracks: [
-        { id: 't', name: 'T', tasks: [{ id: 'a', prompt: 'do it' }] },
-      ],
-    };
-    const resolved = resolveConfig(raw, WORK_DIR);
-    expect(resolved.tracks[0]!.tasks[0]!.ports).toBeUndefined();
-  });
-
-  test('ports is not inherited from track or pipeline', () => {
-    // Ports describe a per-task I/O contract. If we accidentally pulled
-    // them from track defaults, two tasks in the same track would share
-    // input ports and downstream data-flow would be ambiguous. Test that
-    // a track with an unrelated `middlewares` default doesn't spread
-    // anywhere unexpected — purely a regression guard for the no-inherit
-    // invariant.
-    const raw: RawPipelineConfig = {
-      name: 'p',
-      tracks: [
-        {
-          id: 't',
-          name: 'T',
-          middlewares: [{ type: 'static_context', file: './x' }],
-          tasks: [{ id: 'a', prompt: 'x' }, { id: 'b', prompt: 'y' }],
-        },
-      ],
-    };
-    const resolved = resolveConfig(raw, WORK_DIR);
-    for (const task of resolved.tracks[0]!.tasks) {
-      expect(task.ports).toBeUndefined();
-    }
-  });
-});
-
-// ─── deresolvePipeline preserves ports ───────────────────────────────
-
-describe('deresolvePipeline — ports round-trip', () => {
-  test('lightweight bindings round-trip', () => {
+  test('typed inputs and outputs round-trip through deresolve', () => {
     const raw: RawPipelineConfig = {
       name: 'p',
       tracks: [
@@ -123,25 +41,26 @@ describe('deresolvePipeline — ports round-trip', () => {
               id: 'a',
               command: 'echo "{{inputs.city}}"',
               inputs: {
-                city: { from: 't.plan.outputs.city', required: true },
-                mode: { default: 'quick' },
-              },
-              outputs: {
-                raw: { from: 'stdout' },
+                city: {
+                  from: 't.plan.outputs.city',
+                  type: 'enum',
+                  enum: ['Shanghai', 'Paris'],
+                  required: true,
+                },
               },
+              outputs: { raw: { from: 'stdout' } },
             },
           ],
         },
       ],
     };
-    const resolved = resolveConfig(raw, WORK_DIR);
-    const back = deresolvePipeline(resolved, WORK_DIR);
+    const back = deresolvePipeline(resolveConfig(raw, WORK_DIR), WORK_DIR);
     expect(back.tracks[0]!.tasks[0]!.inputs).toEqual(raw.tracks[0]!.tasks[0]!.inputs!);
     expect(back.tracks[0]!.tasks[0]!.outputs).toEqual(raw.tracks[0]!.tasks[0]!.outputs!);
   });
 
-  test('ports with both inputs and outputs round-trip', () => {
-    const raw: RawPipelineConfig = {
+  test('empty binding maps are dropped on deresolve', () => {
+    const resolved: PipelineConfig = {
       name: 'p',
       tracks: [
         {
@@ -150,22 +69,21 @@ describe('deresolvePipeline — ports round-trip', () => {
           tasks: [
             {
               id: 'a',
+              name: 'a',
               prompt: 'hi',
-              ports: {
-                inputs: [{ name: 'city', type: 'string', required: true }],
-                outputs: [{ name: 'temp', type: 'number' }],
-              },
+              inputs: {},
+              outputs: {},
             },
           ],
         },
       ],
     };
-    const resolved = resolveConfig(raw, WORK_DIR);
     const back = deresolvePipeline(resolved, WORK_DIR);
-    expect(back.tracks[0]!.tasks[0]!.ports).toEqual(raw.tracks[0]!.tasks[0]!.ports!);
+    expect(back.tracks[0]!.tasks[0]!.inputs).toBeUndefined();
+    expect(back.tracks[0]!.tasks[0]!.outputs).toBeUndefined();
   });
 
-  test('ports with only outputs round-trip', () => {
+  test('legacy ports are not carried through resolve or deresolve', () => {
     const raw: RawPipelineConfig = {
       name: 'p',
       tracks: [
@@ -175,51 +93,20 @@ describe('deresolvePipeline — ports round-trip', () => {
           tasks: [
             {
               id: 'a',
-              command: 'echo hi',
-              ports: { outputs: [{ name: 'x', type: 'string' }] },
+              command: 'echo ok',
+              ports: { outputs: [{ name: 'old', type: 'string' }] },
             },
           ],
         },
       ],
     };
     const resolved = resolveConfig(raw, WORK_DIR);
-    const back = deresolvePipeline(resolved, WORK_DIR);
-    expect(back.tracks[0]!.tasks[0]!.ports).toEqual({
-      outputs: [{ name: 'x', type: 'string' }],
-    });
-  });
-
-  test('empty ports ({}) is dropped on deresolve', () => {
-    // YAML round-trip prefers field absence over `ports: {}` so a task
-    // that once declared a port but had it cleared in the editor
-    // doesn't persist a useless empty object in the file.
-    const resolved: PipelineConfig = {
-      name: 'p',
-      tracks: [
-        {
-          id: 't',
-          name: 'T',
-          driver: 'opencode',
-          permissions: { read: true, write: false, execute: false },
-          on_failure: 'skip_downstream',
-          tasks: [
-            {
-              id: 'a',
-              name: 'a',
-              prompt: 'hi',
-              permissions: { read: true, write: false, execute: false },
-              driver: 'opencode',
-              ports: {},
-            },
-          ],
-        },
-      ],
-    };
+    expect(resolved.tracks[0]!.tasks[0]!.ports).toBeUndefined();
     const back = deresolvePipeline(resolved, WORK_DIR);
     expect(back.tracks[0]!.tasks[0]!.ports).toBeUndefined();
   });
 
-  test('YAML round-trip via serializePipeline preserves the full ports shape', () => {
+  test('YAML round-trip preserves typed unified binding shape', () => {
     const raw: RawPipelineConfig = {
       name: 'p',
       tracks: [
@@ -230,18 +117,13 @@ describe('deresolvePipeline — ports round-trip', () => {
             {
               id: 'classify',
               prompt: 'pick a bucket',
-              ports: {
-                inputs: [
-                  { name: 'doc', type: 'string', required: true, description: 'Full text' },
-                ],
-                outputs: [
-                  {
-                    name: 'bucket',
-                    type: 'enum',
-                    enum: ['spam', 'ham'],
-                    description: 'Classification',
-                  },
-                ],
+              inputs: { doc: { type: 'string', required: true, description: 'Full text' } },
+              outputs: {
+                bucket: {
+                  type: 'enum',
+                  enum: ['spam', 'ham'],
+                  description: 'Classification',
+                },
               },
             },
           ],
@@ -250,14 +132,11 @@ describe('deresolvePipeline — ports round-trip', () => {
     };
     const yamlText = serializePipeline(raw);
     const parsed = (yaml.load(yamlText) as { pipeline: RawPipelineConfig }).pipeline;
-    expect(parsed.tracks[0]!.tasks[0]!.ports).toEqual(raw.tracks[0]!.tasks[0]!.ports!);
+    expect(parsed.tracks[0]!.tasks[0]!.inputs).toEqual(raw.tracks[0]!.tasks[0]!.inputs!);
+    expect(parsed.tracks[0]!.tasks[0]!.outputs).toEqual(raw.tracks[0]!.tasks[0]!.outputs!);
   });
-});
-
-// ─── parseYaml accepts ports ─────────────────────────────────────────
 
-describe('parseYaml — accepts ports declarations', () => {
-  test('real-world YAML with lightweight bindings parses cleanly', () => {
+  test('real-world YAML with typed bindings parses cleanly', () => {
     const text = `pipeline:
   name: demo
   tracks:
@@ -267,56 +146,27 @@ describe('parseYaml — accepts ports declarations', () => {
         - id: build
           command: bun run build
           outputs:
-            bundlePath: { from: json.bundlePath }
+            bundlePath:
+              from: json.bundlePath
+              type: string
         - id: test
           depends_on: [build]
           command: 'bun test "{{inputs.bundlePath}}"'
           inputs:
             bundlePath:
               from: t.build.outputs.bundlePath
+              type: string
               required: true
 `;
     const config = parseYaml(text);
-    const build = config.tracks[0]!.tasks[0]!;
-    const testTask = config.tracks[0]!.tasks[1]!;
-    expect(build.outputs!.bundlePath).toEqual({ from: 'json.bundlePath' });
-    expect(testTask.inputs!.bundlePath).toEqual({
+    expect(config.tracks[0]!.tasks[0]!.outputs!.bundlePath).toEqual({
+      from: 'json.bundlePath',
+      type: 'string',
+    });
+    expect(config.tracks[0]!.tasks[1]!.inputs!.bundlePath).toEqual({
       from: 't.build.outputs.bundlePath',
+      type: 'string',
       required: true,
     });
   });
-
-  test('real-world YAML with ports parses cleanly', () => {
-    const text = `pipeline:
-  name: demo
-  tracks:
-    - id: t
-      name: Main
-      tasks:
-        - id: plan
-          prompt: Pick a city and id
-          ports:
-            outputs:
-              - name: city
-                type: string
-                description: Target city
-              - name: id
-                type: number
-        - id: fetch
-          depends_on: [plan]
-          command: 'weather.sh --city "{{inputs.city}}" --id {{inputs.id}}'
-          ports:
-            inputs:
-              - { name: city, type: string, required: true }
-              - { name: id, type: number, required: true }
-            outputs:
-              - { name: temp, type: number }
-`;
-    const config = parseYaml(text);
-    const plan = config.tracks[0]!.tasks[0]!;
-    const fetch = config.tracks[0]!.tasks[1]!;
-    expect(plan.ports!.outputs!.map((p) => p.name)).toEqual(['city', 'id']);
-    expect(fetch.ports!.inputs!.map((p) => p.name)).toEqual(['city', 'id']);
-    expect(fetch.ports!.outputs!.map((p) => p.name)).toEqual(['temp']);
-  });
 });

package/src/schema.ts

@@ -161,11 +161,10 @@ export function resolveConfig(raw: RawPipelineConfig, workDir: string): Pipeline
         completion: rawTask.completion,
         agent_profile: rawTask.agent_profile ?? rawTrack.agent_profile,
         cwd: rawTask.cwd ? validatePath(rawTask.cwd, workDir) : trackCwd,
-        // Lightweight bindings and ports: no inheritance — they describe
+        // Unified bindings have no inheritance; they describe
         // per-task data flow, not cross-task defaults.
         inputs: rawTask.inputs,
         outputs: rawTask.outputs,
-        ports: rawTask.ports,
       };
     });
 
@@ -313,11 +312,6 @@ export function deresolvePipeline(config: PipelineConfig, workDir: string): RawP
           : {}),
         ...(task.inputs && Object.keys(task.inputs).length > 0 ? { inputs: task.inputs } : {}),
         ...(task.outputs && Object.keys(task.outputs).length > 0 ? { outputs: task.outputs } : {}),
-        ...(task.ports &&
-        ((task.ports.inputs && task.ports.inputs.length > 0) ||
-          (task.ports.outputs && task.ports.outputs.length > 0))
-          ? { ports: task.ports }
-          : {}),
       };
     });
 

package/src/tagma.test.ts

@@ -3,7 +3,8 @@ import { mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { createTagma } from './tagma';
-import type { DriverPlugin, PipelineConfig } from './types';
+import type { DriverPlugin, TagmaPlugin, TaskResult } from './types';
+import type { TagmaRuntime } from './runtime';
 
 function makeDir(prefix: string): string {
   return mkdtempSync(join(tmpdir(), prefix));
@@ -21,6 +22,76 @@ function makeDriver(name: string, marker: string[]): DriverPlugin {
 }
 
 describe('createTagma', () => {
+  test('runs command tasks through the configured runtime', async () => {
+    const calls: string[] = [];
+    const taskResult: TaskResult = {
+      exitCode: 0,
+      stdout: 'runtime-ok',
+      stderr: '',
+      stdoutPath: null,
+      stderrPath: null,
+      stdoutBytes: 10,
+      stderrBytes: 0,
+      durationMs: 1,
+      sessionId: null,
+      normalizedOutput: null,
+      failureKind: null,
+    };
+    const runtime: TagmaRuntime = {
+      async runCommand(command, cwd) {
+        calls.push(`${cwd}:${command}`);
+        return taskResult;
+      },
+      async runSpawn() {
+        throw new Error('runSpawn should not be called for command tasks');
+      },
+    };
+    const tagma = createTagma({ builtins: false, runtime });
+    const dir = makeDir('tagma-runtime-run-');
+    try {
+      const result = await tagma.run(
+        {
+          name: 'runtime-run',
+          tracks: [
+            {
+              id: 't',
+              name: 'T',
+              tasks: [{ id: 'cmd', name: 'cmd', command: 'fake-only-command' }],
+            },
+          ],
+        },
+        {
+          cwd: dir,
+          skipPluginLoading: true,
+        },
+      );
+
+      expect(result.success).toBe(true);
+      expect(calls).toEqual([`${dir}:fake-only-command`]);
+      expect(result.states.get('t.cmd')?.result?.stdout).toBe('runtime-ok');
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test('registers capability plugins passed to options', () => {
+    const seen: string[] = [];
+    const driver = makeDriver('driver-plugin', seen);
+    const plugin: TagmaPlugin = {
+      name: 'tagma-plugin-local',
+      capabilities: {
+        drivers: {
+          mock: driver,
+        },
+      },
+    };
+
+    const tagma = createTagma({ builtins: false, plugins: [plugin] });
+
+    expect(tagma.registry.getHandler<DriverPlugin>('drivers', 'mock')).toBe(driver);
+    expect(seen).toEqual([]);
+  });
+
   test('instances own isolated plugin registries', () => {
     const seenA: string[] = [];
     const seenB: string[] = [];

package/src/tagma.ts

@@ -2,7 +2,8 @@ import { runPipeline, type EngineResult, type RunPipelineOptions } from './engin
 import { bootstrapBuiltins } from './bootstrap';
 import { PluginRegistry } from './registry';
 import { validateConfig } from './schema';
-import type { PipelineConfig } from './types';
+import { bunRuntime, type TagmaRuntime } from './runtime';
+import type { PipelineConfig, TagmaPlugin } from './types';
 
 export interface CreateTagmaOptions {
   /**
@@ -14,6 +15,15 @@ export interface CreateTagmaOptions {
    * instance registry. Defaults to true.
    */
   readonly builtins?: boolean;
+  /**
+   * Package-level capability plugins to register into this SDK instance.
+   */
+  readonly plugins?: readonly TagmaPlugin[];
+  /**
+   * Runtime implementation used for command and driver process execution.
+   * Defaults to the SDK's Bun runtime.
+   */
+  readonly runtime?: TagmaRuntime;
 }
 
 export interface TagmaRunOptions extends Omit<RunPipelineOptions, 'registry'> {
@@ -28,9 +38,13 @@ export interface Tagma {
 
 export function createTagma(options: CreateTagmaOptions = {}): Tagma {
   const registry = options.registry ?? new PluginRegistry();
+  const runtime = options.runtime ?? bunRuntime();
   if (options.builtins !== false) {
     bootstrapBuiltins(registry);
   }
+  for (const plugin of options.plugins ?? []) {
+    registry.registerTagmaPlugin(plugin);
+  }
 
   return {
     registry,
@@ -38,6 +52,7 @@ export function createTagma(options: CreateTagmaOptions = {}): Tagma {
       return runPipeline(config, cwd, {
         ...runOptions,
         registry,
+        runtime,
       });
     },
     validate(config) {