@tagma/sdk 0.2.1 → 0.2.3

package/README.md

@@ -64,38 +64,217 @@ console.log(result.success ? 'Done' : 'Failed');
 
 ## Pipeline YAML Reference
 
+### Full Structure
+
 ```yaml
 pipeline:
   name: my-pipeline
-  driver: claude-code          # default driver for all tasks
-  timeout: 30m                 # pipeline-level timeout
-  plugins:                     # load external driver plugins
+  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
-      model_tier: high          # high | medium | low
+      color: "#3b82f6"
+      driver: claude-code
+      model_tier: high
+      agent_profile: senior
+      cwd: ./services/backend
       permissions:
         read: true
         write: true
         execute: false
-      on_failure: skip_downstream  # skip_downstream | stop_all | ignore
+      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"
           output: ./output/task-a.txt
           timeout: 10m
+          driver: claude-code
+          model_tier: high
+          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"
+            options: [approve, reject]
+            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]
+        - id: task-c
+          name: Templated task
+          use: "@tagma/template-lint"
+          with:
+            src: ./src
 ```
 
+### 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` |
+| `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_tier` | `string` | No | Inherited from pipeline | AI model tier: `high`, `medium`, `low` |
+| `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` |
+| `output` | `string` | No | — | File path to write task stdout to (relative to workDir) |
+| `driver` | `string` | No | Inherited from track | Driver override for this task |
+| `model_tier` | `string` | No | Inherited from track | Model tier 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) |
+| `use` | `string` | No | — | Template package to expand (e.g. `"@tagma/template-lint"`). Mutually exclusive with `prompt`/`command` |
+| `with` | `Record<string, unknown>` | No | — | Parameters passed to the template referenced by `use` |
+
+### 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_tier`, `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 |
+| `options` | `string[]` | No | — | Choice options (e.g. `[approve, reject]`) |
+| `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()`
@@ -150,6 +329,32 @@ Properties:
 
 Dynamically loads and registers external plugin packages.
 
+### `registerPlugin(category, type, handler): void`
+
+Registers a plugin handler manually. Idempotent — duplicate registrations are silently ignored.
+
+### `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_tier, 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.
+
+### `expandTemplates(tasks, instancePrefix): Promise<RawTaskConfig[]>`
+
+Expands `use:` template references in a task list. Loads template packages (`@tagma/template-*`), resolves parameters, and namespaces task IDs and dependencies. Called internally by `loadPipeline`.
+
 ### `attachStdinApprovalAdapter(gateway): StdinApprovalAdapter`
 
 Attaches an interactive stdin-based approval handler.
@@ -249,6 +454,40 @@ const { nodes, edges } = buildRawDag(draftConfig);
 
 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
+```
+
+### `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 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tagma/sdk",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "type": "module",
   "workspaces": [
     "plugins/*"

package/src/drivers/claude-code.ts

@@ -151,24 +151,28 @@ export const ClaudeCodeDriver: DriverPlugin = {
     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', task.prompt!,
+      '-p',  // no value — prompt is piped via stdin
       '--model', model,
       '--allowedTools', tools,
       '--permission-mode', permissionMode,
       '--output-format', 'json',
-      '--verbose',
+      // 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',
     ];
 
-    const profile = task.agent_profile ?? track.agent_profile;
-    if (profile) {
-      args.push('--append-system-prompt', profile);
-    }
-
     // 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.
@@ -185,12 +189,29 @@ export const ClaudeCodeDriver: DriverPlugin = {
       }
     }
 
-    return { args, cwd: effectiveCwd, env: resolveGitBashEnv() };
+    // --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 {
-      const json = JSON.parse(stdout);
+      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;

package/src/runner.ts

@@ -6,6 +6,24 @@ import { shellArgs } from './utils';
 // Delay before escalating SIGTERM to SIGKILL when killing a timed-out process.
 const SIGKILL_DELAY_MS = 3_000;
 
+/**
+ * On Windows, proc.kill('SIGTERM') / proc.kill('SIGKILL') only terminate the
+ * direct child process. When the child is a .cmd/.bat wrapper (e.g. claude.cmd),
+ * cmd.exe spawns the real process as a grandchild — proc.kill misses it entirely.
+ * `taskkill /F /T /PID` kills the entire process tree rooted at the given PID.
+ */
+function killProcessTree(pid: number): void {
+  if (process.platform !== 'win32') return;
+  try {
+    Bun.spawnSync(['taskkill', '/F', '/T', '/PID', String(pid)], {
+      stdout: 'ignore',
+      stderr: 'ignore',
+    });
+  } catch {
+    /* best-effort — process may have already exited */
+  }
+}
+
 export interface RunOptions {
   readonly timeoutMs?: number;
   readonly signal?: AbortSignal; // pipeline-level abort
@@ -128,15 +146,22 @@ export async function runSpawn(
   const killGracefully = () => {
     if (killedByUs) return;
     killedByUs = true;
-    proc.kill('SIGTERM');
-    // If the child ignores SIGTERM, escalate to SIGKILL after 3 s.
-    forceTimer = setTimeout(() => {
-      try {
-        proc.kill('SIGKILL');
-      } catch {
-        /* already exited */
-      }
-    }, SIGKILL_DELAY_MS);
+
+    if (process.platform === 'win32') {
+      // On Windows, kill the entire process tree via taskkill. This handles
+      // .cmd wrappers and nested child processes that proc.kill() misses.
+      killProcessTree(proc.pid);
+    } else {
+      proc.kill('SIGTERM');
+      // If the child ignores SIGTERM, escalate to SIGKILL after 3 s.
+      forceTimer = setTimeout(() => {
+        try {
+          proc.kill('SIGKILL');
+        } catch {
+          /* already exited */
+        }
+      }, SIGKILL_DELAY_MS);
+    }
   };
 
   if (timeoutMs && timeoutMs > 0) {