@tagma/sdk 0.4.11 → 0.4.13

package/src/pipeline-runner.ts

@@ -1,150 +1,156 @@
-// ═══ PipelineRunner ═══
-//
-// Wraps runPipeline in a lifecycle object suited for multi-pipeline management
-// in sidecar / Tauri IPC scenarios. Each instance controls one pipeline run.
-//
-// Typical sidecar usage:
-//
-//   const runners = new Map<string, PipelineRunner>();
-//
-//   const runner = new PipelineRunner(config, workDir);
-//   runner.subscribe(event => ipcEmit('pipeline_event', event));
-//   runner.start();
-//   runners.set(runner.instanceId, runner);
-//
-//   // Later, from IPC:
-//   runners.get(id)?.abort();
-
-import { runPipeline } from './engine';
-import type { EngineResult, PipelineEvent, RunPipelineOptions } from './engine';
-import type { PipelineConfig, TaskState } from './types';
-import { generateRunId } from './utils';
-
-export type { PipelineEvent, EngineResult };
-
-export type PipelineRunnerStatus = 'idle' | 'running' | 'done' | 'aborted';
-
-export class PipelineRunner {
-  /**
-   * Stable ID assigned before start() — safe to use as a Map key in the sidecar
-   * before the engine-assigned runId becomes available.
-   */
-  readonly instanceId: string;
-
-  /**
-   * The runId generated by the engine. Available after the first 'pipeline_start'
-   * event fires (i.e. effectively immediately after start() is called).
-   * null until then.
-   */
-  private _runId: string | null = null;
-  private _status: PipelineRunnerStatus = 'idle';
-  private _result: Promise<EngineResult> | null = null;
-  private _abortController = new AbortController();
-  private _handlers = new Set<(event: PipelineEvent) => void>();
-  private _states: ReadonlyMap<string, TaskState> | null = null;
-  private _statesMirror = new Map<string, TaskState>();
-
-  constructor(
-    private readonly config: PipelineConfig,
-    private readonly workDir: string,
-    private readonly opts: Omit<RunPipelineOptions, 'signal' | 'onEvent'> = {},
-  ) {
-    this.instanceId = generateRunId();
-  }
-
-  get runId(): string | null { return this._runId; }
-  get status(): PipelineRunnerStatus { return this._status; }
-
-  /**
-   * Start the pipeline. Calling start() more than once returns the same Promise.
-   */
-  start(): Promise<EngineResult> {
-    if (this._result) return this._result;
-
-    // Guard: if abort() was called before start(), the signal is already
-    // aborted. Create a fresh controller so the pipeline doesn't terminate
-    // immediately. If users truly want pre-abort semantics, they call
-    // abort() after start().
-    if (this._abortController.signal.aborted) {
-      this._abortController = new AbortController();
-      this._status = 'idle';
-    }
-
-    this._status = 'running';
-    this._result = runPipeline(this.config, this.workDir, {
-      ...this.opts,
-      signal: this._abortController.signal,
-      onEvent: (event) => {
-        if (event.type === 'pipeline_start') {
-          this._runId = event.runId;
-          // Initialize the live mirror with the full initial state snapshot
-          for (const [id, state] of event.states) {
-            this._statesMirror.set(id, { ...state });
-          }
-        }
-        if (event.type === 'task_status_change') {
-          // Keep the mirror up to date so getStates() works during the run
-          this._statesMirror.set(event.taskId, event.state);
-        }
-        if (event.type === 'pipeline_end') {
-          this._status = this._abortController.signal.aborted ? 'aborted' : 'done';
-        }
-        for (const h of this._handlers) h(event);
-      },
-    }).then(result => {
-      this._states = result.states;
-      if (this._status === 'running') this._status = 'done';
-      return result;
-    }).catch(err => {
-      this._status = 'aborted';
-      throw err;
-    });
-
-    return this._result;
-  }
-
-  /**
-   * Cancel the running pipeline. Safe to call multiple times or before start().
-   */
-  abort(reason?: string): void {
-    this._status = 'aborted';
-    this._abortController.abort(reason);
-  }
-
-  /**
-   * Live snapshot of task states. Available from the first pipeline_start event onward
-   * (i.e. as soon as start() is called) and remains accessible after the run completes.
-   * Returns null only if the pipeline has never started.
-   */
-  getStates(): ReadonlyMap<string, TaskState> | null {
-    if (this._states) return snapshotStates(this._states);
-    if (this._statesMirror.size > 0) return snapshotStates(this._statesMirror);
-    return null;
-  }
-
-  /**
-   * Subscribe to pipeline/task events. Returns an unsubscribe function.
-   * Events are emitted synchronously in the engine's event loop, so keep
-   * handlers non-blocking (e.g. queue to IPC, do not await inside).
-   */
-  subscribe(handler: (event: PipelineEvent) => void): () => void {
-    this._handlers.add(handler);
-    return () => this._handlers.delete(handler);
-  }
-}
-
-/** Deep-copy a states map so callers cannot mutate SDK internals. */
-function snapshotStates(src: ReadonlyMap<string, TaskState>): ReadonlyMap<string, TaskState> {
-  const copy = new Map<string, TaskState>();
-  for (const [id, s] of src) {
-    copy.set(id, {
-      config: { ...s.config },
-      trackConfig: { ...s.trackConfig },
-      status: s.status,
-      result: s.result ? { ...s.result } : null,
-      startedAt: s.startedAt,
-      finishedAt: s.finishedAt,
-    });
-  }
-  return copy;
-}
+// ═══ PipelineRunner ═══
+//
+// Wraps runPipeline in a lifecycle object suited for multi-pipeline management
+// in sidecar / Tauri IPC scenarios. Each instance controls one pipeline run.
+//
+// Typical sidecar usage:
+//
+//   const runners = new Map<string, PipelineRunner>();
+//
+//   const runner = new PipelineRunner(config, workDir);
+//   runner.subscribe(event => ipcEmit('pipeline_event', event));
+//   runner.start();
+//   runners.set(runner.instanceId, runner);
+//
+//   // Later, from IPC:
+//   runners.get(id)?.abort();
+
+import { runPipeline } from './engine';
+import type { EngineResult, PipelineEvent, RunPipelineOptions } from './engine';
+import type { PipelineConfig, TaskState } from './types';
+import { generateRunId } from './utils';
+
+export type { PipelineEvent, EngineResult };
+
+export type PipelineRunnerStatus = 'idle' | 'running' | 'done' | 'aborted';
+
+export class PipelineRunner {
+  /**
+   * Stable ID assigned before start() — safe to use as a Map key in the sidecar
+   * before the engine-assigned runId becomes available.
+   */
+  readonly instanceId: string;
+
+  /**
+   * The runId generated by the engine. Available after the first 'pipeline_start'
+   * event fires (i.e. effectively immediately after start() is called).
+   * null until then.
+   */
+  private _runId: string | null = null;
+  private _status: PipelineRunnerStatus = 'idle';
+  private _result: Promise<EngineResult> | null = null;
+  private _abortController = new AbortController();
+  private _handlers = new Set<(event: PipelineEvent) => void>();
+  private _states: ReadonlyMap<string, TaskState> | null = null;
+  private _statesMirror = new Map<string, TaskState>();
+
+  constructor(
+    private readonly config: PipelineConfig,
+    private readonly workDir: string,
+    private readonly opts: Omit<RunPipelineOptions, 'signal' | 'onEvent'> = {},
+  ) {
+    this.instanceId = generateRunId();
+  }
+
+  get runId(): string | null {
+    return this._runId;
+  }
+  get status(): PipelineRunnerStatus {
+    return this._status;
+  }
+
+  /**
+   * Start the pipeline. Calling start() more than once returns the same Promise.
+   */
+  start(): Promise<EngineResult> {
+    if (this._result) return this._result;
+
+    // Guard: if abort() was called before start(), the signal is already
+    // aborted. Create a fresh controller so the pipeline doesn't terminate
+    // immediately. If users truly want pre-abort semantics, they call
+    // abort() after start().
+    if (this._abortController.signal.aborted) {
+      this._abortController = new AbortController();
+      this._status = 'idle';
+    }
+
+    this._status = 'running';
+    this._result = runPipeline(this.config, this.workDir, {
+      ...this.opts,
+      signal: this._abortController.signal,
+      onEvent: (event) => {
+        if (event.type === 'pipeline_start') {
+          this._runId = event.runId;
+          // Initialize the live mirror with the full initial state snapshot
+          for (const [id, state] of event.states) {
+            this._statesMirror.set(id, { ...state });
+          }
+        }
+        if (event.type === 'task_status_change') {
+          // Keep the mirror up to date so getStates() works during the run
+          this._statesMirror.set(event.taskId, event.state);
+        }
+        if (event.type === 'pipeline_end') {
+          this._status = this._abortController.signal.aborted ? 'aborted' : 'done';
+        }
+        for (const h of this._handlers) h(event);
+      },
+    })
+      .then((result) => {
+        this._states = result.states;
+        if (this._status === 'running') this._status = 'done';
+        return result;
+      })
+      .catch((err) => {
+        this._status = 'aborted';
+        throw err;
+      });
+
+    return this._result;
+  }
+
+  /**
+   * Cancel the running pipeline. Safe to call multiple times or before start().
+   */
+  abort(reason?: string): void {
+    this._status = 'aborted';
+    this._abortController.abort(reason);
+  }
+
+  /**
+   * Live snapshot of task states. Available from the first pipeline_start event onward
+   * (i.e. as soon as start() is called) and remains accessible after the run completes.
+   * Returns null only if the pipeline has never started.
+   */
+  getStates(): ReadonlyMap<string, TaskState> | null {
+    if (this._states) return snapshotStates(this._states);
+    if (this._statesMirror.size > 0) return snapshotStates(this._statesMirror);
+    return null;
+  }
+
+  /**
+   * Subscribe to pipeline/task events. Returns an unsubscribe function.
+   * Events are emitted synchronously in the engine's event loop, so keep
+   * handlers non-blocking (e.g. queue to IPC, do not await inside).
+   */
+  subscribe(handler: (event: PipelineEvent) => void): () => void {
+    this._handlers.add(handler);
+    return () => this._handlers.delete(handler);
+  }
+}
+
+/** Deep-copy a states map so callers cannot mutate SDK internals. */
+function snapshotStates(src: ReadonlyMap<string, TaskState>): ReadonlyMap<string, TaskState> {
+  const copy = new Map<string, TaskState>();
+  for (const [id, s] of src) {
+    copy.set(id, {
+      config: { ...s.config },
+      trackConfig: { ...s.trackConfig },
+      status: s.status,
+      result: s.result ? { ...s.result } : null,
+      startedAt: s.startedAt,
+      finishedAt: s.finishedAt,
+    });
+  }
+  return copy;
+}

package/src/registry.ts

@@ -1,17 +1,26 @@
+import { createRequire } from 'node:module';
+import { pathToFileURL } from 'node:url';
 import type {
-  PluginCategory, DriverPlugin, TriggerPlugin,
-  CompletionPlugin, MiddlewarePlugin, PluginManifest,
+  PluginCategory,
+  DriverPlugin,
+  TriggerPlugin,
+  CompletionPlugin,
+  MiddlewarePlugin,
+  PluginManifest,
 } from './types';
 
 type PluginType = DriverPlugin | TriggerPlugin | CompletionPlugin | MiddlewarePlugin;
 
 const VALID_CATEGORIES: ReadonlySet<PluginCategory> = new Set([
-  'drivers', 'triggers', 'completions', 'middlewares',
+  'drivers',
+  'triggers',
+  'completions',
+  'middlewares',
 ]);
 
 const registries = {
-  drivers:     new Map<string, DriverPlugin>(),
-  triggers:    new Map<string, TriggerPlugin>(),
+  drivers: new Map<string, DriverPlugin>(),
+  triggers: new Map<string, TriggerPlugin>(),
   completions: new Map<string, CompletionPlugin>(),
   middlewares: new Map<string, MiddlewarePlugin>(),
 };
@@ -47,7 +56,7 @@ function validateContract(category: PluginCategory, handler: unknown): void {
       } catch (err) {
         throw new Error(
           `drivers plugin "${h.name}" capabilities accessor threw: ` +
-          (err instanceof Error ? err.message : String(err))
+            (err instanceof Error ? err.message : String(err)),
         );
       }
       if (!caps || typeof caps !== 'object') {
@@ -57,16 +66,14 @@ function validateContract(category: PluginCategory, handler: unknown): void {
       for (const field of ['sessionResume', 'systemPrompt', 'outputFormat'] as const) {
         if (typeof c[field] !== 'boolean') {
           throw new Error(
-            `drivers plugin "${h.name}".capabilities.${field} must be a boolean (got ${typeof c[field]})`
+            `drivers plugin "${h.name}".capabilities.${field} must be a boolean (got ${typeof c[field]})`,
           );
         }
       }
       // Optional methods, but if present must be functions.
       for (const opt of ['parseResult', 'resolveModel', 'resolveTools'] as const) {
         if (h[opt] !== undefined && typeof h[opt] !== 'function') {
-          throw new Error(
-            `drivers plugin "${h.name}".${opt} must be a function or undefined`
-          );
+          throw new Error(`drivers plugin "${h.name}".${opt} must be a function or undefined`);
         }
       }
       break;
@@ -101,7 +108,9 @@ export type RegisterResult = 'registered' | 'replaced' | 'unchanged';
  * minimum interface contract for the category.
  */
 export function registerPlugin<T extends PluginType>(
-  category: PluginCategory, type: string, handler: T,
+  category: PluginCategory,
+  type: string,
+  handler: T,
 ): RegisterResult {
   if (!VALID_CATEGORIES.has(category)) {
     throw new Error(`Unknown plugin category "${category}"`);
@@ -129,14 +138,12 @@ export function unregisterPlugin(category: PluginCategory, type: string): boolea
   return registries[category].delete(type);
 }
 
-export function getHandler<T extends PluginType>(
-  category: PluginCategory, type: string,
-): T {
+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}`
+        `Install the plugin: bun add @tagma/${category.replace(/s$/, '')}-${type}`,
     );
   }
   return handler as T;
@@ -181,7 +188,7 @@ export function readPluginManifest(pkgJson: unknown): PluginManifest | null {
   const type = m.type;
   if (typeof category !== 'string' || !VALID_CATEGORIES.has(category as PluginCategory)) {
     throw new Error(
-      `tagmaPlugin.category must be one of ${[...VALID_CATEGORIES].join(', ')}, got ${JSON.stringify(category)}`
+      `tagmaPlugin.category must be one of ${[...VALID_CATEGORIES].join(', ')}, got ${JSON.stringify(category)}`,
     );
   }
   if (typeof type !== 'string' || type.length === 0) {
@@ -190,20 +197,41 @@ export function readPluginManifest(pkgJson: unknown): PluginManifest | null {
   return { category: category as PluginCategory, type };
 }
 
-export async function loadPlugins(pluginNames: readonly string[]): Promise<void> {
+/**
+ * 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.
+ */
+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.`
+          `(e.g. @tagma/trigger-xyz) or tagma-plugin-* packages. ` +
+          `Relative/absolute paths are not allowed.`,
       );
     }
-    const mod = await import(name);
+    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`
-      );
+      throw new Error(`Plugin "${name}" must export pluginCategory, pluginType, and default`);
     }
     registerPlugin(mod.pluginCategory, mod.pluginType, mod.default);
   }