@tagma/sdk 0.6.10 → 0.6.12

package/src/engine.ts

@@ -31,11 +31,14 @@ import {
   renderOutputSchemaBlock,
 } from './prompt-doc';
 import {
+  extractTaskBindingOutputs,
   extractTaskOutputs,
   inferPromptPorts,
+  resolveTaskBindingInputs,
   resolveTaskInputs,
   substituteInputs,
 } from './ports';
+import type { UpstreamBindingData } from './ports';
 import type { TaskPorts } from './types';
 import {
   executeHook,
@@ -70,6 +73,18 @@ export class TriggerTimeoutError extends Error {
   }
 }
 
+function isPromptTaskConfig(
+  task: TaskConfig,
+): task is TaskConfig & { readonly prompt: string; readonly command?: undefined } {
+  return task.prompt !== undefined && task.command === undefined;
+}
+
+function isCommandTaskConfig(
+  task: TaskConfig,
+): task is TaskConfig & { readonly command: string; readonly prompt?: undefined } {
+  return task.command !== undefined && task.prompt === undefined;
+}
+
 // ═══ Preflight Validation ═══
 
 function preflight(config: PipelineConfig, dag: Dag, registry: PluginRegistry): void {
@@ -81,7 +96,7 @@ function preflight(config: PipelineConfig, dag: Dag, registry: PluginRegistry):
     const driverName = task.driver ?? track.driver ?? config.driver ?? 'opencode';
 
     // Pure command tasks don't use a driver — skip driver registration check.
-    const isCommandOnly = task.command && !task.prompt;
+    const isCommandOnly = isCommandTaskConfig(task);
 
     if (!isCommandOnly && !registry.hasHandler('drivers', driverName)) {
       errors.push(`Task "${node.taskId}": driver "${driverName}" not registered`);
@@ -319,7 +334,7 @@ export async function runPipeline(
     log.section('DAG topology');
     for (const [id, node] of dag.nodes) {
       const deps = node.dependsOn.length ? node.dependsOn.join(', ') : '(root)';
-      const kind = node.task.prompt ? 'ai' : 'cmd';
+      const kind = isPromptTaskConfig(node.task) ? 'ai' : 'cmd';
       log.quiet(`  • ${id}  [${kind}]  track=${node.track.id}  deps=[${deps}]`);
     }
     log.quiet('');
@@ -388,13 +403,12 @@ export async function runPipeline(
 
     const sessionMap = new Map<string, string>();
     const normalizedMap = new Map<string, string>();
-    // 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.
+    // Published structured outputs keyed by fully-qualified task id.
+    // Includes lightweight task.outputs and strict ports.outputs.
     const outputValuesMap = new Map<string, Readonly<Record<string, unknown>>>();
+    // Full upstream result data for lightweight input bindings such as
+    // `taskId.stdout` and `taskId.outputs.name`.
+    const bindingDataMap = new Map<string, UpstreamBindingData>();
     // 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.
@@ -577,7 +591,7 @@ export async function runPipeline(
       return {
         id: taskId,
         name: state.config.name,
-        type: state.config.prompt ? 'ai' : 'command',
+        type: isPromptTaskConfig(state.config) ? 'ai' : 'command',
         status: state.status,
         exit_code: state.result?.exitCode ?? null,
         duration_ms: state.result?.durationMs ?? null,
@@ -614,7 +628,7 @@ export async function runPipeline(
       log.section(`Task ${taskId}`, taskId);
       log.debug(
         `[task:${taskId}]`,
-        `type=${task.prompt ? 'ai' : 'cmd'} track=${track.id} deps=[${node.dependsOn.join(', ') || '(root)'}]`,
+        `type=${isPromptTaskConfig(task) ? 'ai' : 'cmd'} track=${track.id} deps=[${node.dependsOn.join(', ') || '(root)'}]`,
       );
 
       // 1. Check dependencies
@@ -781,7 +795,7 @@ export async function runPipeline(
       // pipeline the Command path uses. Collisions that a Prompt can't
       // disambiguate (same input name on two upstreams, incompatible
       // downstream output types) block the task with a clear message.
-      const isPromptTask = task.prompt !== undefined && task.command === undefined;
+      const isPromptTask = isPromptTaskConfig(task);
       let effectivePorts: TaskPorts | undefined = task.ports;
       let promptInferenceBlockReason: string | null = null;
 
@@ -789,7 +803,7 @@ export async function runPipeline(
         const inference = inferPromptPorts({
           upstreams: node.dependsOn.map((upstreamId) => {
             const upstream = dag.nodes.get(upstreamId);
-            const isUpstreamCommand = !!upstream?.task.command;
+            const isUpstreamCommand = upstream ? isCommandTaskConfig(upstream.task) : false;
             return {
               taskId: upstreamId,
               outputs: isUpstreamCommand ? upstream?.task.ports?.outputs : undefined,
@@ -797,7 +811,7 @@ export async function runPipeline(
           }),
           downstreams: (directDownstreams.get(taskId) ?? []).map((downstreamId) => {
             const downstream = dag.nodes.get(downstreamId);
-            const isDownstreamCommand = !!downstream?.task.command;
+            const isDownstreamCommand = downstream ? isCommandTaskConfig(downstream.task) : false;
             return {
               taskId: downstreamId,
               inputs: isDownstreamCommand ? downstream?.task.ports?.inputs : undefined,
@@ -844,6 +858,44 @@ export async function runPipeline(
         return;
       }
 
+      const bindingResolution = resolveTaskBindingInputs(task, bindingDataMap, node.dependsOn);
+      if (bindingResolution.kind === 'blocked') {
+        log.error(
+          `[task:${taskId}]`,
+          `blocked — cannot resolve task input bindings:\n${bindingResolution.reason}`,
+        );
+        state.result = {
+          exitCode: -1,
+          stdout: '',
+          stderr: `[engine] task input binding resolution failed:\n${bindingResolution.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;
+      }
+      if (bindingResolution.missingOptional.length > 0) {
+        log.debug(
+          `[task:${taskId}]`,
+          `optional input bindings unresolved (empty in placeholders): ${bindingResolution.missingOptional.join(', ')}`,
+        );
+      }
+
       // Feed effective ports into `resolveTaskInputs` by shallow-cloning
       // the task. Prompt tasks get the inferred ports; Command tasks are
       // unchanged (effectivePorts === task.ports).
@@ -880,7 +932,7 @@ export async function runPipeline(
         if (getOnFailure(taskId) === 'stop_all') applyStopAll(node.track.id);
         return;
       }
-      const resolvedInputs = inputResolution.inputs;
+      const resolvedInputs = { ...bindingResolution.inputs, ...inputResolution.inputs };
       resolvedInputsMap.set(taskId, resolvedInputs);
       if (inputResolution.missingOptional.length > 0) {
         log.debug(
@@ -902,7 +954,7 @@ export async function runPipeline(
       setTaskStatus(taskId, 'running');
       log.info(
         `[task:${taskId}]`,
-        task.command ? `running: ${task.command}` : `running (driver task)`,
+        isCommandTaskConfig(task) ? `running: ${task.command}` : `running (driver task)`,
       );
 
       // File-only: resolved config for this task
@@ -940,7 +992,7 @@ export async function runPipeline(
           stderrPath,
         };
 
-        if (task.command) {
+        if (isCommandTaskConfig(task)) {
           // 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
@@ -1168,16 +1220,29 @@ export async function runPipeline(
           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.
+        // Extract declared 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.
         let extractedOutputs: Readonly<Record<string, unknown>> | null = null;
         if (terminalStatus === 'success') {
+          const looseExtraction = extractTaskBindingOutputs(
+            task.outputs,
+            result.stdout,
+            result.stderr,
+            result.normalizedOutput,
+          );
+          if (task.outputs && Object.keys(task.outputs).length > 0) {
+            extractedOutputs = looseExtraction.outputs;
+            log.debug(
+              `[task:${taskId}]`,
+              `extracted binding outputs: ${JSON.stringify(looseExtraction.outputs)}`,
+            );
+            if (looseExtraction.diagnostic) {
+              log.debug(`[task:${taskId}]`, looseExtraction.diagnostic);
+            }
+          }
+
           // Prompt tasks use inferred ports (from direct-downstream Command
           // inputs); Command tasks use their declared ports. Either way,
           // `extractTaskOutputs` is a no-op when there are no declared
@@ -1188,8 +1253,7 @@ export async function runPipeline(
             result.normalizedOutput,
           );
           if (effectivePorts?.outputs && effectivePorts.outputs.length > 0) {
-            extractedOutputs = extraction.outputs;
-            outputValuesMap.set(taskId, extraction.outputs);
+            extractedOutputs = { ...(extractedOutputs ?? {}), ...extraction.outputs };
             log.debug(
               `[task:${taskId}]`,
               `extracted outputs: ${JSON.stringify(extraction.outputs)}` +
@@ -1207,6 +1271,16 @@ export async function runPipeline(
         // — hooks, wire events, test assertions — all go through this
         // one field rather than re-running extraction.
         result = { ...result, outputs: extractedOutputs };
+        if (extractedOutputs !== null) {
+          outputValuesMap.set(taskId, extractedOutputs);
+        }
+        bindingDataMap.set(taskId, {
+          outputs: extractedOutputs,
+          stdout: result.stdout,
+          stderr: result.stderr,
+          normalizedOutput: result.normalizedOutput,
+          exitCode: result.exitCode,
+        });
 
         // Store normalized text separately (in-memory) for continue_from handoff.
         // R15: clip oversized values so a runaway parseResult can't accumulate

package/src/pipeline-runner.test.ts

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

package/src/pipeline-runner.ts

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

package/src/ports.test.ts

@@ -1,8 +1,10 @@
 import { describe, expect, test } from 'bun:test';
 import {
   extractInputReferences,
+  extractTaskBindingOutputs,
   extractTaskOutputs,
   inferPromptPorts,
+  resolveTaskBindingInputs,
   resolveTaskInputs,
   substituteInputs,
 } from './ports';
@@ -244,6 +246,87 @@ describe('resolveTaskInputs', () => {
   });
 });
 
+// ─── resolveTaskBindingInputs ────────────────────────────────────────
+
+describe('resolveTaskBindingInputs', () => {
+  test('resolves literal values and defaults without requiring ports', () => {
+    const t = task({
+      id: 'downstream',
+      command: 'echo',
+      inputs: {
+        city: { value: 'Shanghai' },
+        mode: { from: 't.up.outputs.missing', default: 'quick' },
+      },
+    });
+    const res = resolveTaskBindingInputs(t, new Map(), ['t.up']);
+    expect(res).toEqual({
+      kind: 'ready',
+      inputs: { city: 'Shanghai', mode: 'quick' },
+      missingOptional: [],
+    });
+  });
+
+  test('resolves values from a direct upstream output and stdout', () => {
+    const t = task({
+      id: 'downstream',
+      command: 'echo',
+      inputs: {
+        city: { from: 't.up.outputs.city' },
+        raw: { from: 't.up.stdout' },
+      },
+    });
+    const upstream = new Map([
+      [
+        't.up',
+        {
+          outputs: { city: 'Shanghai' },
+          stdout: 'raw text\n',
+          stderr: '',
+          normalizedOutput: null,
+          exitCode: 0,
+        },
+      ],
+    ]);
+    const res = resolveTaskBindingInputs(t, upstream, ['t.up']);
+    expect(res.kind).toBe('ready');
+    if (res.kind !== 'ready') return;
+    expect(res.inputs).toEqual({ city: 'Shanghai', raw: 'raw text\n' });
+  });
+
+  test('blocks required missing bindings with a readable reason', () => {
+    const t = task({
+      id: 'downstream',
+      command: 'echo',
+      inputs: {
+        city: { from: 't.up.outputs.city', required: true },
+      },
+    });
+    const res = resolveTaskBindingInputs(t, new Map(), ['t.up']);
+    expect(res.kind).toBe('blocked');
+    if (res.kind !== 'blocked') return;
+    expect(res.missingRequired).toEqual(['city']);
+    expect(res.reason).toContain('missing required binding input(s): city');
+  });
+
+  test('detects ambiguous loose output name matches', () => {
+    const t = task({
+      id: 'downstream',
+      command: 'echo',
+      inputs: {
+        val: { from: 'outputs.val', required: true },
+      },
+    });
+    const upstream = new Map([
+      ['t.a', { outputs: { val: 'a' }, stdout: '', stderr: '', normalizedOutput: null, exitCode: 0 }],
+      ['t.b', { outputs: { val: 'b' }, stdout: '', stderr: '', normalizedOutput: null, exitCode: 0 }],
+    ]);
+    const res = resolveTaskBindingInputs(t, upstream, ['t.a', 't.b']);
+    expect(res.kind).toBe('blocked');
+    if (res.kind !== 'blocked') return;
+    expect(res.ambiguous[0]).toEqual({ input: 'val', producers: ['t.a', 't.b'] });
+  });
+});
+
 // ─── extractTaskOutputs ──────────────────────────────────────────────
 
 describe('extractTaskOutputs', () => {
@@ -301,6 +384,50 @@ describe('extractTaskOutputs', () => {
   });
 });
 
+// ─── extractTaskBindingOutputs ───────────────────────────────────────
+
+describe('extractTaskBindingOutputs', () => {
+  test('extracts loose outputs from final-line JSON by default', () => {
+    const r = extractTaskBindingOutputs(
+      {
+        city: {},
+        temp: { from: 'json.temperature' },
+      },
+      'log\n{"city":"Shanghai","temperature":23}\n',
+      '',
+      null,
+    );
+    expect(r.outputs).toEqual({ city: 'Shanghai', temp: 23 });
+    expect(r.diagnostic).toBeNull();
+  });
+
+  test('can publish whole stdout and normalizedOutput as named outputs', () => {
+    const r = extractTaskBindingOutputs(
+      {
+        raw: { from: 'stdout' },
+        normalized: { from: 'normalizedOutput' },
+      },
+      'raw text\n',
+      '',
+      'normalized text',
+    );
+    expect(r.outputs).toEqual({ raw: 'raw text\n', normalized: 'normalized text' });
+  });
+
+  test('uses defaults for missing loose outputs without failing extraction', () => {
+    const r = extractTaskBindingOutputs(
+      {
+        city: { default: 'Unknown' },
+      },
+      'not json\n',
+      '',
+      null,
+    );
+    expect(r.outputs).toEqual({ city: 'Unknown' });
+    expect(r.diagnostic).toBeNull();
+  });
+});
+
 // ─── inferPromptPorts ───────────────────────────────────────────────
 
 describe('inferPromptPorts', () => {