@tagma/sdk 0.6.11 → 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/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', () => {

package/src/ports.ts

@@ -34,7 +34,13 @@
 // Everything here is pure / deterministic so it can be reused by the CLI,
 // the editor (for preview/simulation), and the engine without side effects.
 
-import type { PortDef, PortType, TaskConfig, TaskPorts } from './types';
+import type {
+  PortDef,
+  PortType,
+  TaskConfig,
+  TaskOutputBindings,
+  TaskPorts,
+} from './types';
 
 // ─── Template substitution ────────────────────────────────────────────
 
@@ -244,6 +250,157 @@ export function resolveTaskInputs(
   return { kind: 'ready', inputs, missingOptional };
 }
 
+// ─── Lightweight binding resolution ──────────────────────────────────
+
+export interface UpstreamBindingData {
+  readonly outputs?: Readonly<Record<string, unknown>> | null;
+  readonly stdout?: string;
+  readonly stderr?: string;
+  readonly normalizedOutput?: string | null;
+  readonly exitCode?: number | null;
+}
+
+export type BindingInputResolution =
+  | {
+      readonly kind: 'ready';
+      readonly inputs: Readonly<Record<string, unknown>>;
+      readonly missingOptional: readonly string[];
+    }
+  | {
+      readonly kind: 'blocked';
+      readonly missingRequired: readonly string[];
+      readonly ambiguous: readonly { input: string; producers: readonly string[] }[];
+      readonly reason: string;
+    };
+
+export function resolveTaskBindingInputs(
+  task: Pick<TaskConfig, 'inputs'>,
+  upstreamData: ReadonlyMap<string, UpstreamBindingData>,
+  dependsOn: readonly string[],
+): BindingInputResolution {
+  const bindings = task.inputs;
+  if (!bindings || Object.keys(bindings).length === 0) {
+    return { kind: 'ready', inputs: {}, missingOptional: [] };
+  }
+
+  const inputs: Record<string, unknown> = {};
+  const missingRequired: string[] = [];
+  const missingOptional: string[] = [];
+  const ambiguous: { input: string; producers: string[] }[] = [];
+
+  for (const [name, binding] of Object.entries(bindings)) {
+    let value: unknown;
+    let present = false;
+
+    if ('value' in binding) {
+      value = binding.value;
+      present = true;
+    } else if (binding.from) {
+      const found = resolveBindingSource(binding.from, upstreamData, dependsOn);
+      if (found.kind === 'ambiguous') {
+        ambiguous.push({ input: name, producers: found.producers });
+        continue;
+      }
+      if (found.kind === 'hit') {
+        value = found.value;
+        present = true;
+      }
+    }
+
+    if (!present && 'default' in binding) {
+      value = binding.default;
+      present = true;
+    }
+
+    if (!present || value === undefined || value === null) {
+      if (binding.required === true) {
+        missingRequired.push(name);
+      } else {
+        missingOptional.push(name);
+      }
+      continue;
+    }
+
+    inputs[name] = value;
+  }
+
+  if (missingRequired.length > 0 || ambiguous.length > 0) {
+    const lines: string[] = [];
+    if (missingRequired.length > 0) {
+      lines.push(`missing required binding input(s): ${missingRequired.join(', ')}`);
+    }
+    for (const amb of ambiguous) {
+      lines.push(
+        `binding input "${amb.input}" is produced by multiple upstreams ` +
+          `(${amb.producers.join(', ')}) — use "taskId.outputs.${amb.input}"`,
+      );
+    }
+    return { kind: 'blocked', missingRequired, ambiguous, reason: lines.join('\n') };
+  }
+
+  return { kind: 'ready', inputs, missingOptional };
+}
+
+type BindingLookup =
+  | { kind: 'hit'; producer: string; value: unknown }
+  | { kind: 'miss' }
+  | { kind: 'ambiguous'; producers: string[] };
+
+function resolveBindingSource(
+  source: string,
+  upstreamData: ReadonlyMap<string, UpstreamBindingData>,
+  dependsOn: readonly string[],
+): BindingLookup {
+  if (source.startsWith('outputs.')) {
+    return findOutputByName(source.slice('outputs.'.length), upstreamData, dependsOn);
+  }
+
+  const outputMarker = '.outputs.';
+  const outputIdx = source.lastIndexOf(outputMarker);
+  if (outputIdx > 0) {
+    const upstreamId = source.slice(0, outputIdx);
+    const outputName = source.slice(outputIdx + outputMarker.length);
+    if (!dependsOn.includes(upstreamId)) return { kind: 'miss' };
+    const upstream = upstreamData.get(upstreamId);
+    if (upstream?.outputs && outputName in upstream.outputs) {
+      return { kind: 'hit', producer: upstreamId, value: upstream.outputs[outputName] };
+    }
+    return { kind: 'miss' };
+  }
+
+  for (const field of ['stdout', 'stderr', 'normalizedOutput', 'exitCode'] as const) {
+    const suffix = `.${field}`;
+    if (!source.endsWith(suffix)) continue;
+    const upstreamId = source.slice(0, -suffix.length);
+    if (!dependsOn.includes(upstreamId)) return { kind: 'miss' };
+    const upstream = upstreamData.get(upstreamId);
+    if (!upstream) return { kind: 'miss' };
+    const value = upstream[field];
+    return value === undefined || value === null
+      ? { kind: 'miss' }
+      : { kind: 'hit', producer: upstreamId, value };
+  }
+
+  return { kind: 'miss' };
+}
+
+function findOutputByName(
+  name: string,
+  upstreamData: ReadonlyMap<string, UpstreamBindingData>,
+  dependsOn: readonly string[],
+): BindingLookup {
+  const hits: { producer: string; value: unknown }[] = [];
+  for (const upstreamId of dependsOn) {
+    const upstream = upstreamData.get(upstreamId);
+    if (upstream?.outputs && name in upstream.outputs) {
+      hits.push({ producer: upstreamId, value: upstream.outputs[name] });
+    }
+  }
+  if (hits.length === 0) return { kind: 'miss' };
+  if (hits.length === 1) return { kind: 'hit', producer: hits[0]!.producer, value: hits[0]!.value };
+  return { kind: 'ambiguous', producers: hits.map((h) => h.producer) };
+}
+
 type UpstreamLookup =
   | { kind: 'hit'; producer: string; value: unknown }
   | { kind: 'miss' }
@@ -416,6 +573,72 @@ export function extractTaskOutputs(
   return { outputs, diagnostic };
 }
 
+export function extractTaskBindingOutputs(
+  bindings: TaskOutputBindings | undefined,
+  stdout: string,
+  stderr: string,
+  normalizedOutput: string | null,
+): ExtractResult {
+  if (!bindings || Object.keys(bindings).length === 0) {
+    return { outputs: {}, diagnostic: null };
+  }
+
+  const outputs: Record<string, unknown> = {};
+  const missing: string[] = [];
+  let record: Record<string, unknown> | null | undefined;
+
+  for (const [name, binding] of Object.entries(bindings)) {
+    let value: unknown;
+    let present = false;
+
+    if ('value' in binding) {
+      value = binding.value;
+      present = true;
+    } else {
+      const source = binding.from ?? `json.${name}`;
+      if (source === 'stdout') {
+        value = stdout;
+        present = true;
+      } else if (source === 'stderr') {
+        value = stderr;
+        present = true;
+      } else if (source === 'normalizedOutput') {
+        if (normalizedOutput !== null) {
+          value = normalizedOutput;
+          present = true;
+        }
+      } else if (source.startsWith('json.')) {
+        if (record === undefined) {
+          const jsonSource = (normalizedOutput ?? '').length > 0 ? normalizedOutput! : stdout;
+          record = parseJsonTail(jsonSource);
+        }
+        const key = source.slice('json.'.length);
+        if (record && key in record) {
+          value = record[key];
+          present = true;
+        }
+      }
+    }
+
+    if (!present && 'default' in binding) {
+      value = binding.default;
+      present = true;
+    }
+
+    if (!present || value === undefined || value === null) {
+      missing.push(name);
+      continue;
+    }
+
+    outputs[name] = value;
+  }
+
+  return {
+    outputs,
+    diagnostic: missing.length > 0 ? `outputs: unresolved binding output(s): ${missing.join(', ')}` : null,
+  };
+}
+
 /**
  * Find the last non-empty line that parses as a JSON object. Returns
  * null when no such line exists. Also tries the whole source as a