@relayflows/sdk 2.0.22 → 2.0.24

package/src/communication/relay.ts

@@ -0,0 +1,102 @@
+import { randomUUID, createHash } from 'node:crypto';
+import { mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { createProjection } from './projection.js';
+import { brokerEnvironment } from './environment.js';
+
+export interface RelayEvent { kind: string; name?: string; event_id?: string; delivery_id?: string; verification?: string; [key: string]: unknown }
+export interface RelayHandle {
+  name: string;
+  generation?: string;
+  waitForReady(timeout?: number): Promise<{ reason: string }>;
+  release(reason?: string, options?: { deleteIdentity?: boolean }): Promise<unknown>;
+}
+export interface RelayBroker {
+  spawnPty(input: Record<string, unknown>): Promise<RelayHandle>;
+  onEvent(callback: (event: RelayEvent) => void): () => void;
+  shutdown(): Promise<void>;
+}
+export interface RelayMessaging {
+  agents: { register(input: { name: string; type: string }): Promise<{ token: string }>; delete(name: string): Promise<void> };
+  channels: { create(input: { name: string }): Promise<unknown>; get(name: string): Promise<unknown>; join(name: string): Promise<void> };
+  messages: {
+    direct(input: { to: string; text: string; idempotencyKey: string; metadata: Record<string, unknown>; mode: 'wait' }): Promise<{ id: string }>;
+    send(input: { channel: string; text: string; idempotencyKey: string; metadata: Record<string, unknown> }): Promise<unknown>;
+  };
+}
+interface RelayModules {
+  HarnessDriverClient: { spawn(options: Record<string, unknown>): Promise<RelayBroker> };
+  RelaycastMessagingClient: new (options: Record<string, unknown>) => RelayMessaging;
+}
+export async function loadRelayModules(): Promise<RelayModules> {
+  // Variable imports keep optional packages out of ordinary execution and bundles.
+  const driver = '@agent-relay/harness-driver';
+  const sdk = '@agent-relay/sdk';
+  try {
+    const [harness, messaging] = await Promise.all([import(driver), import(sdk)]);
+    return { HarnessDriverClient: harness.HarnessDriverClient, RelaycastMessagingClient: messaging.RelaycastMessagingClient };
+  } catch {
+    throw new Error('Agent communication requires optional @agent-relay/harness-driver and @agent-relay/sdk packages (>=12.3.1).');
+  }
+}
+export function relayWorkspaceKey(env = process.env): string {
+  const key = env.RELAY_API_KEY?.trim();
+  if (!key?.startsWith('rk_live_')) throw new Error('Agent communication requires RELAY_API_KEY for an existing workspace.');
+  return key;
+}
+export interface RelayRuntime {
+  broker: RelayBroker;
+  messaging: RelayMessaging;
+  prefix: string;
+  channel: string;
+  project: ReturnType<typeof createProjection>;
+  close(): Promise<void>;
+}
+const runtimes = new Map<string, { references: number; runtime: Promise<RelayRuntime> }>();
+export async function acquireRelayRuntime(dataDir: string, runId: string): Promise<RelayRuntime> {
+  const key = `${dataDir}\0${runId}`;
+  let entry = runtimes.get(key);
+  if (!entry) {
+    entry = { references: 0, runtime: createRuntime(dataDir, runId) };
+    runtimes.set(key, entry);
+  }
+  entry.references++;
+  try {
+    const runtime = await entry.runtime;
+    let closed = false;
+    return { ...runtime, close: async () => {
+      if (closed) return;
+      closed = true;
+      if (--entry!.references === 0) { runtimes.delete(key); await runtime.close(); }
+    } };
+  } catch (error) {
+    if (--entry.references === 0) runtimes.delete(key);
+    throw error;
+  }
+}
+async function createRuntime(dataDir: string, runId: string): Promise<RelayRuntime> {
+  const workspaceKey = relayWorkspaceKey();
+  const { HarnessDriverClient, RelaycastMessagingClient } = await loadRelayModules();
+  const hash = createHash('sha256').update(runId).digest('hex').slice(0, 12);
+  const prefix = `flow-${hash}-${randomUUID().slice(0, 8)}`;
+  const channel = `wf-${runId.toLowerCase()}`;
+  const options = { workspaceKey, ...(process.env.RELAY_BASE_URL ? { baseUrl: process.env.RELAY_BASE_URL } : {}) };
+  const workspace = new RelaycastMessagingClient(options);
+  const publisher = `${prefix}-journal`;
+  const registration = await workspace.agents.register({ name: publisher, type: 'agent' });
+  let broker: RelayBroker | undefined;
+  try {
+    const messaging = new RelaycastMessagingClient({ ...options, agentToken: registration.token });
+    const cwd = join(dataDir, 'communication', prefix);
+    await mkdir(cwd, { recursive: true, mode: 0o700 });
+    broker = await HarnessDriverClient.spawn({ workspaceKey, brokerName: prefix, cwd, channels: [],
+      ...(process.env.RELAYFLOW_RELAY_BROKER_BIN ? { binaryPath: process.env.RELAYFLOW_RELAY_BROKER_BIN } : {}),
+      env: brokerEnvironment(process.env) });
+    return { broker, messaging, prefix, channel, project: createProjection(messaging, channel, runId), close: async () => {
+      try { await broker!.shutdown(); } finally { await workspace.agents.delete(publisher); }
+    } };
+  } catch (error) {
+    try { await broker?.shutdown(); } finally { await workspace.agents.delete(publisher); }
+    throw error;
+  }
+}

package/src/communication/session.ts

@@ -0,0 +1,84 @@
+import { createHash } from 'node:crypto';
+import type { JournalClient } from '../journal-client.js';
+import type { StepDispatchEvent } from '../protocol.js';
+import type { CommunicationInstruction } from './spec.js';
+import { channelName } from './spec.js';
+import type { RelayRuntime } from './relay.js';
+import type { CommunicationToolRequest } from './tools.js';
+
+/** Journal operations belong to the dispatched worker connection, never the broker. */
+export class CommunicationSession {
+  private readonly pending = new Map<string, number>();
+  private finished = false;
+  private serial: Promise<unknown> = Promise.resolve();
+  constructor(private readonly client: JournalClient, private readonly dispatch: StepDispatchEvent,
+    private readonly spec: CommunicationInstruction, private readonly relay: RelayRuntime,
+    private readonly complete: (summary: string) => void,
+    private readonly fatal: (error: unknown) => void = () => {}) {}
+
+  private identity(from: string, to: string) {
+    const { run_id, step_id, attempt, idempotency_key } = this.dispatch;
+    return { run_id, step_id, attempt, idempotency_key, channel: channelName(from, to) };
+  }
+  private lock<T>(work: () => Promise<T>): Promise<T> {
+    const next = this.serial.then(work);
+    this.serial = next.catch(() => {});
+    return next;
+  }
+  private async journal<T>(write: () => Promise<T>): Promise<T> {
+    try { return await write(); }
+    catch (error) { this.fatal(error); throw error; }
+  }
+  invoke(request: CommunicationToolRequest): Promise<unknown> {
+    return this.lock(async () => {
+      if (this.finished) throw new Error('Communication session has completed');
+      const { operation, values } = request;
+      const [peer, id, text] = values;
+      if (operation === 'send') {
+        if (values.length !== 3 || !peer || !this.spec.outgoing.includes(peer) || !id || !text)
+          throw new Error('Use send DECLARED_PEER STABLE_MESSAGE_ID TEXT');
+        // Only the kernel deduplicates sends across worker attempts.
+        return this.journal(() => this.client.channelAppend({ ...this.identity(this.dispatch.step_id, peer), message_id: id, message: text }));
+      }
+      if (operation === 'ack') {
+        if (values.length !== 2 || !peer || !this.spec.incoming.includes(peer)
+          || !Number.isSafeInteger(Number(id)) || this.pending.get(peer) !== Number(id))
+          throw new Error('Use ack PEER DELIVERY_SEQ from a received message');
+        const result = await this.journal(() => this.client.channelAck({ ...this.identity(peer, this.dispatch.step_id), delivery_seq: Number(id) }));
+        this.pending.delete(peer);
+        return result;
+      }
+      if (operation === 'complete') {
+        if (values.length !== 1 || !peer) throw new Error('Use complete SUMMARY');
+        if (this.pending.size) throw new Error('Acknowledge processed messages before completing');
+        this.finished = true;
+        // Let the tool response flush before releasing its managed process.
+        setTimeout(() => this.complete(peer), 100);
+        return { completed: true };
+      }
+      throw new Error('Unknown communication operation');
+    });
+  }
+  pump(): Promise<void> {
+    return this.lock(async () => {
+      if (this.finished) return;
+      for (const peer of this.spec.incoming) {
+        if (this.pending.has(peer)) continue;
+        const entry = await this.client.channelReceive(this.identity(peer, this.dispatch.step_id));
+        if (!entry) continue;
+        const key = createHash('sha256').update(JSON.stringify([
+          this.dispatch.run_id, this.dispatch.step_id, this.dispatch.attempt, entry.seq,
+        ])).digest('hex');
+        const text = `Flow message from ${peer}; delivery_seq=${entry.seq}.\n${JSON.stringify(entry.payload.message)}\nAfter processing, use the flow helper: ack ${peer} ${entry.seq}.`;
+        const metadata = { run_id: this.dispatch.run_id, step_id: this.dispatch.step_id, delivery_seq: entry.seq };
+        // A successful injection is not a processing acknowledgement.
+        await this.relay.messaging.messages.direct({ to: `${this.relay.prefix}-${this.dispatch.step_id}`,
+          text, metadata, idempotencyKey: key, mode: 'wait' });
+        this.pending.set(peer, entry.seq);
+        this.relay.project({
+          text: `${peer} -> ${this.dispatch.step_id}: ${JSON.stringify(entry.payload.message)}`,
+          metadata, idempotencyKey: `${key}-projection` });
+      }
+    });
+  }
+}

package/src/communication/spec.ts

@@ -0,0 +1,106 @@
+import type { StepSpec } from '../spec.js';
+import { createHash } from 'node:crypto';
+
+export const COMMUNICATION_TYPE = 'relayflows.communication.v1';
+export interface CommunicationEdge { from: string; to: string }
+export interface CommunicationInstruction {
+  type: typeof COMMUNICATION_TYPE;
+  instruction: string;
+  incoming: string[];
+  outgoing: string[];
+  timeoutMs: number;
+}
+const record = (v: unknown): v is Record<string, unknown> => v !== null && typeof v === 'object' && !Array.isArray(v);
+const name = (v: unknown): v is string => typeof v === 'string' && /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/.test(v);
+export function channelName(from: string, to: string): string {
+  return `a2a-${createHash('sha256').update(JSON.stringify([from, to])).digest('hex').slice(0, 24)}`;
+}
+export function communicationInstruction(instruction: unknown): CommunicationInstruction | undefined {
+  if (typeof instruction !== 'string' || !instruction.startsWith('{')) return;
+  let value: unknown;
+  try { value = JSON.parse(instruction); } catch { return; }
+  if (!record(value) || value.type !== COMMUNICATION_TYPE) return;
+  if (Object.keys(value).some(k => !['type', 'instruction', 'incoming', 'outgoing', 'timeoutMs'].includes(k))
+    || typeof value.instruction !== 'string' || !Array.isArray(value.incoming) || !value.incoming.every(name)
+    || !Array.isArray(value.outgoing) || !value.outgoing.every(name)
+    || value.incoming.length + value.outgoing.length === 0
+    || !Number.isSafeInteger(value.timeoutMs) || Number(value.timeoutMs) < 1 || Number(value.timeoutMs) > 900_000) {
+    throw new Error('Invalid agent communication instruction');
+  }
+  return value as unknown as CommunicationInstruction;
+}
+
+/** Authoring sugar only: kernel vocabulary remains agent + declared streams. */
+export function expandCommunication(value: unknown): unknown {
+  if (!record(value) || !('communication' in value)) return value;
+  const { communication, ...flow } = value;
+  if (!record(communication) || Object.keys(communication).some(k => !['links', 'timeoutMs'].includes(k))
+    || !Array.isArray(communication.links) || !Array.isArray(flow.steps)) {
+    throw new Error('communication requires links: [{ from, to }] and optional timeoutMs');
+  }
+  const timeoutMs = communication.timeoutMs ?? 300_000;
+  if (!Number.isSafeInteger(timeoutMs) || Number(timeoutMs) < 1 || Number(timeoutMs) > 900_000) {
+    throw new Error('communication.timeoutMs must be between 1 and 900000');
+  }
+  const steps = flow.steps as Record<string, unknown>[];
+  const byId = new Map(steps.filter(record).map(step => [step.id, step]));
+  const edges: CommunicationEdge[] = [];
+  for (const link of communication.links) {
+    if (!record(link) || Object.keys(link).some(k => !['from', 'to'].includes(k))
+      || !name(link.from) || !name(link.to) || link.from === link.to
+      || byId.get(link.from)?.type !== 'agent' || byId.get(link.to)?.type !== 'agent') {
+      throw new Error('communication links must name two different agent step ids');
+    }
+    if (edges.some(e => e.from === link.from && e.to === link.to)) throw new Error('Duplicate communication link');
+    edges.push({ from: link.from, to: link.to });
+  }
+  const ancestors = (id: string, visited = new Set<string>()): Set<string> => {
+    if (visited.has(id)) return visited;
+    visited.add(id);
+    const step = byId.get(id);
+    for (const dependency of Array.isArray(step?.dependsOn) ? step.dependsOn : []) {
+      if (typeof dependency === 'string') ancestors(dependency, visited);
+    }
+    return visited;
+  };
+  for (const edge of edges) {
+    if (ancestors(edge.from).has(edge.to) || ancestors(edge.to).has(edge.from)) {
+      throw new Error('Communicating agents must be concurrent, not dependency ancestors');
+    }
+  }
+  return { ...flow, steps: steps.map(step => {
+    const incoming = edges.filter(e => e.to === step.id).map(e => e.from);
+    const outgoing = edges.filter(e => e.from === step.id).map(e => e.to);
+    if (!incoming.length && !outgoing.length) return step;
+    if (step.transport === 'relay') throw new Error('communication cannot be combined with task transport: relay');
+    if (typeof step.instruction !== 'string') throw new Error('Communicating agents require an instruction');
+    const surfaces = record(step.surfaces) ? step.surfaces : {};
+    const streams = Array.isArray(surfaces.streams) ? surfaces.streams : [];
+    return { ...step,
+      instruction: JSON.stringify({ type: COMMUNICATION_TYPE, instruction: step.instruction, incoming, outgoing, timeoutMs }),
+      // One writer per directed channel; shared writable channels serialize agents.
+      surfaces: { ...surfaces, streams: [...streams,
+        { stream: channelName(String(step.id), '$receipts') },
+        ...outgoing.map(to => ({ stream: channelName(String(step.id), to) }))] },
+    };
+  }) };
+}
+
+/** Check normalized dependencies too, including implicit input bindings. */
+export function validateCommunicationTopology(steps: StepSpec[]): void {
+  const byId = new Map(steps.map(step => [step.id, step]));
+  const communicating = steps.filter(step => step.type === 'agent' && communicationInstruction(step.instruction));
+  const depends = (id: string, target: string, visited = new Set<string>()): boolean => {
+    if (visited.has(id)) return false;
+    visited.add(id);
+    return byId.get(id)?.dependsOn?.some(parent => parent === target || depends(parent, target, visited)) ?? false;
+  };
+  for (const a of communicating) for (const b of communicating) {
+    if (a.id === b.id || a.type !== 'agent' || b.type !== 'agent') continue;
+    if (depends(a.id, b.id)) throw new Error('Communicating agents must be concurrent, not dependency ancestors');
+    if (a.surfaces?.streams?.some(s => b.surfaces?.streams?.some(t => s.stream === t.stream))
+      || a.surfaces?.workspace?.some(s => b.surfaces?.workspace?.some(t => s.surface === t.surface))) {
+      throw new Error('Communicating agents cannot share writable surfaces: the kernel would serialize them');
+    }
+  }
+}

package/src/communication/tool.ts

@@ -0,0 +1,22 @@
+/** Standalone helper source also works when the SDK is bundled into a binary. */
+export const toolSource = String.raw`
+import { createConnection } from 'node:net';
+import { once } from 'node:events';
+async function main() {
+  const path = process.env.RELAYFLOW_COMMUNICATION_SOCKET;
+  const token = process.env.RELAYFLOW_COMMUNICATION_TOKEN;
+  if (!path || !token) throw new Error('No communication session attached to this agent');
+  const [operation, ...values] = process.argv.slice(2);
+  if (!['send', 'ack', 'complete'].includes(operation)) throw new Error('Use send PEER ID TEXT, ack PEER SEQ, or complete SUMMARY');
+  const socket = createConnection(path);
+  await once(socket, 'connect');
+  socket.setTimeout(30_000, () => socket.destroy(new Error('Communication tool timed out')));
+  socket.end(JSON.stringify({ token, operation, values }) + '\n');
+  let text = '';
+  for await (const chunk of socket) text += chunk;
+  const result = JSON.parse(text);
+  if (typeof result.error === 'string') throw new Error(result.error);
+  process.stdout.write(JSON.stringify(result.result) + '\n');
+}
+void main().catch(error => { console.error(error.message); process.exitCode = 1; });
+`;

package/src/communication/tools.ts

@@ -0,0 +1,50 @@
+import { toolSource } from './tool.js';
+import { createServer, type Socket } from 'node:net';
+import { chmod, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { randomBytes, timingSafeEqual } from 'node:crypto';
+
+export interface CommunicationToolRequest { operation: string; values: string[] }
+export async function openCommunicationTools(invoke: (request: CommunicationToolRequest) => Promise<unknown>) {
+  const directory = await mkdtemp(join(tmpdir(), 'flows-comm-'));
+  const path = join(directory, 'agent.sock');
+  const helperPath = join(directory, 'tool.mjs');
+  const token = randomBytes(32).toString('hex');
+  const sockets = new Set<Socket>();
+  let busy = false;
+  const server = createServer({ allowHalfOpen: true }, socket => {
+    sockets.add(socket);
+    socket.on('close', () => sockets.delete(socket));
+    socket.on('error', () => {});
+    socket.setTimeout(30_000, () => socket.destroy());
+    let text = '';
+    socket.on('data', chunk => {
+      text += chunk;
+      if (Buffer.byteLength(text) > 32_768) socket.destroy();
+    });
+    socket.on('end', async () => {
+      if (busy) { socket.end(JSON.stringify({ error: 'Call communication tools sequentially' })); return; }
+      busy = true;
+      try {
+        const input = JSON.parse(text);
+        if (typeof input.token !== 'string' || Buffer.byteLength(input.token) !== Buffer.byteLength(token)
+          || !timingSafeEqual(Buffer.from(input.token), Buffer.from(token))) throw new Error('Unauthorized communication session');
+        if (typeof input.operation !== 'string' || !Array.isArray(input.values)
+          || !input.values.every((value: unknown) => typeof value === 'string')) throw new Error('Invalid communication tool request');
+        socket.end(JSON.stringify({ result: await invoke({ operation: input.operation, values: input.values }) }));
+      } catch (error) { socket.end(JSON.stringify({ error: error instanceof Error ? error.message : 'Communication tool failed' })); }
+      finally { busy = false; }
+    });
+  });
+  try {
+    await new Promise<void>((resolve, reject) => { server.once('error', reject); server.listen(path, resolve); });
+    await chmod(path, 0o600);
+    await writeFile(helperPath, toolSource, { mode: 0o600 });
+  } catch (error) { await rm(directory, { recursive: true, force: true }); throw error; }
+  return { path, helperPath, token, close: async () => {
+    for (const socket of sockets) socket.destroy();
+    await new Promise<void>((resolve, reject) => server.close(error => error ? reject(error) : resolve()));
+    await rm(directory, { recursive: true, force: true });
+  } };
+}

package/src/communication/worker.ts

@@ -0,0 +1,95 @@
+import { communicationHistory } from './history.js';
+import { basename } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import type { JournalClient } from '../journal-client.js';
+import type { StepDispatchEvent } from '../protocol.js';
+import type { KernelAgentStep } from '../spec.js';
+import { withWorkerLease } from '../worker-lease.js';
+import { workerInstruction } from '../worker-input.js';
+import { resolveCliModel } from '../cli-adapter.js';
+import { channelName, type CommunicationInstruction } from './spec.js';
+import { acquireRelayRuntime, type RelayHandle } from './relay.js';
+import { CommunicationSession } from './session.js';
+import { openCommunicationTools } from './tools.js';
+import { agentEnvironment } from './environment.js';
+
+export function requireCommunicationCli(cli: string | undefined): void {
+  if (!cli?.trim()) throw new Error('Agent communication requires a declared CLI executable');
+}
+export async function completeCommunicationDispatch(client: JournalClient, dispatch: StepDispatchEvent,
+  instruction: CommunicationInstruction, dataDir: string): Promise<void> {
+  const spec = dispatch.spec as KernelAgentStep;
+  requireCommunicationCli(spec.cli);
+  let output: unknown;
+  let completionReason: 'success' | 'worker_error' = 'success';
+  try {
+    output = await withWorkerLease(client, dispatch, signal => run(client, dispatch, instruction, spec, dataDir, signal));
+  } catch (error) {
+    completionReason = 'worker_error';
+    output = { error: error instanceof Error ? error.message : String(error) };
+  }
+  await client.stepComplete(dispatch.run_id, dispatch.step_id, dispatch.attempt, dispatch.idempotency_key,
+    completionReason, { output, usage: { tokens_in: 0, tokens_out: 0, dollars_unmetered: true },
+      started_pins: dispatch.pins, end_pins: dispatch.pins });
+}
+async function run(client: JournalClient, dispatch: StepDispatchEvent, instruction: CommunicationInstruction,
+  spec: KernelAgentStep, dataDir: string, lease: AbortSignal): Promise<unknown> {
+  const controller = new AbortController();
+  const signal = AbortSignal.any([lease, controller.signal, AbortSignal.timeout(instruction.timeoutMs)]);
+  const relay = await acquireRelayRuntime(dataDir, dispatch.run_id);
+  let handle: RelayHandle | undefined;
+  let tools: Awaited<ReturnType<typeof openCommunicationTools>> | undefined;
+  let pumping: Promise<void> | undefined;
+  let receipts = Promise.resolve();
+  let unsubscribe: (() => void) | undefined;
+  try {
+    let resolve!: (value: unknown) => void;
+    let reject!: (reason: unknown) => void;
+    const result = new Promise<unknown>((yes, no) => { resolve = yes; reject = no; });
+    // Install the rejection handler before spawn/readiness can fail.
+    void result.catch(() => {});
+    const abort = () => reject(signal.reason);
+    signal.addEventListener('abort', abort, { once: true });
+    if (signal.aborted) abort();
+    const session = new CommunicationSession(client, dispatch, instruction, relay, summary => resolve({ summary }), reject);
+    tools = await openCommunicationTools(request => session.invoke(request));
+    const quote = (value: string) => "'" + value.replaceAll("'", "'\"'\"'") + "'";
+    const helper = `node ${quote(tools.helperPath)}`;
+    const history = await communicationHistory(client, dispatch, instruction);
+    const prompt = `${workerInstruction(instruction.instruction, dispatch)}${history}\n\nYou are flow agent ${dispatch.step_id}. Concurrent peers send messages automatically into your session through Relay. Do not poll for messages. Use your shell/terminal execution tool with ${helper} for flow communication:\n- send PEER STABLE_ID 'message text' (outgoing peers: ${instruction.outgoing.join(', ') || 'none'})\n- ack PEER DELIVERY_SEQ only after processing that message (incoming peers: ${instruction.incoming.join(', ') || 'none'})\n- complete 'summary' when your task and conversation are finished.\nUse these helpers for all peer communication; do not use Relay MCP messaging tools. Stay available for injected messages until the conversation is complete. Use stable semantic message IDs so retries deduplicate sends.`;
+    const name = `${relay.prefix}-${dispatch.step_id}`;
+    unsubscribe = relay.broker.onEvent(event => {
+      if (event.name !== name || !['delivery_injected', 'delivery_verified'].includes(event.kind)) return;
+      receipts = receipts.then(async () => {
+        await client.streamAppend(dispatch.run_id, channelName(dispatch.step_id, '$receipts'), {
+          kind: event.kind, delivery_id: event.delivery_id, verification: event.verification,
+          attempt: dispatch.attempt, processing_ack: false,
+        });
+      });
+      void receipts.catch(reject);
+    });
+    // Relay supplies each CLI's launch flags and injection behavior.
+    handle = await relay.broker.spawnPty({ name, cli: basename(spec.cli!).replace(/\.exe$/i, ''), task: prompt, channels: [], skipRelayPrompt: true,
+      model: resolveCliModel(spec.cli!, spec.model), cwd: spec.cwd ?? process.cwd(),
+      harnessConfig: { runtime: 'pty', command: quote(spec.cli!), args: [],
+        cwd: spec.cwd ?? process.cwd(), env: { ...agentEnvironment(spec.cli!),
+          RELAYFLOW_COMMUNICATION_SOCKET: tools.path, RELAYFLOW_COMMUNICATION_TOKEN: tools.token },
+        delivery: { mode: 'pty-injection', format: 'relay-block' } } });
+    const ready = await handle.waitForReady(Math.min(instruction.timeoutMs, 90_000));
+    if (ready.reason !== 'ready') throw new Error(`Communication agent did not become ready: ${ready.reason}`);
+    pumping = (async () => {
+      while (!signal.aborted) { await session.pump(); await delay(200, undefined, { signal }); }
+    })();
+    void pumping.catch(error => { if (!controller.signal.aborted) reject(error); });
+    try { return await result; } finally { signal.removeEventListener('abort', abort); }
+  } finally {
+    controller.abort();
+    unsubscribe?.();
+    try { await pumping?.catch(error => { if (error?.name !== 'AbortError') throw error; }); }
+    finally {
+      try { await receipts; }
+      finally { try { await handle?.release('Flow communication attempt ended', { deleteIdentity: true }); }
+        finally { try { await tools?.close(); } finally { await relay.close(); } } }
+    }
+  }
+}

package/src/compile.ts

@@ -43,6 +43,7 @@ import { validateOutputDeclaration } from './output-schema.js';
 import { validateSpec, type ValidationResult } from './validate.js';
 import { snapshotJsonValue } from './json-value.js';
 import { expandYamlHelpers } from './yaml-helpers.js';
+import { expandCommunication, validateCommunicationTopology } from './communication/spec.js';
 
 export class CompileError extends Error {
   readonly errors: string[];
@@ -125,7 +126,7 @@ export function compileSpec(spec: unknown): CompiledFlowSpec {
   let snapshot: unknown;
   try {
     snapshot = snapshotJsonValue(spec, 'spec');
-    snapshot = expandYamlHelpers(snapshot);
+    snapshot = expandCommunication(expandYamlHelpers(snapshot));
   } catch (error) {
     throw new CompileError([
       error instanceof Error ? error.message : 'spec: expected JSON-compatible data',
@@ -155,6 +156,8 @@ export function compileSpec(spec: unknown): CompiledFlowSpec {
   // They are resolved exactly once at the kernel boundary, after public
   // preflight has validated every declaration with truthful provenance.
   const steps = input.steps.map(compileStep);
+  try { validateCommunicationTopology(steps); }
+  catch (error) { throw new CompileError([error instanceof Error ? error.message : String(error)]); }
   const flow: CompiledFlowSpec = {
     version: input.version,
     ...(input.name !== undefined ? { name: input.name } : {}),

package/src/failure-kinds.ts

@@ -77,6 +77,7 @@ export const CHECK_FAILURE_KINDS = [
  */
 export const PREFLIGHT_WARNING_KINDS = [
   'unprovable_effects',
+  'managed_cli_unverified',
   'command_unresolved',
   'command_unprovable',
   'vacuous_gate',
@@ -160,6 +161,21 @@ export interface StepFailedDetails {
   stepType?: string;
   /** The kernel's per-step reason, e.g. `worker_error`, `retries_exhausted`. */
   completionReason?: string;
+  /**
+   * The attempt this failure was recorded on, from the journal entry envelope.
+   * Absent when the journal did not name one — never defaulted to 1, because
+   * "how many attempts ran is unknown" and "exactly one ran" are different
+   * answers and only the second is evidence.
+   */
+  attempt?: number;
+  /**
+   * The step's attempt budget, from `step.attempt.started`'s `max_iterations`.
+   * Reported beside `retries_exhausted` so that reason cannot be read as
+   * "retries happened": a deterministic step's default budget is 1, so a
+   * single failed attempt with no retry at all terminates as
+   * `retries_exhausted`.
+   */
+  maxIterations?: number;
   exitCode?: number;
   /** Terminal-safe UTF-8 excerpt, at most 1,024 bytes. */
   stdoutTail?: string;

package/src/index.ts

@@ -58,7 +58,16 @@ export type { HeaderBudget } from './budget.js';
 export type { StepSpend } from './protocol.js';
 export { SPEC_SCHEMA_VERSION } from './spec.js';
 
-export { CloudFlowError, type CloudConnectionOptions } from './cloud-http.js';
+export { CloudFlowError, type CloudConnectionOptions, type CloudConfigurationReason } from './cloud-http.js';
+export {
+  listCloudRuns, getCloudRunDetail, getCloudRunSteps, getCloudRunLog,
+  type CloudRunSummary, type CloudRunList, type CloudRunDetail, type CloudStep, type CloudStepAttempt,
+  type CloudStepTranscript, type CloudToolCall, type CloudToolCount, type CloudRunLog,
+} from './cloud-read.js';
+export {
+  parseAgentTranscript, renderAgentTranscript,
+  type ParsedTranscript, type TranscriptEntry,
+} from './cloud-transcript.js';
 export {
   runInCloud, getCloudFlowRun, waitForCloudFlowRun,
   type CloudFlowSource, type RunInCloudOptions, type CloudRunReceipt, type CloudRunState,

package/src/journal-client.ts

@@ -237,8 +237,8 @@ export class JournalClient extends EventEmitter {
   }
 
   /** Connection becomes a worker; receives `step.dispatch` events. */
-  workerAttach(workerId: string, stepTypes: StepType[], pins?: Pins, capacity?: number): Promise<VerbContract['worker.attach']['result']> {
-    return this.request('worker.attach', { worker_id: workerId, step_types: stepTypes, pins, capacity });
+  workerAttach(workerId: string, stepTypes: StepType[], pins?: Pins, capacity?: number, requiredStreams?: string[]): Promise<VerbContract['worker.attach']['result']> {
+    return this.request('worker.attach', { worker_id: workerId, step_types: stepTypes, pins, capacity, required_streams: requiredStreams });
   }
 
   /**
@@ -421,6 +421,16 @@ export class JournalClient extends EventEmitter {
     return this.request('event.submit', { spec, event });
   }
 
+  channelAppend(params: VerbContract['channel.append']['params']): Promise<VerbContract['channel.append']['result']> {
+    return this.request('channel.append', params);
+  }
+  channelReceive(params: VerbContract['channel.receive']['params']): Promise<VerbContract['channel.receive']['result']> {
+    return this.request('channel.receive', params);
+  }
+  channelAck(params: VerbContract['channel.ack']['params']): Promise<VerbContract['channel.ack']['result']> {
+    return this.request('channel.ack', params);
+  }
+
   /** Durable channel write; journals `stream.appended`. */
   streamAppend(runId: string, stream: string, message: unknown): Promise<VerbContract['stream.append']['result']> {
     return this.request('stream.append', { run_id: runId, stream, message });