@tagma/sdk 0.6.12 → 0.7.1

package/src/index.ts

@@ -0,0 +1,28 @@
+export { createTagma } from './tagma';
+export type { CreateTagmaOptions, Tagma, TagmaRunOptions } from './tagma';
+export { definePipeline } from './pipeline-definition';
+export { PluginRegistry } from './registry';
+export { TriggerBlockedError, TriggerTimeoutError } from './engine';
+export type { EngineResult, RunEventPayload } from './engine';
+export { RUN_PROTOCOL_VERSION, TASK_LOG_CAP } from './types';
+export type {
+  PipelineConfig,
+  RawPipelineConfig,
+  RawTrackConfig,
+  RawTaskConfig,
+  TrackConfig,
+  TaskConfig,
+  RunSnapshotPayload,
+  WireRunEvent,
+  RunTaskState,
+  TaskLogLine,
+  ApprovalRequestInfo,
+  TaskStatus,
+  ApprovalRequest,
+  PluginCategory,
+  DriverPlugin,
+  TriggerPlugin,
+  CompletionPlugin,
+  MiddlewarePlugin,
+  RunEventPayload as PipelineRunEventPayload,
+} from '@tagma/types';

package/src/pipeline-definition.ts

@@ -0,0 +1,5 @@
+import type { RawPipelineConfig } from './types';
+
+export function definePipeline<T extends RawPipelineConfig>(pipeline: T): T {
+  return pipeline;
+}

package/src/pipeline-runner.test.ts

@@ -11,7 +11,7 @@ function makeDir(): string {
   return mkdtempSync(join(tmpdir(), 'tagma-pipeline-runner-'));
 }
 
-function portsPipeline(dir: string): PipelineConfig {
+function bindingsPipeline(dir: string): PipelineConfig {
   const emit = join(dir, 'emit.js');
   writeFileSync(
     emit,
@@ -31,18 +31,14 @@ function portsPipeline(dir: string): PipelineConfig {
             id: 'up',
             name: 'up',
             command: `node "${emit}"`,
-            ports: {
-              outputs: [{ name: 'city', type: 'string' }],
-            },
+            outputs: { city: { type: 'string' } },
           },
           {
             id: 'down',
             name: 'down',
             depends_on: ['up'],
             command: `node "${echo}" "{{inputs.city}}"`,
-            ports: {
-              inputs: [{ name: 'city', type: 'string', required: true }],
-            },
+            inputs: { city: { from: 't.up.outputs.city', type: 'string', required: true } },
           },
         ],
       },
@@ -67,7 +63,7 @@ describe('PipelineRunner task snapshot', () => {
   test('getTasks reflects task_update inputs and outputs', async () => {
     const dir = makeDir();
     try {
-      const runner = await run(portsPipeline(dir), dir);
+      const runner = await run(bindingsPipeline(dir), dir);
 
       const tasks = runner.getTasks();
       const up = tasks.get('t.up');
@@ -82,7 +78,7 @@ describe('PipelineRunner task snapshot', () => {
   test('getTasks folds streamed task logs into the task snapshot', async () => {
     const dir = makeDir();
     try {
-      const runner = await run(portsPipeline(dir), dir);
+      const runner = await run(bindingsPipeline(dir), dir);
 
       const tasks = runner.getTasks();
       const up = tasks.get('t.up');

package/src/pipeline-runner.ts

@@ -13,7 +13,7 @@
 //
 //   const runners = new Map<string, PipelineRunner>();
 //
-//   const runner = new PipelineRunner(config, workDir);
+//   const runner = new PipelineRunner(config, workDir, { registry });
 //   runner.subscribe(event => ipcEmit('run_event', event));
 //   runner.start();
 //   runners.set(runner.instanceId, runner);
@@ -29,6 +29,7 @@ import { generateRunId } from './utils';
 export type { EngineResult };
 
 export type PipelineRunnerStatus = 'idle' | 'running' | 'done' | 'aborted';
+export type PipelineRunnerOptions = Omit<RunPipelineOptions, 'signal' | 'onEvent'>;
 
 export class PipelineRunner {
   /**
@@ -57,7 +58,7 @@ export class PipelineRunner {
   constructor(
     private readonly config: PipelineConfig,
     private readonly workDir: string,
-    private readonly opts: Omit<RunPipelineOptions, 'signal' | 'onEvent'> = {},
+    private readonly opts: PipelineRunnerOptions,
   ) {
     this.instanceId = generateRunId();
   }

package/src/plugin-registry.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from 'bun:test';
-import { PluginRegistry, defaultRegistry } from './registry';
+import { PluginRegistry } from './registry';
 import { bootstrapBuiltins } from './bootstrap';
 import { runPipeline } from './engine';
 import type { DriverPlugin, TriggerPlugin, PipelineConfig } from './types';
@@ -80,7 +80,7 @@ describe('PluginRegistry — instance isolation', () => {
     expect(reg.getHandler<DriverPlugin>('drivers', 'mock').name).toBe('two');
   });
 
-  test('bootstrapBuiltins(target) populates a specific instance without touching the default', () => {
+  test('bootstrapBuiltins(target) populates a specific instance', () => {
     const fresh = new PluginRegistry();
     expect(fresh.hasHandler('drivers', 'opencode')).toBe(false);
 
@@ -222,13 +222,9 @@ describe('runPipeline — options.registry isolation', () => {
     }
   });
 
-  test('omitting options.registry falls back to defaultRegistry', async () => {
-    // bootstrapBuiltins into default happens in most host callers; do it
-    // explicitly here so the test is independent of module-load order.
-    bootstrapBuiltins(defaultRegistry);
-
+  test('runPipeline rejects missing explicit registry', async () => {
     const config: PipelineConfig = {
-      name: 'default-fallback',
+      name: 'missing-registry',
       tracks: [
         {
           id: 't',
@@ -239,8 +235,9 @@ describe('runPipeline — options.registry isolation', () => {
     };
     const tmp = mkdtempSync(join(tmpdir(), 'tagma-default-'));
     try {
-      const res = await runPipeline(config, tmp, { skipPluginLoading: true });
-      expect(res.success).toBe(true);
+      await expect(
+        runPipeline(config, tmp, { skipPluginLoading: true } as never),
+      ).rejects.toThrow(/requires options\.registry/);
     } finally {
       rmSync(tmp, { recursive: true, force: true });
     }

package/src/plugins.ts

@@ -0,0 +1,18 @@
+export { bootstrapBuiltins } from './bootstrap';
+export {
+  PluginRegistry,
+  isValidPluginName,
+  PLUGIN_NAME_RE,
+  readPluginManifest,
+} from './registry';
+export type { RegisterResult } from './registry';
+export type {
+  PluginCategory,
+  PluginModule,
+  PluginManifest,
+  DriverPlugin,
+  TriggerPlugin,
+  CompletionPlugin,
+  MiddlewarePlugin,
+} from './types';
+

package/src/ports.test.ts

@@ -249,6 +249,59 @@ describe('resolveTaskInputs', () => {
 // ─── resolveTaskBindingInputs ────────────────────────────────────────
 
 describe('resolveTaskBindingInputs', () => {
+  test('coerces typed unified inputs from upstream outputs', () => {
+    const t = task({
+      id: 'downstream',
+      command: 'echo',
+      inputs: {
+        id: { from: 't.up.outputs.id', type: 'number', required: true },
+        enabled: { value: 'true', type: 'boolean' },
+      },
+    });
+    const upstream = new Map([
+      [
+        't.up',
+        {
+          outputs: { id: '42' },
+          stdout: '',
+          stderr: '',
+          normalizedOutput: null,
+          exitCode: 0,
+        },
+      ],
+    ]);
+    const res = resolveTaskBindingInputs(t, upstream, ['t.up']);
+    expect(res.kind).toBe('ready');
+    if (res.kind !== 'ready') return;
+    expect(res.inputs).toEqual({ id: 42, enabled: true });
+  });
+
+  test('blocks typed unified input coercion failures', () => {
+    const t = task({
+      id: 'downstream',
+      command: 'echo',
+      inputs: {
+        id: { from: 't.up.outputs.id', type: 'number', required: true },
+      },
+    });
+    const upstream = new Map([
+      [
+        't.up',
+        {
+          outputs: { id: 'not-a-number' },
+          stdout: '',
+          stderr: '',
+          normalizedOutput: null,
+          exitCode: 0,
+        },
+      ],
+    ]);
+    const res = resolveTaskBindingInputs(t, upstream, ['t.up']);
+    expect(res.kind).toBe('blocked');
+    if (res.kind !== 'blocked') return;
+    expect(res.typeErrors).toEqual([{ input: 'id', reason: 'expected number, got string' }]);
+  });
+
   test('resolves literal values and defaults without requiring ports', () => {
     const t = task({
       id: 'downstream',
@@ -387,6 +440,33 @@ describe('extractTaskOutputs', () => {
 // ─── extractTaskBindingOutputs ───────────────────────────────────────
 
 describe('extractTaskBindingOutputs', () => {
+  test('coerces typed unified outputs from final-line JSON', () => {
+    const r = extractTaskBindingOutputs(
+      {
+        id: { type: 'number' },
+        ok: { from: 'json.success', type: 'boolean' },
+      },
+      'log\n{"id":"42","success":"true"}\n',
+      '',
+      null,
+    );
+    expect(r.outputs).toEqual({ id: 42, ok: true });
+    expect(r.diagnostic).toBeNull();
+  });
+
+  test('diagnoses typed unified output coercion failures', () => {
+    const r = extractTaskBindingOutputs(
+      {
+        id: { type: 'number' },
+      },
+      '{"id":"nope"}',
+      '',
+      null,
+    );
+    expect(r.outputs).toEqual({});
+    expect(r.diagnostic).toContain('"id": expected number, got string');
+  });
+
   test('extracts loose outputs from final-line JSON by default', () => {
     const r = extractTaskBindingOutputs(
       {

package/src/ports.ts

@@ -270,6 +270,7 @@ export type BindingInputResolution =
       readonly kind: 'blocked';
       readonly missingRequired: readonly string[];
       readonly ambiguous: readonly { input: string; producers: readonly string[] }[];
+      readonly typeErrors: readonly { input: string; reason: string }[];
       readonly reason: string;
     };
 
@@ -287,6 +288,7 @@ export function resolveTaskBindingInputs(
   const missingRequired: string[] = [];
   const missingOptional: string[] = [];
   const ambiguous: { input: string; producers: string[] }[] = [];
+  const typeErrors: { input: string; reason: string }[] = [];
 
   for (const [name, binding] of Object.entries(bindings)) {
     let value: unknown;
@@ -321,10 +323,16 @@ export function resolveTaskBindingInputs(
       continue;
     }
 
-    inputs[name] = value;
+    const coerced = coerceBindingValue(binding, value);
+    if (coerced.kind === 'error') {
+      typeErrors.push({ input: name, reason: coerced.reason });
+      continue;
+    }
+
+    inputs[name] = coerced.value;
   }
 
-  if (missingRequired.length > 0 || ambiguous.length > 0) {
+  if (missingRequired.length > 0 || ambiguous.length > 0 || typeErrors.length > 0) {
     const lines: string[] = [];
     if (missingRequired.length > 0) {
       lines.push(`missing required binding input(s): ${missingRequired.join(', ')}`);
@@ -335,7 +343,10 @@ export function resolveTaskBindingInputs(
           `(${amb.producers.join(', ')}) — use "taskId.outputs.${amb.input}"`,
       );
     }
-    return { kind: 'blocked', missingRequired, ambiguous, reason: lines.join('\n') };
+    for (const te of typeErrors) {
+      lines.push(`binding input "${te.input}": ${te.reason}`);
+    }
+    return { kind: 'blocked', missingRequired, ambiguous, typeErrors, reason: lines.join('\n') };
   }
 
   return { kind: 'ready', inputs, missingOptional };
@@ -494,6 +505,21 @@ function coerceValue(port: PortDef, raw: unknown): Coercion {
   }
 }
 
+function coerceBindingValue(
+  binding: { readonly type?: PortType; readonly enum?: readonly string[] },
+  raw: unknown,
+): Coercion {
+  if (!binding.type) return { kind: 'ok', value: raw };
+  return coerceValue(
+    {
+      name: 'binding',
+      type: binding.type,
+      ...(binding.enum ? { enum: binding.enum } : {}),
+    },
+    raw,
+  );
+}
+
 function describe(v: unknown): string {
   if (v === null) return 'null';
   if (Array.isArray(v)) return 'array';
@@ -630,7 +656,13 @@ export function extractTaskBindingOutputs(
       continue;
     }
 
-    outputs[name] = value;
+    const coerced = coerceBindingValue(binding, value);
+    if (coerced.kind === 'error') {
+      missing.push(`"${name}": ${coerced.reason}`);
+      continue;
+    }
+
+    outputs[name] = coerced.value;
   }
 
   return {

package/src/registry.ts

@@ -37,7 +37,7 @@ function singularCategory(category: PluginCategory): string {
  * registration time rather than crashing the engine mid-run.
  *
  * For drivers we materialize `capabilities` and assert each field is a
- * boolean — otherwise a plugin author can write
+ * boolean �?otherwise a plugin author can write
  *     get capabilities() { throw new Error('boom') }
  * and pass the basic typeof check, then crash preflight when the engine
  * touches `driver.capabilities.sessionResume`. (R8)
@@ -55,7 +55,7 @@ function validateContract(category: PluginCategory, handler: unknown): void {
       if (typeof h.buildCommand !== 'function') {
         throw new Error(`drivers plugin "${h.name}" must export buildCommand()`);
       }
-      // Materialize capabilities — this triggers any throwing getter NOW
+      // Materialize capabilities �?this triggers any throwing getter NOW
       // instead of during preflight.
       let caps: unknown;
       try {
@@ -132,7 +132,7 @@ export function isValidPluginName(name: unknown): name is string {
  *
  * Returns the strongly-typed manifest if the field is present and
  * well-formed (`category` is one of the four known categories and `type`
- * is a non-empty string). Returns `null` if the field is absent — that
+ * is a non-empty string). Returns `null` if the field is absent �?that
  * is the host's signal that the package is a library, not a plugin.
  *
  * Throws if the field is present but malformed: that's a packaging bug
@@ -170,9 +170,7 @@ export function readPluginManifest(pkgJson: unknown): PluginManifest | null {
 /**
  * Instance-scoped plugin registry. Each workspace in a multi-tenant sidecar
  * owns its own PluginRegistry, so installing/uninstalling a driver in one
- * workspace cannot clobber another. The process-wide `defaultRegistry`
- * exported at the bottom of this file preserves the historical free-function
- * API (registerPlugin / getHandler / …) for CLI and single-tenant hosts.
+ * workspace cannot clobber another.
  */
 export class PluginRegistry {
   private readonly registries = {
@@ -216,12 +214,12 @@ export class PluginRegistry {
     if (wasReplaced) {
       // D18: surface silent shadowing. Hot-reload flows legitimately replace
       // handlers; installing two different plugin packages that both claim
-      // the same (category, type) does not — the second wins and breaks the
+      // the same (category, type) does not �?the second wins and breaks the
       // first's consumers with no audit trail. A console.warn is cheap,
       // respects existing callers that rely on 'replaced', and gives ops a
       // grep-able signal when registrations collide unexpectedly.
       console.warn(
-        `[tagma-sdk] registerPlugin: replaced existing ${category}/${type} — ` +
+        `[tagma-sdk] registerPlugin: replaced existing ${category}/${type} �?` +
           `check for duplicate plugin packages claiming the same type.`,
       );
     }
@@ -231,8 +229,7 @@ export class PluginRegistry {
   /**
    * Remove a plugin from the in-process registry. Returns true if a plugin
    * was actually removed. Note: ESM module caching is not affected, so
-   * re-importing the same file after unregister will yield the cached module —
-   * callers wanting a fresh load must restart the host process.
+   * re-importing the same file after unregister will yield the cached module �?   * callers wanting a fresh load must restart the host process.
    */
   unregisterPlugin(category: PluginCategory, type: string): boolean {
     if (!VALID_CATEGORIES.has(category)) return false;
@@ -299,42 +296,3 @@ export class PluginRegistry {
     }
   }
 }
-
-/**
- * Process-wide default registry. Preserves the historical free-function API
- * for CLI and single-tenant hosts. Multi-tenant hosts (the editor sidecar
- * after the one-sidecar refactor) build their own `PluginRegistry` per
- * workspace and pass it through `RunPipelineOptions.registry`.
- */
-export const defaultRegistry = new PluginRegistry();
-
-export function registerPlugin<T extends PluginType>(
-  category: PluginCategory,
-  type: string,
-  handler: T,
-): RegisterResult {
-  return defaultRegistry.registerPlugin(category, type, handler);
-}
-
-export function unregisterPlugin(category: PluginCategory, type: string): boolean {
-  return defaultRegistry.unregisterPlugin(category, type);
-}
-
-export function getHandler<T extends PluginType>(category: PluginCategory, type: string): T {
-  return defaultRegistry.getHandler<T>(category, type);
-}
-
-export function hasHandler(category: PluginCategory, type: string): boolean {
-  return defaultRegistry.hasHandler(category, type);
-}
-
-export function listRegistered(category: PluginCategory): string[] {
-  return defaultRegistry.listRegistered(category);
-}
-
-export function loadPlugins(
-  pluginNames: readonly string[],
-  resolveFrom?: string,
-): Promise<void> {
-  return defaultRegistry.loadPlugins(pluginNames, resolveFrom);
-}