@tagma/sdk 0.6.7 → 0.6.9

package/src/ports.test.ts

@@ -2,6 +2,7 @@ import { describe, expect, test } from 'bun:test';
 import {
   extractInputReferences,
   extractTaskOutputs,
+  inferPromptPorts,
   resolveTaskInputs,
   substituteInputs,
 } from './ports';
@@ -299,3 +300,172 @@ describe('extractTaskOutputs', () => {
     expect(r.diagnostic).toContain('could not find a final-line JSON object');
   });
 });
+
+// ─── inferPromptPorts ───────────────────────────────────────────────
+
+describe('inferPromptPorts', () => {
+  test('inputs are taken from direct-upstream Command outputs', () => {
+    const r = inferPromptPorts({
+      upstreams: [
+        {
+          taskId: 't.up',
+          outputs: [
+            { name: 'city', type: 'string' },
+            { name: 'id', type: 'number' },
+          ],
+        },
+      ],
+      downstreams: [],
+    });
+    expect(r.inputConflicts).toEqual([]);
+    expect(r.outputConflicts).toEqual([]);
+    expect(r.ports.inputs).toHaveLength(2);
+    expect(r.ports.inputs?.map((p) => p.name).sort()).toEqual(['city', 'id']);
+    // Inferred inputs default to required: the LLM wouldn't see a real
+    // value if the upstream failed to produce one.
+    expect(r.ports.inputs?.every((p) => p.required === true)).toBe(true);
+    expect(r.ports.outputs).toBeUndefined();
+  });
+
+  test('outputs are taken from direct-downstream Command inputs', () => {
+    const r = inferPromptPorts({
+      upstreams: [],
+      downstreams: [
+        {
+          taskId: 't.down',
+          inputs: [
+            { name: 'greeting', type: 'string', required: true },
+            { name: 'target', type: 'string', default: 'world' },
+          ],
+        },
+      ],
+    });
+    expect(r.outputConflicts).toEqual([]);
+    expect(r.ports.outputs?.map((p) => p.name).sort()).toEqual(['greeting', 'target']);
+    // Outputs drop input-only fields (required, default, from).
+    for (const p of r.ports.outputs ?? []) {
+      expect(p).not.toHaveProperty('required');
+      expect(p).not.toHaveProperty('default');
+      expect(p).not.toHaveProperty('from');
+    }
+    expect(r.ports.inputs).toBeUndefined();
+  });
+
+  test('Prompt neighbors (outputs undefined) contribute nothing', () => {
+    const r = inferPromptPorts({
+      upstreams: [
+        { taskId: 't.up', outputs: undefined }, // Prompt upstream
+      ],
+      downstreams: [
+        { taskId: 't.down', inputs: undefined }, // Prompt downstream
+      ],
+    });
+    expect(r.ports).toEqual({});
+    expect(r.inputConflicts).toEqual([]);
+    expect(r.outputConflicts).toEqual([]);
+  });
+
+  test('two upstreams with the same output name produce an input conflict', () => {
+    const r = inferPromptPorts({
+      upstreams: [
+        { taskId: 't.a', outputs: [{ name: 'city', type: 'string' }] },
+        { taskId: 't.b', outputs: [{ name: 'city', type: 'string' }] },
+      ],
+      downstreams: [],
+    });
+    expect(r.inputConflicts).toHaveLength(1);
+    expect(r.inputConflicts[0]!.portName).toBe('city');
+    expect(r.inputConflicts[0]!.producers.map((p) => p.taskId).sort()).toEqual(['t.a', 't.b']);
+    expect(r.inputConflicts[0]!.reason).toMatch(/cannot disambiguate/);
+  });
+
+  test('two downstreams with compatible input types merge silently', () => {
+    const r = inferPromptPorts({
+      upstreams: [],
+      downstreams: [
+        {
+          taskId: 't.d1',
+          inputs: [{ name: 'date', type: 'string', required: true }],
+        },
+        {
+          taskId: 't.d2',
+          inputs: [{ name: 'date', type: 'string', required: false }],
+        },
+      ],
+    });
+    expect(r.outputConflicts).toEqual([]);
+    expect(r.ports.outputs).toHaveLength(1);
+    expect(r.ports.outputs![0]!.name).toBe('date');
+    expect(r.ports.outputs![0]!.type).toBe('string');
+  });
+
+  test('two downstreams with incompatible input types produce an output conflict', () => {
+    const r = inferPromptPorts({
+      upstreams: [],
+      downstreams: [
+        { taskId: 't.d1', inputs: [{ name: 'date', type: 'string' }] },
+        { taskId: 't.d2', inputs: [{ name: 'date', type: 'number' }] },
+      ],
+    });
+    expect(r.outputConflicts).toHaveLength(1);
+    expect(r.outputConflicts[0]!.portName).toBe('date');
+    expect(r.outputConflicts[0]!.reason).toMatch(/conflicting type requirements/);
+  });
+
+  test('enum ports with differing value sets are incompatible', () => {
+    const r = inferPromptPorts({
+      upstreams: [],
+      downstreams: [
+        {
+          taskId: 't.d1',
+          inputs: [{ name: 'bucket', type: 'enum', enum: ['a', 'b'] }],
+        },
+        {
+          taskId: 't.d2',
+          inputs: [{ name: 'bucket', type: 'enum', enum: ['a', 'c'] }],
+        },
+      ],
+    });
+    expect(r.outputConflicts).toHaveLength(1);
+  });
+
+  test('enum ports with identical value sets merge', () => {
+    const r = inferPromptPorts({
+      upstreams: [],
+      downstreams: [
+        {
+          taskId: 't.d1',
+          inputs: [{ name: 'bucket', type: 'enum', enum: ['a', 'b'] }],
+        },
+        {
+          taskId: 't.d2',
+          inputs: [{ name: 'bucket', type: 'enum', enum: ['b', 'a'] }], // different order, same set
+        },
+      ],
+    });
+    expect(r.outputConflicts).toEqual([]);
+    expect(r.ports.outputs).toHaveLength(1);
+  });
+
+  test('description and enum propagate from the first occurrence', () => {
+    const r = inferPromptPorts({
+      upstreams: [
+        {
+          taskId: 't.up',
+          outputs: [
+            {
+              name: 'kind',
+              type: 'enum',
+              enum: ['hot', 'cold'],
+              description: 'Weather kind',
+            },
+          ],
+        },
+      ],
+      downstreams: [],
+    });
+    const port = r.ports.inputs![0]!;
+    expect(port.description).toBe('Weather kind');
+    expect(port.enum).toEqual(['hot', 'cold']);
+  });
+});

package/src/ports.ts

@@ -1,6 +1,6 @@
-// ═══ Task ports: substitute / resolve / extract ═══
+// ═══ Task ports: substitute / resolve / extract / infer ═══
 //
-// One module, three concerns, all keyed on `task.ports`:
+// One module, four concerns, all keyed on `task.ports`:
 //
 //   1. `substituteInputs(text, inputs)` — expand `{{inputs.<name>}}` in
 //      user-authored strings (command lines, prompts). Strict syntax, no
@@ -22,10 +22,19 @@
 //      it. Prefer `normalizedOutput` for AI tasks, fall back to raw
 //      stdout — command tasks only ever have stdout.
 //
+//   4. `inferPromptPorts({upstreams, downstreams})` — Prompt Tasks do NOT
+//      declare ports; their I/O contract is inferred from direct-neighbor
+//      Command Tasks. This helper synthesizes a `TaskPorts` object the
+//      engine can feed into the three concerns above, and surfaces any
+//      collisions that block the task (same port name on two upstreams,
+//      incompatible types across downstreams, …). Prompt neighbors
+//      contribute zero structured I/O — they pass free text via
+//      `continue_from` / normalizedOutput instead.
+//
 // 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, TaskConfig, TaskPorts } from './types';
+import type { PortDef, PortType, TaskConfig, TaskPorts } from './types';
 
 // ─── Template substitution ────────────────────────────────────────────
 
@@ -440,3 +449,222 @@ function safeParseJson(candidate: string): Record<string, unknown> | null {
   }
   return null;
 }
+
+// ─── Prompt-task port inference ───────────────────────────────────────
+//
+// Prompt Tasks have no declared ports. The engine calls `inferPromptPorts`
+// to synthesize one from the Task's direct DAG neighbors:
+//
+//   - **inputs** are taken from the declared `outputs` of every direct
+//     upstream Command Task. The union of names becomes the Prompt's
+//     inferred inputs. Upstream Prompt neighbors contribute nothing —
+//     information flows between Prompts as free text through
+//     `continue_from` / normalizedOutput, not through port values.
+//
+//   - **outputs** are taken from the declared `inputs` of every direct
+//     downstream Command Task. The union of names becomes the Prompt's
+//     inferred outputs, which drives the `[Output Format]` block that
+//     tells the LLM what JSON to emit. Downstream Prompt neighbors
+//     contribute nothing (they just consume free text).
+//
+// Collisions:
+//
+//   - **Input collision**: two upstream Commands both export an output
+//     named `city`. Command→Command would let a downstream add
+//     `from: taskId.city` to pick one; Prompt Tasks have no port
+//     declarations and therefore no escape hatch. The only fix is to
+//     rename on the Command side. We surface this as an `inputConflicts`
+//     entry; the engine blocks the task with that reason.
+//
+  //   - **Output collision with compatible types** (e.g. both downstreams
+  //     ask for `date: string`) → merged into a single inferred output.
+  //     Compatibility is determined by `type` and `enum` only; `description`
+  //     differences are ignored. The Prompt produces one `date`; both
+  //     downstreams consume it.
+//
+//   - **Output collision with incompatible types** (e.g. one downstream
+//     wants `date: string`, another `date: number`) → no single LLM
+//     emission can satisfy both. Surfaced as `outputConflicts`; engine
+//     blocks the task. User must rename on one side.
+
+export interface PromptUpstreamNeighbor {
+  readonly taskId: string;
+  /**
+   * Declared outputs of the upstream task. `undefined` signals that the
+   * neighbor is a Prompt Task (no structured contribution) or otherwise
+   * has no outputs to offer. The inference logic treats `undefined` and
+   * an empty array the same way — neither contributes ports.
+   */
+  readonly outputs: readonly PortDef[] | undefined;
+}
+
+export interface PromptDownstreamNeighbor {
+  readonly taskId: string;
+  /**
+   * Declared inputs of the downstream task. `undefined` signals a
+   * Prompt-Task neighbor or a Command Task without declared inputs.
+   * Either way it contributes no ports to the inferred output contract.
+   */
+  readonly inputs: readonly PortDef[] | undefined;
+}
+
+export interface PromptPortConflict {
+  readonly portName: string;
+  readonly producers: readonly { readonly taskId: string; readonly type: PortType }[];
+  /** Pre-formatted human-readable reason for logs / stderr. */
+  readonly reason: string;
+}
+
+export interface PromptPortInference {
+  /**
+   * Synthetic `TaskPorts` the engine feeds into the resolve / substitute /
+   * render / extract helpers, exactly as if the Prompt had declared these
+   * ports itself. Empty arrays are preserved as absent so downstream code
+   * paths treat "no ports" uniformly (see engine.ts's existing
+   * `task.ports?.outputs && task.ports.outputs.length > 0` guard).
+   */
+  readonly ports: TaskPorts;
+  readonly inputConflicts: readonly PromptPortConflict[];
+  readonly outputConflicts: readonly PromptPortConflict[];
+}
+
+/**
+ * Derive the effective `TaskPorts` for a Prompt Task from its direct
+ * neighbors. See the module-level "Prompt-task port inference" comment
+ * for the full contract.
+ *
+ * Pure function — no side effects, safe to call from the CLI, editor
+ * preview, and engine hot path alike.
+ */
+export function inferPromptPorts(input: {
+  readonly upstreams: readonly PromptUpstreamNeighbor[];
+  readonly downstreams: readonly PromptDownstreamNeighbor[];
+}): PromptPortInference {
+  const { upstreams, downstreams } = input;
+
+  // ─── Inputs: union of upstream-Command outputs ─────────────────────
+  //
+  // Walk every upstream in DAG order. First occurrence of a name wins
+  // (for the synthesized port shape used to resolve values). Subsequent
+  // occurrences under the same name become an `inputConflicts` entry —
+  // the engine blocks the task because a Prompt can't disambiguate.
+  const inputsByName = new Map<string, { port: PortDef; firstProducer: string }>();
+  const inputCollisionSources = new Map<string, { taskId: string; type: PortType }[]>();
+
+  for (const upstream of upstreams) {
+    if (!upstream.outputs || upstream.outputs.length === 0) continue;
+    for (const out of upstream.outputs) {
+      const prior = inputsByName.get(out.name);
+      if (!prior) {
+        // Copy the shape verbatim but drop output-only fields and force
+        // `required: true`. Prompt-task inferred inputs are required by
+        // default: the LLM wouldn't be getting a real-world value
+        // otherwise, and substituting an empty string silently is the
+        // same kind of bug we already reject elsewhere.
+        inputsByName.set(out.name, {
+          port: {
+            name: out.name,
+            type: out.type,
+            ...(out.description ? { description: out.description } : {}),
+            ...(out.enum ? { enum: [...out.enum] } : {}),
+            required: true,
+          },
+          firstProducer: upstream.taskId,
+        });
+        continue;
+      }
+      // Collision — seed the source list with the first producer too so
+      // the emitted conflict lists *all* contributing producers.
+      const list = inputCollisionSources.get(out.name) ?? [
+        { taskId: prior.firstProducer, type: prior.port.type },
+      ];
+      list.push({ taskId: upstream.taskId, type: out.type });
+      inputCollisionSources.set(out.name, list);
+    }
+  }
+
+  const inputConflicts: PromptPortConflict[] = [];
+  for (const [portName, producers] of inputCollisionSources) {
+    const producerList = producers.map((p) => p.taskId).join(', ');
+    inputConflicts.push({
+      portName,
+      producers,
+      reason:
+        `input "${portName}" is produced by multiple upstream Commands (${producerList}) — ` +
+        `Prompt tasks cannot disambiguate (no explicit "from:" binding). ` +
+        `Rename the output on one of the upstream Commands.`,
+    });
+  }
+
+  // ─── Outputs: union of downstream-Command inputs ───────────────────
+  //
+  // Compatible repeats merge (preserve first-encountered shape; prefer
+  // required when any downstream requires it). Incompatible repeats
+  // (different type, different enum set) go to `outputConflicts`.
+  const outputsByName = new Map<string, { port: PortDef; firstConsumer: string }>();
+  const outputCollisionSources = new Map<string, { taskId: string; type: PortType }[]>();
+
+  for (const downstream of downstreams) {
+    if (!downstream.inputs || downstream.inputs.length === 0) continue;
+    for (const inp of downstream.inputs) {
+      const prior = outputsByName.get(inp.name);
+      if (!prior) {
+        // Outputs drop input-only fields (required, default, from).
+        outputsByName.set(inp.name, {
+          port: {
+            name: inp.name,
+            type: inp.type,
+            ...(inp.description ? { description: inp.description } : {}),
+            ...(inp.enum ? { enum: [...inp.enum] } : {}),
+          },
+          firstConsumer: downstream.taskId,
+        });
+        continue;
+      }
+      if (portsAreCompatible(prior.port, inp)) continue; // merge silently
+      const list = outputCollisionSources.get(inp.name) ?? [
+        { taskId: prior.firstConsumer, type: prior.port.type },
+      ];
+      list.push({ taskId: downstream.taskId, type: inp.type });
+      outputCollisionSources.set(inp.name, list);
+    }
+  }
+
+  const outputConflicts: PromptPortConflict[] = [];
+  for (const [portName, producers] of outputCollisionSources) {
+    const consumerList = producers.map((p) => `${p.taskId} (${p.type})`).join(', ');
+    outputConflicts.push({
+      portName,
+      producers,
+      reason:
+        `output "${portName}" has conflicting type requirements across downstream Commands ` +
+        `(${consumerList}) — a single LLM emission cannot satisfy both. ` +
+        `Rename the input on one of the downstream Commands.`,
+    });
+  }
+
+  const inferredInputs = [...inputsByName.values()].map((e) => e.port);
+  const inferredOutputs = [...outputsByName.values()].map((e) => e.port);
+
+  const ports: TaskPorts = {
+    ...(inferredInputs.length > 0 ? { inputs: inferredInputs } : {}),
+    ...(inferredOutputs.length > 0 ? { outputs: inferredOutputs } : {}),
+  };
+  return { ports, inputConflicts, outputConflicts };
+}
+
+/**
+ * Two ports with the same name are compatible if they agree on `type`
+ * and, for enum ports, on the enum value set. Descriptions and
+ * required/default flags are deliberately ignored — they don't affect
+ * whether a single value can satisfy both consumers.
+ */
+function portsAreCompatible(a: PortDef, b: PortDef): boolean {
+  if (a.type !== b.type) return false;
+  if (a.type === 'enum') {
+    const aEnum = [...(a.enum ?? [])].sort().join('');
+    const bEnum = [...(b.enum ?? [])].sort().join('');
+    if (aEnum !== bEnum) return false;
+  }
+  return true;
+}

package/src/runner.test.ts

@@ -55,10 +55,10 @@ test('runSpawn: oversized output — bounded tail in memory, full bytes on disk'
     expect(result.exitCode).toBe(0);
     // Total bytes reported match reality
     expect(result.stdoutBytes).toBe(totalBytes);
-    // In-memory tail bounded (tail + truncation marker header is a couple
-    // hundred bytes at most; give it slack)
+    // In-memory tail bounded above (tail + truncation marker header is a
+    // couple hundred bytes at most; give it slack). No lower bound — chunk
+    // boundaries are platform-dependent so the exact retained size varies.
     expect(result.stdout.length).toBeLessThan(cap + 1024);
-    expect(result.stdout.length).toBeGreaterThan(cap - 1024);
     // Truncation breadcrumb present and points at the full output
     expect(result.stdout).toContain('truncated from head');
     expect(result.stdout).toContain(stdoutPath);

package/src/runner.ts

@@ -114,12 +114,20 @@ async function collectStream(
   const chunks: Uint8Array[] = [];
   let tailBytes = 0;
   let totalBytes = 0;
-  const reader = stream.getReader();
+  let streamError: Error | null = null;
 
   try {
-    for (;;) {
-      const { done, value } = await reader.read();
-      if (done) break;
+    // Use for await...of to avoid Bun bug where getReader() returns an
+    // incomplete reader missing releaseLock() under concurrent spawn.
+    // https://github.com/oven-sh/bun/issues/28952
+    //
+    // Bun 1.3.x also has sporadic failures iterating a spawned process's
+    // stream under concurrent Bun.spawn — the iterator throws mid-drain even
+    // when the child exited 0. We record the error as a breadcrumb instead
+    // of propagating, so the caller still sees the real exitCode from
+    // proc.exited and a task that the OS considered successful doesn't get
+    // marked failed over a runtime stream glitch.
+    for await (const value of stream as AsyncIterable<Uint8Array>) {
       totalBytes += value.length;
 
       // Disk: persist every byte. Failure here degrades to tail-only mode
@@ -157,8 +165,12 @@ async function collectStream(
         tailBytes = chunks[0]!.length;
       }
     }
+  } catch (err) {
+    streamError = err instanceof Error ? err : new Error(String(err));
+    console.error(
+      `[runner] stream read failed: ${streamError.message} — returning partial output`,
+    );
   } finally {
-    reader.releaseLock();
     if (fh) {
       try {
         await fh.close();
@@ -187,6 +199,10 @@ async function collectStream(
     text = `[…${dropped} bytes truncated from head — full output at: ${pathHint}]\n${text}`;
   }
 
+  if (streamError) {
+    text = text + `\n[runner] stream read aborted: ${streamError.message}`;
+  }
+
   return {
     text,
     totalBytes,

package/src/sdk.ts

@@ -27,7 +27,11 @@ export {
 
 // ── Raw config validation (real-time feedback) ──
 export { validateRaw } from './validate-raw';
-export type { ValidationError } from './validate-raw';
+export type { ValidationError, KnownPluginTypes } from './validate-raw';
+
+// ── YAML compiler (validation + compile log support) ──
+export { compileYamlContent } from './yaml-compiler';
+export type { YamlCompileResult, CompileYamlOptions } from './yaml-compiler';
 
 // ── Schema: parse / resolve / load / serialize / validate ──
 export {
@@ -127,8 +131,17 @@ export {
   extractInputReferences,
   resolveTaskInputs,
   extractTaskOutputs,
+  inferPromptPorts,
+} from './ports';
+export type {
+  SubstituteResult,
+  InputResolution,
+  ExtractResult,
+  PromptPortInference,
+  PromptPortConflict,
+  PromptUpstreamNeighbor,
+  PromptDownstreamNeighbor,
 } from './ports';
-export type { SubstituteResult, InputResolution, ExtractResult } from './ports';
 
 // ── All types from @tagma/types + runtime constants ──
 export * from './types';