@tagma/sdk 0.6.9 → 0.6.11

package/src/pipeline-runner.test.ts

@@ -0,0 +1,95 @@
+import { describe, expect, test } from 'bun:test';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { bootstrapBuiltins } from './bootstrap';
+import { PipelineRunner } from './pipeline-runner';
+import { PluginRegistry } from './registry';
+import type { PipelineConfig } from './types';
+
+function makeDir(): string {
+  return mkdtempSync(join(tmpdir(), 'tagma-pipeline-runner-'));
+}
+
+function portsPipeline(dir: string): PipelineConfig {
+  const emit = join(dir, 'emit.js');
+  writeFileSync(
+    emit,
+    'process.stdout.write(JSON.stringify({ city: "Shanghai" }) + "\\n");\n',
+  );
+  const echo = join(dir, 'echo.js');
+  writeFileSync(echo, 'process.stdout.write(process.argv[2] + "\\n");\n');
+
+  return {
+    name: 'runner-snapshot',
+    tracks: [
+      {
+        id: 't',
+        name: 'T',
+        tasks: [
+          {
+            id: 'up',
+            name: 'up',
+            command: `node "${emit}"`,
+            ports: {
+              outputs: [{ name: 'city', type: 'string' }],
+            },
+          },
+          {
+            id: 'down',
+            name: 'down',
+            depends_on: ['up'],
+            command: `node "${echo}" "{{inputs.city}}"`,
+            ports: {
+              inputs: [{ name: 'city', type: 'string', required: true }],
+            },
+          },
+        ],
+      },
+    ],
+  };
+}
+
+async function run(config: PipelineConfig, dir: string): Promise<PipelineRunner> {
+  const registry = new PluginRegistry();
+  bootstrapBuiltins(registry);
+  const runner = new PipelineRunner(config, dir, {
+    registry,
+    skipPluginLoading: true,
+  });
+
+  const result = await runner.start();
+  expect(result.success).toBe(true);
+  return runner;
+}
+
+describe('PipelineRunner task snapshot', () => {
+  test('getTasks reflects task_update inputs and outputs', async () => {
+    const dir = makeDir();
+    try {
+      const runner = await run(portsPipeline(dir), dir);
+
+      const tasks = runner.getTasks();
+      const up = tasks.get('t.up');
+      const down = tasks.get('t.down');
+      expect(up?.outputs).toEqual({ city: 'Shanghai' });
+      expect(down?.inputs).toEqual({ city: 'Shanghai' });
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test('getTasks folds streamed task logs into the task snapshot', async () => {
+    const dir = makeDir();
+    try {
+      const runner = await run(portsPipeline(dir), dir);
+
+      const tasks = runner.getTasks();
+      const up = tasks.get('t.up');
+      expect(up?.logs.length).toBeGreaterThan(0);
+      expect(up?.totalLogCount).toBeGreaterThan(0);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});

package/src/pipeline-runner.ts

@@ -23,7 +23,7 @@
 
 import { runPipeline } from './engine';
 import type { EngineResult, RunPipelineOptions } from './engine';
-import type { PipelineConfig, RunEventPayload, RunTaskState } from './types';
+import { TASK_LOG_CAP, type PipelineConfig, type RunEventPayload, type RunTaskState } from './types';
 import { generateRunId } from './utils';
 
 export type { EngineResult };
@@ -132,12 +132,29 @@ export class PipelineRunner {
           stderrBytes: pick(event.stderrBytes, prev.stderrBytes),
           sessionId: pick(event.sessionId, prev.sessionId),
           normalizedOutput: pick(event.normalizedOutput, prev.normalizedOutput),
+          outputs: pick(event.outputs, prev.outputs),
+          inputs: pick(event.inputs, prev.inputs),
           resolvedDriver: pick(event.resolvedDriver, prev.resolvedDriver),
           resolvedModel: pick(event.resolvedModel, prev.resolvedModel),
           resolvedPermissions: pick(event.resolvedPermissions, prev.resolvedPermissions),
         });
         return;
       }
+      case 'task_log': {
+        if (event.taskId === null) return;
+        const prev = this._tasks.get(event.taskId);
+        if (!prev) return;
+        const logs = [
+          ...prev.logs,
+          { level: event.level, timestamp: event.timestamp, text: event.text },
+        ];
+        this._tasks.set(event.taskId, {
+          ...prev,
+          logs: logs.slice(-TASK_LOG_CAP),
+          totalLogCount: prev.totalLogCount + 1,
+        });
+        return;
+      }
       case 'run_end':
         this._status = this._abortController.signal.aborted ? 'aborted' : 'done';
         return;

package/src/plugin-registry.test.ts

@@ -135,6 +135,24 @@ describe('PluginRegistry — validation', () => {
       ),
     ).toThrow(/non-empty "name"/);
   });
+
+  test('rejects plugin type identifiers that are not YAML-safe ids', () => {
+    const reg = new PluginRegistry();
+    expect(() =>
+      reg.registerPlugin(
+        'drivers',
+        '../evil',
+        makeDriver('evil', []),
+      ),
+    ).toThrow(/Plugin type .* must match/);
+  });
+
+  test('middleware install hint uses singular middleware package name', () => {
+    const reg = new PluginRegistry();
+    expect(() => reg.getHandler('middlewares', 'audit')).toThrow(
+      /bun add @tagma\/middleware-audit/,
+    );
+  });
 });
 
 describe('runPipeline — options.registry isolation', () => {

package/src/registry.ts

@@ -17,6 +17,20 @@ const VALID_CATEGORIES: ReadonlySet<PluginCategory> = new Set([
   'completions',
   'middlewares',
 ]);
+const PLUGIN_TYPE_RE = /^[A-Za-z_][A-Za-z0-9_-]*$/;
+
+function singularCategory(category: PluginCategory): string {
+  switch (category) {
+    case 'drivers':
+      return 'driver';
+    case 'triggers':
+      return 'trigger';
+    case 'completions':
+      return 'completion';
+    case 'middlewares':
+      return 'middleware';
+  }
+}
 
 /**
  * Minimal contract enforcement so a malformed plugin fails fast at
@@ -145,6 +159,11 @@ export function readPluginManifest(pkgJson: unknown): PluginManifest | null {
   if (typeof type !== 'string' || type.length === 0) {
     throw new Error(`tagmaPlugin.type must be a non-empty string, got ${JSON.stringify(type)}`);
   }
+  if (!PLUGIN_TYPE_RE.test(type)) {
+    throw new Error(
+      `tagmaPlugin.type must match ${PLUGIN_TYPE_RE} (letters, digits, underscores, hyphens; no paths or dots), got ${JSON.stringify(type)}`,
+    );
+  }
   return { category: category as PluginCategory, type };
 }
 
@@ -183,6 +202,11 @@ export class PluginRegistry {
     if (typeof type !== 'string' || type.length === 0) {
       throw new Error(`Plugin type must be a non-empty string (category="${category}")`);
     }
+    if (!PLUGIN_TYPE_RE.test(type)) {
+      throw new Error(
+        `Plugin type "${type}" must match ${PLUGIN_TYPE_RE} (letters, digits, underscores, hyphens; no paths or dots)`,
+      );
+    }
     validateContract(category, handler);
     const registry = this.registries[category] as Map<string, T>;
     const existing = registry.get(type);
@@ -220,7 +244,7 @@ export class PluginRegistry {
     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/${singularCategory(category)}-${type}`,
       );
     }
     return handler as T;

package/src/schema.test.ts

@@ -1,7 +1,7 @@
 import { describe, expect, test } from 'bun:test';
 import yaml from 'js-yaml';
 import type { PipelineConfig, RawPipelineConfig } from './types';
-import { deresolvePipeline, serializePipeline } from './schema';
+import { deresolvePipeline, parseYaml, resolveConfig, serializePipeline } from './schema';
 
 function parsePipelineYaml(content: string): RawPipelineConfig {
   const doc = yaml.load(content) as { pipeline: RawPipelineConfig };
@@ -56,6 +56,37 @@ describe('completion default serialization', () => {
     });
   });
 
+  test('serializePipeline drops continue_from from command tasks (prompt-only field)', () => {
+    const raw: RawPipelineConfig = {
+      name: 'Strip Continue From',
+      tracks: [
+        {
+          id: 'track_a',
+          name: 'Track A',
+          tasks: [
+            { id: 'upstream', prompt: 'generate something' },
+            // Simulates a task the user authored as `prompt` with a
+            // continue_from, then toggled to `command` in the editor panel.
+            // The field should not survive serialization.
+            {
+              id: 'downstream',
+              command: 'bun run build',
+              continue_from: 'upstream',
+              depends_on: ['upstream'],
+            },
+            // A prompt task keeps its continue_from as-is.
+            { id: 'threaded', prompt: 'refine', continue_from: 'upstream' },
+          ],
+        },
+      ],
+    };
+
+    const parsed = parsePipelineYaml(serializePipeline(raw));
+    expect(parsed.tracks[0].tasks[1].continue_from).toBeUndefined();
+    expect(parsed.tracks[0].tasks[1].depends_on).toEqual(['upstream']);
+    expect(parsed.tracks[0].tasks[2].continue_from).toBe('upstream');
+  });
+
   test('deresolvePipeline also omits the default exit_code completion', () => {
     const resolved: PipelineConfig = {
       name: 'Deresolve Defaults',
@@ -99,3 +130,84 @@ describe('completion default serialization', () => {
     });
   });
 });
+
+describe('parseYaml structural validation', () => {
+  test('rejects non-array pipeline.tracks with a clear error', () => {
+    expect(() =>
+      parseYaml(`
+pipeline:
+  name: Bad
+  tracks:
+    id: not-an-array
+`),
+    ).toThrow(/pipeline\.tracks must be an array/);
+  });
+
+  test('rejects non-array track.tasks with a clear error', () => {
+    expect(() =>
+      parseYaml(`
+pipeline:
+  name: Bad
+  tracks:
+    - id: t
+      name: T
+      tasks:
+        id: not-an-array
+`),
+    ).toThrow(/track "t": tasks must be an array/);
+  });
+});
+
+describe('permissions inheritance', () => {
+  test('resolveConfig applies pipeline-level permissions to tracks and tasks', () => {
+    const raw: RawPipelineConfig = {
+      name: 'Pipeline Permissions',
+      permissions: { read: true, write: true, execute: false },
+      tracks: [
+        {
+          id: 'track_a',
+          name: 'Track A',
+          tasks: [{ id: 'task_1', prompt: 'hello' }],
+        },
+      ],
+    };
+
+    const resolved = resolveConfig(raw, 'D:/workspace');
+    expect(resolved.tracks[0].permissions).toEqual({ read: true, write: true, execute: false });
+    expect(resolved.tracks[0].tasks[0].permissions).toEqual({
+      read: true,
+      write: true,
+      execute: false,
+    });
+  });
+
+  test('deresolvePipeline preserves pipeline-level permissions without repeating inherited values', () => {
+    const resolved: PipelineConfig = {
+      name: 'Deresolve Permissions',
+      permissions: { read: true, write: true, execute: false },
+      tracks: [
+        {
+          id: 'track_a',
+          name: 'Track A',
+          permissions: { read: true, write: true, execute: false },
+          cwd: 'D:/workspace',
+          tasks: [
+            {
+              id: 'task_1',
+              name: 'Task 1',
+              prompt: 'hello',
+              permissions: { read: true, write: true, execute: false },
+              cwd: 'D:/workspace',
+            },
+          ],
+        },
+      ],
+    };
+
+    const raw = deresolvePipeline(resolved, 'D:/workspace');
+
+    expect(raw.permissions).toEqual({ read: true, write: true, execute: false });
+    expect(raw.tracks[0].permissions).toBeUndefined();
+    expect(raw.tracks[0].tasks[0].permissions).toBeUndefined();
+  });
+});

package/src/schema.ts

@@ -17,13 +17,17 @@ import { buildDag } from './dag';
 // ═══ YAML Parsing ═══
 
 export function parseYaml(content: string): RawPipelineConfig {
-  const doc = yaml.load(content) as { pipeline?: RawPipelineConfig };
+  const doc = yaml.load(content) as { pipeline?: unknown };
   if (!doc?.pipeline) {
     throw new Error('YAML must contain a top-level "pipeline" key');
   }
-  const p = doc.pipeline;
+  if (typeof doc.pipeline !== 'object' || Array.isArray(doc.pipeline)) {
+    throw new Error('pipeline must be an object');
+  }
+  const p = doc.pipeline as RawPipelineConfig;
   if (!p.name) throw new Error('pipeline.name is required');
-  if (!p.tracks || p.tracks.length === 0) throw new Error('pipeline.tracks must be non-empty');
+  if (!Array.isArray(p.tracks)) throw new Error('pipeline.tracks must be an array');
+  if (p.tracks.length === 0) throw new Error('pipeline.tracks must be non-empty');
 
   // D14: Detect duplicate track IDs before per-track validation so the error
   // message is clear ("Duplicate track id") rather than a confusing DAG error
@@ -60,10 +64,16 @@ function assertValidId(id: string, label: string): void {
 }
 
 function validateRawTrack(track: RawTrackConfig): void {
+  if (!track || typeof track !== 'object' || Array.isArray(track)) {
+    throw new Error('track must be an object');
+  }
   if (!track.id) throw new Error('track.id is required');
   assertValidId(track.id, `track "${track.id}"`);
   if (!track.name) throw new Error(`track "${track.id}": name is required`);
-  if (!track.tasks || track.tasks.length === 0) {
+  if (!Array.isArray(track.tasks)) {
+    throw new Error(`track "${track.id}": tasks must be an array`);
+  }
+  if (track.tasks.length === 0) {
     throw new Error(`track "${track.id}": tasks must be non-empty`);
   }
   for (const task of track.tasks) {
@@ -72,6 +82,9 @@ function validateRawTrack(track: RawTrackConfig): void {
 }
 
 function validateRawTask(task: RawTaskConfig, trackId: string): void {
+  if (!task || typeof task !== 'object' || Array.isArray(task)) {
+    throw new Error(`track "${trackId}": task must be an object`);
+  }
   if (!task.id) throw new Error(`track "${trackId}": task.id is required`);
   assertValidId(task.id, `task "${task.id}" in track "${trackId}"`);
 
@@ -140,7 +153,7 @@ export function resolveConfig(raw: RawPipelineConfig, workDir: string): Pipeline
         model: rawTask.model ?? rawTrack.model ?? raw.model,
         reasoning_effort:
           rawTask.reasoning_effort ?? rawTrack.reasoning_effort ?? raw.reasoning_effort,
-        permissions: rawTask.permissions ?? rawTrack.permissions ?? DEFAULT_PERMISSIONS,
+        permissions: rawTask.permissions ?? rawTrack.permissions ?? raw.permissions ?? DEFAULT_PERMISSIONS,
         driver: rawTask.driver ?? trackDriver ?? 'opencode',
         timeout: rawTask.timeout,
         // Middleware: Task-level overrides Track (including [] to disable)
@@ -161,7 +174,7 @@ export function resolveConfig(raw: RawPipelineConfig, workDir: string): Pipeline
       agent_profile: rawTrack.agent_profile,
       model: rawTrack.model ?? raw.model,
       reasoning_effort: rawTrack.reasoning_effort ?? raw.reasoning_effort,
-      permissions: rawTrack.permissions ?? DEFAULT_PERMISSIONS,
+      permissions: rawTrack.permissions ?? raw.permissions ?? DEFAULT_PERMISSIONS,
       driver: trackDriver ?? 'opencode',
       cwd: trackCwd,
       middlewares: rawTrack.middlewares,
@@ -175,6 +188,7 @@ export function resolveConfig(raw: RawPipelineConfig, workDir: string): Pipeline
     driver: raw.driver,
     model: raw.model,
     reasoning_effort: raw.reasoning_effort,
+    permissions: raw.permissions,
     timeout: raw.timeout,
     plugins: raw.plugins,
     hooks: raw.hooks,
@@ -208,14 +222,32 @@ function stripDefaultTaskCompletion<T extends { completion?: CompletionConfig }>
   return rest as T;
 }
 
-function stripDefaultCompletionsForSerialization<T extends PipelineConfig | RawPipelineConfig>(
+// `continue_from` is a prompt-only field — it tells AI drivers with
+// session-resume capability to thread off an upstream prompt task's context.
+// A command task runs as a plain shell subprocess and has no session to
+// resume, so any `continue_from` on a command task is dead weight. Drop it
+// at serialization time so YAML on disk never carries the stale field after
+// a user toggles task mode from prompt → command. The tagma-yaml agent's
+// system prompt (apps/editor/server/opencode-seed.ts) documents this
+// stripping — keep them in sync.
+function stripPromptOnlyFieldsFromCommandTask<
+  T extends { command?: string; continue_from?: string },
+>(task: T): T {
+  if (task.command === undefined || task.continue_from === undefined) return task;
+  const { continue_from: _cf, ...rest } = task;
+  return rest as T;
+}
+
+function stripForSerialization<T extends PipelineConfig | RawPipelineConfig>(
   config: T,
 ): T {
   return {
     ...config,
     tracks: config.tracks.map((track) => ({
       ...track,
-      tasks: track.tasks.map((task) => stripDefaultTaskCompletion(task)),
+      tasks: track.tasks.map((task) =>
+        stripPromptOnlyFieldsFromCommandTask(stripDefaultTaskCompletion(task)),
+      ),
     })),
   } as T;
 }
@@ -228,7 +260,7 @@ function stripDefaultCompletionsForSerialization<T extends PipelineConfig | RawP
  */
 export function serializePipeline(config: PipelineConfig | RawPipelineConfig): string {
   return yaml.dump(
-    { pipeline: stripDefaultCompletionsForSerialization(config) },
+    { pipeline: stripForSerialization(config) },
     { lineWidth: 120, indent: 2 },
   );
 }
@@ -302,7 +334,7 @@ export function deresolvePipeline(config: PipelineConfig, workDir: string): RawP
       ...(track.on_failure && track.on_failure !== 'skip_downstream'
         ? { on_failure: track.on_failure }
         : {}),
-      ...(track.permissions && !permissionsEqual(track.permissions, DEFAULT_PERMISSIONS)
+      ...(track.permissions && !permissionsEqual(track.permissions, config.permissions ?? DEFAULT_PERMISSIONS)
         ? { permissions: track.permissions }
         : {}),
       tasks,
@@ -314,6 +346,9 @@ export function deresolvePipeline(config: PipelineConfig, workDir: string): RawP
     ...(config.driver ? { driver: config.driver } : {}),
     ...(config.model ? { model: config.model } : {}),
     ...(config.reasoning_effort ? { reasoning_effort: config.reasoning_effort } : {}),
+    ...(config.permissions && !permissionsEqual(config.permissions, DEFAULT_PERMISSIONS)
+      ? { permissions: config.permissions }
+      : {}),
     ...(config.timeout ? { timeout: config.timeout } : {}),
     ...(config.plugins?.length ? { plugins: config.plugins } : {}),
     ...(config.hooks ? { hooks: config.hooks } : {}),

package/src/task-ref.ts

@@ -68,6 +68,7 @@ export function buildTaskIndex(config: RawPipelineConfig | PipelineConfig): Task
   const bareToQualified = new Map<string, string>();
   for (const track of config.tracks ?? []) {
     if (!track?.id) continue;
+    if (!Array.isArray(track.tasks)) continue;
     for (const task of track.tasks ?? []) {
       if (!task?.id) continue;
       const qid = qualifyTaskId(track.id, task.id);

package/src/utils.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, test } from 'bun:test';
+import { mkdirSync, mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { validatePath } from './utils';
+
+describe('validatePath', () => {
+  test('rejects real parent traversal outside the project root', () => {
+    const root = mkdtempSync(join(tmpdir(), 'tagma-validate-path-'));
+    try {
+      expect(() => validatePath('../outside', root)).toThrow(/escapes project root/);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  test('allows project-local names that merely start with two dots', () => {
+    const root = mkdtempSync(join(tmpdir(), 'tagma-validate-path-'));
+    try {
+      const inside = join(root, '..inside');
+      mkdirSync(inside);
+
+      expect(validatePath('..inside', root)).toBe(inside);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+});

package/src/utils.ts

@@ -1,4 +1,4 @@
-import { resolve, relative, parse as parsePath } from 'path';
+import { isAbsolute, resolve, relative, parse as parsePath, sep } from 'path';
 import { realpathSync, lstatSync, existsSync } from 'fs';
 import { randomBytes } from 'crypto';
 
@@ -38,7 +38,7 @@ export function validatePath(filePath: string, projectRoot: string): string {
   }
 
   const rel = relative(projectRoot, resolved);
-  if (rel.startsWith('..') || rel.startsWith('/')) {
+  if (rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
     throw new Error(
       `Security: path "${filePath}" escapes project root. ` +
         `All file references must be within "${projectRoot}".`,
@@ -83,7 +83,7 @@ export function validatePath(filePath: string, projectRoot: string): string {
       );
     }
     const realRel = relative(realRoot, real);
-    if (realRel.startsWith('..') || realRel.startsWith('/')) {
+    if (realRel === '..' || realRel.startsWith(`..${sep}`) || isAbsolute(realRel)) {
       throw new Error(
         `Security: path "${filePath}" resolves via symlink to "${real}" which escapes project root "${realRoot}".`,
       );

package/src/validate-raw-plugin-types.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, test } from 'bun:test';
+import { compileYamlContent } from './yaml-compiler';
+import { validateRaw } from './validate-raw';
+import type { RawPipelineConfig } from './types';
+
+describe('validateRaw known plugin types', () => {
+  test('warns when pipeline, track, or prompt task references an unknown driver', () => {
+    const config: RawPipelineConfig = {
+      name: 'driver checks',
+      driver: 'missing-pipeline',
+      tracks: [
+        {
+          id: 'main',
+          name: 'Main',
+          driver: 'missing-track',
+          tasks: [
+            {
+              id: 'prompt',
+              name: 'Prompt',
+              prompt: 'hello',
+              driver: 'missing-task',
+            },
+          ],
+        },
+      ],
+    };
+
+    const diagnostics = validateRaw(config, { drivers: ['opencode'] });
+    expect(diagnostics.map((d) => d.message)).toEqual(
+      expect.arrayContaining([
+        'Unknown driver type "missing-pipeline"',
+        'Unknown driver type "missing-track"',
+        'Unknown driver type "missing-task"',
+      ]),
+    );
+  });
+
+  test('compileYamlContent includes unknown driver warnings from knownTypes.drivers', () => {
+    const result = compileYamlContent(
+      [
+        'pipeline:',
+        '  name: Unknown Driver',
+        '  driver: ghost',
+        '  tracks:',
+        '    - id: main',
+        '      name: Main',
+        '      tasks:',
+        '        - id: prompt',
+        '          name: Prompt',
+        '          prompt: Hello',
+        '',
+      ].join('\n'),
+      { knownTypes: { drivers: ['opencode'] } },
+    );
+
+    expect(result.validation.warnings.map((w) => w.message)).toContain(
+      'Unknown driver type "ghost"',
+    );
+  });
+});