@tagma/sdk 0.7.1 → 0.7.4

package/src/runtime.ts

@@ -0,0 +1,12 @@
+export * from '@tagma/runtime-bun';
+export type {
+  OpenRunLogOptions,
+  PruneLogOptions,
+  RunOptions,
+  RuntimeLogSink,
+  RuntimeLogStore,
+  RuntimeWatchEvent,
+  RuntimeWatchOptions,
+  TagmaRuntime,
+  TaskOutputPathOptions,
+} from '@tagma/core';

package/src/schema-ports.test.ts

@@ -83,6 +83,29 @@ describe('schema — unified bindings passthrough', () => {
     expect(back.tracks[0]!.tasks[0]!.outputs).toBeUndefined();
   });
 
+  test('legacy ports are not carried through resolve or deresolve', () => {
+    const raw: RawPipelineConfig = {
+      name: 'p',
+      tracks: [
+        {
+          id: 't',
+          name: 'T',
+          tasks: [
+            {
+              id: 'a',
+              command: 'echo ok',
+              ports: { outputs: [{ name: 'old', type: 'string' }] },
+            },
+          ],
+        },
+      ],
+    };
+    const resolved = resolveConfig(raw, WORK_DIR);
+    expect(resolved.tracks[0]!.tasks[0]!.ports).toBeUndefined();
+    const back = deresolvePipeline(resolved, WORK_DIR);
+    expect(back.tracks[0]!.tasks[0]!.ports).toBeUndefined();
+  });
+
   test('YAML round-trip preserves typed unified binding shape', () => {
     const raw: RawPipelineConfig = {
       name: 'p',

package/src/schema.ts

@@ -161,11 +161,10 @@ export function resolveConfig(raw: RawPipelineConfig, workDir: string): Pipeline
         completion: rawTask.completion,
         agent_profile: rawTask.agent_profile ?? rawTrack.agent_profile,
         cwd: rawTask.cwd ? validatePath(rawTask.cwd, workDir) : trackCwd,
-        // Lightweight bindings and ports: no inheritance — they describe
+        // Unified bindings have no inheritance; they describe
         // per-task data flow, not cross-task defaults.
         inputs: rawTask.inputs,
         outputs: rawTask.outputs,
-        ports: rawTask.ports,
       };
     });
 
@@ -313,11 +312,6 @@ export function deresolvePipeline(config: PipelineConfig, workDir: string): RawP
           : {}),
         ...(task.inputs && Object.keys(task.inputs).length > 0 ? { inputs: task.inputs } : {}),
         ...(task.outputs && Object.keys(task.outputs).length > 0 ? { outputs: task.outputs } : {}),
-        ...(task.ports &&
-        ((task.ports.inputs && task.ports.inputs.length > 0) ||
-          (task.ports.outputs && task.ports.outputs.length > 0))
-          ? { ports: task.ports }
-          : {}),
       };
     });
 

package/src/tagma.test.ts

@@ -3,7 +3,8 @@ import { mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { createTagma } from './tagma';
-import type { DriverPlugin, PipelineConfig } from './types';
+import type { DriverPlugin, TagmaPlugin, TaskResult } from './types';
+import type { TagmaRuntime } from './runtime';
 
 function makeDir(prefix: string): string {
   return mkdtempSync(join(tmpdir(), prefix));
@@ -20,7 +21,239 @@ function makeDriver(name: string, marker: string[]): DriverPlugin {
   };
 }
 
+function memoryLogStore() {
+  return {
+    openRunLog({ runId }: { runId: string }) {
+      return {
+        path: `mem://${runId}/pipeline.log`,
+        dir: `mem://${runId}`,
+        append() {
+          /* memory sink */
+        },
+        close() {
+          /* memory sink */
+        },
+      };
+    },
+    taskOutputPath({
+      runId,
+      taskId,
+      stream,
+    }: {
+      runId: string;
+      taskId: string;
+      stream: 'stdout' | 'stderr';
+    }) {
+      return `mem://${runId}/${taskId}.${stream}`;
+    },
+    logsDir(workDir: string) {
+      return `mem://${workDir}/logs`;
+    },
+    async prune() {
+      /* memory sink */
+    },
+  };
+}
+
 describe('createTagma', () => {
+  test('runs command tasks through the configured runtime', async () => {
+    const calls: string[] = [];
+    const taskResult: TaskResult = {
+      exitCode: 0,
+      stdout: 'runtime-ok',
+      stderr: '',
+      stdoutPath: null,
+      stderrPath: null,
+      stdoutBytes: 10,
+      stderrBytes: 0,
+      durationMs: 1,
+      sessionId: null,
+      normalizedOutput: null,
+      failureKind: null,
+    };
+    const runtime: TagmaRuntime = {
+      async runCommand(command, cwd) {
+        calls.push(`${cwd}:${command}`);
+        return taskResult;
+      },
+      async runSpawn() {
+        throw new Error('runSpawn should not be called for command tasks');
+      },
+      async ensureDir() {
+        /* no-op */
+      },
+      async fileExists() {
+        return false;
+      },
+      async *watch() {
+        /* no-op */
+      },
+      logStore: memoryLogStore(),
+      now() {
+        return new Date('2026-04-26T00:00:00.000Z');
+      },
+      sleep() {
+        return Promise.resolve();
+      },
+    };
+    const tagma = createTagma({ builtins: false, runtime });
+    const dir = makeDir('tagma-runtime-run-');
+    try {
+      const result = await tagma.run(
+        {
+          name: 'runtime-run',
+          tracks: [
+            {
+              id: 't',
+              name: 'T',
+              tasks: [{ id: 'cmd', name: 'cmd', command: 'fake-only-command' }],
+            },
+          ],
+        },
+        {
+          cwd: dir,
+          skipPluginLoading: true,
+        },
+      );
+
+      expect(result.success).toBe(true);
+      expect(calls).toEqual([`${dir}:fake-only-command`]);
+      expect(result.states.get('t.cmd')?.result?.stdout).toBe('runtime-ok');
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test('routes run logs and task output artifacts through the runtime log store', async () => {
+    const calls: string[] = [];
+    let stdoutPath: string | undefined;
+    let stderrPath: string | undefined;
+
+    const runtime = {
+      async runCommand(_command: string, _cwd: string, options?: { stdoutPath?: string; stderrPath?: string }) {
+        stdoutPath = options?.stdoutPath;
+        stderrPath = options?.stderrPath;
+        return {
+          exitCode: 0,
+          stdout: 'runtime-log-ok',
+          stderr: '',
+          stdoutPath: options?.stdoutPath ?? null,
+          stderrPath: options?.stderrPath ?? null,
+          stdoutBytes: 14,
+          stderrBytes: 0,
+          durationMs: 1,
+          sessionId: null,
+          normalizedOutput: null,
+          failureKind: null,
+        } satisfies TaskResult;
+      },
+      async runSpawn() {
+        throw new Error('runSpawn should not be called for command tasks');
+      },
+      async ensureDir(path: string) {
+        calls.push(`ensure:${path}`);
+      },
+      async fileExists(path: string) {
+        calls.push(`exists:${path}`);
+        return false;
+      },
+      async *watch(path: string) {
+        calls.push(`watch:${path}`);
+      },
+      now() {
+        return new Date('2026-04-26T00:00:00.000Z');
+      },
+      sleep(ms: number) {
+        calls.push(`sleep:${ms}`);
+        return Promise.resolve();
+      },
+      logStore: {
+        openRunLog({ runId, header }: { runId: string; header: string }) {
+          calls.push(`open:${runId}:${header.includes(runId)}`);
+          return {
+            path: `mem://${runId}/pipeline.log`,
+            dir: `mem://${runId}`,
+            append(line: string) {
+              calls.push(`append:${line.length > 0}`);
+            },
+            close() {
+              calls.push(`close:${runId}`);
+            },
+          };
+        },
+        taskOutputPath({
+          runId,
+          taskId,
+          stream,
+        }: {
+          runId: string;
+          taskId: string;
+          stream: 'stdout' | 'stderr';
+        }) {
+          calls.push(`task-output:${taskId}:${stream}`);
+          return `mem://${runId}/${taskId}.${stream}`;
+        },
+        logsDir(workDir: string) {
+          calls.push(`logs-dir:${workDir}`);
+          return `mem://${workDir}/logs`;
+        },
+        async prune({ keep, excludeRunId }: { keep: number; excludeRunId: string }) {
+          calls.push(`prune:${keep}:${excludeRunId}`);
+        },
+      },
+    } as unknown as TagmaRuntime;
+
+    const tagma = createTagma({ builtins: false, runtime });
+    const dir = makeDir('tagma-runtime-log-store-');
+    try {
+      const result = await tagma.run(
+        {
+          name: 'runtime-log-store',
+          tracks: [
+            {
+              id: 't',
+              name: 'T',
+              tasks: [{ id: 'cmd', name: 'cmd', command: 'fake-only-command' }],
+            },
+          ],
+        },
+        {
+          cwd: dir,
+          skipPluginLoading: true,
+        },
+      );
+
+      expect(result.success).toBe(true);
+      expect(result.logPath).toMatch(/^mem:\/\/run_.+\/pipeline\.log$/);
+      expect(stdoutPath).toMatch(/^mem:\/\/run_.+\/t\.cmd\.stdout$/);
+      expect(stderrPath).toMatch(/^mem:\/\/run_.+\/t\.cmd\.stderr$/);
+      expect(calls.some((call) => call.startsWith('open:run_'))).toBe(true);
+      expect(calls).toContain('task-output:t.cmd:stdout');
+      expect(calls).toContain('task-output:t.cmd:stderr');
+      expect(calls.some((call) => call.startsWith('prune:20:run_'))).toBe(true);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test('registers capability plugins passed to options', () => {
+    const seen: string[] = [];
+    const driver = makeDriver('driver-plugin', seen);
+    const plugin: TagmaPlugin = {
+      name: 'tagma-plugin-local',
+      capabilities: {
+        drivers: {
+          mock: driver,
+        },
+      },
+    };
+
+    const tagma = createTagma({ builtins: false, plugins: [plugin] });
+
+    expect(tagma.registry.getHandler<DriverPlugin>('drivers', 'mock')).toBe(driver);
+    expect(seen).toEqual([]);
+  });
+
   test('instances own isolated plugin registries', () => {
     const seenA: string[] = [];
     const seenB: string[] = [];

package/src/tagma.ts

@@ -1,8 +1,14 @@
-import { runPipeline, type EngineResult, type RunPipelineOptions } from './engine';
+import {
+  PluginRegistry,
+  runPipeline,
+  type EngineResult,
+  type RunPipelineOptions,
+} from '@tagma/core';
 import { bootstrapBuiltins } from './bootstrap';
-import { PluginRegistry } from './registry';
 import { validateConfig } from './schema';
-import type { PipelineConfig } from './types';
+import { bunRuntime } from '@tagma/runtime-bun';
+import type { TagmaRuntime } from '@tagma/core';
+import type { PipelineConfig, TagmaPlugin } from './types';
 
 export interface CreateTagmaOptions {
   /**
@@ -14,9 +20,18 @@ export interface CreateTagmaOptions {
    * instance registry. Defaults to true.
    */
   readonly builtins?: boolean;
+  /**
+   * Package-level capability plugins to register into this SDK instance.
+   */
+  readonly plugins?: readonly TagmaPlugin[];
+  /**
+   * Runtime implementation used for command and driver process execution.
+   * Defaults to the SDK's Bun runtime.
+   */
+  readonly runtime?: TagmaRuntime;
 }
 
-export interface TagmaRunOptions extends Omit<RunPipelineOptions, 'registry'> {
+export interface TagmaRunOptions extends Omit<RunPipelineOptions, 'registry' | 'runtime'> {
   readonly cwd: string;
 }
 
@@ -28,9 +43,13 @@ export interface Tagma {
 
 export function createTagma(options: CreateTagmaOptions = {}): Tagma {
   const registry = options.registry ?? new PluginRegistry();
+  const runtime = options.runtime ?? bunRuntime();
   if (options.builtins !== false) {
     bootstrapBuiltins(registry);
   }
+  for (const plugin of options.plugins ?? []) {
+    registry.registerTagmaPlugin(plugin);
+  }
 
   return {
     registry,
@@ -38,6 +57,7 @@ export function createTagma(options: CreateTagmaOptions = {}): Tagma {
       return runPipeline(config, cwd, {
         ...runOptions,
         registry,
+        runtime,
       });
     },
     validate(config) {

package/src/triggers/file.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, test } from 'bun:test';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { InMemoryApprovalGateway } from '../approval';
+import { FileTrigger } from './file';
+import type { TagmaRuntime } from '../runtime';
+
+function makeDir(prefix: string): string {
+  return mkdtempSync(join(tmpdir(), prefix));
+}
+
+describe('FileTrigger runtime boundary', () => {
+  test('uses ctx.runtime watch APIs instead of direct chokidar or Bun file APIs', async () => {
+    const dir = makeDir('tagma-file-trigger-runtime-');
+    const calls: string[] = [];
+    const runtime = {
+      async runCommand() {
+        throw new Error('runCommand should not be called by FileTrigger');
+      },
+      async runSpawn() {
+        throw new Error('runSpawn should not be called by FileTrigger');
+      },
+      async ensureDir(path: string) {
+        calls.push(`ensure:${path}`);
+      },
+      async fileExists(path: string) {
+        calls.push(`exists:${path}`);
+        return false;
+      },
+      async *watch(path: string, options?: { cwd?: string }) {
+        calls.push(`watch:${path}:${options?.cwd ?? ''}`);
+        yield { type: 'ready', path: '' };
+        yield { type: 'add', path: 'target.txt' };
+      },
+      now() {
+        return new Date('2026-04-26T00:00:00.000Z');
+      },
+      sleep() {
+        return Promise.resolve();
+      },
+      logStore: {
+        openRunLog() {
+          throw new Error('logStore should not be called by FileTrigger');
+        },
+        taskOutputPath() {
+          throw new Error('logStore should not be called by FileTrigger');
+        },
+        logsDir() {
+          throw new Error('logStore should not be called by FileTrigger');
+        },
+      },
+    } as unknown as TagmaRuntime;
+
+    try {
+      await expect(
+        FileTrigger.watch(
+          { type: 'file', path: 'target.txt', timeout: '0.05s' },
+          {
+            taskId: 't.wait',
+            trackId: 't',
+            workDir: dir,
+            signal: new AbortController().signal,
+            approvalGateway: new InMemoryApprovalGateway(),
+            runtime,
+          } as never,
+        ),
+      ).resolves.toEqual({ path: resolve(dir, 'target.txt') });
+
+      expect(calls).toEqual([
+        `ensure:${dir}`,
+        `watch:${dir}:${dir}`,
+        `exists:${resolve(dir, 'target.txt')}`,
+      ]);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});

package/src/triggers/file.ts

@@ -1,9 +1,7 @@
-import { watch } from 'chokidar';
 import { resolve, dirname } from 'path';
-import { mkdir } from 'fs/promises';
 import type { TriggerPlugin, TriggerContext } from '../types';
 import { parseDuration, validatePath } from '../utils';
-import { TriggerTimeoutError } from '../engine';
+import { TriggerTimeoutError } from '../core/trigger-errors';
 
 const IS_WINDOWS = process.platform === 'win32';
 
@@ -37,128 +35,97 @@ export const FileTrigger: TriggerPlugin = {
     const safePath = validatePath(filePath, ctx.workDir);
     const timeoutMs = config.timeout != null ? parseDuration(String(config.timeout)) : 0;
 
-    // Hoist the async work into a named async function so the Promise
-    // constructor itself is synchronous — avoids the no-async-promise-executor
-    // lint error and ensures exceptions are always propagated via reject().
-    async function start(
-      resolve_p: (value: unknown) => void,
-      reject: (reason?: unknown) => void,
-    ): Promise<void> {
-      if (ctx.signal.aborted) {
-        reject(new Error('Pipeline aborted'));
-        return;
-      }
-
-      let settled = false;
-      let timer: ReturnType<typeof setTimeout> | null = null;
-
-      // Ensure the parent directory exists so the watcher doesn't fail
-      // with ENOENT for nested paths like `build/output/result.json`.
-      const dir = dirname(safePath);
-      try {
-        await mkdir(dir, { recursive: true });
-      } catch {
-        /* best effort — dir may already exist */
-      }
-
-      // Pass `cwd: dir` so chokidar resolves paths relative to the watched
-      // directory. The 'add'/'change' events will then carry paths relative
-      // to `dir`, which we resolve with `resolve(dir, addedPath)` for an
-      // accurate absolute comparison — fixing the ambiguous process.cwd()
-      // resolution of the previous implementation.
-      const watcher = watch(dir, {
-        ignoreInitial: true,
-        depth: 0,
-        cwd: dir,
-        awaitWriteFinish: { stabilityThreshold: 100, pollInterval: 50 },
-      });
-
-      const cleanup = () => {
-        if (settled) return;
-        settled = true;
-        watcher.close().catch(() => {
-          /* ignore */
-        });
-        if (timer) clearTimeout(timer);
-        ctx.signal.removeEventListener('abort', onAbort);
-      };
-
-      const onAbort = () => {
-        cleanup();
-        reject(new Error('Pipeline aborted'));
-      };
-
-      watcher.on('add', (addedPath: string) => {
-        if (settled) return;
-        if (pathsEqual(resolve(dir, addedPath), safePath)) {
-          cleanup();
-          resolve_p({ path: safePath });
-        }
-      });
-
-      // Also fire on 'change' so that overwriting an existing file is detected.
-      // Without this, upstream tasks that truncate-and-rewrite a file emit only
-      // a 'change' event and the downstream trigger would never resolve.
-      watcher.on('change', (changedPath: string) => {
-        if (settled) return;
-        if (pathsEqual(resolve(dir, changedPath), safePath)) {
-          cleanup();
-          resolve_p({ path: safePath });
-        }
-      });
-
-      watcher.on('error', (err: unknown) => {
-        if (settled) return;
-        cleanup();
-        reject(
-          new Error(
-            `file trigger watch error: ${err instanceof Error ? err.message : String(err)}`,
-          ),
-        );
-      });
+    return waitForFile({ filePath, safePath, timeoutMs, timeoutLabel: config.timeout, ctx });
+  },
+};
 
-      // After the watcher finishes its initial scan, check if the file already exists.
-      // Doing this inside 'ready' eliminates the race window between existence check
-      // and watcher startup, so we neither miss events nor double-resolve.
-      watcher.on('ready', () => {
-        if (settled) return;
-        Bun.file(safePath)
-          .exists()
-          .then((exists) => {
-            if (settled) return;
-            if (exists) {
-              cleanup();
-              resolve_p({ path: safePath });
-            }
-          })
-          .catch((err: unknown) => {
-            if (settled) return;
-            cleanup();
+async function waitForFile(options: {
+  readonly filePath: string;
+  readonly safePath: string;
+  readonly timeoutMs: number;
+  readonly timeoutLabel: unknown;
+  readonly ctx: TriggerContext;
+}): Promise<unknown> {
+  const { filePath, safePath, timeoutMs, timeoutLabel, ctx } = options;
+  if (ctx.signal.aborted) throw new Error('Pipeline aborted');
+
+  const dir = dirname(safePath);
+  await ctx.runtime.ensureDir(dir).catch(() => {
+    /* best effort; runtime watch will surface real failures */
+  });
+
+  const watchController = new AbortController();
+  let removeAbortListener = () => {
+    /* no-op until the abort listener is installed */
+  };
+  const abortPromise = new Promise<never>((_, reject) => {
+    const onAbort = () => {
+      watchController.abort();
+      reject(new Error('Pipeline aborted'));
+    };
+    ctx.signal.addEventListener('abort', onAbort, { once: true });
+    removeAbortListener = () => ctx.signal.removeEventListener('abort', onAbort);
+  });
+
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  const timeoutPromise =
+    timeoutMs > 0
+      ? new Promise<never>((_, reject) => {
+          timer = setTimeout(() => {
+            watchController.abort();
             reject(
-              new Error(
-                `file trigger existence check failed: ${err instanceof Error ? err.message : String(err)}`,
+              new TriggerTimeoutError(
+                `file trigger timeout: ${filePath} did not appear within ${timeoutLabel}`,
               ),
             );
-          });
-      });
+          }, timeoutMs);
+        })
+      : new Promise<never>(() => {
+          /* no timeout */
+        });
 
-      if (timeoutMs > 0) {
-        timer = setTimeout(() => {
-          if (settled) return;
-          cleanup();
-          reject(
-            new TriggerTimeoutError(
-              `file trigger timeout: ${filePath} did not appear within ${config.timeout}`,
-            ),
+  async function watchLoop(): Promise<unknown> {
+    // Pass `cwd: dir` so runtimes can emit paths relative to the watched
+    // directory. The 'add'/'change' events are resolved against `dir` before
+    // comparison, preserving the old chokidar behavior without coupling this
+    // trigger to chokidar or Bun file APIs.
+    for await (const event of ctx.runtime.watch(dir, {
+      ignoreInitial: true,
+      depth: 0,
+      cwd: dir,
+      awaitWriteFinishMs: 100,
+      signal: watchController.signal,
+    })) {
+      if (event.type === 'ready') {
+        let exists = false;
+        try {
+          exists = await ctx.runtime.fileExists(safePath);
+        } catch (err) {
+          throw new Error(
+            `file trigger existence check failed: ${err instanceof Error ? err.message : String(err)}`,
           );
-        }, timeoutMs);
+        }
+        if (exists) return { path: safePath };
+        continue;
       }
 
-      ctx.signal.addEventListener('abort', onAbort);
+      if (
+        (event.type === 'add' || event.type === 'change') &&
+        pathsEqual(resolve(dir, event.path), safePath)
+      ) {
+        return { path: safePath };
+      }
     }
 
-    return new Promise((resolve_p, reject) => {
-      start(resolve_p, reject).catch(reject);
-    });
-  },
-};
+    if (ctx.signal.aborted) throw new Error('Pipeline aborted');
+    throw new Error(`file trigger watch ended before ${filePath} appeared`);
+  }
+
+  try {
+    return await Promise.race([watchLoop(), timeoutPromise, abortPromise]);
+  } finally {
+    if (timer !== null) clearTimeout(timer);
+    removeAbortListener();
+    watchController.abort();
+  }
+}