@tagma/sdk 0.6.4 → 0.6.6

package/README.md

@@ -72,6 +72,7 @@ console.log(result.success ? 'Done' : 'Failed');
 - **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
+- **Typed task ports** -- declare named, typed `inputs` / `outputs` on a task. Inputs from upstream tasks are substituted into `command` / `prompt` via `{{inputs.<name>}}` and rendered as an `[Inputs]` context block for AI tasks; outputs are extracted from the final-line JSON object on stdout (or `normalizedOutput`) and surfaced to downstream tasks
 
 ## Pipeline YAML Reference
 
@@ -199,6 +200,7 @@ Each hook value can be a single command string or an array of commands.
 | `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)                                         |
+| `ports`         | `TaskPorts`          | No       | —                    | Typed input/output ports — see Typed Ports below                                                       |
 
 ### Permissions
 
@@ -218,6 +220,51 @@ Track-level `middlewares` apply to all tasks in the track. Setting task-level `m
 
 ---
 
+### Typed Ports
+
+Tasks can declare named, typed `inputs` / `outputs`. Inputs flow in from upstream task outputs; outputs are extracted from a task's stdout (or the AI driver's `normalizedOutput`) on success.
+
+```yaml
+- id: lookup-weather
+  name: Lookup weather
+  command: weather.sh --city "{{inputs.city}}"
+  ports:
+    inputs:
+      - { name: city, type: string, required: true, description: Target city }
+    outputs:
+      - { name: temperature, type: number, description: Current temperature in Celsius }
+      - { name: conditions, type: enum, enum: [sunny, cloudy, rain, snow] }
+
+- id: write-report
+  depends_on: [lookup-weather]
+  prompt: 'Write a brief weather report for {{inputs.city}}.'
+  ports:
+    inputs:
+      - { name: city, type: string, required: true }
+      - { name: temperature, type: number, required: true }
+      - { name: conditions, type: enum, enum: [sunny, cloudy, rain, snow] }
+```
+
+#### `PortDef` fields
+
+| Field         | Type                                                  | Required | Description                                                                                                                                                                       |
+| ------------- | ----------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `name`        | `string`                                              | Yes      | Port name; also the substitution key (`{{inputs.<name>}}`)                                                                                                                        |
+| `type`        | `'string' \| 'number' \| 'boolean' \| 'enum' \| 'json'` | Yes      | Coercion type. Mismatched values block the task with a typed-error diagnostic                                                                                                     |
+| `description` | `string`                                              | No       | Free-text description; rendered into the `[Inputs]` / `[Output Format]` blocks                                                                                                    |
+| `required`    | `boolean`                                             | No       | Inputs only. When `true`, missing upstream value (and no `default`) blocks the task                                                                                               |
+| `default`     | `unknown`                                             | No       | Inputs only. Fallback value when no upstream produces the port                                                                                                                    |
+| `enum`        | `string[]`                                            | When `type: enum` | Allowed values                                                                                                                                                                    |
+| `from`        | `string`                                              | No       | Inputs only. Explicit upstream binding — bare `portName` (match by name) or `taskId.portName` (fully qualified). Unset = match by name across all direct upstreams; ambiguous matches block |
+
+#### Substitution and AI prompt blocks
+
+- `{{inputs.<name>}}` is expanded verbatim in `command` and `prompt` strings before execution. Quote your placeholders in command lines (`--city "{{inputs.city}}"`) — the engine does not shell-escape.
+- AI tasks additionally get two prepended `PromptContextBlock`s: `[Output Format]` (instructs the model to emit a final-line JSON object matching the declared outputs) and `[Inputs]` (renders the resolved inputs as `name: value  # description`). Tasks without ports get no extra blocks.
+- Output extraction strategy: prefer `normalizedOutput` (AI tasks), fall back to stdout (command tasks). Find the last non-empty line that parses as a JSON object, then read each declared output key. Failures append a diagnostic to stderr; the port is absent from `outputs` and downstream tasks see it as missing.
+
+---
+
 ### Built-in Triggers
 
 #### `manual` — Human approval gate
@@ -306,6 +353,8 @@ Options:
 - `maxLogRuns` -- number of per-run log directories to keep under `<workDir>/.tagma/logs/` (default: 20)
 - `skipPluginLoading` -- skip the engine's built-in `loadPlugins(config.plugins)` call. Set this when the host has already pre-loaded plugins from a custom resolution path (e.g. the editor loading from the user's workspace `node_modules`) so the engine doesn't re-resolve them via Node's default cwd-based import.
 
+> **stdout / stderr persistence.** The engine streams every task's stdout and stderr to disk under `<workDir>/.tagma/logs/<runId>/<taskId>.stdout` and `.stderr`. The `TaskResult.stdout` / `stderr` strings are bounded tails (8 MB / 4 MB by default) — long outputs are truncated from the head with a marker, and consumers that need the full bytes should read `TaskResult.stdoutPath` / `stderrPath`. Use `TaskResult.stdoutBytes` / `stderrBytes` to display "32 MB (truncated)" without re-stat'ing the file.
+
 ### `PipelineRunner`
 
 Higher-level wrapper for managing multiple concurrent pipeline runs — designed for sidecar / Tauri IPC scenarios where the frontend controls pipeline lifecycle by ID.
@@ -474,11 +523,27 @@ Validates a resolved pipeline config without executing it. Checks DAG structure
 
 Use `validateRaw` for editing raw configs in a UI; use `validateConfig` after `resolveConfig` for a final pre-run check.
 
+### Typed Ports API
+
+Pure helpers backing the `task.ports` feature (see Typed Ports above). Safe to use in editors, simulators, and custom drivers — no I/O, no side effects.
+
+| Function                                                | Description                                                                                                                                                                                                                          |
+| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `substituteInputs(text, inputs)`                        | Expand `{{inputs.<name>}}` placeholders in `text`. Returns `{ text, unresolved }`. Strings pass through, numbers/booleans coerce via `String(...)`, objects/arrays via `JSON.stringify`. Caller is responsible for shell quoting     |
+| `extractInputReferences(text)`                          | Return the set of input port names referenced by `{{inputs.<name>}}` placeholders in `text`. Use at edit time to flag undeclared references                                                                                          |
+| `resolveTaskInputs(task, upstreamOutputs, dependsOn)`   | Gather the input values a task will consume from its direct upstreams. Applies `from` bindings, defaults, and type coercion. Returns `{ kind: 'ready', inputs, missingOptional }` or `{ kind: 'blocked', missingRequired, ambiguous, typeErrors, reason }` |
+| `extractTaskOutputs(ports, stdout, normalizedOutput)`   | Pull declared output values from a terminated task's output. Strategy: prefer `normalizedOutput`; find the last non-empty line that parses as a JSON object; coerce each declared key. Returns `{ outputs, diagnostic }`             |
+| `prependContext(doc, block)`                            | Same shape as `appendContext` but prepends; the engine uses this to place `[Output Format]` and `[Inputs]` blocks before middleware-added context                                                                                    |
+| `renderInputsBlock(inputsDecl, values)`                 | Build the `[Inputs]` `PromptContextBlock` rendered into AI prompts (`name: value  # description` lines). Returns `null` when no inputs to render                                                                                     |
+| `renderOutputSchemaBlock(outputsDecl)`                  | Build the `[Output Format]` `PromptContextBlock` instructing the model to emit a final-line JSON object matching the declared outputs. Returns `null` when no outputs declared                                                       |
+
+Custom drivers that wrap the prompt in their own envelope can read `DriverContext.inputs` (resolved + coerced map keyed by port name) and call `substituteInputs` themselves — the engine has already substituted into `task.prompt` upstream, so most drivers can ignore this.
+
 ### `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.
+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, port shape (name format, valid `type`, duplicate names, `enum` requires non-empty `enum` array, `required`/`from` ignored on outputs), and `{{inputs.<name>}}` references resolving to a declared input port.
 
 Does **not** check plugin registration (plugins may not be loaded at edit time).
 
@@ -562,11 +627,14 @@ Truncates `text` to at most `maxBytes` UTF-8 bytes (default 16 KB), appending a
 
 ## 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-claude-code](https://www.npmjs.com/package/@tagma/driver-claude-code) | Claude Code CLI driver plugin |
+| 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-claude-code](https://www.npmjs.com/package/@tagma/driver-claude-code)     | Claude Code CLI driver plugin                 |
+| [@tagma/middleware-lightrag](https://www.npmjs.com/package/@tagma/middleware-lightrag)   | LightRAG knowledge-graph retrieval middleware |
+| [@tagma/trigger-webhook](https://www.npmjs.com/package/@tagma/trigger-webhook)           | HTTP webhook trigger plugin                   |
+| [@tagma/completion-llm-judge](https://www.npmjs.com/package/@tagma/completion-llm-judge) | LLM-as-judge completion plugin                |
 
 ## License
 

package/dist/engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,cAAc,EAEd,SAAS,EAaT,eAAe,EAEhB,MAAM,SAAS,CAAC;AAEjB,OAAO,EAAmB,KAAK,cAAc,EAAE,MAAM,YAAY,CAAC;AAelE,OAAO,EAA2B,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AAM3E,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,QAAQ,CAAC,IAAI,EAAG,iBAAiB,CAAU;gBAC/B,OAAO,EAAE,MAAM;CAI5B;AAED,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,QAAQ,CAAC,IAAI,EAAG,iBAAiB,CAAU;gBAC/B,OAAO,EAAE,MAAM;CAI5B;AA6ED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE;QAChB,KAAK,EAAE,MAAM,CAAC;QACd,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,EAAE,MAAM,CAAC;QACf,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;IACF,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;CACjD;AAWD,YAAY,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAuC/C,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,eAAe,CAAC,EAAE,eAAe,CAAC;IAC3C;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,CAAC;IACpD;;;;;OAKG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,OAAO,CAAC;IACrC;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,cAAc,CAAC;CACpC;AAWD,wBAAsB,WAAW,CAC/B,MAAM,EAAE,cAAc,EACtB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,YAAY,CAAC,CAo5BvB"}
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,cAAc,EAEd,SAAS,EAaT,eAAe,EAEhB,MAAM,SAAS,CAAC;AAEjB,OAAO,EAAmB,KAAK,cAAc,EAAE,MAAM,YAAY,CAAC;AAsBlE,OAAO,EAA2B,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AAM3E,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,QAAQ,CAAC,IAAI,EAAG,iBAAiB,CAAU;gBAC/B,OAAO,EAAE,MAAM;CAI5B;AAED,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,QAAQ,CAAC,IAAI,EAAG,iBAAiB,CAAU;gBAC/B,OAAO,EAAE,MAAM;CAI5B;AA6ED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE;QAChB,KAAK,EAAE,MAAM,CAAC;QACd,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,EAAE,MAAM,CAAC;QACf,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;IACF,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;CACjD;AAWD,YAAY,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AA8C/C,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,eAAe,CAAC,EAAE,eAAe,CAAC;IAC3C;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,CAAC;IACpD;;;;;OAKG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,OAAO,CAAC;IACrC;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,cAAc,CAAC;CACpC;AAWD,wBAAsB,WAAW,CAC/B,MAAM,EAAE,cAAc,EACtB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,YAAY,CAAC,CAqlCvB"}

package/dist/engine.js

@@ -4,7 +4,8 @@ import { buildDag } from './dag';
 import { defaultRegistry } from './registry';
 import { runSpawn, runCommand } from './runner';
 import { parseDuration, nowISO, generateRunId } from './utils';
-import { promptDocumentFromString, serializePromptDocument } from './prompt-doc';
+import { promptDocumentFromString, serializePromptDocument, prependContext, renderInputsBlock, renderOutputSchemaBlock, } from './prompt-doc';
+import { extractTaskOutputs, resolveTaskInputs, substituteInputs } from './ports';
 import { executeHook, buildPipelineStartContext, buildTaskContext, buildPipelineCompleteContext, buildPipelineErrorContext, } from './hooks';
 import { Logger, tailLines, clip } from './logger';
 import { InMemoryApprovalGateway } from './approval';
@@ -102,12 +103,19 @@ function toRunTaskState(taskId, trackId, taskName, state) {
         exitCode: result?.exitCode ?? null,
         stdout: result?.stdout ?? '',
         stderr: result?.stderr ?? '',
+        stdoutPath: result?.stdoutPath ?? null,
         stderrPath: result?.stderrPath ?? null,
+        stdoutBytes: result?.stdoutBytes ?? null,
+        stderrBytes: result?.stderrBytes ?? null,
         sessionId: result?.sessionId ?? null,
         normalizedOutput: result?.normalizedOutput ?? null,
         resolvedDriver: cfg.driver ?? null,
         resolvedModel: cfg.model ?? null,
         resolvedPermissions: cfg.permissions ?? null,
+        // Ports not yet wired through the engine's event surface. Null placeholder
+        // keeps the wire type honest until the ports extraction pass lands.
+        outputs: result?.outputs ?? null,
+        inputs: null,
         logs: [],
         totalLogCount: 0,
     };
@@ -218,6 +226,17 @@ export async function runPipeline(config, workDir, options = {}) {
         emit({ type: 'run_start', runId, tasks: runStartTasks });
         const sessionMap = new Map();
         const normalizedMap = new Map();
+        // Extracted port outputs keyed by fully-qualified task id. Populated
+        // after a task succeeds when its `ports.outputs` is declared; read by
+        // downstream tasks via `resolveTaskInputs` to assemble their inputs.
+        // Kept separate from normalizedMap so the continue_from text handoff
+        // and the typed-port data handoff don't pollute each other — they
+        // solve different problems and have different lifetimes.
+        const outputValuesMap = new Map();
+        // Resolved port inputs keyed by fully-qualified task id. Written once,
+        // just before a task runs, so every subsequent task_update event can
+        // echo them to the UI without re-resolving.
+        const resolvedInputsMap = new Map();
         // Pipeline timeout + abort reason tracking.
         //
         // `abortReason` replaces the previous `pipelineAborted: boolean`: it
@@ -314,9 +333,14 @@ export async function runPipeline(config, workDir, options = {}) {
                 exitCode: result?.exitCode,
                 stdout: result?.stdout,
                 stderr: result?.stderr,
+                stdoutPath: result?.stdoutPath ?? null,
                 stderrPath: result?.stderrPath ?? null,
+                stdoutBytes: result?.stdoutBytes ?? null,
+                stderrBytes: result?.stderrBytes ?? null,
                 sessionId: result?.sessionId ?? null,
                 normalizedOutput: result?.normalizedOutput ?? null,
+                inputs: resolvedInputsMap.get(taskId) ?? null,
+                outputs: outputValuesMap.get(taskId) ?? null,
                 resolvedDriver: cfg.driver ?? null,
                 resolvedModel: cfg.model ?? null,
                 resolvedPermissions: cfg.permissions ?? null,
@@ -413,20 +437,28 @@ export async function runPipeline(config, workDir, options = {}) {
                 log.debug(`[task:${taskId}]`, `trigger wait: type=${task.trigger.type} ${JSON.stringify(task.trigger)}`);
                 try {
                     const triggerPlugin = registry.getHandler('triggers', task.trigger.type);
-                    // R6: race the plugin's watch() against the pipeline's abort signal.
-                    // Third-party triggers may forget to wire up ctx.signal — without
-                    // this race, an aborted pipeline would hang forever waiting for the
-                    // plugin's watch promise to resolve. The race resolves on whichever
-                    // path settles first, and the cleanup paths in finally never run on
-                    // the orphaned plugin promise (it's allowed to leak a watcher; the
-                    // pipeline is being torn down anyway).
+                    // R6: race the plugin's watch() against the pipeline's abort signal
+                    // AND the task-level timeout. Third-party triggers may forget to
+                    // wire up ctx.signal — without the abort race, an aborted pipeline
+                    // would hang forever waiting for the plugin's watch promise to
+                    // resolve. And without the timeout race, a buggy watch() that never
+                    // settles would ignore the user's `task.timeout` (which the spawn
+                    // path at step 4 already honours) — a task could wedge the whole
+                    // pipeline until pipeline-level timeout fires (or forever, if none
+                    // is set). Honouring task.timeout here makes the two stages
+                    // symmetric. The cleanup paths in finally never run on the orphaned
+                    // plugin promise (it's allowed to leak a watcher; the pipeline is
+                    // being torn down anyway).
+                    const triggerTimeoutMs = task.timeout ? parseDuration(task.timeout) : 0;
                     await new Promise((resolve, reject) => {
                         let settled = false;
+                        let timer = null;
                         const onAbort = () => {
                             if (settled)
                                 return;
                             settled = true;
-                            abortController.signal.removeEventListener('abort', onAbort);
+                            if (timer !== null)
+                                clearTimeout(timer);
                             reject(new Error('Pipeline aborted'));
                         };
                         if (abortController.signal.aborted) {
@@ -434,6 +466,15 @@ export async function runPipeline(config, workDir, options = {}) {
                             return;
                         }
                         abortController.signal.addEventListener('abort', onAbort, { once: true });
+                        if (triggerTimeoutMs > 0) {
+                            timer = setTimeout(() => {
+                                if (settled)
+                                    return;
+                                settled = true;
+                                abortController.signal.removeEventListener('abort', onAbort);
+                                reject(new TriggerTimeoutError(`Trigger "${task.trigger.type}" did not settle within ${task.timeout} (task-level timeout)`));
+                            }, triggerTimeoutMs);
+                        }
                         triggerPlugin
                             .watch(task.trigger, {
                             taskId: node.taskId,
@@ -446,12 +487,16 @@ export async function runPipeline(config, workDir, options = {}) {
                             if (settled)
                                 return;
                             settled = true;
+                            if (timer !== null)
+                                clearTimeout(timer);
                             abortController.signal.removeEventListener('abort', onAbort);
                             resolve(v);
                         }, (e) => {
                             if (settled)
                                 return;
                             settled = true;
+                            if (timer !== null)
+                                clearTimeout(timer);
                             abortController.signal.removeEventListener('abort', onAbort);
                             reject(e);
                         });
@@ -510,6 +555,49 @@ export async function runPipeline(config, workDir, options = {}) {
                 }
                 return;
             }
+            // 3.5. Resolve port inputs from upstream outputs. This is the last
+            // gate before execution: missing-required inputs block the task
+            // without ever spawning a process, so the caller sees a clear
+            // "blocked: missing input X" rather than a cryptic runtime error
+            // from a command that expanded a placeholder to the empty string.
+            // Resolution runs even for tasks that declare no ports — the call
+            // is cheap and returns `{kind: 'ready', inputs: {}}` in that case,
+            // which downstream code handles uniformly.
+            const inputResolution = resolveTaskInputs(task, outputValuesMap, node.dependsOn);
+            if (inputResolution.kind === 'blocked') {
+                log.error(`[task:${taskId}]`, `blocked — cannot resolve port inputs:\n${inputResolution.reason}`);
+                state.result = {
+                    exitCode: -1,
+                    stdout: '',
+                    stderr: `[engine] port input resolution failed:\n${inputResolution.reason}`,
+                    stdoutPath: null,
+                    stderrPath: null,
+                    durationMs: 0,
+                    sessionId: null,
+                    normalizedOutput: null,
+                    failureKind: 'spawn_error',
+                    outputs: null,
+                };
+                state.finishedAt = nowISO();
+                setTaskStatus(taskId, 'blocked');
+                try {
+                    await fireHook(taskId, 'task_failure');
+                }
+                catch (hookErr) {
+                    log.error(`[task:${taskId}]`, `hook execution failed: ${hookErr instanceof Error ? hookErr.message : String(hookErr)}`);
+                }
+                if (getOnFailure(taskId) === 'stop_all')
+                    applyStopAll(node.track.id);
+                return;
+            }
+            const resolvedInputs = inputResolution.inputs;
+            resolvedInputsMap.set(taskId, resolvedInputs);
+            if (inputResolution.missingOptional.length > 0) {
+                log.debug(`[task:${taskId}]`, `optional inputs unresolved (empty in placeholders): ${inputResolution.missingOptional.join(', ')}`);
+            }
+            if (task.ports?.inputs && task.ports.inputs.length > 0) {
+                log.debug(`[task:${taskId}]`, `resolved inputs: ${JSON.stringify(resolvedInputs)}`);
+            }
             // 4. Mark running — set startedAt before emitting so subscribers see a
             // complete task_update (startedAt non-null) on the status transition.
             state.startedAt = nowISO();
@@ -531,17 +619,60 @@ export async function runPipeline(config, workDir, options = {}) {
             try {
                 let result;
                 const timeoutMs = task.timeout ? parseDuration(task.timeout) : undefined;
-                const runOpts = { timeoutMs, signal: abortController.signal };
+                // Stream child stdout/stderr directly to disk in the logger's run dir
+                // and keep only a bounded tail in the returned TaskResult. Filenames
+                // mirror the existing `.stderr` naming — dots in task ids are replaced
+                // so hierarchical ids (e.g. `track1.task2`) map cleanly to a flat dir.
+                const fsSafeTaskId = taskId.replace(/\./g, '_');
+                const stdoutPath = resolve(log.dir, `${fsSafeTaskId}.stdout`);
+                const stderrPath = resolve(log.dir, `${fsSafeTaskId}.stderr`);
+                const runOpts = {
+                    timeoutMs,
+                    signal: abortController.signal,
+                    stdoutPath,
+                    stderrPath,
+                };
                 if (task.command) {
-                    log.debug(`[task:${taskId}]`, `command: ${task.command}`);
-                    result = await runCommand(task.command, task.cwd ?? workDir, runOpts);
+                    // Substitute `{{inputs.X}}` placeholders into the command
+                    // string. Tasks with no declared inputs always produce the same
+                    // string back (no placeholders to match). Unresolved references
+                    // render empty — validate-raw flags undeclared references as
+                    // errors, so the only way to land here with an unresolved is an
+                    // optional input that had no upstream producer and no default,
+                    // which we surface in the log.
+                    const { text: expandedCommand, unresolved } = substituteInputs(task.command, resolvedInputs);
+                    if (unresolved.length > 0) {
+                        log.debug(`[task:${taskId}]`, `command placeholders rendered empty: ${unresolved.join(', ')}`);
+                    }
+                    log.debug(`[task:${taskId}]`, `command: ${expandedCommand}`);
+                    result = await runCommand(expandedCommand, task.cwd ?? workDir, runOpts);
                 }
                 else {
                     // AI task: apply middleware chain against a structured PromptDocument.
                     const driverName = task.driver ?? track.driver ?? config.driver ?? 'opencode';
                     const driver = registry.getHandler('drivers', driverName);
-                    const originalLen = task.prompt.length;
-                    let doc = promptDocumentFromString(task.prompt);
+                    // Substitute placeholders in the user-authored prompt before
+                    // wrapping into a PromptDocument so middlewares see the
+                    // already-resolved task text.
+                    const { text: expandedPrompt, unresolved } = substituteInputs(task.prompt, resolvedInputs);
+                    if (unresolved.length > 0) {
+                        log.debug(`[task:${taskId}]`, `prompt placeholders rendered empty: ${unresolved.join(', ')}`);
+                    }
+                    const originalLen = expandedPrompt.length;
+                    let doc = promptDocumentFromString(expandedPrompt);
+                    // Prepend port-related context blocks so the model sees them
+                    // before any middleware-added retrieval / memory blocks. Order
+                    // matters: [Output Format] first (sets the deliverable), then
+                    // [Inputs] (the concrete data to operate on). Empty blocks are
+                    // filtered out — tasks without ports get no extra blocks at all.
+                    const outputFormatBlock = renderOutputSchemaBlock(task.ports?.outputs);
+                    if (outputFormatBlock) {
+                        doc = prependContext(doc, outputFormatBlock);
+                    }
+                    const inputsBlock = renderInputsBlock(task.ports?.inputs, resolvedInputs);
+                    if (inputsBlock) {
+                        doc = prependContext(doc, inputsBlock);
+                    }
                     const mws = task.middlewares !== undefined ? task.middlewares : track.middlewares;
                     if (mws && mws.length > 0) {
                         log.debug(`[task:${taskId}]`, `middleware chain: ${mws.map((m) => m.type).join(' → ')}`);
@@ -625,6 +756,13 @@ export async function runPipeline(config, workDir, options = {}) {
                         // contexts and task). Drivers that read task.prompt see the
                         // default serialization and need no changes.
                         promptDoc: doc,
+                        // Ports feature: resolved input values keyed by port name,
+                        // already coerced to the declared port type. Drivers that
+                        // need to re-substitute placeholders inside a custom envelope
+                        // can read this and call `substituteInputs`; most drivers can
+                        // ignore it because the engine has already expanded
+                        // `{{inputs.X}}` into `task.prompt` upstream.
+                        inputs: resolvedInputs,
                     };
                     const spec = await driver.buildCommand(enrichedTask, track, driverCtx);
                     log.debug(`[task:${taskId}]`, `driver=${driverName}`);
@@ -672,6 +810,33 @@ export async function runPipeline(config, workDir, options = {}) {
                 else {
                     terminalStatus = 'success';
                 }
+                // Extract declared port outputs from the task's output stream.
+                // Only meaningful on success — a failed task's output is whatever
+                // the child happened to emit before exiting, and downstream tasks
+                // shouldn't receive partial data. `extractTaskOutputs` is a no-op
+                // when the task has no declared outputs, so this is free for
+                // pre-ports tasks. Diagnostics are appended to stderr so users
+                // see *why* a downstream input is missing without having to dig
+                // through driver-specific logs.
+                let extractedOutputs = null;
+                if (terminalStatus === 'success') {
+                    const extraction = extractTaskOutputs(task.ports, result.stdout, result.normalizedOutput);
+                    if (task.ports?.outputs && task.ports.outputs.length > 0) {
+                        extractedOutputs = extraction.outputs;
+                        outputValuesMap.set(taskId, extraction.outputs);
+                        log.debug(`[task:${taskId}]`, `extracted outputs: ${JSON.stringify(extraction.outputs)}`);
+                        if (extraction.diagnostic) {
+                            log.error(`[task:${taskId}]`, extraction.diagnostic);
+                            const note = `\n[engine] ${extraction.diagnostic}`;
+                            result = { ...result, stderr: result.stderr + note };
+                        }
+                    }
+                }
+                // Attach outputs to the result (null when task has no declared
+                // outputs or extraction failed entirely). Consumers of TaskResult
+                // — hooks, wire events, test assertions — all go through this
+                // one field rather than re-running extraction.
+                result = { ...result, outputs: extractedOutputs };
                 // Store normalized text separately (in-memory) for continue_from handoff.
                 // R15: clip oversized values so a runaway parseResult can't accumulate
                 // hundreds of MB across tasks.
@@ -682,11 +847,9 @@ export async function runPipeline(config, workDir, options = {}) {
                         : result.normalizedOutput;
                     normalizedMap.set(taskId, clipped);
                 }
-                if (result.stderr) {
-                    const stderrPath = resolve(log.dir, `${taskId.replace(/\./g, '_')}.stderr`);
-                    await Bun.write(stderrPath, result.stderr);
-                    result = { ...result, stderrPath };
-                }
+                // Note: stderr is already persisted by runner.ts as it streams; the
+                // old "write full string after the fact" block is gone — that's what
+                // the streaming rewrite fixed (unbounded in-memory buffering).
                 if (result.sessionId) {
                     // H1: qualified-only key.
                     sessionMap.set(taskId, result.sessionId);
@@ -707,11 +870,18 @@ export async function runPipeline(config, workDir, options = {}) {
                         log.error(`[task:${taskId}]`, `stderr tail:\n${tail}`);
                     }
                 }
-                // File-only: full stdout/stderr dump (clipped) + extracted metadata
-                log.debug(`[task:${taskId}]`, `stdout: ${result.stdout.length} chars, stderr: ${result.stderr.length} chars`);
+                // File-only: byte counts (prefer full totals from the runner over the
+                // bounded tail length so oversized outputs show their real size) +
+                // paths to the on-disk full copies.
+                const stdoutSize = result.stdoutBytes ?? result.stdout.length;
+                const stderrSize = result.stderrBytes ?? result.stderr.length;
+                log.debug(`[task:${taskId}]`, `stdout: ${stdoutSize} bytes, stderr: ${stderrSize} bytes`);
                 if (result.sessionId) {
                     log.debug(`[task:${taskId}]`, `sessionId: ${result.sessionId}`);
                 }
+                if (result.stdoutPath) {
+                    log.debug(`[task:${taskId}]`, `wrote stdout: ${result.stdoutPath}`);
+                }
                 if (result.stderrPath) {
                     log.debug(`[task:${taskId}]`, `wrote stderr: ${result.stderrPath}`);
                 }
@@ -732,7 +902,10 @@ export async function runPipeline(config, workDir, options = {}) {
                     exitCode: -1,
                     stdout: '',
                     stderr: errMsg,
+                    stdoutPath: null,
                     stderrPath: null,
+                    stdoutBytes: 0,
+                    stderrBytes: errMsg.length,
                     durationMs: 0,
                     sessionId: null,
                     normalizedOutput: null,