@tagma/sdk 0.6.1 → 0.6.3

package/src/engine.ts

@@ -20,7 +20,7 @@ import type {
   RunTaskState,
 } from './types';
 import { buildDag, type Dag } from './dag';
-import { getHandler, hasHandler, loadPlugins } from './registry';
+import { defaultRegistry, type PluginRegistry } from './registry';
 import { runSpawn, runCommand } from './runner';
 import { parseDuration, nowISO, generateRunId } from './utils';
 import { promptDocumentFromString, serializePromptDocument } from './prompt-doc';
@@ -59,7 +59,7 @@ export class TriggerTimeoutError extends Error {
 
 // ═══ Preflight Validation ═══
 
-function preflight(config: PipelineConfig, dag: Dag): void {
+function preflight(config: PipelineConfig, dag: Dag, registry: PluginRegistry): void {
   const errors: string[] = [];
 
   for (const [, node] of dag.nodes) {
@@ -70,15 +70,15 @@ function preflight(config: PipelineConfig, dag: Dag): void {
     // Pure command tasks don't use a driver — skip driver registration check.
     const isCommandOnly = task.command && !task.prompt;
 
-    if (!isCommandOnly && !hasHandler('drivers', driverName)) {
+    if (!isCommandOnly && !registry.hasHandler('drivers', driverName)) {
       errors.push(`Task "${node.taskId}": driver "${driverName}" not registered`);
     }
 
-    if (task.trigger && !hasHandler('triggers', task.trigger.type)) {
+    if (task.trigger && !registry.hasHandler('triggers', task.trigger.type)) {
       errors.push(`Task "${node.taskId}": trigger type "${task.trigger.type}" not registered`);
     }
 
-    if (task.completion && !hasHandler('completions', task.completion.type)) {
+    if (task.completion && !registry.hasHandler('completions', task.completion.type)) {
       errors.push(
         `Task "${node.taskId}": completion type "${task.completion.type}" not registered`,
       );
@@ -86,13 +86,13 @@ function preflight(config: PipelineConfig, dag: Dag): void {
 
     const mws = task.middlewares ?? track.middlewares ?? [];
     for (const mw of mws) {
-      if (!hasHandler('middlewares', mw.type)) {
+      if (!registry.hasHandler('middlewares', mw.type)) {
         errors.push(`Task "${node.taskId}": middleware type "${mw.type}" not registered`);
       }
     }
 
-    if (task.continue_from && hasHandler('drivers', driverName)) {
-      const driver = getHandler<DriverPlugin>('drivers', driverName);
+    if (task.continue_from && registry.hasHandler('drivers', driverName)) {
+      const driver = registry.getHandler<DriverPlugin>('drivers', driverName);
       if (!driver.capabilities.sessionResume) {
         // buildDag has already qualified `continue_from` and stored the result
         // on the node; preflight runs after buildDag, so the upstream id is
@@ -106,8 +106,8 @@ function preflight(config: PipelineConfig, dag: Dag): void {
             // (when the upstream driver implements parseResult and returns normalizedOutput).
             const upstreamDriverName =
               upstream.task.driver ?? upstream.track.driver ?? config.driver ?? 'opencode';
-            const upstreamDriver = hasHandler('drivers', upstreamDriverName)
-              ? getHandler<DriverPlugin>('drivers', upstreamDriverName)
+            const upstreamDriver = registry.hasHandler('drivers', upstreamDriverName)
+              ? registry.getHandler<DriverPlugin>('drivers', upstreamDriverName)
               : null;
             const canNormalize = typeof upstreamDriver?.parseResult === 'function';
 
@@ -225,6 +225,13 @@ export interface RunPipelineOptions {
    * doesn't re-resolve them via Node's default cwd-based import.
    */
   readonly skipPluginLoading?: boolean;
+  /**
+   * Plugin registry to resolve drivers/triggers/completions/middlewares from.
+   * Defaults to the process-wide `defaultRegistry`. Multi-tenant hosts pass a
+   * per-workspace registry so concurrent runs in different workspaces see
+   * isolated handler sets.
+   */
+  readonly registry?: PluginRegistry;
 }
 
 // Poll interval when no tasks are in-flight but non-terminal tasks remain
@@ -243,6 +250,7 @@ export async function runPipeline(
 ): Promise<EngineResult> {
   const approvalGateway = options.approvalGateway ?? new InMemoryApprovalGateway();
   const maxLogRuns = options.maxLogRuns ?? 20;
+  const registry = options.registry ?? defaultRegistry;
 
   // Load any plugins declared in the pipeline config before preflight so that
   // drivers, completions, and middlewares referenced in YAML are registered.
@@ -250,12 +258,12 @@ export async function runPipeline(
   // from the user's workspace node_modules) pass skipPluginLoading: true so
   // we don't re-resolve via Node's cwd-based default import.
   if (!options.skipPluginLoading && config.plugins?.length) {
-    await loadPlugins(config.plugins);
+    await registry.loadPlugins(config.plugins);
   }
 
   const dag = buildDag(config);
   const runId = options.runId ?? generateRunId();
-  preflight(config, dag);
+  preflight(config, dag, registry);
 
   const startedAt = nowISO();
   const pipelineInfo: PipelineInfo = { name: config.name, run_id: runId, started_at: startedAt };
@@ -579,7 +587,7 @@ export async function runPipeline(
           `trigger wait: type=${task.trigger.type} ${JSON.stringify(task.trigger)}`,
         );
         try {
-          const triggerPlugin = getHandler<TriggerPlugin>('triggers', task.trigger.type);
+          const triggerPlugin = registry.getHandler<TriggerPlugin>('triggers', task.trigger.type);
           // R6: race the plugin's watch() against the pipeline's abort signal.
           // Third-party triggers may forget to wire up ctx.signal — without
           // this race, an aborted pipeline would hang forever waiting for the
@@ -724,7 +732,7 @@ export async function runPipeline(
         } else {
           // AI task: apply middleware chain against a structured PromptDocument.
           const driverName = task.driver ?? track.driver ?? config.driver ?? 'opencode';
-          const driver = getHandler<DriverPlugin>('drivers', driverName);
+          const driver = registry.getHandler<DriverPlugin>('drivers', driverName);
 
           const originalLen = task.prompt!.length;
           let doc: PromptDocument = promptDocumentFromString(task.prompt!);
@@ -740,7 +748,7 @@ export async function runPipeline(
               workDir: task.cwd ?? workDir,
             };
             for (const mwConfig of mws) {
-              const mwPlugin = getHandler<MiddlewarePlugin>('middlewares', mwConfig.type);
+              const mwPlugin = registry.getHandler<MiddlewarePlugin>('middlewares', mwConfig.type);
               const beforeBlocks = doc.contexts.length;
               const beforeLen = serializePromptDocument(doc).length;
 
@@ -870,7 +878,7 @@ export async function runPipeline(
         } else if (result.exitCode !== 0) {
           terminalStatus = 'failed';
         } else if (task.completion) {
-          const plugin = getHandler<CompletionPlugin>('completions', task.completion.type);
+          const plugin = registry.getHandler<CompletionPlugin>('completions', task.completion.type);
           const completionCtx = { workDir: task.cwd ?? workDir, signal: abortController.signal };
           const passed = await plugin.check(
             task.completion as Record<string, unknown>,

package/src/plugin-registry.test.ts

@@ -0,0 +1,230 @@
+import { describe, expect, test } from 'bun:test';
+import { PluginRegistry, defaultRegistry } from './registry';
+import { bootstrapBuiltins } from './bootstrap';
+import { runPipeline } from './engine';
+import type { DriverPlugin, TriggerPlugin, PipelineConfig } from './types';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+function makeDriver(name: string, marker: string[]): DriverPlugin {
+  return {
+    name,
+    capabilities: { sessionResume: false, systemPrompt: false, outputFormat: false },
+    async buildCommand() {
+      marker.push(`buildCommand:${name}`);
+      return { args: ['echo', 'noop'] };
+    },
+  };
+}
+
+function makeTrigger(name: string, marker: string[]): TriggerPlugin {
+  return {
+    name,
+    async watch() {
+      marker.push(`watch:${name}`);
+    },
+  };
+}
+
+describe('PluginRegistry — instance isolation', () => {
+  test('two registries do not share drivers registered under the same type', () => {
+    const regA = new PluginRegistry();
+    const regB = new PluginRegistry();
+    const markerA: string[] = [];
+    const markerB: string[] = [];
+
+    regA.registerPlugin('drivers', 'mock', makeDriver('mockA', markerA));
+    regB.registerPlugin('drivers', 'mock', makeDriver('mockB', markerB));
+
+    expect(regA.getHandler<DriverPlugin>('drivers', 'mock').name).toBe('mockA');
+    expect(regB.getHandler<DriverPlugin>('drivers', 'mock').name).toBe('mockB');
+
+    expect(regA.hasHandler('drivers', 'mock')).toBe(true);
+    expect(regB.hasHandler('drivers', 'mock')).toBe(true);
+    expect(regA.hasHandler('triggers', 'mock')).toBe(false);
+  });
+
+  test('unregistering in one registry does not affect the other', () => {
+    const regA = new PluginRegistry();
+    const regB = new PluginRegistry();
+    regA.registerPlugin('drivers', 'mock', makeDriver('mockA', []));
+    regB.registerPlugin('drivers', 'mock', makeDriver('mockB', []));
+
+    expect(regA.unregisterPlugin('drivers', 'mock')).toBe(true);
+    expect(regA.hasHandler('drivers', 'mock')).toBe(false);
+    expect(regB.hasHandler('drivers', 'mock')).toBe(true);
+  });
+
+  test('listRegistered is scoped per instance', () => {
+    const regA = new PluginRegistry();
+    const regB = new PluginRegistry();
+    regA.registerPlugin('triggers', 'a-only', makeTrigger('a-only', []));
+    regB.registerPlugin('triggers', 'b-only', makeTrigger('b-only', []));
+
+    expect(regA.listRegistered('triggers')).toEqual(['a-only']);
+    expect(regB.listRegistered('triggers')).toEqual(['b-only']);
+  });
+
+  test('registering the same instance twice returns unchanged', () => {
+    const reg = new PluginRegistry();
+    const driver = makeDriver('same', []);
+    expect(reg.registerPlugin('drivers', 'mock', driver)).toBe('registered');
+    expect(reg.registerPlugin('drivers', 'mock', driver)).toBe('unchanged');
+  });
+
+  test('replacing with a different handler returns replaced', () => {
+    const reg = new PluginRegistry();
+    expect(reg.registerPlugin('drivers', 'mock', makeDriver('one', []))).toBe('registered');
+    expect(reg.registerPlugin('drivers', 'mock', makeDriver('two', []))).toBe('replaced');
+    expect(reg.getHandler<DriverPlugin>('drivers', 'mock').name).toBe('two');
+  });
+
+  test('bootstrapBuiltins(target) populates a specific instance without touching the default', () => {
+    const fresh = new PluginRegistry();
+    expect(fresh.hasHandler('drivers', 'opencode')).toBe(false);
+
+    bootstrapBuiltins(fresh);
+
+    expect(fresh.hasHandler('drivers', 'opencode')).toBe(true);
+    expect(fresh.hasHandler('triggers', 'file')).toBe(true);
+    expect(fresh.hasHandler('triggers', 'manual')).toBe(true);
+    expect(fresh.hasHandler('completions', 'exit_code')).toBe(true);
+    expect(fresh.hasHandler('middlewares', 'static_context')).toBe(true);
+
+    // Default registry's state is independent of `fresh` — if the default
+    // happens to have opencode (because another test bootstrapped it), that
+    // is fine; the guarantee is that `fresh.unregister` does not leak.
+    fresh.unregisterPlugin('drivers', 'opencode');
+    expect(fresh.hasHandler('drivers', 'opencode')).toBe(false);
+  });
+});
+
+describe('PluginRegistry — validation', () => {
+  test('rejects unknown category', () => {
+    const reg = new PluginRegistry();
+    expect(() =>
+      reg.registerPlugin(
+        'nope' as 'drivers',
+        'x',
+        makeDriver('x', []),
+      ),
+    ).toThrow(/Unknown plugin category/);
+  });
+
+  test('rejects driver missing buildCommand', () => {
+    const reg = new PluginRegistry();
+    expect(() =>
+      reg.registerPlugin(
+        'drivers',
+        'broken',
+        // deliberately bad: no buildCommand
+        { name: 'broken', capabilities: { sessionResume: false, systemPrompt: false, outputFormat: false } } as unknown as DriverPlugin,
+      ),
+    ).toThrow(/must export buildCommand/);
+  });
+
+  test('rejects handler with missing name', () => {
+    const reg = new PluginRegistry();
+    expect(() =>
+      reg.registerPlugin(
+        'drivers',
+        'x',
+        // deliberately bad: no name
+        { capabilities: { sessionResume: false, systemPrompt: false, outputFormat: false }, buildCommand: async () => ({ args: [] }) } as unknown as DriverPlugin,
+      ),
+    ).toThrow(/non-empty "name"/);
+  });
+});
+
+describe('runPipeline — options.registry isolation', () => {
+  test('concurrent runs with different registries see their own drivers', async () => {
+    const regA = new PluginRegistry();
+    const regB = new PluginRegistry();
+    const seenA: string[] = [];
+    const seenB: string[] = [];
+
+    bootstrapBuiltins(regA);
+    bootstrapBuiltins(regB);
+
+    regA.registerPlugin('drivers', 'mock', makeDriver('mockA', seenA));
+    regB.registerPlugin('drivers', 'mock', makeDriver('mockB', seenB));
+
+    // Command-only pipeline exercises the preflight path (which uses the
+    // registry) plus the run-loop path without requiring a real driver
+    // invocation. We verify isolation by asserting that preflight with a
+    // registry missing `mock` rejects, while the matching registry accepts.
+    const config: PipelineConfig = {
+      name: 'isolation-test',
+      tracks: [
+        {
+          id: 't',
+          name: 'T',
+          tasks: [{ id: 'only', name: 'only', command: 'echo hi' }],
+        },
+      ],
+    };
+
+    const tmpA = mkdtempSync(join(tmpdir(), 'tagma-regA-'));
+    const tmpB = mkdtempSync(join(tmpdir(), 'tagma-regB-'));
+    try {
+      const [resA, resB] = await Promise.all([
+        runPipeline(config, tmpA, { registry: regA, skipPluginLoading: true }),
+        runPipeline(config, tmpB, { registry: regB, skipPluginLoading: true }),
+      ]);
+      expect(resA.success).toBe(true);
+      expect(resB.success).toBe(true);
+      expect(resA.runId).not.toBe(resB.runId);
+    } finally {
+      rmSync(tmpA, { recursive: true, force: true });
+      rmSync(tmpB, { recursive: true, force: true });
+    }
+  });
+
+  test('preflight fails when referenced driver is missing from the passed registry', async () => {
+    const regNoOpencode = new PluginRegistry();
+    // Deliberately do NOT bootstrap builtins — opencode is not registered.
+    const config: PipelineConfig = {
+      name: 'preflight-miss',
+      tracks: [
+        {
+          id: 't',
+          name: 'T',
+          tasks: [{ id: 'x', name: 'x', prompt: 'hello' }],
+        },
+      ],
+    };
+    const tmp = mkdtempSync(join(tmpdir(), 'tagma-miss-'));
+    try {
+      await expect(
+        runPipeline(config, tmp, { registry: regNoOpencode, skipPluginLoading: true }),
+      ).rejects.toThrow(/driver "opencode" not registered/);
+    } finally {
+      rmSync(tmp, { recursive: true, force: true });
+    }
+  });
+
+  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);
+
+    const config: PipelineConfig = {
+      name: 'default-fallback',
+      tracks: [
+        {
+          id: 't',
+          name: 'T',
+          tasks: [{ id: 'only', name: 'only', command: 'echo hi' }],
+        },
+      ],
+    };
+    const tmp = mkdtempSync(join(tmpdir(), 'tagma-default-'));
+    try {
+      const res = await runPipeline(config, tmp, { skipPluginLoading: true });
+      expect(res.success).toBe(true);
+    } finally {
+      rmSync(tmp, { recursive: true, force: true });
+    }
+  });
+});

package/src/registry.ts

@@ -18,13 +18,6 @@ const VALID_CATEGORIES: ReadonlySet<PluginCategory> = new Set([
   'middlewares',
 ]);
 
-const registries = {
-  drivers: new Map<string, DriverPlugin>(),
-  triggers: new Map<string, TriggerPlugin>(),
-  completions: new Map<string, CompletionPlugin>(),
-  middlewares: new Map<string, MiddlewarePlugin>(),
-};
-
 /**
  * Minimal contract enforcement so a malformed plugin fails fast at
  * registration time rather than crashing the engine mid-run.
@@ -111,73 +104,6 @@ function validateContract(category: PluginCategory, handler: unknown): void {
 
 export type RegisterResult = 'registered' | 'replaced' | 'unchanged';
 
-/**
- * Register a plugin under (category, type). Returns:
- *   - 'registered' on first registration
- *   - 'replaced'   when an existing entry was overwritten with a different handler
- *   - 'unchanged'  when the same handler instance was already present
- *
- * Throws if `category` is unknown, `type` is empty, or `handler` violates the
- * minimum interface contract for the category.
- */
-export function registerPlugin<T extends PluginType>(
-  category: PluginCategory,
-  type: string,
-  handler: T,
-): RegisterResult {
-  if (!VALID_CATEGORIES.has(category)) {
-    throw new Error(`Unknown plugin category "${category}"`);
-  }
-  if (typeof type !== 'string' || type.length === 0) {
-    throw new Error(`Plugin type must be a non-empty string (category="${category}")`);
-  }
-  validateContract(category, handler);
-  const registry = registries[category] as Map<string, T>;
-  const existing = registry.get(type);
-  if (existing === handler) return 'unchanged';
-  const wasReplaced = existing !== undefined;
-  registry.set(type, handler);
-  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
-    // 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} — ` +
-        `check for duplicate plugin packages claiming the same type.`,
-    );
-  }
-  return wasReplaced ? 'replaced' : '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.
- */
-export function unregisterPlugin(category: PluginCategory, type: string): boolean {
-  if (!VALID_CATEGORIES.has(category)) return false;
-  return registries[category].delete(type);
-}
-
-export function getHandler<T extends PluginType>(category: PluginCategory, type: string): T {
-  const handler = registries[category].get(type);
-  if (!handler) {
-    throw new Error(
-      `${category} type "${type}" not registered.\n` +
-        `Install the plugin: bun add @tagma/${category.replace(/s$/, '')}-${type}`,
-    );
-  }
-  return handler as T;
-}
-
-export function hasHandler(category: PluginCategory, type: string): boolean {
-  return registries[category].has(type);
-}
-
 // Plugin name must be a scoped npm package or a tagma-prefixed package.
 // Reject absolute/relative paths and suspicious patterns to prevent
 // arbitrary code execution via crafted YAML configs.
@@ -223,45 +149,168 @@ export function readPluginManifest(pkgJson: unknown): PluginManifest | null {
 }
 
 /**
- * Load and register a list of plugin packages.
- *
- * @param pluginNames - Validated npm package names to load.
- * @param resolveFrom - Optional absolute path to resolve plugins from (e.g. the
- *   workspace's working directory). When omitted, the default ESM resolution
- *   uses the SDK's own `node_modules`, which will fail for plugins installed
- *   only in the user's workspace. CLI callers should pass `process.cwd()` or
- *   the workspace root so that workspace-local plugins resolve correctly.
+ * 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.
  */
-export async function loadPlugins(
-  pluginNames: readonly string[],
-  resolveFrom?: string,
-): Promise<void> {
-  for (const name of pluginNames) {
-    if (!isValidPluginName(name)) {
-      throw new Error(
-        `Plugin "${name}" rejected: plugin names must be scoped npm packages ` +
-          `(e.g. @tagma/trigger-xyz) or tagma-plugin-* packages. ` +
-          `Relative/absolute paths are not allowed.`,
+export class PluginRegistry {
+  private readonly registries = {
+    drivers: new Map<string, DriverPlugin>(),
+    triggers: new Map<string, TriggerPlugin>(),
+    completions: new Map<string, CompletionPlugin>(),
+    middlewares: new Map<string, MiddlewarePlugin>(),
+  };
+
+  /**
+   * Register a plugin under (category, type). Returns:
+   *   - 'registered' on first registration
+   *   - 'replaced'   when an existing entry was overwritten with a different handler
+   *   - 'unchanged'  when the same handler instance was already present
+   *
+   * Throws if `category` is unknown, `type` is empty, or `handler` violates
+   * the minimum interface contract for the category.
+   */
+  registerPlugin<T extends PluginType>(
+    category: PluginCategory,
+    type: string,
+    handler: T,
+  ): RegisterResult {
+    if (!VALID_CATEGORIES.has(category)) {
+      throw new Error(`Unknown plugin category "${category}"`);
+    }
+    if (typeof type !== 'string' || type.length === 0) {
+      throw new Error(`Plugin type must be a non-empty string (category="${category}")`);
+    }
+    validateContract(category, handler);
+    const registry = this.registries[category] as Map<string, T>;
+    const existing = registry.get(type);
+    if (existing === handler) return 'unchanged';
+    const wasReplaced = existing !== undefined;
+    registry.set(type, handler);
+    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
+      // 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} — ` +
+          `check for duplicate plugin packages claiming the same type.`,
       );
     }
-    let moduleUrl: string = name;
-    if (resolveFrom) {
-      // Resolve the package entry point relative to the caller's directory so
-      // plugins installed in the workspace's node_modules are found even when
-      // the SDK itself lives elsewhere (e.g. a global install or a monorepo
-      // sibling package).
-      const req = createRequire(resolveFrom.endsWith('/') ? resolveFrom : resolveFrom + '/');
-      const resolved = req.resolve(name);
-      moduleUrl = pathToFileURL(resolved).href;
+    return wasReplaced ? 'replaced' : '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.
+   */
+  unregisterPlugin(category: PluginCategory, type: string): boolean {
+    if (!VALID_CATEGORIES.has(category)) return false;
+    return this.registries[category].delete(type);
+  }
+
+  getHandler<T extends PluginType>(category: PluginCategory, type: string): T {
+    const handler = this.registries[category].get(type);
+    if (!handler) {
+      throw new Error(
+        `${category} type "${type}" not registered.\n` +
+          `Install the plugin: bun add @tagma/${category.replace(/s$/, '')}-${type}`,
+      );
     }
-    const mod = await import(moduleUrl);
-    if (!mod.pluginCategory || !mod.pluginType || !mod.default) {
-      throw new Error(`Plugin "${name}" must export pluginCategory, pluginType, and default`);
+    return handler as T;
+  }
+
+  hasHandler(category: PluginCategory, type: string): boolean {
+    return this.registries[category].has(type);
+  }
+
+  listRegistered(category: PluginCategory): string[] {
+    return [...this.registries[category].keys()];
+  }
+
+  /**
+   * Load and register a list of plugin packages into this registry.
+   *
+   * @param pluginNames - Validated npm package names to load.
+   * @param resolveFrom - Optional absolute path to resolve plugins from (e.g.
+   *   the workspace's working directory). When omitted, the default ESM
+   *   resolution uses the SDK's own `node_modules`, which will fail for
+   *   plugins installed only in the user's workspace. CLI callers should
+   *   pass `process.cwd()` or the workspace root so that workspace-local
+   *   plugins resolve correctly.
+   */
+  async loadPlugins(
+    pluginNames: readonly string[],
+    resolveFrom?: string,
+  ): Promise<void> {
+    for (const name of pluginNames) {
+      if (!isValidPluginName(name)) {
+        throw new Error(
+          `Plugin "${name}" rejected: plugin names must be scoped npm packages ` +
+            `(e.g. @tagma/trigger-xyz) or tagma-plugin-* packages. ` +
+            `Relative/absolute paths are not allowed.`,
+        );
+      }
+      let moduleUrl: string = name;
+      if (resolveFrom) {
+        // Resolve the package entry point relative to the caller's directory
+        // so plugins installed in the workspace's node_modules are found
+        // even when the SDK itself lives elsewhere (e.g. a global install
+        // or a monorepo sibling package).
+        const req = createRequire(resolveFrom.endsWith('/') ? resolveFrom : resolveFrom + '/');
+        const resolved = req.resolve(name);
+        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);
     }
-    registerPlugin(mod.pluginCategory, mod.pluginType, mod.default);
   }
 }
 
+/**
+ * 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 [...registries[category].keys()];
+  return defaultRegistry.listRegistered(category);
+}
+
+export function loadPlugins(
+  pluginNames: readonly string[],
+  resolveFrom?: string,
+): Promise<void> {
+  return defaultRegistry.loadPlugins(pluginNames, resolveFrom);
 }

package/src/sdk.ts

@@ -46,6 +46,8 @@ export type { DagNode, Dag, RawDagNode, RawDag } from './dag';
 // ── Plugin registry ──
 export { bootstrapBuiltins } from './bootstrap';
 export {
+  PluginRegistry,
+  defaultRegistry,
   loadPlugins,
   registerPlugin,
   unregisterPlugin,