@tagma/sdk 0.6.7 → 0.6.9

package/src/engine-ports-mixed.test.ts

@@ -0,0 +1,499 @@
+import { describe, expect, test } from 'bun:test';
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { PluginRegistry } from './registry';
+import { bootstrapBuiltins } from './bootstrap';
+import { runPipeline, type RunEventPayload } from './engine';
+import type { DriverPlugin, PipelineConfig, TaskConfig, TaskPorts, TaskStatus } from './types';
+
+// Mixed-mode port tests. Prompt Tasks do NOT declare ports — their I/O
+// contract is inferred from direct-neighbor Command Tasks. The three
+// cross-type boundaries the design has to cover:
+//
+//   prompt → command     (AI task produces outputs inferred from the
+//                         downstream Command's declared inputs)
+//   command → prompt     (AI task consumes the upstream Command's
+//                         declared outputs via substitution + [Inputs])
+//   prompt → prompt      (no structured port flow — free text only,
+//                         carried by continue_from / normalizedOutput)
+//
+// A mock AI driver stands in for a real LLM. It records the engine's
+// serialized prompt to a sidecar file and emits a per-task JSON
+// response on the final stdout line, simulating the `[Output Format]`
+// contract. Asserting on the sidecar record lets each test verify the
+// engine prepended the right `[Inputs]` / `[Output Format]` blocks
+// and expanded `{{inputs.X}}` placeholders inside the prompt.
+
+const PERMS = { read: true, write: false, execute: false };
+
+function makeDir(): string {
+  return mkdtempSync(join(tmpdir(), 'tagma-ports-mixed-'));
+}
+
+function writeEmitScript(dir: string, name: string, payload: Record<string, unknown>): string {
+  const path = join(dir, `${name}.js`);
+  const src = `process.stdout.write(${JSON.stringify(JSON.stringify(payload))});\nprocess.stdout.write('\\n');\n`;
+  writeFileSync(path, src);
+  return path;
+}
+
+function writeEchoArgsScript(dir: string, name: string): string {
+  const path = join(dir, `${name}.js`);
+  const src = `process.stdout.write(process.argv.slice(2).join('|'));\nprocess.stdout.write('\\n');\n`;
+  writeFileSync(path, src);
+  return path;
+}
+
+/**
+ * Mock-driver spawn script: read stdin (the serialized prompt), write
+ * it to a sidecar record file, echo it to stdout, then append the
+ * `MOCK_RESPONSE` env value as the final line — which extractTaskOutputs
+ * picks up as the model's JSON output.
+ */
+function writeMockDriverScript(dir: string): string {
+  const path = join(dir, 'mock-driver.js');
+  const src = [
+    `const fs = require('fs');`,
+    `const recordPath = process.env.MOCK_RECORD_PATH;`,
+    `let buf = '';`,
+    `process.stdin.setEncoding('utf8');`,
+    `process.stdin.on('data', (c) => { buf += c; });`,
+    `process.stdin.on('end', () => {`,
+    `  if (recordPath) fs.writeFileSync(recordPath, buf);`,
+    `  process.stdout.write(buf);`,
+    `  if (!buf.endsWith('\\n')) process.stdout.write('\\n');`,
+    `  const resp = process.env.MOCK_RESPONSE || '';`,
+    `  if (resp) process.stdout.write(resp + '\\n');`,
+    `});`,
+  ].join('\n');
+  writeFileSync(path, src);
+  return path;
+}
+
+interface MockConfig {
+  /** Per-task-id JSON response the mock "model" emits as its final line. */
+  readonly responses: Readonly<Record<string, Record<string, unknown>>>;
+  /** Per-task-id file path where the echoed prompt is recorded. */
+  readonly records: Readonly<Record<string, string>>;
+}
+
+function makeMockDriver(scriptPath: string, cfg: MockConfig): DriverPlugin {
+  return {
+    name: 'mock-echo',
+    capabilities: { sessionResume: false, systemPrompt: true, outputFormat: true },
+    async buildCommand(task) {
+      const env: Record<string, string> = {};
+      const resp = cfg.responses[task.id];
+      if (resp) env.MOCK_RESPONSE = JSON.stringify(resp);
+      const recordPath = cfg.records[task.id];
+      if (recordPath) env.MOCK_RECORD_PATH = recordPath;
+      return {
+        args: ['node', scriptPath],
+        stdin: task.prompt ?? '',
+        env,
+      };
+    },
+    parseResult(stdout) {
+      // A real AI driver strips transport chrome and returns only the
+      // model's message here. For the mock, the entire stdout IS the
+      // model's echo + final JSON line, so exposing it unchanged is
+      // equivalent.
+      return { normalizedOutput: stdout };
+    },
+  };
+}
+
+function registryWithMock(scriptPath: string, cfg: MockConfig): PluginRegistry {
+  const reg = new PluginRegistry();
+  bootstrapBuiltins(reg);
+  reg.registerPlugin('drivers', 'mock-echo', makeMockDriver(scriptPath, cfg));
+  return reg;
+}
+
+function task(overrides: Partial<TaskConfig> & { id: string }): TaskConfig {
+  return {
+    name: overrides.id,
+    permissions: PERMS,
+    driver: 'opencode',
+    ...overrides,
+  };
+}
+
+function pipeline(tasks: TaskConfig[]): PipelineConfig {
+  return {
+    name: 'ports-mixed-test',
+    tracks: [
+      {
+        id: 't',
+        name: 'T',
+        driver: 'opencode',
+        permissions: PERMS,
+        on_failure: 'skip_downstream',
+        tasks,
+      },
+    ],
+  };
+}
+
+interface RunResult {
+  events: RunEventPayload[];
+  success: boolean;
+}
+
+async function run(
+  config: PipelineConfig,
+  workDir: string,
+  registry: PluginRegistry,
+): Promise<RunResult> {
+  const events: RunEventPayload[] = [];
+  const result = await runPipeline(config, workDir, {
+    registry,
+    skipPluginLoading: true,
+    onEvent: (e) => events.push(e),
+  });
+  return { events, success: result.success };
+}
+
+function finalUpdateFor(events: RunEventPayload[], qid: string): RunEventPayload | undefined {
+  let last: RunEventPayload | undefined;
+  for (const ev of events) {
+    if (ev.type === 'task_update' && ev.taskId === qid) last = ev;
+  }
+  return last;
+}
+
+function finalStatusFrom(events: RunEventPayload[], qid: string): TaskStatus | undefined {
+  const last = finalUpdateFor(events, qid);
+  return last && last.type === 'task_update' ? last.status : undefined;
+}
+
+describe('engine — ports: mixed prompt/command combinations', () => {
+  test('prompt → command: prompt outputs are inferred from downstream Command inputs', async () => {
+    const dir = makeDir();
+    try {
+      const mockScript = writeMockDriverScript(dir);
+      const echo = writeEchoArgsScript(dir, 'echo');
+      const upRecord = join(dir, 'up.prompt');
+      const responses: Record<string, Record<string, unknown>> = {
+        up: { city: 'Shanghai', id: 7 },
+      };
+      const records: Record<string, string> = { up: upRecord };
+
+      // `up` is a Prompt — it declares NO ports. Its output schema is
+      // inferred at runtime from `down`'s declared inputs, which drives
+      // the `[Output Format]` block the mock "model" sees.
+      const config = pipeline([
+        task({
+          id: 'up',
+          prompt: 'Pick a random city.',
+          driver: 'mock-echo',
+        }),
+        task({
+          id: 'down',
+          depends_on: ['up'],
+          command: `node "${echo}" "{{inputs.city}}" "{{inputs.id}}"`,
+          ports: {
+            inputs: [
+              { name: 'city', type: 'string', required: true },
+              { name: 'id', type: 'number', required: true },
+            ],
+          } as TaskPorts,
+        }),
+      ]);
+
+      const registry = registryWithMock(mockScript, { responses, records });
+      const { events, success } = await run(config, dir, registry);
+      expect(success).toBe(true);
+
+      // Upstream prompt was enriched with an [Output Format] block that
+      // names the keys `down` wants (city, id) — inferred, not declared.
+      expect(existsSync(upRecord)).toBe(true);
+      const upPrompt = readFileSync(upRecord, 'utf8');
+      expect(upPrompt).toContain('[Output Format]');
+      expect(upPrompt).toContain('city');
+      expect(upPrompt).toContain('id');
+
+      // Engine extracted the mock's final-line JSON from normalizedOutput
+      // using the inferred output schema.
+      const upFinal = finalUpdateFor(events, 't.up')!;
+      if (upFinal.type !== 'task_update') throw new Error('expected update');
+      expect(upFinal.status).toBe('success');
+      expect(upFinal.outputs).toEqual({ city: 'Shanghai', id: 7 });
+
+      // Downstream command saw the values post-substitution.
+      const downFinal = finalUpdateFor(events, 't.down')!;
+      if (downFinal.type !== 'task_update') throw new Error('expected update');
+      expect(downFinal.status).toBe('success');
+      expect((downFinal.stdout ?? '').trim()).toBe('Shanghai|7');
+      expect(downFinal.inputs).toEqual({ city: 'Shanghai', id: 7 });
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test('command → prompt: prompt inputs are inferred from upstream Command outputs', async () => {
+    const dir = makeDir();
+    try {
+      const mockScript = writeMockDriverScript(dir);
+      const emit = writeEmitScript(dir, 'emit', { city: 'Berlin', id: 3 });
+      const downRecord = join(dir, 'down.prompt');
+      const responses: Record<string, Record<string, unknown>> = {
+        down: { summary: 'ok' },
+      };
+      const records: Record<string, string> = { down: downRecord };
+
+      // `down` is a Prompt — it declares NO ports. Its input schema is
+      // inferred from `up`'s declared outputs; its output schema is
+      // empty (no downstream Command to infer from), so `down` is a
+      // terminal free-text Prompt with structured inputs only.
+      const config = pipeline([
+        task({
+          id: 'up',
+          command: `node "${emit}"`,
+          ports: {
+            outputs: [
+              { name: 'city', type: 'string' },
+              { name: 'id', type: 'number' },
+            ],
+          } as TaskPorts,
+        }),
+        task({
+          id: 'down',
+          depends_on: ['up'],
+          prompt: 'City is {{inputs.city}}, id={{inputs.id}}.',
+          driver: 'mock-echo',
+        }),
+      ]);
+
+      const registry = registryWithMock(mockScript, { responses, records });
+      const { events, success } = await run(config, dir, registry);
+      expect(success).toBe(true);
+
+      // Downstream prompt saw:
+      //   1. Placeholders substituted with concrete values
+      //   2. An [Inputs] context block listing the inferred values
+      //   3. NO [Output Format] block (no downstream Command to infer
+      //      an output contract from — the Prompt is terminal)
+      const downPrompt = readFileSync(downRecord, 'utf8');
+      expect(downPrompt).toContain('City is Berlin, id=3.');
+      expect(downPrompt).toContain('[Inputs]');
+      expect(downPrompt).toMatch(/city:\s*"Berlin"/);
+      expect(downPrompt).toMatch(/id:\s*3\b/);
+      expect(downPrompt).not.toContain('[Output Format]');
+
+      const downFinal = finalUpdateFor(events, 't.down')!;
+      if (downFinal.type !== 'task_update') throw new Error('expected update');
+      expect(downFinal.inputs).toEqual({ city: 'Berlin', id: 3 });
+      // No downstream Command → no inferred outputs → outputs stay null.
+      expect(downFinal.outputs).toBeFalsy();
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test('command → prompt → command: prompt relays structured data both directions', async () => {
+    const dir = makeDir();
+    try {
+      const mockScript = writeMockDriverScript(dir);
+      const emit = writeEmitScript(dir, 'emit', { city: 'Paris' });
+      const echo = writeEchoArgsScript(dir, 'echo');
+      const midRecord = join(dir, 'mid.prompt');
+      const responses: Record<string, Record<string, unknown>> = {
+        mid: { greeting: 'Bonjour Paris' },
+      };
+      const records: Record<string, string> = { mid: midRecord };
+
+      // `mid` is a Prompt between two Commands. Its inferred inputs
+      // come from `up` (city), its inferred outputs come from `down`
+      // (greeting). No ports declared on `mid`.
+      const config = pipeline([
+        task({
+          id: 'up',
+          command: `node "${emit}"`,
+          ports: { outputs: [{ name: 'city', type: 'string' }] } as TaskPorts,
+        }),
+        task({
+          id: 'mid',
+          depends_on: ['up'],
+          prompt: 'Generate a greeting for {{inputs.city}}.',
+          driver: 'mock-echo',
+        }),
+        task({
+          id: 'down',
+          depends_on: ['mid'],
+          command: `node "${echo}" "{{inputs.greeting}}"`,
+          ports: {
+            inputs: [{ name: 'greeting', type: 'string', required: true }],
+          } as TaskPorts,
+        }),
+      ]);
+
+      const registry = registryWithMock(mockScript, { responses, records });
+      const { events, success } = await run(config, dir, registry);
+      expect(success).toBe(true);
+
+      // Middle prompt has both [Inputs] (from upstream) and
+      // [Output Format] (from downstream) — inferred in both directions.
+      const midPrompt = readFileSync(midRecord, 'utf8');
+      expect(midPrompt).toContain('[Inputs]');
+      expect(midPrompt).toMatch(/city:\s*"Paris"/);
+      expect(midPrompt).toContain('[Output Format]');
+      expect(midPrompt).toContain('greeting');
+      expect(midPrompt).toContain('Generate a greeting for Paris.');
+
+      const midFinal = finalUpdateFor(events, 't.mid')!;
+      if (midFinal.type !== 'task_update') throw new Error('expected update');
+      expect(midFinal.inputs).toEqual({ city: 'Paris' });
+      expect(midFinal.outputs).toEqual({ greeting: 'Bonjour Paris' });
+
+      const downFinal = finalUpdateFor(events, 't.down')!;
+      if (downFinal.type !== 'task_update') throw new Error('expected update');
+      expect((downFinal.stdout ?? '').trim()).toBe('Bonjour Paris');
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test('prompt → prompt: no structured port flow, free text only', async () => {
+    const dir = makeDir();
+    try {
+      const mockScript = writeMockDriverScript(dir);
+      const downRecord = join(dir, 'down.prompt');
+      const responses: Record<string, Record<string, unknown>> = {
+        up: { city: 'Tokyo' },
+        down: { greeting: 'hello Tokyo' },
+      };
+      const records: Record<string, string> = { down: downRecord };
+
+      // Neither Prompt has a Command neighbor in either direction, so
+      // both have empty inferred ports. `up`'s JSON final line is NOT
+      // extracted (no inferred outputs); `down` does NOT see `[Inputs]`
+      // or `[Output Format]`. Information between them flows only
+      // through continue_from / free text — and the downstream's
+      // `{{inputs.city}}` is an author error the engine logs as
+      // "placeholder rendered empty".
+      const config = pipeline([
+        task({
+          id: 'up',
+          prompt: 'Pick a city.',
+          driver: 'mock-echo',
+        }),
+        task({
+          id: 'down',
+          depends_on: ['up'],
+          prompt: 'Greet the city.',
+          driver: 'mock-echo',
+        }),
+      ]);
+
+      const registry = registryWithMock(mockScript, { responses, records });
+      const { events, success } = await run(config, dir, registry);
+      expect(success).toBe(true);
+      expect(finalStatusFrom(events, 't.up')).toBe('success');
+      expect(finalStatusFrom(events, 't.down')).toBe('success');
+
+      // No inferred outputs on either side.
+      const upFinal = finalUpdateFor(events, 't.up')!;
+      if (upFinal.type !== 'task_update') throw new Error('expected update');
+      expect(upFinal.outputs).toBeFalsy();
+
+      // Down's prompt has no [Inputs] / [Output Format] blocks.
+      const downPrompt = readFileSync(downRecord, 'utf8');
+      expect(downPrompt).not.toContain('[Inputs]');
+      expect(downPrompt).not.toContain('[Output Format]');
+
+      const downFinal = finalUpdateFor(events, 't.down')!;
+      if (downFinal.type !== 'task_update') throw new Error('expected update');
+      expect(downFinal.inputs).toEqual({});
+      expect(downFinal.outputs).toBeFalsy();
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test('prompt with two upstream Commands exporting the same name → blocked', async () => {
+    const dir = makeDir();
+    try {
+      const mockScript = writeMockDriverScript(dir);
+      const emitA = writeEmitScript(dir, 'emitA', { val: 'from-a' });
+      const emitB = writeEmitScript(dir, 'emitB', { val: 'from-b' });
+      const responses: Record<string, Record<string, unknown>> = {};
+      const records: Record<string, string> = {};
+
+      const config = pipeline([
+        task({
+          id: 'a',
+          command: `node "${emitA}"`,
+          ports: { outputs: [{ name: 'val', type: 'string' }] } as TaskPorts,
+        }),
+        task({
+          id: 'b',
+          command: `node "${emitB}"`,
+          ports: { outputs: [{ name: 'val', type: 'string' }] } as TaskPorts,
+        }),
+        task({
+          id: 'down',
+          depends_on: ['a', 'b'],
+          prompt: 'Use {{inputs.val}}',
+          driver: 'mock-echo',
+        }),
+      ]);
+
+      const registry = registryWithMock(mockScript, { responses, records });
+      const { events } = await run(config, dir, registry);
+      expect(finalStatusFrom(events, 't.down')).toBe('blocked');
+      const downFinal = finalUpdateFor(events, 't.down');
+      if (downFinal?.type === 'task_update') {
+        expect(downFinal.stderr ?? '').toMatch(/cannot disambiguate|produced by multiple upstream/i);
+      }
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test('prompt with two downstream Commands disagreeing on input type → blocked', async () => {
+    const dir = makeDir();
+    try {
+      const mockScript = writeMockDriverScript(dir);
+      const echo1 = writeEchoArgsScript(dir, 'echo1');
+      const echo2 = writeEchoArgsScript(dir, 'echo2');
+      const responses: Record<string, Record<string, unknown>> = {};
+      const records: Record<string, string> = {};
+
+      const config = pipeline([
+        task({
+          id: 'mid',
+          prompt: 'produce a date',
+          driver: 'mock-echo',
+        }),
+        task({
+          id: 'd1',
+          depends_on: ['mid'],
+          command: `node "${echo1}" "{{inputs.date}}"`,
+          ports: {
+            inputs: [{ name: 'date', type: 'string', required: true }],
+          } as TaskPorts,
+        }),
+        task({
+          id: 'd2',
+          depends_on: ['mid'],
+          command: `node "${echo2}" "{{inputs.date}}"`,
+          ports: {
+            inputs: [{ name: 'date', type: 'number', required: true }],
+          } as TaskPorts,
+        }),
+      ]);
+
+      const registry = registryWithMock(mockScript, { responses, records });
+      const { events } = await run(config, dir, registry);
+      expect(finalStatusFrom(events, 't.mid')).toBe('blocked');
+      const midFinal = finalUpdateFor(events, 't.mid');
+      if (midFinal?.type === 'task_update') {
+        expect(midFinal.stderr ?? '').toMatch(/conflicting type requirements|conflicting output/i);
+      }
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});

package/src/engine.ts

@@ -30,7 +30,13 @@ import {
   renderInputsBlock,
   renderOutputSchemaBlock,
 } from './prompt-doc';
-import { extractTaskOutputs, resolveTaskInputs, substituteInputs } from './ports';
+import {
+  extractTaskOutputs,
+  inferPromptPorts,
+  resolveTaskInputs,
+  substituteInputs,
+} from './ports';
+import type { TaskPorts } from './types';
 import {
   executeHook,
   buildPipelineStartContext,
@@ -393,6 +399,20 @@ export async function runPipeline(
     // just before a task runs, so every subsequent task_update event can
     // echo them to the UI without re-resolving.
     const resolvedInputsMap = new Map<string, Readonly<Record<string, unknown>>>();
+    // Reverse adjacency: for each task, list the direct-downstream task ids
+    // (tasks whose `depends_on` includes this one after DAG qualification).
+    // Computed once up front so Prompt-task port inference — which needs
+    // "what Commands directly consume me?" — is O(1) instead of O(tasks)
+    // per Prompt start. `dag.nodes` only exposes forward edges via
+    // `dependsOn`, so we build this locally.
+    const directDownstreams = new Map<string, string[]>();
+    for (const [id] of dag.nodes) directDownstreams.set(id, []);
+    for (const [id, node] of dag.nodes) {
+      for (const upstream of node.dependsOn) {
+        const list = directDownstreams.get(upstream);
+        if (list) list.push(id);
+      }
+    }
 
     // Pipeline timeout + abort reason tracking.
     //
@@ -753,7 +773,83 @@ export async function runPipeline(
       // 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);
+      //
+      // Prompt Tasks have no declared ports — their I/O contract is
+      // inferred from direct-neighbor Command Tasks (see ports.ts:
+      // `inferPromptPorts`). We synthesize a `TaskPorts` object and
+      // feed it into the same resolve/substitute/render/extract
+      // 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;
+      let effectivePorts: TaskPorts | undefined = task.ports;
+      let promptInferenceBlockReason: string | null = null;
+
+      if (isPromptTask) {
+        const inference = inferPromptPorts({
+          upstreams: node.dependsOn.map((upstreamId) => {
+            const upstream = dag.nodes.get(upstreamId);
+            const isUpstreamCommand = !!upstream?.task.command;
+            return {
+              taskId: upstreamId,
+              outputs: isUpstreamCommand ? upstream?.task.ports?.outputs : undefined,
+            };
+          }),
+          downstreams: (directDownstreams.get(taskId) ?? []).map((downstreamId) => {
+            const downstream = dag.nodes.get(downstreamId);
+            const isDownstreamCommand = !!downstream?.task.command;
+            return {
+              taskId: downstreamId,
+              inputs: isDownstreamCommand ? downstream?.task.ports?.inputs : undefined,
+            };
+          }),
+        });
+        effectivePorts = inference.ports;
+        if (inference.inputConflicts.length > 0 || inference.outputConflicts.length > 0) {
+          const lines: string[] = [];
+          for (const c of inference.inputConflicts) lines.push(c.reason);
+          for (const c of inference.outputConflicts) lines.push(c.reason);
+          promptInferenceBlockReason = lines.join('\n');
+        }
+      }
+
+      if (promptInferenceBlockReason !== null) {
+        log.error(
+          `[task:${taskId}]`,
+          `blocked — prompt port inference failed:\n${promptInferenceBlockReason}`,
+        );
+        state.result = {
+          exitCode: -1,
+          stdout: '',
+          stderr: `[engine] prompt port inference failed:\n${promptInferenceBlockReason}`,
+          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;
+      }
+
+      // Feed effective ports into `resolveTaskInputs` by shallow-cloning
+      // the task. Prompt tasks get the inferred ports; Command tasks are
+      // unchanged (effectivePorts === task.ports).
+      const taskForResolve: TaskConfig =
+        effectivePorts === task.ports ? task : { ...task, ports: effectivePorts };
+      const inputResolution = resolveTaskInputs(taskForResolve, outputValuesMap, node.dependsOn);
       if (inputResolution.kind === 'blocked') {
         log.error(
           `[task:${taskId}]`,
@@ -792,10 +888,11 @@ export async function runPipeline(
           `optional inputs unresolved (empty in placeholders): ${inputResolution.missingOptional.join(', ')}`,
         );
       }
-      if (task.ports?.inputs && task.ports.inputs.length > 0) {
+      if (effectivePorts?.inputs && effectivePorts.inputs.length > 0) {
         log.debug(
           `[task:${taskId}]`,
-          `resolved inputs: ${JSON.stringify(resolvedInputs)}`,
+          `resolved inputs: ${JSON.stringify(resolvedInputs)}` +
+            (isPromptTask ? ' (inferred from upstream Commands)' : ''),
         );
       }
 
@@ -888,11 +985,11 @@ export async function runPipeline(
           // 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);
+          const outputFormatBlock = renderOutputSchemaBlock(effectivePorts?.outputs);
           if (outputFormatBlock) {
             doc = prependContext(doc, outputFormatBlock);
           }
-          const inputsBlock = renderInputsBlock(task.ports?.inputs, resolvedInputs);
+          const inputsBlock = renderInputsBlock(effectivePorts?.inputs, resolvedInputs);
           if (inputsBlock) {
             doc = prependContext(doc, inputsBlock);
           }
@@ -996,6 +1093,13 @@ export async function runPipeline(
             ...task,
             prompt,
             continue_from: node.resolvedContinueFrom,
+            // Hand the driver the EFFECTIVE port schema rather than the
+            // raw task.ports. For Prompt tasks this is the one inferred
+            // from neighbor Commands; Command tasks are unchanged.
+            // Drivers that introspect ports (e.g. to annotate a system
+            // prompt with the I/O contract) otherwise saw `undefined`
+            // for every prompt and had no way to know the contract.
+            ports: effectivePorts,
           };
           const driverCtx: DriverContext = {
             sessionMap,
@@ -1074,17 +1178,22 @@ export async function runPipeline(
         // through driver-specific logs.
         let extractedOutputs: Readonly<Record<string, unknown>> | null = null;
         if (terminalStatus === 'success') {
+          // 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
+          // outputs to pull, so pre-ports tasks pay nothing for this call.
           const extraction = extractTaskOutputs(
-            task.ports,
+            effectivePorts,
             result.stdout,
             result.normalizedOutput,
           );
-          if (task.ports?.outputs && task.ports.outputs.length > 0) {
+          if (effectivePorts?.outputs && effectivePorts.outputs.length > 0) {
             extractedOutputs = extraction.outputs;
             outputValuesMap.set(taskId, extraction.outputs);
             log.debug(
               `[task:${taskId}]`,
-              `extracted outputs: ${JSON.stringify(extraction.outputs)}`,
+              `extracted outputs: ${JSON.stringify(extraction.outputs)}` +
+                (isPromptTask ? ' (inferred from downstream Commands)' : ''),
             );
             if (extraction.diagnostic) {
               log.error(`[task:${taskId}]`, extraction.diagnostic);