@tagma/sdk 0.4.14 → 0.4.16

package/README.md

@@ -1,569 +1,569 @@
-# @tagma/sdk
-
-> ## ⚠️ Bun-only runtime
->
-> ```bash
-> bun add @tagma/sdk
-> ```
->
-> This package is published as pre-built JavaScript (`dist/`), but the runtime
-> uses Bun-only APIs (`Bun.spawn`, `Bun.file`, `Bun.serve`). It will install
-> under `npm` / `yarn` / `pnpm` without error, but **crash at runtime on Node**
-> the first time a pipeline spawns a task. Get Bun at <https://bun.sh>.
->
-> _(The `npm i @tagma/sdk` line in the npmjs.com sidebar is auto-generated by
-> the npm registry website and cannot be removed — please ignore it and use
-> the command above.)_
-
-A local AI task orchestration SDK for [Bun](https://bun.sh). Define multi-track pipelines in YAML, run AI coding agents (Claude Code, Codex, OpenCode) and shell commands in parallel with dependency resolution, approval gates, and lifecycle hooks.
-
-## Install
-
-**Requires Bun ≥ 1.3.** Node/npm are not supported.
-
-```bash
-bun add @tagma/sdk
-```
-
-## Quick Start
-
-**1. Define a pipeline** (`pipeline.yaml`)
-
-```yaml
-pipeline:
-  name: build-and-test
-  tracks:
-    - id: backend
-      name: Backend
-      driver: claude-code
-      permissions: { read: true, write: true, execute: false }
-      tasks:
-        - id: implement
-          name: Implement feature
-          prompt: 'Add a /health endpoint to src/server.ts'
-        - id: test
-          name: Run tests
-          command: 'bun test'
-          depends_on: [implement]
-```
-
-**2. Run it programmatically**
-
-```ts
-import { bootstrapBuiltins, loadPipeline, runPipeline, InMemoryApprovalGateway } from '@tagma/sdk';
-
-// Register built-in drivers, triggers, completions
-bootstrapBuiltins();
-
-const yaml = await Bun.file('pipeline.yaml').text();
-const config = await loadPipeline(yaml, process.cwd());
-
-const result = await runPipeline(config, process.cwd());
-console.log(result.success ? 'Done' : 'Failed');
-```
-
-## Features
-
-- **Multi-track DAG execution** -- tasks run in parallel across tracks, respecting `depends_on` ordering
-- **Driver plugins** -- built-in `claude-code` driver; install `@tagma/driver-codex` or `@tagma/driver-opencode` for other agents
-- **Session handoff** -- `continue_from` passes context between tasks (session resume or text injection)
-- **Approval gates** -- trigger-based approval with stdin and WebSocket adapters
-- **Lifecycle hooks** -- `pipeline_start`, `task_start`, `task_success`, `task_failure`, `pipeline_complete`, `pipeline_error`
-- **Middleware** -- enrich prompts before execution (e.g. inject static context)
-- **Completion checks** -- validate task output with `exit_code`, `file_exists`, or `output_check` plugins
-- **Plugin schemas** -- triggers/completions/middlewares can declare a `PluginSchema` so visual editors render typed forms for their config
-
-## Pipeline YAML Reference
-
-### Full Structure
-
-```yaml
-pipeline:
-  name: my-pipeline
-  driver: claude-code
-  timeout: 30m
-  plugins:
-    - '@tagma/driver-codex'
-  hooks:
-    pipeline_start: 'echo starting'
-    task_start: 'echo task begin'
-    task_success: 'echo task ok'
-    task_failure: 'notify-slack.sh'
-    pipeline_complete: 'echo done'
-    pipeline_error: 'alert.sh'
-  tracks:
-    - id: track-1
-      name: Track One
-      color: '#3b82f6'
-      driver: claude-code
-      model: claude-sonnet-4-6
-      agent_profile: senior
-      cwd: ./services/backend
-      permissions:
-        read: true
-        write: true
-        execute: false
-      on_failure: skip_downstream
-      middlewares:
-        - type: static_context
-          file: ./context.md
-          label: Architecture Guide
-      tasks:
-        - id: task-a
-          name: Do something
-          prompt: 'Your prompt here'
-          timeout: 10m
-          driver: claude-code
-          model: claude-sonnet-4-6
-          agent_profile: senior
-          cwd: ./src
-          permissions:
-            read: true
-            write: true
-            execute: false
-          middlewares:
-            - type: static_context
-              file: ./ref.md
-          trigger:
-            type: manual
-            message: 'Approve before running'
-            timeout: 5m
-          completion:
-            type: exit_code
-            expect: 0
-        - id: task-b
-          name: Follow up
-          prompt: 'Continue the work'
-          continue_from: task-a
-          depends_on: [task-a]
-```
-
-### Pipeline Fields
-
-| Field     | Type            | Required | Description                                                                                |
-| --------- | --------------- | -------- | ------------------------------------------------------------------------------------------ |
-| `name`    | `string`        | Yes      | Pipeline name, used in logs and run IDs                                                    |
-| `driver`  | `string`        | No       | Default driver for all tracks/tasks (inherited). Built-in: `claude-code`                   |
-| `model`   | `string`        | No       | Default model for all tracks/tasks (inherited). Exact model name, e.g. `claude-sonnet-4-6` |
-| `timeout` | `string`        | No       | Pipeline-level timeout. Format: `"30s"`, `"5m"`, `"2h"`                                    |
-| `plugins` | `string[]`      | No       | External plugin packages to load, e.g. `["@tagma/driver-codex"]`                           |
-| `hooks`   | `HooksConfig`   | No       | Shell commands to run at lifecycle events (see Hooks below)                                |
-| `tracks`  | `TrackConfig[]` | Yes      | List of parallel execution tracks                                                          |
-
-### Hooks Fields
-
-Each hook value can be a single command string or an array of commands.
-
-| Field               | Type                 | Description                                  |
-| ------------------- | -------------------- | -------------------------------------------- |
-| `pipeline_start`    | `string \| string[]` | Runs when the pipeline begins                |
-| `task_start`        | `string \| string[]` | Runs before each task starts                 |
-| `task_success`      | `string \| string[]` | Runs after a task succeeds                   |
-| `task_failure`      | `string \| string[]` | Runs after a task fails                      |
-| `pipeline_complete` | `string \| string[]` | Runs when the pipeline finishes successfully |
-| `pipeline_error`    | `string \| string[]` | Runs when the pipeline finishes with errors  |
-
-### Track Fields
-
-| Field           | Type                 | Required | Default                 | Description                                                          |
-| --------------- | -------------------- | -------- | ----------------------- | -------------------------------------------------------------------- |
-| `id`            | `string`             | Yes      | —                       | Unique track identifier                                              |
-| `name`          | `string`             | Yes      | —                       | Display name                                                         |
-| `color`         | `string`             | No       | —                       | Color hint for UI rendering (e.g. `"#3b82f6"`)                       |
-| `driver`        | `string`             | No       | Inherited from pipeline | Driver for all tasks in this track                                   |
-| `model`         | `string`             | No       | Inherited from pipeline | Exact model name passed to the driver CLI (e.g. `claude-sonnet-4-6`) |
-| `agent_profile` | `string`             | No       | —                       | Named agent configuration profile                                    |
-| `cwd`           | `string`             | No       | Pipeline workDir        | Working directory for tasks in this track (relative path)            |
-| `permissions`   | `Permissions`        | No       | Inherited from pipeline | Default permissions for tasks (see Permissions)                      |
-| `on_failure`    | `OnFailure`          | No       | `skip_downstream`       | Failure strategy: `skip_downstream`, `stop_all`, `ignore`            |
-| `middlewares`   | `MiddlewareConfig[]` | No       | —                       | Middlewares applied to all tasks (task-level overrides track-level)  |
-| `tasks`         | `TaskConfig[]`       | Yes      | —                       | Ordered list of tasks in this track                                  |
-
-### Task Fields
-
-| Field           | Type                 | Required | Default              | Description                                                                                            |
-| --------------- | -------------------- | -------- | -------------------- | ------------------------------------------------------------------------------------------------------ |
-| `id`            | `string`             | Yes      | —                    | Unique task identifier (unique within the pipeline)                                                    |
-| `name`          | `string`             | No       | —                    | Display name                                                                                           |
-| `prompt`        | `string`             | No\*     | —                    | AI prompt to send to the driver. \*Mutually exclusive with `command`                                   |
-| `command`       | `string`             | No\*     | —                    | Shell command to execute directly. \*Mutually exclusive with `prompt`                                  |
-| `depends_on`    | `string[]`           | No       | —                    | Task IDs that must complete before this task runs. Cross-track refs use `trackId.taskId`               |
-| `continue_from` | `string`             | No       | —                    | Task ID whose output/session to continue from (session handoff). Cross-track refs use `trackId.taskId` |
-| `driver`        | `string`             | No       | Inherited from track | Driver override for this task                                                                          |
-| `model`         | `string`             | No       | Inherited from track | Model name override for this task                                                                      |
-| `agent_profile` | `string`             | No       | Inherited from track | Agent profile override                                                                                 |
-| `cwd`           | `string`             | No       | Inherited from track | Working directory override (relative path)                                                             |
-| `timeout`       | `string`             | No       | —                    | Task-level timeout. Format: `"30s"`, `"5m"`, `"2h"`                                                    |
-| `permissions`   | `Permissions`        | No       | Inherited from track | Permission override (see Permissions)                                                                  |
-| `middlewares`   | `MiddlewareConfig[]` | No       | Inherited from track | Middleware override. Set `[]` to disable inherited middlewares                                         |
-| `trigger`       | `TriggerConfig`      | No       | —                    | Gate that must resolve before the task runs (see Triggers)                                             |
-| `completion`    | `CompletionConfig`   | No       | —                    | Post-execution check to validate task output (see Completions)                                         |
-
-### Permissions
-
-| Field     | Type      | Default | Description                         |
-| --------- | --------- | ------- | ----------------------------------- |
-| `read`    | `boolean` | —       | Allow the agent to read files       |
-| `write`   | `boolean` | —       | Allow the agent to write files      |
-| `execute` | `boolean` | —       | Allow the agent to execute commands |
-
-### Inheritance
-
-Fields are inherited top-down: **pipeline → track → task**. A value set at a lower level overrides the inherited value.
-
-Inherited fields: `driver`, `model`, `permissions`, `cwd`, `middlewares`.
-
-Track-level `middlewares` apply to all tasks in the track. Setting task-level `middlewares` **replaces** (not appends) the track-level list. Use `middlewares: []` to disable all inherited middlewares for a task.
-
----
-
-### Built-in Triggers
-
-#### `manual` — Human approval gate
-
-| Field      | Type       | Required | Default                                                | Description                                       |
-| ---------- | ---------- | -------- | ------------------------------------------------------ | ------------------------------------------------- |
-| `type`     | `"manual"` | Yes      | —                                                      | Trigger type                                      |
-| `message`  | `string`   | No       | `"Manual confirmation required for task \"{taskId}\""` | Message shown to the approver                     |
-| `timeout`  | `string`   | No       | —                                                      | How long to wait for a decision before timing out |
-| `metadata` | `object`   | No       | —                                                      | Arbitrary metadata passed to the approval gateway |
-
-#### `file` — File watcher gate
-
-| Field     | Type     | Required | Default | Description                                    |
-| --------- | -------- | -------- | ------- | ---------------------------------------------- |
-| `type`    | `"file"` | Yes      | —       | Trigger type                                   |
-| `path`    | `string` | Yes      | —       | File path to watch (relative to workDir)       |
-| `timeout` | `string` | No       | —       | How long to wait for the file to appear/change |
-
----
-
-### Built-in Completions
-
-#### `exit_code` — Exit code check
-
-| Field    | Type                 | Required | Default | Description                                                        |
-| -------- | -------------------- | -------- | ------- | ------------------------------------------------------------------ |
-| `type`   | `"exit_code"`        | Yes      | —       | Completion type                                                    |
-| `expect` | `number \| number[]` | No       | `0`     | Expected exit code(s). Pass an array for multiple acceptable codes |
-
-#### `file_exists` — File existence check
-
-| Field      | Type                       | Required | Default | Description                                           |
-| ---------- | -------------------------- | -------- | ------- | ----------------------------------------------------- |
-| `type`     | `"file_exists"`            | Yes      | —       | Completion type                                       |
-| `path`     | `string`                   | Yes      | —       | File or directory path to check (relative to workDir) |
-| `kind`     | `"file" \| "dir" \| "any"` | No       | `"any"` | Entity type constraint                                |
-| `min_size` | `number`                   | No       | —       | Minimum file size in bytes (files only)               |
-
-#### `output_check` — Command-based output validation
-
-| Field     | Type             | Required | Default | Description                                                             |
-| --------- | ---------------- | -------- | ------- | ----------------------------------------------------------------------- |
-| `type`    | `"output_check"` | Yes      | —       | Completion type                                                         |
-| `check`   | `string`         | Yes      | —       | Shell command to run. Task stdout is piped to its stdin; exits 0 = pass |
-| `timeout` | `string`         | No       | `"30s"` | Max time to wait for the check command                                  |
-
----
-
-### Built-in Middlewares
-
-#### `static_context` — Prepend file content to prompt
-
-| Field   | Type               | Required | Default                   | Description                                    |
-| ------- | ------------------ | -------- | ------------------------- | ---------------------------------------------- |
-| `type`  | `"static_context"` | Yes      | —                         | Middleware type                                |
-| `file`  | `string`           | Yes      | —                         | Path to the context file (relative to workDir) |
-| `label` | `string`           | No       | `"Reference: {filename}"` | Label for the injected context section         |
-
-## API
-
-### `bootstrapBuiltins()`
-
-Registers all built-in plugins (claude-code driver, file/manual triggers, completion checks, static-context middleware).
-
-### `loadPipeline(yaml: string, workDir: string): Promise<PipelineConfig>`
-
-Parses YAML, resolves inheritance, and validates the configuration.
-
-### `runPipeline(config, workDir, options?): Promise<EngineResult>`
-
-Executes the pipeline. Returns `{ success, runId, logPath, summary, states }`.
-
-Options:
-
-- `approvalGateway` -- custom `ApprovalGateway` instance (defaults to `InMemoryApprovalGateway`)
-- `signal` -- `AbortSignal` to cancel the run externally
-- `onEvent` -- callback for real-time `PipelineEvent` updates:
-  - `pipeline_start` — pipeline began; includes `states: ReadonlyMap<taskId, TaskState>` (initial snapshot of all tasks at `waiting`)
-  - `task_status_change` — a task changed status; includes `state: TaskState` (complete snapshot at the time of change: `startedAt` is populated before the `running` event; `result` and `finishedAt` are populated before any terminal-status event)
-  - `task_log` — a structured log line was written to `pipeline.log`. Mirrors every `Logger` call (info/warn/error/debug/section/quiet) and carries `{ taskId: string | null, level, timestamp, text }`. `taskId` is non-null for lines tagged with a `[task:<id>]` prefix (or passed explicitly to `section`/`quiet`) and `null` for pipeline-wide messages such as the configuration dump and DAG topology. Use this to stream the full run process into UIs without tailing the log file.
-  - `pipeline_end` — pipeline finished; includes `success: boolean`
-- `runId` -- caller-supplied run ID. When provided the engine uses this instead of generating its own, keeping the caller and the SDK log directories aligned on the same ID
-- `maxLogRuns` -- number of per-run log directories to keep under `<workDir>/.tagma/logs/` (default: 20)
-
-### `PipelineRunner`
-
-Higher-level wrapper for managing multiple concurrent pipeline runs — designed for sidecar / Tauri IPC scenarios where the frontend controls pipeline lifecycle by ID.
-
-```ts
-const runner = new PipelineRunner(config, workDir);
-
-// Subscribe before start — handler is called for every PipelineEvent
-const unsubscribe = runner.subscribe((event) => {
-  tauriEmit('pipeline_event', { id: runner.instanceId, event });
-});
-
-runner.start(); // returns Promise<EngineResult>, idempotent
-
-// Cancel from IPC
-runner.abort();
-
-// Available from the first pipeline_start event onward (not just after completion)
-// Returns null only if the pipeline has never started
-const states = runner.getStates(); // ReadonlyMap<taskId, TaskState> | null
-```
-
-Properties:
-
-- `instanceId` — stable ID assigned at construction, safe to use as a Map key before `start()`
-- `runId` — engine-assigned run ID, available after the first `pipeline_start` event (`null` until then)
-- `status` — `'idle' | 'running' | 'done' | 'aborted'`
-
-### `TriggerBlockedError` / `TriggerTimeoutError`
-
-Typed error classes for trigger plugin error classification. The engine uses `instanceof` checks on these to set the correct task status (`blocked` or `timeout`) instead of matching on error message substrings.
-
-Built-in triggers (`manual`, `file`) throw these automatically. Third-party trigger plugins should throw `TriggerBlockedError` for user/policy rejections and `TriggerTimeoutError` for genuine wait timeouts. Plugins that throw plain `Error` still work — the engine falls back to string matching for backward compatibility, but typed errors are preferred to avoid misclassification from coincidental substrings.
-
-```ts
-import { TriggerBlockedError, TriggerTimeoutError } from '@tagma/sdk';
-
-// In a custom trigger plugin:
-throw new TriggerBlockedError('Access denied by policy');
-throw new TriggerTimeoutError('File did not appear within 30s');
-```
-
-### `loadPlugins(names: string[]): Promise<void>`
-
-Dynamically loads and registers external plugin packages.
-
-### `registerPlugin(category, type, handler): void`
-
-Registers a plugin handler manually. Idempotent — duplicate registrations are silently ignored.
-
-Plugin handlers (`TriggerPlugin`, `CompletionPlugin`, `MiddlewarePlugin`) may optionally expose a declarative `schema: PluginSchema` field so visual editors can render a typed form for the plugin's config instead of a raw key/value editor:
-
-```ts
-import type { TriggerPlugin } from '@tagma/types';
-
-export const HttpTrigger: TriggerPlugin = {
-  name: 'http',
-  schema: {
-    description: 'Wait for an HTTP endpoint to return 2xx before the task runs.',
-    fields: {
-      url: { type: 'string', required: true, placeholder: 'https://...' },
-      method: { type: 'enum', enum: ['GET', 'POST'], default: 'GET' },
-      timeout: { type: 'duration', description: 'Give up after this long.' },
-    },
-  },
-  async watch(config, ctx) {
-    /* ... */
-  },
-};
-```
-
-The schema is purely descriptive — plugins still perform their own runtime validation. Supported field types: `string`, `number`, `boolean`, `enum`, `path`, `duration`, `number-or-list`. Each field can declare `required`, `default`, `description`, `enum`, `min`/`max`, `placeholder`. Built-in plugins (`file`/`manual` triggers; `exit_code`/`file_exists`/`output_check` completions; `static_context` middleware) all ship with schemas so editors can generate forms out of the box.
-
-### `getHandler(category, type): PluginType`
-
-Retrieves a registered plugin handler. Throws if the plugin is not registered.
-
-### `hasHandler(category, type): boolean`
-
-Returns `true` if a handler is registered for the given category and type.
-
-### `listRegistered(category): string[]`
-
-Lists all registered handler type names for a plugin category (`'drivers'`, `'triggers'`, `'completions'`, `'middlewares'`).
-
-### `resolveConfig(raw: RawPipelineConfig, workDir: string): PipelineConfig`
-
-Resolves a raw pipeline config into a fully resolved `PipelineConfig` — applies inheritance (pipeline → track → task) for driver, model, permissions, and cwd. Validates and resolves all file paths against `workDir`.
-
-Use `loadPipeline` for the common parse-and-resolve flow. Use `resolveConfig` directly when you need to manipulate the raw config between parsing and resolution.
-
-### `attachStdinApprovalAdapter(gateway): StdinApprovalAdapter`
-
-Attaches an interactive stdin-based approval handler.
-
-### `attachWebSocketApprovalAdapter(gateway, options?): WebSocketApprovalAdapter`
-
-Starts a WebSocket server for remote approval decisions.
-
-### Config CRUD (`config-ops`)
-
-Pure, immutable helper functions for building and editing `RawPipelineConfig` in a visual editor. No runtime dependencies — safe to use in renderer processes.
-
-```ts
-import {
-  createEmptyPipeline,
-  setPipelineField,
-  upsertTrack,
-  removeTrack,
-  moveTrack,
-  updateTrack,
-  upsertTask,
-  removeTask,
-  moveTask,
-  transferTask,
-  serializePipeline,
-} from '@tagma/sdk';
-
-// Build a config programmatically
-let config = createEmptyPipeline('my-pipeline');
-config = upsertTrack(config, { id: 'backend', name: 'Backend', tasks: [] });
-config = upsertTask(config, 'backend', { id: 'implement', prompt: 'Add /health endpoint' });
-
-// Sync back to YAML
-const yaml = serializePipeline(config);
-```
-
-| Function                                                             | Description                                                                                                                                                                                                                           |
-| -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `createEmptyPipeline(name)`                                          | Create a minimal pipeline config                                                                                                                                                                                                      |
-| `setPipelineField(config, fields)`                                   | Update top-level pipeline fields                                                                                                                                                                                                      |
-| `upsertTrack(config, track)`                                         | Insert or replace a track by id                                                                                                                                                                                                       |
-| `removeTrack(config, trackId)`                                       | Remove a track                                                                                                                                                                                                                        |
-| `moveTrack(config, trackId, toIndex)`                                | Reorder a track                                                                                                                                                                                                                       |
-| `updateTrack(config, trackId, fields)`                               | Patch track fields (not tasks)                                                                                                                                                                                                        |
-| `upsertTask(config, trackId, task)`                                  | Insert or replace a task                                                                                                                                                                                                              |
-| `removeTask(config, trackId, taskId, cleanRefs?)`                    | Remove a task; pass `cleanRefs: true` to also strip dangling `depends_on` / `continue_from` references. Only refs that resolve to the deleted task are removed — same-named tasks in other tracks are unaffected                      |
-| `moveTask(config, trackId, taskId, toIndex)`                         | Reorder a task within its track                                                                                                                                                                                                       |
-| `transferTask(config, fromTrackId, taskId, toTrackId, qualifyRefs?)` | Move a task across tracks. When `qualifyRefs` is `true` (default), bare `depends_on` / `continue_from` references to the moved task are converted to fully-qualified form (`toTrackId.taskId`) so same-track resolution stays correct |
-
-### `parseYaml(content: string): RawPipelineConfig`
-
-Parses a YAML string and returns the raw (unresolved) pipeline config. Use this when you need to edit and re-save YAML without losing relative paths or user-authored formatting — pass the result to `serializePipeline()` rather than going through `loadPipeline()`.
-
-### `deresolvePipeline(config: PipelineConfig, workDir: string): RawPipelineConfig`
-
-Converts a resolved `PipelineConfig` back to a `RawPipelineConfig` suitable for serialization. Strips injected defaults and converts absolute `cwd` paths back to relative so the output YAML is portable across machines.
-
-Use this when you have a programmatically modified resolved config and need to save it back to YAML:
-
-```ts
-// Correct: load → modify resolved config → deresolve → save
-const config = await loadPipeline(yaml, workDir);
-const modified = { ...config, name: 'renamed' };
-const savedYaml = serializePipeline(deresolvePipeline(modified, workDir));
-
-// Also correct: work entirely in raw space (preferred for visual editors)
-const raw = parseYaml(yaml);
-const updatedRaw = setPipelineField(raw, { name: 'renamed' });
-const savedYaml = serializePipeline(updatedRaw);
-```
-
-### `validateConfig(config: PipelineConfig): string[]`
-
-Validates a resolved pipeline config without executing it. Checks DAG structure (cycles, missing dependencies). Returns an array of error message strings — empty means valid.
-
-Use `validateRaw` for editing raw configs in a UI; use `validateConfig` after `resolveConfig` for a final pre-run check.
-
-### `validateRaw(config: RawPipelineConfig): ValidationError[]`
-
-Validates a raw pipeline config without resolving inheritance or executing anything. Returns a flat list of `{ path, message }` objects — empty array means valid.
-
-Checks: required fields, `prompt`/`command` exclusivity, duplicate task IDs within a track, `depends_on`/`continue_from` reference integrity (including ambiguous bare refs that exist in multiple tracks — use `trackId.taskId` to disambiguate), circular dependency detection.
-
-Does **not** check plugin registration (plugins may not be loaded at edit time).
-
-```ts
-const errors = validateRaw(draftConfig);
-if (errors.length > 0) {
-  errors.forEach((e) => highlightNode(e.path, e.message));
-}
-```
-
-### `buildRawDag(config: RawPipelineConfig): RawDag`
-
-Extracts the topology of a raw (unresolved) pipeline config as a graph — no `workDir` or plugin registration required. Intended for the visual editor to render the flow graph during editing.
-
-Returns `{ nodes: ReadonlyMap<taskId, RawDagNode>, edges: { from, to }[] }` where each edge represents a dependency (from must complete before to). Unresolvable refs are silently skipped.
-
-```ts
-const { nodes, edges } = buildRawDag(draftConfig);
-// nodes — keyed by "trackId.taskId"
-// edges — [{ from: "track.taskA", to: "track.taskB" }, ...]
-```
-
-Use `buildDag` instead when you have a fully resolved `PipelineConfig` and need topological sort order.
-
-### `Logger`
-
-Dual-channel logger — console + file. Creates a per-run log file at `<workDir>/.tagma/logs/<runId>/pipeline.log`.
-
-```ts
-const logger = new Logger(workDir, runId);
-logger.info('[track]', 'message'); // console + file
-logger.warn('[track]', 'message'); // console + file
-logger.error('[track]', 'message'); // console + file
-logger.debug('[track]', 'message'); // file only
-logger.section('Title'); // file only — visual separator
-logger.quiet(bulkText); // file only — bulk payload
-logger.path; // log file path
-logger.dir; // run artifact directory
-logger.close(); // close the persistent file handle (called automatically by runPipeline at run completion)
-```
-
-Pass an optional third argument to stream every appended line out as a
-structured `LogRecord` — `runPipeline` uses this to emit `task_log` events:
-
-```ts
-import { Logger, type LogRecord } from '@tagma/sdk';
-
-const logger = new Logger(workDir, runId, (record: LogRecord) => {
-  // record = { level, taskId, timestamp, text }
-  // level  = 'info' | 'warn' | 'error' | 'debug' | 'section' | 'quiet'
-  // taskId is extracted from a '[task:<id>]' prefix, or null for untagged lines
-  forwardToUI(record);
-});
-```
-
-`section` and `quiet` carry no prefix, so pass an explicit `taskId` when the
-line logically belongs to a task — the extractor cannot infer one otherwise:
-
-```ts
-logger.section(`Task ${taskId}`, taskId);
-logger.quiet(`--- stdout (${taskId}) ---\n${body}\n--- end stdout ---`, taskId);
-```
-
-### `tailLines(text: string, n: number): string`
-
-Returns the last `n` non-empty lines of `text`, joined with newlines.
-
-### `clip(text: string, maxBytes?: number): string`
-
-Truncates `text` to at most `maxBytes` UTF-8 bytes (default 16 KB), appending a `…[truncated N bytes]` marker when truncation occurs. Multi-byte characters (CJK, emoji) are counted correctly.
-
-### Utilities
-
-| Function                              | Description                                               |
-| ------------------------------------- | --------------------------------------------------------- |
-| `parseDuration(input)`                | Parses `"30s"`, `"5m"`, `"2h"` → milliseconds             |
-| `validatePath(filePath, projectRoot)` | Resolves path, throws if it escapes project root          |
-| `generateRunId()`                     | Generates a unique run ID (`run_<ts>_<seq>_<rand>`)       |
-| `nowISO()`                            | Returns `new Date().toISOString()`                        |
-| `truncateForName(text, maxLen?)`      | Truncates first line to `maxLen` (default 40) for display |
-
-## Related Packages
-
-| Package                                                                        | Description                |
-| ------------------------------------------------------------------------------ | -------------------------- |
-| [@tagma/types](https://www.npmjs.com/package/@tagma/types)                     | Shared TypeScript types    |
-| [@tagma/driver-codex](https://www.npmjs.com/package/@tagma/driver-codex)       | Codex CLI driver plugin    |
-| [@tagma/driver-opencode](https://www.npmjs.com/package/@tagma/driver-opencode) | OpenCode CLI driver plugin |
-
-## License
-
-MIT
+# @tagma/sdk
+
+> ## ⚠️ Bun-only runtime
+>
+> ```bash
+> bun add @tagma/sdk
+> ```
+>
+> This package is published as pre-built JavaScript (`dist/`), but the runtime
+> uses Bun-only APIs (`Bun.spawn`, `Bun.file`, `Bun.serve`). It will install
+> under `npm` / `yarn` / `pnpm` without error, but **crash at runtime on Node**
+> the first time a pipeline spawns a task. Get Bun at <https://bun.sh>.
+>
+> _(The `npm i @tagma/sdk` line in the npmjs.com sidebar is auto-generated by
+> the npm registry website and cannot be removed — please ignore it and use
+> the command above.)_
+
+A local AI task orchestration SDK for [Bun](https://bun.sh). Define multi-track pipelines in YAML, run AI coding agents (Claude Code, Codex, OpenCode) and shell commands in parallel with dependency resolution, approval gates, and lifecycle hooks.
+
+## Install
+
+**Requires Bun ≥ 1.3.** Node/npm are not supported.
+
+```bash
+bun add @tagma/sdk
+```
+
+## Quick Start
+
+**1. Define a pipeline** (`pipeline.yaml`)
+
+```yaml
+pipeline:
+  name: build-and-test
+  tracks:
+    - id: backend
+      name: Backend
+      driver: claude-code
+      permissions: { read: true, write: true, execute: false }
+      tasks:
+        - id: implement
+          name: Implement feature
+          prompt: 'Add a /health endpoint to src/server.ts'
+        - id: test
+          name: Run tests
+          command: 'bun test'
+          depends_on: [implement]
+```
+
+**2. Run it programmatically**
+
+```ts
+import { bootstrapBuiltins, loadPipeline, runPipeline, InMemoryApprovalGateway } from '@tagma/sdk';
+
+// Register built-in drivers, triggers, completions
+bootstrapBuiltins();
+
+const yaml = await Bun.file('pipeline.yaml').text();
+const config = await loadPipeline(yaml, process.cwd());
+
+const result = await runPipeline(config, process.cwd());
+console.log(result.success ? 'Done' : 'Failed');
+```
+
+## Features
+
+- **Multi-track DAG execution** -- tasks run in parallel across tracks, respecting `depends_on` ordering
+- **Driver plugins** -- built-in `claude-code` driver; install `@tagma/driver-codex` or `@tagma/driver-opencode` for other agents
+- **Session handoff** -- `continue_from` passes context between tasks (session resume or text injection)
+- **Approval gates** -- trigger-based approval with stdin and WebSocket adapters
+- **Lifecycle hooks** -- `pipeline_start`, `task_start`, `task_success`, `task_failure`, `pipeline_complete`, `pipeline_error`
+- **Middleware** -- enrich prompts before execution (e.g. inject static context)
+- **Completion checks** -- validate task output with `exit_code`, `file_exists`, or `output_check` plugins
+- **Plugin schemas** -- triggers/completions/middlewares can declare a `PluginSchema` so visual editors render typed forms for their config
+
+## Pipeline YAML Reference
+
+### Full Structure
+
+```yaml
+pipeline:
+  name: my-pipeline
+  driver: claude-code
+  timeout: 30m
+  plugins:
+    - '@tagma/driver-codex'
+  hooks:
+    pipeline_start: 'echo starting'
+    task_start: 'echo task begin'
+    task_success: 'echo task ok'
+    task_failure: 'notify-slack.sh'
+    pipeline_complete: 'echo done'
+    pipeline_error: 'alert.sh'
+  tracks:
+    - id: track-1
+      name: Track One
+      color: '#3b82f6'
+      driver: claude-code
+      model: claude-sonnet-4-6
+      agent_profile: senior
+      cwd: ./services/backend
+      permissions:
+        read: true
+        write: true
+        execute: false
+      on_failure: skip_downstream
+      middlewares:
+        - type: static_context
+          file: ./context.md
+          label: Architecture Guide
+      tasks:
+        - id: task-a
+          name: Do something
+          prompt: 'Your prompt here'
+          timeout: 10m
+          driver: claude-code
+          model: claude-sonnet-4-6
+          agent_profile: senior
+          cwd: ./src
+          permissions:
+            read: true
+            write: true
+            execute: false
+          middlewares:
+            - type: static_context
+              file: ./ref.md
+          trigger:
+            type: manual
+            message: 'Approve before running'
+            timeout: 5m
+          completion:
+            type: exit_code
+            expect: 0
+        - id: task-b
+          name: Follow up
+          prompt: 'Continue the work'
+          continue_from: task-a
+          depends_on: [task-a]
+```
+
+### Pipeline Fields
+
+| Field     | Type            | Required | Description                                                                                |
+| --------- | --------------- | -------- | ------------------------------------------------------------------------------------------ |
+| `name`    | `string`        | Yes      | Pipeline name, used in logs and run IDs                                                    |
+| `driver`  | `string`        | No       | Default driver for all tracks/tasks (inherited). Built-in: `claude-code`                   |
+| `model`   | `string`        | No       | Default model for all tracks/tasks (inherited). Exact model name, e.g. `claude-sonnet-4-6` |
+| `timeout` | `string`        | No       | Pipeline-level timeout. Format: `"30s"`, `"5m"`, `"2h"`                                    |
+| `plugins` | `string[]`      | No       | External plugin packages to load, e.g. `["@tagma/driver-codex"]`                           |
+| `hooks`   | `HooksConfig`   | No       | Shell commands to run at lifecycle events (see Hooks below)                                |
+| `tracks`  | `TrackConfig[]` | Yes      | List of parallel execution tracks                                                          |
+
+### Hooks Fields
+
+Each hook value can be a single command string or an array of commands.
+
+| Field               | Type                 | Description                                  |
+| ------------------- | -------------------- | -------------------------------------------- |
+| `pipeline_start`    | `string \| string[]` | Runs when the pipeline begins                |
+| `task_start`        | `string \| string[]` | Runs before each task starts                 |
+| `task_success`      | `string \| string[]` | Runs after a task succeeds                   |
+| `task_failure`      | `string \| string[]` | Runs after a task fails                      |
+| `pipeline_complete` | `string \| string[]` | Runs when the pipeline finishes successfully |
+| `pipeline_error`    | `string \| string[]` | Runs when the pipeline finishes with errors  |
+
+### Track Fields
+
+| Field           | Type                 | Required | Default                 | Description                                                          |
+| --------------- | -------------------- | -------- | ----------------------- | -------------------------------------------------------------------- |
+| `id`            | `string`             | Yes      | —                       | Unique track identifier                                              |
+| `name`          | `string`             | Yes      | —                       | Display name                                                         |
+| `color`         | `string`             | No       | —                       | Color hint for UI rendering (e.g. `"#3b82f6"`)                       |
+| `driver`        | `string`             | No       | Inherited from pipeline | Driver for all tasks in this track                                   |
+| `model`         | `string`             | No       | Inherited from pipeline | Exact model name passed to the driver CLI (e.g. `claude-sonnet-4-6`) |
+| `agent_profile` | `string`             | No       | —                       | Named agent configuration profile                                    |
+| `cwd`           | `string`             | No       | Pipeline workDir        | Working directory for tasks in this track (relative path)            |
+| `permissions`   | `Permissions`        | No       | Inherited from pipeline | Default permissions for tasks (see Permissions)                      |
+| `on_failure`    | `OnFailure`          | No       | `skip_downstream`       | Failure strategy: `skip_downstream`, `stop_all`, `ignore`            |
+| `middlewares`   | `MiddlewareConfig[]` | No       | —                       | Middlewares applied to all tasks (task-level overrides track-level)  |
+| `tasks`         | `TaskConfig[]`       | Yes      | —                       | Ordered list of tasks in this track                                  |
+
+### Task Fields
+
+| Field           | Type                 | Required | Default              | Description                                                                                            |
+| --------------- | -------------------- | -------- | -------------------- | ------------------------------------------------------------------------------------------------------ |
+| `id`            | `string`             | Yes      | —                    | Unique task identifier (unique within the pipeline)                                                    |
+| `name`          | `string`             | No       | —                    | Display name                                                                                           |
+| `prompt`        | `string`             | No\*     | —                    | AI prompt to send to the driver. \*Mutually exclusive with `command`                                   |
+| `command`       | `string`             | No\*     | —                    | Shell command to execute directly. \*Mutually exclusive with `prompt`                                  |
+| `depends_on`    | `string[]`           | No       | —                    | Task IDs that must complete before this task runs. Cross-track refs use `trackId.taskId`               |
+| `continue_from` | `string`             | No       | —                    | Task ID whose output/session to continue from (session handoff). Cross-track refs use `trackId.taskId` |
+| `driver`        | `string`             | No       | Inherited from track | Driver override for this task                                                                          |
+| `model`         | `string`             | No       | Inherited from track | Model name override for this task                                                                      |
+| `agent_profile` | `string`             | No       | Inherited from track | Agent profile override                                                                                 |
+| `cwd`           | `string`             | No       | Inherited from track | Working directory override (relative path)                                                             |
+| `timeout`       | `string`             | No       | —                    | Task-level timeout. Format: `"30s"`, `"5m"`, `"2h"`                                                    |
+| `permissions`   | `Permissions`        | No       | Inherited from track | Permission override (see Permissions)                                                                  |
+| `middlewares`   | `MiddlewareConfig[]` | No       | Inherited from track | Middleware override. Set `[]` to disable inherited middlewares                                         |
+| `trigger`       | `TriggerConfig`      | No       | —                    | Gate that must resolve before the task runs (see Triggers)                                             |
+| `completion`    | `CompletionConfig`   | No       | —                    | Post-execution check to validate task output (see Completions)                                         |
+
+### Permissions
+
+| Field     | Type      | Default | Description                         |
+| --------- | --------- | ------- | ----------------------------------- |
+| `read`    | `boolean` | —       | Allow the agent to read files       |
+| `write`   | `boolean` | —       | Allow the agent to write files      |
+| `execute` | `boolean` | —       | Allow the agent to execute commands |
+
+### Inheritance
+
+Fields are inherited top-down: **pipeline → track → task**. A value set at a lower level overrides the inherited value.
+
+Inherited fields: `driver`, `model`, `permissions`, `cwd`, `middlewares`.
+
+Track-level `middlewares` apply to all tasks in the track. Setting task-level `middlewares` **replaces** (not appends) the track-level list. Use `middlewares: []` to disable all inherited middlewares for a task.
+
+---
+
+### Built-in Triggers
+
+#### `manual` — Human approval gate
+
+| Field      | Type       | Required | Default                                                | Description                                       |
+| ---------- | ---------- | -------- | ------------------------------------------------------ | ------------------------------------------------- |
+| `type`     | `"manual"` | Yes      | —                                                      | Trigger type                                      |
+| `message`  | `string`   | No       | `"Manual confirmation required for task \"{taskId}\""` | Message shown to the approver                     |
+| `timeout`  | `string`   | No       | —                                                      | How long to wait for a decision before timing out |
+| `metadata` | `object`   | No       | —                                                      | Arbitrary metadata passed to the approval gateway |
+
+#### `file` — File watcher gate
+
+| Field     | Type     | Required | Default | Description                                    |
+| --------- | -------- | -------- | ------- | ---------------------------------------------- |
+| `type`    | `"file"` | Yes      | —       | Trigger type                                   |
+| `path`    | `string` | Yes      | —       | File path to watch (relative to workDir)       |
+| `timeout` | `string` | No       | —       | How long to wait for the file to appear/change |
+
+---
+
+### Built-in Completions
+
+#### `exit_code` — Exit code check
+
+| Field    | Type                 | Required | Default | Description                                                        |
+| -------- | -------------------- | -------- | ------- | ------------------------------------------------------------------ |
+| `type`   | `"exit_code"`        | Yes      | —       | Completion type                                                    |
+| `expect` | `number \| number[]` | No       | `0`     | Expected exit code(s). Pass an array for multiple acceptable codes |
+
+#### `file_exists` — File existence check
+
+| Field      | Type                       | Required | Default | Description                                           |
+| ---------- | -------------------------- | -------- | ------- | ----------------------------------------------------- |
+| `type`     | `"file_exists"`            | Yes      | —       | Completion type                                       |
+| `path`     | `string`                   | Yes      | —       | File or directory path to check (relative to workDir) |
+| `kind`     | `"file" \| "dir" \| "any"` | No       | `"any"` | Entity type constraint                                |
+| `min_size` | `number`                   | No       | —       | Minimum file size in bytes (files only)               |
+
+#### `output_check` — Command-based output validation
+
+| Field     | Type             | Required | Default | Description                                                             |
+| --------- | ---------------- | -------- | ------- | ----------------------------------------------------------------------- |
+| `type`    | `"output_check"` | Yes      | —       | Completion type                                                         |
+| `check`   | `string`         | Yes      | —       | Shell command to run. Task stdout is piped to its stdin; exits 0 = pass |
+| `timeout` | `string`         | No       | `"30s"` | Max time to wait for the check command                                  |
+
+---
+
+### Built-in Middlewares
+
+#### `static_context` — Prepend file content to prompt
+
+| Field   | Type               | Required | Default                   | Description                                    |
+| ------- | ------------------ | -------- | ------------------------- | ---------------------------------------------- |
+| `type`  | `"static_context"` | Yes      | —                         | Middleware type                                |
+| `file`  | `string`           | Yes      | —                         | Path to the context file (relative to workDir) |
+| `label` | `string`           | No       | `"Reference: {filename}"` | Label for the injected context section         |
+
+## API
+
+### `bootstrapBuiltins()`
+
+Registers all built-in plugins (claude-code driver, file/manual triggers, completion checks, static-context middleware).
+
+### `loadPipeline(yaml: string, workDir: string): Promise<PipelineConfig>`
+
+Parses YAML, resolves inheritance, and validates the configuration.
+
+### `runPipeline(config, workDir, options?): Promise<EngineResult>`
+
+Executes the pipeline. Returns `{ success, runId, logPath, summary, states }`.
+
+Options:
+
+- `approvalGateway` -- custom `ApprovalGateway` instance (defaults to `InMemoryApprovalGateway`)
+- `signal` -- `AbortSignal` to cancel the run externally
+- `onEvent` -- callback for real-time `PipelineEvent` updates:
+  - `pipeline_start` — pipeline began; includes `states: ReadonlyMap<taskId, TaskState>` (initial snapshot of all tasks at `waiting`)
+  - `task_status_change` — a task changed status; includes `state: TaskState` (complete snapshot at the time of change: `startedAt` is populated before the `running` event; `result` and `finishedAt` are populated before any terminal-status event)
+  - `task_log` — a structured log line was written to `pipeline.log`. Mirrors every `Logger` call (info/warn/error/debug/section/quiet) and carries `{ taskId: string | null, level, timestamp, text }`. `taskId` is non-null for lines tagged with a `[task:<id>]` prefix (or passed explicitly to `section`/`quiet`) and `null` for pipeline-wide messages such as the configuration dump and DAG topology. Use this to stream the full run process into UIs without tailing the log file.
+  - `pipeline_end` — pipeline finished; includes `success: boolean`
+- `runId` -- caller-supplied run ID. When provided the engine uses this instead of generating its own, keeping the caller and the SDK log directories aligned on the same ID
+- `maxLogRuns` -- number of per-run log directories to keep under `<workDir>/.tagma/logs/` (default: 20)
+
+### `PipelineRunner`
+
+Higher-level wrapper for managing multiple concurrent pipeline runs — designed for sidecar / Tauri IPC scenarios where the frontend controls pipeline lifecycle by ID.
+
+```ts
+const runner = new PipelineRunner(config, workDir);
+
+// Subscribe before start — handler is called for every PipelineEvent
+const unsubscribe = runner.subscribe((event) => {
+  tauriEmit('pipeline_event', { id: runner.instanceId, event });
+});
+
+runner.start(); // returns Promise<EngineResult>, idempotent
+
+// Cancel from IPC
+runner.abort();
+
+// Available from the first pipeline_start event onward (not just after completion)
+// Returns null only if the pipeline has never started
+const states = runner.getStates(); // ReadonlyMap<taskId, TaskState> | null
+```
+
+Properties:
+
+- `instanceId` — stable ID assigned at construction, safe to use as a Map key before `start()`
+- `runId` — engine-assigned run ID, available after the first `pipeline_start` event (`null` until then)
+- `status` — `'idle' | 'running' | 'done' | 'aborted'`
+
+### `TriggerBlockedError` / `TriggerTimeoutError`
+
+Typed error classes for trigger plugin error classification. The engine uses `instanceof` checks on these to set the correct task status (`blocked` or `timeout`) instead of matching on error message substrings.
+
+Built-in triggers (`manual`, `file`) throw these automatically. Third-party trigger plugins should throw `TriggerBlockedError` for user/policy rejections and `TriggerTimeoutError` for genuine wait timeouts. Plugins that throw plain `Error` still work — the engine falls back to string matching for backward compatibility, but typed errors are preferred to avoid misclassification from coincidental substrings.
+
+```ts
+import { TriggerBlockedError, TriggerTimeoutError } from '@tagma/sdk';
+
+// In a custom trigger plugin:
+throw new TriggerBlockedError('Access denied by policy');
+throw new TriggerTimeoutError('File did not appear within 30s');
+```
+
+### `loadPlugins(names: string[]): Promise<void>`
+
+Dynamically loads and registers external plugin packages.
+
+### `registerPlugin(category, type, handler): void`
+
+Registers a plugin handler manually. Idempotent — duplicate registrations are silently ignored.
+
+Plugin handlers (`TriggerPlugin`, `CompletionPlugin`, `MiddlewarePlugin`) may optionally expose a declarative `schema: PluginSchema` field so visual editors can render a typed form for the plugin's config instead of a raw key/value editor:
+
+```ts
+import type { TriggerPlugin } from '@tagma/types';
+
+export const HttpTrigger: TriggerPlugin = {
+  name: 'http',
+  schema: {
+    description: 'Wait for an HTTP endpoint to return 2xx before the task runs.',
+    fields: {
+      url: { type: 'string', required: true, placeholder: 'https://...' },
+      method: { type: 'enum', enum: ['GET', 'POST'], default: 'GET' },
+      timeout: { type: 'duration', description: 'Give up after this long.' },
+    },
+  },
+  async watch(config, ctx) {
+    /* ... */
+  },
+};
+```
+
+The schema is purely descriptive — plugins still perform their own runtime validation. Supported field types: `string`, `number`, `boolean`, `enum`, `path`, `duration`, `number-or-list`. Each field can declare `required`, `default`, `description`, `enum`, `min`/`max`, `placeholder`. Built-in plugins (`file`/`manual` triggers; `exit_code`/`file_exists`/`output_check` completions; `static_context` middleware) all ship with schemas so editors can generate forms out of the box.
+
+### `getHandler(category, type): PluginType`
+
+Retrieves a registered plugin handler. Throws if the plugin is not registered.
+
+### `hasHandler(category, type): boolean`
+
+Returns `true` if a handler is registered for the given category and type.
+
+### `listRegistered(category): string[]`
+
+Lists all registered handler type names for a plugin category (`'drivers'`, `'triggers'`, `'completions'`, `'middlewares'`).
+
+### `resolveConfig(raw: RawPipelineConfig, workDir: string): PipelineConfig`
+
+Resolves a raw pipeline config into a fully resolved `PipelineConfig` — applies inheritance (pipeline → track → task) for driver, model, permissions, and cwd. Validates and resolves all file paths against `workDir`.
+
+Use `loadPipeline` for the common parse-and-resolve flow. Use `resolveConfig` directly when you need to manipulate the raw config between parsing and resolution.
+
+### `attachStdinApprovalAdapter(gateway): StdinApprovalAdapter`
+
+Attaches an interactive stdin-based approval handler.
+
+### `attachWebSocketApprovalAdapter(gateway, options?): WebSocketApprovalAdapter`
+
+Starts a WebSocket server for remote approval decisions.
+
+### Config CRUD (`config-ops`)
+
+Pure, immutable helper functions for building and editing `RawPipelineConfig` in a visual editor. No runtime dependencies — safe to use in renderer processes.
+
+```ts
+import {
+  createEmptyPipeline,
+  setPipelineField,
+  upsertTrack,
+  removeTrack,
+  moveTrack,
+  updateTrack,
+  upsertTask,
+  removeTask,
+  moveTask,
+  transferTask,
+  serializePipeline,
+} from '@tagma/sdk';
+
+// Build a config programmatically
+let config = createEmptyPipeline('my-pipeline');
+config = upsertTrack(config, { id: 'backend', name: 'Backend', tasks: [] });
+config = upsertTask(config, 'backend', { id: 'implement', prompt: 'Add /health endpoint' });
+
+// Sync back to YAML
+const yaml = serializePipeline(config);
+```
+
+| Function                                                             | Description                                                                                                                                                                                                                           |
+| -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `createEmptyPipeline(name)`                                          | Create a minimal pipeline config                                                                                                                                                                                                      |
+| `setPipelineField(config, fields)`                                   | Update top-level pipeline fields                                                                                                                                                                                                      |
+| `upsertTrack(config, track)`                                         | Insert or replace a track by id                                                                                                                                                                                                       |
+| `removeTrack(config, trackId)`                                       | Remove a track                                                                                                                                                                                                                        |
+| `moveTrack(config, trackId, toIndex)`                                | Reorder a track                                                                                                                                                                                                                       |
+| `updateTrack(config, trackId, fields)`                               | Patch track fields (not tasks)                                                                                                                                                                                                        |
+| `upsertTask(config, trackId, task)`                                  | Insert or replace a task                                                                                                                                                                                                              |
+| `removeTask(config, trackId, taskId, cleanRefs?)`                    | Remove a task; pass `cleanRefs: true` to also strip dangling `depends_on` / `continue_from` references. Only refs that resolve to the deleted task are removed — same-named tasks in other tracks are unaffected                      |
+| `moveTask(config, trackId, taskId, toIndex)`                         | Reorder a task within its track                                                                                                                                                                                                       |
+| `transferTask(config, fromTrackId, taskId, toTrackId, qualifyRefs?)` | Move a task across tracks. When `qualifyRefs` is `true` (default), bare `depends_on` / `continue_from` references to the moved task are converted to fully-qualified form (`toTrackId.taskId`) so same-track resolution stays correct |
+
+### `parseYaml(content: string): RawPipelineConfig`
+
+Parses a YAML string and returns the raw (unresolved) pipeline config. Use this when you need to edit and re-save YAML without losing relative paths or user-authored formatting — pass the result to `serializePipeline()` rather than going through `loadPipeline()`.
+
+### `deresolvePipeline(config: PipelineConfig, workDir: string): RawPipelineConfig`
+
+Converts a resolved `PipelineConfig` back to a `RawPipelineConfig` suitable for serialization. Strips injected defaults and converts absolute `cwd` paths back to relative so the output YAML is portable across machines.
+
+Use this when you have a programmatically modified resolved config and need to save it back to YAML:
+
+```ts
+// Correct: load → modify resolved config → deresolve → save
+const config = await loadPipeline(yaml, workDir);
+const modified = { ...config, name: 'renamed' };
+const savedYaml = serializePipeline(deresolvePipeline(modified, workDir));
+
+// Also correct: work entirely in raw space (preferred for visual editors)
+const raw = parseYaml(yaml);
+const updatedRaw = setPipelineField(raw, { name: 'renamed' });
+const savedYaml = serializePipeline(updatedRaw);
+```
+
+### `validateConfig(config: PipelineConfig): string[]`
+
+Validates a resolved pipeline config without executing it. Checks DAG structure (cycles, missing dependencies). Returns an array of error message strings — empty means valid.
+
+Use `validateRaw` for editing raw configs in a UI; use `validateConfig` after `resolveConfig` for a final pre-run check.
+
+### `validateRaw(config: RawPipelineConfig): ValidationError[]`
+
+Validates a raw pipeline config without resolving inheritance or executing anything. Returns a flat list of `{ path, message }` objects — empty array means valid.
+
+Checks: required fields, `prompt`/`command` exclusivity, duplicate task IDs within a track, `depends_on`/`continue_from` reference integrity (including ambiguous bare refs that exist in multiple tracks — use `trackId.taskId` to disambiguate), circular dependency detection.
+
+Does **not** check plugin registration (plugins may not be loaded at edit time).
+
+```ts
+const errors = validateRaw(draftConfig);
+if (errors.length > 0) {
+  errors.forEach((e) => highlightNode(e.path, e.message));
+}
+```
+
+### `buildRawDag(config: RawPipelineConfig): RawDag`
+
+Extracts the topology of a raw (unresolved) pipeline config as a graph — no `workDir` or plugin registration required. Intended for the visual editor to render the flow graph during editing.
+
+Returns `{ nodes: ReadonlyMap<taskId, RawDagNode>, edges: { from, to }[] }` where each edge represents a dependency (from must complete before to). Unresolvable refs are silently skipped.
+
+```ts
+const { nodes, edges } = buildRawDag(draftConfig);
+// nodes — keyed by "trackId.taskId"
+// edges — [{ from: "track.taskA", to: "track.taskB" }, ...]
+```
+
+Use `buildDag` instead when you have a fully resolved `PipelineConfig` and need topological sort order.
+
+### `Logger`
+
+Dual-channel logger — console + file. Creates a per-run log file at `<workDir>/.tagma/logs/<runId>/pipeline.log`.
+
+```ts
+const logger = new Logger(workDir, runId);
+logger.info('[track]', 'message'); // console + file
+logger.warn('[track]', 'message'); // console + file
+logger.error('[track]', 'message'); // console + file
+logger.debug('[track]', 'message'); // file only
+logger.section('Title'); // file only — visual separator
+logger.quiet(bulkText); // file only — bulk payload
+logger.path; // log file path
+logger.dir; // run artifact directory
+logger.close(); // close the persistent file handle (called automatically by runPipeline at run completion)
+```
+
+Pass an optional third argument to stream every appended line out as a
+structured `LogRecord` — `runPipeline` uses this to emit `task_log` events:
+
+```ts
+import { Logger, type LogRecord } from '@tagma/sdk';
+
+const logger = new Logger(workDir, runId, (record: LogRecord) => {
+  // record = { level, taskId, timestamp, text }
+  // level  = 'info' | 'warn' | 'error' | 'debug' | 'section' | 'quiet'
+  // taskId is extracted from a '[task:<id>]' prefix, or null for untagged lines
+  forwardToUI(record);
+});
+```
+
+`section` and `quiet` carry no prefix, so pass an explicit `taskId` when the
+line logically belongs to a task — the extractor cannot infer one otherwise:
+
+```ts
+logger.section(`Task ${taskId}`, taskId);
+logger.quiet(`--- stdout (${taskId}) ---\n${body}\n--- end stdout ---`, taskId);
+```
+
+### `tailLines(text: string, n: number): string`
+
+Returns the last `n` non-empty lines of `text`, joined with newlines.
+
+### `clip(text: string, maxBytes?: number): string`
+
+Truncates `text` to at most `maxBytes` UTF-8 bytes (default 16 KB), appending a `…[truncated N bytes]` marker when truncation occurs. Multi-byte characters (CJK, emoji) are counted correctly.
+
+### Utilities
+
+| Function                              | Description                                               |
+| ------------------------------------- | --------------------------------------------------------- |
+| `parseDuration(input)`                | Parses `"30s"`, `"5m"`, `"2h"` → milliseconds             |
+| `validatePath(filePath, projectRoot)` | Resolves path, throws if it escapes project root          |
+| `generateRunId()`                     | Generates a unique run ID (`run_<ts>_<seq>_<rand>`)       |
+| `nowISO()`                            | Returns `new Date().toISOString()`                        |
+| `truncateForName(text, maxLen?)`      | Truncates first line to `maxLen` (default 40) for display |
+
+## Related Packages
+
+| Package                                                                        | Description                |
+| ------------------------------------------------------------------------------ | -------------------------- |
+| [@tagma/types](https://www.npmjs.com/package/@tagma/types)                     | Shared TypeScript types    |
+| [@tagma/driver-codex](https://www.npmjs.com/package/@tagma/driver-codex)       | Codex CLI driver plugin    |
+| [@tagma/driver-opencode](https://www.npmjs.com/package/@tagma/driver-opencode) | OpenCode CLI driver plugin |
+
+## License
+
+MIT