@tagma/sdk 0.6.11 → 0.7.0

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.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

@@ -1,8 +1,10 @@
 import { describe, expect, test } from 'bun:test';
 import {
   extractInputReferences,
+  extractTaskBindingOutputs,
   extractTaskOutputs,
   inferPromptPorts,
+  resolveTaskBindingInputs,
   resolveTaskInputs,
   substituteInputs,
 } from './ports';
@@ -244,6 +246,87 @@ describe('resolveTaskInputs', () => {
   });
 });
 
+// ─── resolveTaskBindingInputs ────────────────────────────────────────
+
+describe('resolveTaskBindingInputs', () => {
+  test('resolves literal values and defaults without requiring ports', () => {
+    const t = task({
+      id: 'downstream',
+      command: 'echo',
+      inputs: {
+        city: { value: 'Shanghai' },
+        mode: { from: 't.up.outputs.missing', default: 'quick' },
+      },
+    });
+    const res = resolveTaskBindingInputs(t, new Map(), ['t.up']);
+    expect(res).toEqual({
+      kind: 'ready',
+      inputs: { city: 'Shanghai', mode: 'quick' },
+      missingOptional: [],
+    });
+  });
+
+  test('resolves values from a direct upstream output and stdout', () => {
+    const t = task({
+      id: 'downstream',
+      command: 'echo',
+      inputs: {
+        city: { from: 't.up.outputs.city' },
+        raw: { from: 't.up.stdout' },
+      },
+    });
+    const upstream = new Map([
+      [
+        't.up',
+        {
+          outputs: { city: 'Shanghai' },
+          stdout: 'raw text\n',
+          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({ city: 'Shanghai', raw: 'raw text\n' });
+  });
+
+  test('blocks required missing bindings with a readable reason', () => {
+    const t = task({
+      id: 'downstream',
+      command: 'echo',
+      inputs: {
+        city: { from: 't.up.outputs.city', required: true },
+      },
+    });
+    const res = resolveTaskBindingInputs(t, new Map(), ['t.up']);
+    expect(res.kind).toBe('blocked');
+    if (res.kind !== 'blocked') return;
+    expect(res.missingRequired).toEqual(['city']);
+    expect(res.reason).toContain('missing required binding input(s): city');
+  });
+
+  test('detects ambiguous loose output name matches', () => {
+    const t = task({
+      id: 'downstream',
+      command: 'echo',
+      inputs: {
+        val: { from: 'outputs.val', required: true },
+      },
+    });
+    const upstream = new Map([
+      ['t.a', { outputs: { val: 'a' }, stdout: '', stderr: '', normalizedOutput: null, exitCode: 0 }],
+      ['t.b', { outputs: { val: 'b' }, stdout: '', stderr: '', normalizedOutput: null, exitCode: 0 }],
+    ]);
+    const res = resolveTaskBindingInputs(t, upstream, ['t.a', 't.b']);
+    expect(res.kind).toBe('blocked');
+    if (res.kind !== 'blocked') return;
+    expect(res.ambiguous[0]).toEqual({ input: 'val', producers: ['t.a', 't.b'] });
+  });
+});
+
 // ─── extractTaskOutputs ──────────────────────────────────────────────
 
 describe('extractTaskOutputs', () => {
@@ -301,6 +384,50 @@ describe('extractTaskOutputs', () => {
   });
 });
 
+// ─── extractTaskBindingOutputs ───────────────────────────────────────
+
+describe('extractTaskBindingOutputs', () => {
+  test('extracts loose outputs from final-line JSON by default', () => {
+    const r = extractTaskBindingOutputs(
+      {
+        city: {},
+        temp: { from: 'json.temperature' },
+      },
+      'log\n{"city":"Shanghai","temperature":23}\n',
+      '',
+      null,
+    );
+    expect(r.outputs).toEqual({ city: 'Shanghai', temp: 23 });
+    expect(r.diagnostic).toBeNull();
+  });
+
+  test('can publish whole stdout and normalizedOutput as named outputs', () => {
+    const r = extractTaskBindingOutputs(
+      {
+        raw: { from: 'stdout' },
+        normalized: { from: 'normalizedOutput' },
+      },
+      'raw text\n',
+      '',
+      'normalized text',
+    );
+    expect(r.outputs).toEqual({ raw: 'raw text\n', normalized: 'normalized text' });
+  });
+
+  test('uses defaults for missing loose outputs without failing extraction', () => {
+    const r = extractTaskBindingOutputs(
+      {
+        city: { default: 'Unknown' },
+      },
+      'not json\n',
+      '',
+      null,
+    );
+    expect(r.outputs).toEqual({ city: 'Unknown' });
+    expect(r.diagnostic).toBeNull();
+  });
+});
+
 // ─── inferPromptPorts ───────────────────────────────────────────────
 
 describe('inferPromptPorts', () => {

package/src/ports.ts

@@ -34,7 +34,13 @@
 // Everything here is pure / deterministic so it can be reused by the CLI,
 // the editor (for preview/simulation), and the engine without side effects.
 
-import type { PortDef, PortType, TaskConfig, TaskPorts } from './types';
+import type {
+  PortDef,
+  PortType,
+  TaskConfig,
+  TaskOutputBindings,
+  TaskPorts,
+} from './types';
 
 // ─── Template substitution ────────────────────────────────────────────
 
@@ -244,6 +250,157 @@ export function resolveTaskInputs(
   return { kind: 'ready', inputs, missingOptional };
 }
 
+// ─── Lightweight binding resolution ──────────────────────────────────
+
+export interface UpstreamBindingData {
+  readonly outputs?: Readonly<Record<string, unknown>> | null;
+  readonly stdout?: string;
+  readonly stderr?: string;
+  readonly normalizedOutput?: string | null;
+  readonly exitCode?: number | null;
+}
+
+export type BindingInputResolution =
+  | {
+      readonly kind: 'ready';
+      readonly inputs: Readonly<Record<string, unknown>>;
+      readonly missingOptional: readonly string[];
+    }
+  | {
+      readonly kind: 'blocked';
+      readonly missingRequired: readonly string[];
+      readonly ambiguous: readonly { input: string; producers: readonly string[] }[];
+      readonly reason: string;
+    };
+
+export function resolveTaskBindingInputs(
+  task: Pick<TaskConfig, 'inputs'>,
+  upstreamData: ReadonlyMap<string, UpstreamBindingData>,
+  dependsOn: readonly string[],
+): BindingInputResolution {
+  const bindings = task.inputs;
+  if (!bindings || Object.keys(bindings).length === 0) {
+    return { kind: 'ready', inputs: {}, missingOptional: [] };
+  }
+
+  const inputs: Record<string, unknown> = {};
+  const missingRequired: string[] = [];
+  const missingOptional: string[] = [];
+  const ambiguous: { input: string; producers: string[] }[] = [];
+
+  for (const [name, binding] of Object.entries(bindings)) {
+    let value: unknown;
+    let present = false;
+
+    if ('value' in binding) {
+      value = binding.value;
+      present = true;
+    } else if (binding.from) {
+      const found = resolveBindingSource(binding.from, upstreamData, dependsOn);
+      if (found.kind === 'ambiguous') {
+        ambiguous.push({ input: name, producers: found.producers });
+        continue;
+      }
+      if (found.kind === 'hit') {
+        value = found.value;
+        present = true;
+      }
+    }
+
+    if (!present && 'default' in binding) {
+      value = binding.default;
+      present = true;
+    }
+
+    if (!present || value === undefined || value === null) {
+      if (binding.required === true) {
+        missingRequired.push(name);
+      } else {
+        missingOptional.push(name);
+      }
+      continue;
+    }
+
+    inputs[name] = value;
+  }
+
+  if (missingRequired.length > 0 || ambiguous.length > 0) {
+    const lines: string[] = [];
+    if (missingRequired.length > 0) {
+      lines.push(`missing required binding input(s): ${missingRequired.join(', ')}`);
+    }
+    for (const amb of ambiguous) {
+      lines.push(
+        `binding input "${amb.input}" is produced by multiple upstreams ` +
+          `(${amb.producers.join(', ')}) — use "taskId.outputs.${amb.input}"`,
+      );
+    }
+    return { kind: 'blocked', missingRequired, ambiguous, reason: lines.join('\n') };
+  }
+
+  return { kind: 'ready', inputs, missingOptional };
+}
+
+type BindingLookup =
+  | { kind: 'hit'; producer: string; value: unknown }
+  | { kind: 'miss' }
+  | { kind: 'ambiguous'; producers: string[] };
+
+function resolveBindingSource(
+  source: string,
+  upstreamData: ReadonlyMap<string, UpstreamBindingData>,
+  dependsOn: readonly string[],
+): BindingLookup {
+  if (source.startsWith('outputs.')) {
+    return findOutputByName(source.slice('outputs.'.length), upstreamData, dependsOn);
+  }
+
+  const outputMarker = '.outputs.';
+  const outputIdx = source.lastIndexOf(outputMarker);
+  if (outputIdx > 0) {
+    const upstreamId = source.slice(0, outputIdx);
+    const outputName = source.slice(outputIdx + outputMarker.length);
+    if (!dependsOn.includes(upstreamId)) return { kind: 'miss' };
+    const upstream = upstreamData.get(upstreamId);
+    if (upstream?.outputs && outputName in upstream.outputs) {
+      return { kind: 'hit', producer: upstreamId, value: upstream.outputs[outputName] };
+    }
+    return { kind: 'miss' };
+  }
+
+  for (const field of ['stdout', 'stderr', 'normalizedOutput', 'exitCode'] as const) {
+    const suffix = `.${field}`;
+    if (!source.endsWith(suffix)) continue;
+    const upstreamId = source.slice(0, -suffix.length);
+    if (!dependsOn.includes(upstreamId)) return { kind: 'miss' };
+    const upstream = upstreamData.get(upstreamId);
+    if (!upstream) return { kind: 'miss' };
+    const value = upstream[field];
+    return value === undefined || value === null
+      ? { kind: 'miss' }
+      : { kind: 'hit', producer: upstreamId, value };
+  }
+
+  return { kind: 'miss' };
+}
+
+function findOutputByName(
+  name: string,
+  upstreamData: ReadonlyMap<string, UpstreamBindingData>,
+  dependsOn: readonly string[],
+): BindingLookup {
+  const hits: { producer: string; value: unknown }[] = [];
+  for (const upstreamId of dependsOn) {
+    const upstream = upstreamData.get(upstreamId);
+    if (upstream?.outputs && name in upstream.outputs) {
+      hits.push({ producer: upstreamId, value: upstream.outputs[name] });
+    }
+  }
+  if (hits.length === 0) return { kind: 'miss' };
+  if (hits.length === 1) return { kind: 'hit', producer: hits[0]!.producer, value: hits[0]!.value };
+  return { kind: 'ambiguous', producers: hits.map((h) => h.producer) };
+}
+
 type UpstreamLookup =
   | { kind: 'hit'; producer: string; value: unknown }
   | { kind: 'miss' }
@@ -416,6 +573,72 @@ export function extractTaskOutputs(
   return { outputs, diagnostic };
 }
 
+export function extractTaskBindingOutputs(
+  bindings: TaskOutputBindings | undefined,
+  stdout: string,
+  stderr: string,
+  normalizedOutput: string | null,
+): ExtractResult {
+  if (!bindings || Object.keys(bindings).length === 0) {
+    return { outputs: {}, diagnostic: null };
+  }
+
+  const outputs: Record<string, unknown> = {};
+  const missing: string[] = [];
+  let record: Record<string, unknown> | null | undefined;
+
+  for (const [name, binding] of Object.entries(bindings)) {
+    let value: unknown;
+    let present = false;
+
+    if ('value' in binding) {
+      value = binding.value;
+      present = true;
+    } else {
+      const source = binding.from ?? `json.${name}`;
+      if (source === 'stdout') {
+        value = stdout;
+        present = true;
+      } else if (source === 'stderr') {
+        value = stderr;
+        present = true;
+      } else if (source === 'normalizedOutput') {
+        if (normalizedOutput !== null) {
+          value = normalizedOutput;
+          present = true;
+        }
+      } else if (source.startsWith('json.')) {
+        if (record === undefined) {
+          const jsonSource = (normalizedOutput ?? '').length > 0 ? normalizedOutput! : stdout;
+          record = parseJsonTail(jsonSource);
+        }
+        const key = source.slice('json.'.length);
+        if (record && key in record) {
+          value = record[key];
+          present = true;
+        }
+      }
+    }
+
+    if (!present && 'default' in binding) {
+      value = binding.default;
+      present = true;
+    }
+
+    if (!present || value === undefined || value === null) {
+      missing.push(name);
+      continue;
+    }
+
+    outputs[name] = value;
+  }
+
+  return {
+    outputs,
+    diagnostic: missing.length > 0 ? `outputs: unresolved binding output(s): ${missing.join(', ')}` : null,
+  };
+}
+
 /**
  * Find the last non-empty line that parses as a JSON object. Returns
  * null when no such line exists. Also tries the whole source as a

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