@tagma/sdk 0.4.19 → 0.5.1

package/src/pipeline-runner.ts

@@ -1,14 +1,20 @@
 // ═══ PipelineRunner ═══
 //
-// Wraps runPipeline in a lifecycle object suited for multi-pipeline management
-// in sidecar / Tauri IPC scenarios. Each instance controls one pipeline run.
+// Wraps runPipeline in a lifecycle object suited for multi-pipeline
+// management in sidecar / Tauri IPC scenarios. Each instance controls
+// one pipeline run.
+//
+// The runner forwards wire-shape `RunEventPayload` values to its
+// subscribers — identical to what the editor server broadcasts over SSE —
+// so sidecar hosts don't need to know anything about the engine's
+// internal TaskState.
 //
 // Typical sidecar usage:
 //
 //   const runners = new Map<string, PipelineRunner>();
 //
 //   const runner = new PipelineRunner(config, workDir);
-//   runner.subscribe(event => ipcEmit('pipeline_event', event));
+//   runner.subscribe(event => ipcEmit('run_event', event));
 //   runner.start();
 //   runners.set(runner.instanceId, runner);
 //
@@ -16,33 +22,37 @@
 //   runners.get(id)?.abort();
 
 import { runPipeline } from './engine';
-import type { EngineResult, PipelineEvent, RunPipelineOptions } from './engine';
-import type { PipelineConfig, TaskState } from './types';
+import type { EngineResult, RunPipelineOptions } from './engine';
+import type { PipelineConfig, RunEventPayload, RunTaskState } from './types';
 import { generateRunId } from './utils';
 
-export type { PipelineEvent, EngineResult };
+export type { 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.
+   * Stable ID assigned before start() — safe to use as a Map key 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.
+   * The runId generated by the engine. Set when the first `run_start`
+   * event arrives on the forwarded event stream. 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>();
+  private _handlers = new Set<(event: RunEventPayload) => void>();
+  /**
+   * Wire-shape task mirror, kept in sync with `run_start` / `task_update`
+   * events. Exposed through `getTasks()`. Hosts see the same wire
+   * projection the editor client sees, so there is exactly one task-state
+   * vocabulary across IPC boundaries.
+   */
+  private _tasks = new Map<string, RunTaskState>();
 
   constructor(
     private readonly config: PipelineConfig,
@@ -79,25 +89,11 @@ export class PipelineRunner {
       ...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';
-        }
+        this._applyEvent(event);
         for (const h of this._handlers) h(event);
       },
     })
       .then((result) => {
-        this._states = result.states;
         if (this._status === 'running') this._status = 'done';
         return result;
       })
@@ -109,6 +105,44 @@ export class PipelineRunner {
     return this._result;
   }
 
+  private _applyEvent(event: RunEventPayload): void {
+    switch (event.type) {
+      case 'run_start':
+        this._runId = event.runId;
+        this._tasks.clear();
+        for (const t of event.tasks) this._tasks.set(t.taskId, { ...t });
+        return;
+      case 'task_update': {
+        const prev = this._tasks.get(event.taskId);
+        if (!prev) return;
+        const pick = <T>(incoming: T | undefined, previous: T): T =>
+          incoming !== undefined ? incoming : previous;
+        this._tasks.set(event.taskId, {
+          ...prev,
+          status: event.status,
+          startedAt: pick(event.startedAt, prev.startedAt),
+          finishedAt: pick(event.finishedAt, prev.finishedAt),
+          durationMs: pick(event.durationMs, prev.durationMs),
+          exitCode: pick(event.exitCode, prev.exitCode),
+          stdout: pick(event.stdout, prev.stdout),
+          stderr: pick(event.stderr, prev.stderr),
+          stderrPath: pick(event.stderrPath, prev.stderrPath),
+          sessionId: pick(event.sessionId, prev.sessionId),
+          normalizedOutput: pick(event.normalizedOutput, prev.normalizedOutput),
+          resolvedDriver: pick(event.resolvedDriver, prev.resolvedDriver),
+          resolvedModel: pick(event.resolvedModel, prev.resolvedModel),
+          resolvedPermissions: pick(event.resolvedPermissions, prev.resolvedPermissions),
+        });
+        return;
+      }
+      case 'run_end':
+        this._status = this._abortController.signal.aborted ? 'aborted' : 'done';
+        return;
+      default:
+        return;
+    }
+  }
+
   /**
    * Cancel the running pipeline. Safe to call multiple times or before start().
    */
@@ -118,39 +152,22 @@ export class PipelineRunner {
   }
 
   /**
-   * 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.
+   * Live snapshot of wire-shape task states. Populated from the first
+   * `run_start` event onward. Returns an empty map before the run starts.
    */
-  getStates(): ReadonlyMap<string, TaskState> | null {
-    if (this._states) return snapshotStates(this._states);
-    if (this._statesMirror.size > 0) return snapshotStates(this._statesMirror);
-    return null;
+  getTasks(): ReadonlyMap<string, RunTaskState> {
+    const copy = new Map<string, RunTaskState>();
+    for (const [id, t] of this._tasks) copy.set(id, { ...t });
+    return copy;
   }
 
   /**
-   * 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 to run 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 {
+  subscribe(handler: (event: RunEventPayload) => 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

@@ -144,7 +144,6 @@ export function registerPlugin<T extends PluginType>(
     // 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.
-    // eslint-disable-next-line no-console
     console.warn(
       `[tagma-sdk] registerPlugin: replaced existing ${category}/${type} — ` +
         `check for duplicate plugin packages claiming the same type.`,

package/src/schema.test.ts

@@ -63,7 +63,7 @@ describe('completion default serialization', () => {
         {
           id: 'track_a',
           name: 'Track A',
-          driver: 'claude-code',
+          driver: 'opencode',
           permissions: { read: true, write: false, execute: false },
           on_failure: 'skip_downstream',
           cwd: 'D:/workspace',
@@ -72,7 +72,7 @@ describe('completion default serialization', () => {
               id: 'task_1',
               name: 'Task 1',
               prompt: 'hello',
-              driver: 'claude-code',
+              driver: 'opencode',
               permissions: { read: true, write: false, execute: false },
               cwd: 'D:/workspace',
               completion: { type: 'exit_code', expect: 0 },
@@ -81,7 +81,7 @@ describe('completion default serialization', () => {
               id: 'task_2',
               name: 'Task 2',
               prompt: 'custom',
-              driver: 'claude-code',
+              driver: 'opencode',
               permissions: { read: true, write: false, execute: false },
               cwd: 'D:/workspace',
               completion: { type: 'output_check', check: 'test -f ./done.txt' },

package/src/schema.ts

@@ -141,7 +141,7 @@ export function resolveConfig(raw: RawPipelineConfig, workDir: string): Pipeline
         reasoning_effort:
           rawTask.reasoning_effort ?? rawTrack.reasoning_effort ?? raw.reasoning_effort,
         permissions: rawTask.permissions ?? rawTrack.permissions ?? DEFAULT_PERMISSIONS,
-        driver: rawTask.driver ?? trackDriver ?? 'claude-code',
+        driver: rawTask.driver ?? trackDriver ?? 'opencode',
         timeout: rawTask.timeout,
         // Middleware: Task-level overrides Track (including [] to disable)
         middlewares: rawTask.middlewares !== undefined ? rawTask.middlewares : rawTrack.middlewares,
@@ -159,7 +159,7 @@ export function resolveConfig(raw: RawPipelineConfig, workDir: string): Pipeline
       model: rawTrack.model ?? raw.model,
       reasoning_effort: rawTrack.reasoning_effort ?? raw.reasoning_effort,
       permissions: rawTrack.permissions ?? DEFAULT_PERMISSIONS,
-      driver: trackDriver ?? 'claude-code',
+      driver: trackDriver ?? 'opencode',
       cwd: trackCwd,
       middlewares: rawTrack.middlewares,
       on_failure: rawTrack.on_failure ?? 'skip_downstream',
@@ -243,7 +243,7 @@ export function deresolvePipeline(config: PipelineConfig, workDir: string): RawP
   const tracks: RawTrackConfig[] = config.tracks.map((track) => {
     const trackCwdRel =
       track.cwd && track.cwd !== workDir ? relative(workDir, track.cwd) : undefined;
-    const effectiveTrackDriver = track.driver ?? config.driver ?? 'claude-code';
+    const effectiveTrackDriver = track.driver ?? config.driver ?? 'opencode';
     const effectiveTrackModel = track.model ?? config.model;
     const effectiveTrackReasoning = track.reasoning_effort ?? config.reasoning_effort;
 
@@ -286,7 +286,7 @@ export function deresolvePipeline(config: PipelineConfig, workDir: string): RawP
       ...(track.reasoning_effort && track.reasoning_effort !== config.reasoning_effort
         ? { reasoning_effort: track.reasoning_effort }
         : {}),
-      ...(track.driver && track.driver !== (config.driver ?? 'claude-code')
+      ...(track.driver && track.driver !== (config.driver ?? 'opencode')
         ? { driver: track.driver }
         : {}),
       ...(trackCwdRel ? { cwd: trackCwdRel } : {}),

package/src/sdk.ts

@@ -5,7 +5,7 @@
 
 // ── Core engine ──
 export { runPipeline, TriggerBlockedError, TriggerTimeoutError } from './engine';
-export type { EngineResult, RunPipelineOptions, PipelineEvent } from './engine';
+export type { EngineResult, RunPipelineOptions, RunEventPayload } from './engine';
 
 // ── Pipeline runner (multi-pipeline lifecycle management) ──
 export { PipelineRunner } from './pipeline-runner';

package/src/drivers/claude-code.ts

@@ -1,250 +0,0 @@
-import { existsSync } from 'node:fs';
-import { isAbsolute, relative, dirname, join } from 'node:path';
-import type {
-  DriverPlugin,
-  DriverCapabilities,
-  DriverResultMeta,
-  TaskConfig,
-  TrackConfig,
-  DriverContext,
-  SpawnSpec,
-  Permissions,
-} from '../types';
-
-// Claude Code CLI reference: https://code.claude.com/docs/en/cli-reference
-
-const DEFAULT_MODEL = 'sonnet';
-
-// Claude Code CLI accepts --effort low|medium|high|max. tagma's vocabulary
-// is low|medium|high, so low/medium/high pass through unchanged; users who
-// want the claude-specific "max" tier can also set it explicitly.
-const VALID_EFFORT = new Set(['low', 'medium', 'high', 'max']);
-
-function resolveModel(): string {
-  return DEFAULT_MODEL;
-}
-
-function resolveTools(permissions: Permissions): string {
-  const tools = ['Grep', 'Glob'];
-  if (permissions.read) tools.push('Read');
-  if (permissions.write) tools.push('Edit', 'Write');
-  if (permissions.execute) tools.push('Bash');
-  return tools.join(',');
-}
-
-// Maps our Permissions to Claude Code's --permission-mode. In print (-p) mode
-// Claude needs non-interactive permission handling:
-// - `bypassPermissions` skips all checks (required for reliable Bash automation
-//   under `execute: true`, matches the "full trust" semantics of that tier).
-// - `dontAsk` auto-denies anything outside `--allowedTools`, which is exactly
-//   what we want for read/write tiers: the allowedTools whitelist already
-//   enumerates what Claude may do, and dontAsk makes violations fail fast
-//   instead of hanging on a prompt no one can answer in headless mode.
-// See: https://code.claude.com/docs/en/permission-modes
-function resolvePermissionMode(permissions: Permissions): string {
-  if (permissions.execute) return 'bypassPermissions';
-  return 'dontAsk';
-}
-
-// Returns true if `sub` is inside `root` (or equal to it).
-function isInside(root: string, sub: string): boolean {
-  const rel = relative(root, sub);
-  return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
-}
-
-// Claude Code requires CLAUDE_CODE_GIT_BASH_PATH on Windows pointing to
-// Git Bash (bin\bash.exe under a Git for Windows install). See:
-//   https://code.claude.com/docs/en/troubleshooting#windows-claude-code-on-windows-requires-git-bash
-// The path must use native Windows backslashes — forward slashes are rejected
-// by Claude Code's path validation.
-function resolveGitBashEnv(): Record<string, string> {
-  if (process.platform !== 'win32') return {};
-
-  // Respect user-provided value if it points to an actual file. If the user
-  // set it to a non-existent path, fall through to discovery rather than
-  // propagating the broken config.
-  const existing = process.env.CLAUDE_CODE_GIT_BASH_PATH;
-  if (existing && existsSync(existing)) return {};
-
-  const discovered = discoverGitBash();
-  return discovered ? { CLAUDE_CODE_GIT_BASH_PATH: discovered } : {};
-}
-
-function discoverGitBash(): string | null {
-  // Strategy 1: find git.exe in PATH (equivalent to `where.exe git`) and
-  // walk up looking for bin\bash.exe under a Git install root. Git for
-  // Windows may expose multiple git.exe locations (cmd\git.exe,
-  // mingw64\bin\git.exe, mingw64\libexec\git-core\git.exe), so we walk up
-  // several levels rather than assuming a fixed depth.
-  const gitExe = findExeInPath('git.exe');
-  if (gitExe) {
-    let dir = dirname(gitExe);
-    for (let depth = 0; depth < 5; depth++) {
-      const candidate = join(dir, 'bin', 'bash.exe');
-      if (existsSync(candidate)) return candidate;
-      const parent = dirname(dir);
-      if (parent === dir) break;
-      dir = parent;
-    }
-  }
-
-  // Strategy 2: check common Git for Windows install locations.
-  // Uses %ProgramFiles%/%LOCALAPPDATA%/%USERPROFILE% env vars so it works on
-  // systems where those aren't mapped to C:\ (e.g. localized Windows).
-  const programFiles = process.env['ProgramFiles'] ?? 'C:\\Program Files';
-  const programFilesX86 = process.env['ProgramFiles(x86)'] ?? 'C:\\Program Files (x86)';
-  const localAppData = process.env['LOCALAPPDATA'];
-  const userProfile = process.env['USERPROFILE'];
-
-  const candidates = [
-    join(programFiles, 'Git', 'bin', 'bash.exe'),
-    join(programFilesX86, 'Git', 'bin', 'bash.exe'),
-    // Git for Windows user-level install
-    localAppData && join(localAppData, 'Programs', 'Git', 'bin', 'bash.exe'),
-    // Scoop
-    userProfile && join(userProfile, 'scoop', 'apps', 'git', 'current', 'bin', 'bash.exe'),
-    // Chocolatey default
-    'C:\\tools\\git\\bin\\bash.exe',
-  ].filter((p): p is string => Boolean(p));
-
-  for (const c of candidates) {
-    if (existsSync(c)) return c;
-  }
-
-  // Strategy 3: scan PATH for any entry containing "git" (e.g. Git's
-  // mingw64/bin or usr/bin already in PATH), walk up to find bash.exe.
-  // Catches custom install locations.
-  const pathEntries = (process.env.PATH ?? '').split(';');
-  for (const entry of pathEntries) {
-    if (!/git/i.test(entry)) continue;
-    const normalized = entry.replace(/\//g, '\\').replace(/\\+$/, '');
-    const parts = normalized.split('\\');
-    for (let depth = 1; depth <= 4; depth++) {
-      const root = parts.slice(0, parts.length - depth).join('\\');
-      if (!root) continue;
-      const candidate = root + '\\bin\\bash.exe';
-      if (existsSync(candidate)) return candidate;
-    }
-  }
-
-  return null;
-}
-
-function findExeInPath(exe: string): string | null {
-  const pathDirs = (process.env.PATH ?? '').split(';');
-  for (const dir of pathDirs) {
-    if (!dir) continue;
-    const full = join(dir, exe);
-    if (existsSync(full)) return full;
-  }
-  return null;
-}
-
-export const ClaudeCodeDriver: DriverPlugin = {
-  name: 'claude-code',
-
-  capabilities: {
-    sessionResume: true,
-    systemPrompt: true,
-    outputFormat: true,
-  } satisfies DriverCapabilities,
-
-  resolveModel,
-  resolveTools,
-
-  async buildCommand(task: TaskConfig, track: TrackConfig, ctx: DriverContext): Promise<SpawnSpec> {
-    const permissions = task.permissions ?? track.permissions!;
-    const model = task.model ?? track.model ?? DEFAULT_MODEL;
-    // SDK schema layer already resolved task → track → pipeline inheritance.
-    // Drop unknown effort values so a typo can't break `claude -p` startup;
-    // validateRaw / the UI should prevent this from reaching us in practice.
-    const rawEffort = task.reasoning_effort ?? track.reasoning_effort;
-    const effort = rawEffort && VALID_EFFORT.has(rawEffort) ? rawEffort : null;
-    const tools = resolveTools(permissions);
-    const permissionMode = resolvePermissionMode(permissions);
-
-    // Pass the prompt via stdin instead of as a -p argument value. On Windows,
-    // multi-line strings in CLI arguments break cmd.exe argument parsing when
-    // the executable is a .cmd wrapper — newlines cause all subsequent flags
-    // (--output-format, --model, etc.) to be silently dropped.
-    const stdin = task.prompt!;
-
-    const args: string[] = [
-      'claude',
-      '-p', // no value — prompt is piped via stdin
-      '--model',
-      model,
-      '--allowedTools',
-      tools,
-      '--permission-mode',
-      permissionMode,
-      '--output-format',
-      'json',
-      // NOTE: do NOT use --verbose here. It changes stdout from a single JSON
-      // result object to a JSON event-stream array, breaking parseResult's
-      // session_id extraction (needed for continue_from) and normalizedOutput.
-      // The engine already captures stdout/stderr for pipeline logs.
-      // Pin to project+local settings only; don't inherit arbitrary user-level
-      // config (hooks, MCP servers, etc.) into pipeline automation.
-      '--setting-sources',
-      'project,local',
-    ];
-
-    if (effort) {
-      args.push('--effort', effort);
-    }
-
-    // If the task runs in a subdirectory of the project, grant read/edit
-    // access to the project root via --add-dir so Claude can still see
-    // shared files (configs, types, etc.) outside task.cwd.
-    const effectiveCwd = task.cwd ?? ctx.workDir;
-    if (effectiveCwd !== ctx.workDir && isInside(ctx.workDir, effectiveCwd)) {
-      args.push('--add-dir', ctx.workDir);
-    }
-
-    // Native session resume
-    if (task.continue_from) {
-      const sessionId = ctx.sessionMap.get(task.continue_from);
-      if (sessionId) {
-        args.push('--resume', sessionId);
-      }
-    }
-
-    // --append-system-prompt MUST be last: its value may contain newlines,
-    // and on Windows cmd.exe can silently drop any flags that follow a
-    // newline-containing argument.
-    const profile = task.agent_profile ?? track.agent_profile;
-    if (profile) {
-      args.push('--append-system-prompt', profile);
-    }
-
-    return { args, cwd: effectiveCwd, env: resolveGitBashEnv(), stdin };
-  },
-
-  parseResult(stdout: string): DriverResultMeta {
-    try {
-      let json = JSON.parse(stdout);
-
-      // --verbose produces a JSON array of events; extract the final "result"
-      // event so session_id and normalizedOutput are correctly populated.
-      if (Array.isArray(json)) {
-        const resultEvent = json.findLast((e: Record<string, unknown>) => e.type === 'result');
-        if (!resultEvent) return { normalizedOutput: stdout };
-        json = resultEvent;
-      }
-
-      // Extract canonical text: strip JSON envelope so downstream drivers
-      // get the actual AI response, not metadata
-      const normalizedOutput = json.result ?? json.text ?? json.content ?? stdout;
-      return {
-        sessionId: json.session_id,
-        normalizedOutput:
-          typeof normalizedOutput === 'string'
-            ? normalizedOutput
-            : JSON.stringify(normalizedOutput),
-      };
-    } catch {
-      return { normalizedOutput: stdout };
-    }
-  },
-};