@tagma/sdk 0.7.0 → 0.7.3

package/src/plugin-registry.test.ts

@@ -3,9 +3,10 @@ import { PluginRegistry } from './registry';
 import { bootstrapBuiltins } from './bootstrap';
 import { runPipeline } from './engine';
 import type { DriverPlugin, TriggerPlugin, PipelineConfig } from './types';
-import { mkdtempSync, rmSync } from 'node:fs';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
+import type { TagmaPlugin } from './types';
 
 function makeDriver(name: string, marker: string[]): DriverPlugin {
   return {
@@ -100,6 +101,130 @@ describe('PluginRegistry — instance isolation', () => {
   });
 });
 
+describe('PluginRegistry — capability plugins', () => {
+  test('registerTagmaPlugin registers multiple capabilities from one package', () => {
+    const reg = new PluginRegistry();
+    const driver = makeDriver('cap-driver', []);
+    const trigger = makeTrigger('cap-trigger', []);
+    const plugin: TagmaPlugin = {
+      name: 'tagma-plugin-multi',
+      capabilities: {
+        drivers: { cap_driver: driver },
+        triggers: { cap_trigger: trigger },
+      },
+    };
+
+    expect(reg.registerTagmaPlugin(plugin)).toEqual([
+      { category: 'drivers', type: 'cap_driver', result: 'registered' },
+      { category: 'triggers', type: 'cap_trigger', result: 'registered' },
+    ]);
+    expect(reg.getHandler<DriverPlugin>('drivers', 'cap_driver')).toBe(driver);
+    expect(reg.getHandler<TriggerPlugin>('triggers', 'cap_trigger')).toBe(trigger);
+  });
+
+  test('registerTagmaPlugin keeps replacement warnings from the registry path', () => {
+    const reg = new PluginRegistry();
+    const originalWarn = console.warn;
+    const warnings: string[] = [];
+    console.warn = (message?: unknown) => {
+      warnings.push(String(message));
+    };
+    try {
+      reg.registerPlugin('drivers', 'mock', makeDriver('first', []));
+      const result = reg.registerTagmaPlugin({
+        name: 'tagma-plugin-replacement',
+        capabilities: {
+          drivers: { mock: makeDriver('second', []) },
+        },
+      });
+
+      expect(result).toEqual([{ category: 'drivers', type: 'mock', result: 'replaced' }]);
+      expect(warnings).toContain(
+        '[tagma-sdk] registerPlugin: replaced existing drivers/mock - check for duplicate plugin packages claiming the same type.',
+      );
+    } finally {
+      console.warn = originalWarn;
+    }
+  });
+
+  test('loadPlugins accepts capability plugin default exports', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'tagma-capability-plugin-'));
+    const pluginDir = join(dir, 'node_modules', 'tagma-plugin-capability');
+    mkdirSync(pluginDir, { recursive: true });
+    writeFileSync(
+      join(pluginDir, 'package.json'),
+      JSON.stringify({ name: 'tagma-plugin-capability', version: '1.0.0', type: 'module', main: './index.js' }),
+      'utf-8',
+    );
+    writeFileSync(
+      join(pluginDir, 'index.js'),
+      [
+        'const driver = {',
+        "  name: 'cap-driver',",
+        '  capabilities: { sessionResume: false, systemPrompt: false, outputFormat: false },',
+        "  async buildCommand() { return { args: ['echo', 'cap'] }; },",
+        '};',
+        'const trigger = {',
+        "  name: 'cap-trigger',",
+        '  async watch() {}',
+        '};',
+        'export default {',
+        "  name: 'tagma-plugin-capability',",
+        '  capabilities: {',
+        '    drivers: { cap_driver: driver },',
+        '    triggers: { cap_trigger: trigger },',
+        '  },',
+        '};',
+        '',
+      ].join('\n'),
+      'utf-8',
+    );
+
+    try {
+      const reg = new PluginRegistry();
+      await reg.loadPlugins(['tagma-plugin-capability'], dir);
+      expect(reg.hasHandler('drivers', 'cap_driver')).toBe(true);
+      expect(reg.hasHandler('triggers', 'cap_trigger')).toBe(true);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test('loadPlugins rejects legacy plugin module exports', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'tagma-legacy-plugin-'));
+    const pluginDir = join(dir, 'node_modules', 'tagma-plugin-legacy');
+    mkdirSync(pluginDir, { recursive: true });
+    writeFileSync(
+      join(pluginDir, 'package.json'),
+      JSON.stringify({ name: 'tagma-plugin-legacy', version: '1.0.0', type: 'module', main: './index.js' }),
+      'utf-8',
+    );
+    writeFileSync(
+      join(pluginDir, 'index.js'),
+      [
+        "export const pluginCategory = 'drivers';",
+        "export const pluginType = 'legacy';",
+        'export default {',
+        "  name: 'legacy',",
+        '  capabilities: { sessionResume: false, systemPrompt: false, outputFormat: false },',
+        "  async buildCommand() { return { args: ['echo', 'legacy'] }; },",
+        '};',
+        '',
+      ].join('\n'),
+      'utf-8',
+    );
+
+    try {
+      const reg = new PluginRegistry();
+      await expect(reg.loadPlugins(['tagma-plugin-legacy'], dir)).rejects.toThrow(
+        /must default-export a TagmaPlugin/,
+      );
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});
+
 describe('PluginRegistry — validation', () => {
   test('rejects unknown category', () => {
     const reg = new PluginRegistry();
@@ -153,6 +278,18 @@ describe('PluginRegistry — validation', () => {
       /bun add @tagma\/middleware-audit/,
     );
   });
+
+  test('rejects middleware without enhanceDoc', () => {
+    const reg = new PluginRegistry();
+    expect(() =>
+      reg.registerPlugin('middlewares', 'old', {
+        name: 'old',
+        async enhance(prompt: string) {
+          return prompt;
+        },
+      } as never),
+    ).toThrow(/must export enhanceDoc/);
+  });
 });
 
 describe('runPipeline — options.registry isolation', () => {

package/src/plugins.ts

@@ -5,14 +5,17 @@ export {
   PLUGIN_NAME_RE,
   readPluginManifest,
 } from './registry';
-export type { RegisterResult } from './registry';
+export type { RegisteredCapability, RegisterResult } from './registry';
 export type {
+  CapabilityHandler,
   PluginCategory,
+  PluginCapabilities,
   PluginModule,
   PluginManifest,
+  PluginSetupContext,
+  TagmaPlugin,
   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

@@ -1,24 +1,34 @@
 import { createRequire } from 'node:module';
 import { pathToFileURL } from 'node:url';
 import type {
+  CapabilityHandler,
   PluginCategory,
   DriverPlugin,
   TriggerPlugin,
   CompletionPlugin,
   MiddlewarePlugin,
   PluginManifest,
+  TagmaPlugin,
 } from './types';
 
-type PluginType = DriverPlugin | TriggerPlugin | CompletionPlugin | MiddlewarePlugin;
+type PluginType = CapabilityHandler;
 
-const VALID_CATEGORIES: ReadonlySet<PluginCategory> = new Set([
+const CAPABILITY_CATEGORIES = [
   'drivers',
   'triggers',
   'completions',
   'middlewares',
-]);
+] as const satisfies readonly PluginCategory[];
+
+const VALID_CATEGORIES: ReadonlySet<PluginCategory> = new Set(CAPABILITY_CATEGORIES);
 const PLUGIN_TYPE_RE = /^[A-Za-z_][A-Za-z0-9_-]*$/;
 
+export interface RegisteredCapability {
+  readonly category: PluginCategory;
+  readonly type: string;
+  readonly result: RegisterResult;
+}
+
 function singularCategory(category: PluginCategory): string {
   switch (category) {
     case 'drivers':
@@ -37,7 +47,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 +65,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 {
@@ -96,22 +106,11 @@ function validateContract(category: PluginCategory, handler: unknown): void {
       }
       break;
     case 'middlewares':
-      // A middleware must provide at least one entry point. `enhanceDoc` is
-      // the structured PromptDocument API (preferred); `enhance` is the
-      // legacy string-in/string-out API the engine still supports for
-      // v0.x plugins. Requiring only `enhance` here rejects every built-in
-      // and every plugin written against the current types.
-      if (typeof h.enhanceDoc !== 'function' && typeof h.enhance !== 'function') {
+      if (typeof h.enhanceDoc !== 'function') {
         throw new Error(
-          `middlewares plugin "${h.name}" must export enhanceDoc() or enhance()`,
+          `middlewares plugin "${h.name}" must export enhanceDoc()`,
         );
       }
-      if (h.enhanceDoc !== undefined && typeof h.enhanceDoc !== 'function') {
-        throw new Error(`middlewares plugin "${h.name}".enhanceDoc must be a function or undefined`);
-      }
-      if (h.enhance !== undefined && typeof h.enhance !== 'function') {
-        throw new Error(`middlewares plugin "${h.name}".enhance must be a function or undefined`);
-      }
       break;
   }
 }
@@ -132,7 +131,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
@@ -167,6 +166,33 @@ export function readPluginManifest(pkgJson: unknown): PluginManifest | null {
   return { category: category as PluginCategory, type };
 }
 
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function isTagmaPlugin(value: unknown): value is TagmaPlugin {
+  if (!isRecord(value)) return false;
+  if (typeof value.name !== 'string' || value.name.length === 0) return false;
+  if (value.capabilities !== undefined && !isRecord(value.capabilities)) return false;
+  if (value.setup !== undefined && typeof value.setup !== 'function') return false;
+  return true;
+}
+
+function hasSupportedCapabilityMap(plugin: TagmaPlugin): boolean {
+  if (!plugin.capabilities) return false;
+  const capabilities = plugin.capabilities as Record<string, unknown>;
+  return CAPABILITY_CATEGORIES.some((category) => capabilities[category] !== undefined);
+}
+
+function moduleDefaultPlugin(name: string, mod: unknown): TagmaPlugin {
+  if (!isRecord(mod) || !isTagmaPlugin(mod.default) || !hasSupportedCapabilityMap(mod.default)) {
+    throw new Error(
+      `Plugin "${name}" must default-export a TagmaPlugin with capabilities maps`,
+    );
+  }
+  return mod.default;
+}
+
 /**
  * Instance-scoped plugin registry. Each workspace in a multi-tenant sidecar
  * owns its own PluginRegistry, so installing/uninstalling a driver in one
@@ -214,22 +240,54 @@ 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.`,
       );
     }
     return wasReplaced ? 'replaced' : 'registered';
   }
 
+  registerTagmaPlugin(plugin: TagmaPlugin): RegisteredCapability[] {
+    if (!isTagmaPlugin(plugin)) {
+      throw new Error('TagmaPlugin must be an object with a non-empty "name"');
+    }
+    if (!plugin.capabilities) {
+      throw new Error(`TagmaPlugin "${plugin.name}" must declare capabilities`);
+    }
+
+    const registered: RegisteredCapability[] = [];
+    const capabilities = plugin.capabilities as Record<string, unknown>;
+    for (const category of CAPABILITY_CATEGORIES) {
+      const handlers = capabilities[category];
+      if (handlers === undefined) continue;
+      if (!isRecord(handlers)) {
+        throw new Error(
+          `TagmaPlugin "${plugin.name}" capabilities.${category} must be an object map`,
+        );
+      }
+      for (const [type, handler] of Object.entries(handlers)) {
+        const result = this.registerPlugin(category, type, handler as PluginType);
+        registered.push({ category, type, result });
+      }
+    }
+
+    if (registered.length === 0) {
+      throw new Error(
+        `TagmaPlugin "${plugin.name}" must declare at least one supported capability`,
+      );
+    }
+    return registered;
+  }
+
   /**
    * 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;
@@ -289,10 +347,7 @@ export class PluginRegistry {
         moduleUrl = pathToFileURL(resolved).href;
       }
       const mod = await import(moduleUrl);
-      if (!mod.pluginCategory || !mod.pluginType || !mod.default) {
-        throw new Error(`Plugin "${name}" must export pluginCategory, pluginType, and default`);
-      }
-      this.registerPlugin(mod.pluginCategory, mod.pluginType, mod.default);
+      this.registerTagmaPlugin(moduleDefaultPlugin(name, mod));
     }
   }
 }

package/src/runtime.ts

@@ -0,0 +1,20 @@
+import type { DriverPlugin, SpawnSpec, TaskResult } from './types';
+import { runCommand, runSpawn, type RunOptions } from './runner';
+
+export type { RunOptions };
+
+export interface TagmaRuntime {
+  runSpawn(
+    spec: SpawnSpec,
+    driver: DriverPlugin | null,
+    options?: RunOptions,
+  ): Promise<TaskResult>;
+  runCommand(command: string, cwd: string, options?: RunOptions): Promise<TaskResult>;
+}
+
+export function bunRuntime(): TagmaRuntime {
+  return {
+    runSpawn,
+    runCommand,
+  };
+}