@relayflows/sdk 2.0.55 → 2.0.56

package/src/cloud-deploy.ts

@@ -1,3 +1,4 @@
+import { isFlowName } from './bundle-transport.js';
 import { randomBytes, createHash } from 'node:crypto';
 import { readFile } from 'node:fs/promises';
 import { dirname, resolve } from 'node:path';
@@ -73,10 +74,10 @@ export interface FlowTriggerSource {
 
 export interface DeployToCloudInput {
   path: string;
-  repository: DeployRepository;
+  repository?: DeployRepository;
   sources: FlowTriggerSource[];
   /** The `f.human` approver handle every launched run receives as `input.approver`. */
-  approver: string;
+  approver?: string;
   /** Defaults to the flow's declared name. */
   name?: string;
   /**
@@ -118,7 +119,7 @@ export interface CloudDeployment {
   agentId: string;
   name: string;
   status: string;
-  repository: DeployRepository;
+  repository?: DeployRepository;
   sources: FlowTriggerSource[];
   sourceSha256: string;
   /** What the source declared it needs; the harnesses became `inputs.agents` unless `agents` was given. */
@@ -255,28 +256,32 @@ export async function deployToCloud(
   input: DeployToCloudInput, options: CloudConnectionOptions = {},
 ): Promise<CloudDeployment> {
   const { bytes, source, definition, extensions, projectCli } = await loadDeploySource(input);
-  if (input.sources.length === 0 || input.sources.length > 10) {
-    throw new CloudFlowError('invalid_input', 'Give between one and ten --on trigger sources.');
+  if (input.sources.length > 10) {
+    throw new CloudFlowError('invalid_input', 'Give at most ten --on trigger sources.');
   }
   if (new Set(input.sources.map(s => s.provider)).size !== input.sources.length) {
     throw new CloudFlowError('invalid_input', 'Each trigger provider can be given once.');
   }
-  const approver = input.approver.trim();
-  if (!approver) throw new CloudFlowError('invalid_input', '--approver must name who approves f.human questions.');
+  const manual = input.sources.length === 0;
+  const approver = input.approver?.trim();
+  if (!manual && !input.repository) throw new CloudFlowError('invalid_input', 'Triggered deployments require --repo.');
+  if (!manual && !approver) throw new CloudFlowError('invalid_input', '--approver must name who approves f.human questions.');
   const name = (input.name ?? definition.name).trim();
   if (!name || name.length > 100) throw new CloudFlowError('invalid_input', 'Deployment name must be 1-100 characters.');
+  if (manual && !isFlowName(name)) throw new CloudFlowError('invalid_input',
+    'Manual flow names must start with a letter or digit and contain only letters, digits, underscores or hyphens (up to 100 characters). Use --name.');
   // Scope same-host sources to the target rather than waking on every project.
-  const target = `${input.repository.owner}/${input.repository.name}`;
+  const target = input.repository ? `${input.repository.owner}/${input.repository.name}` : undefined;
   const sources = input.sources.map(s => {
     if (s.provider === 'github' && s.settings['repository'] === undefined) {
-      if (input.repository.host === 'gitlab') {
+      if (input.repository?.host === 'gitlab') {
         throw new CloudFlowError('invalid_input',
           'A GitLab target needs an explicit --on github:repository=owner/name for a GitHub source.');
       }
-      return { ...s, settings: { ...s.settings, repository: target } };
+      return { ...s, settings: { ...s.settings, repository: target! } };
     }
-    if (s.provider === 'gitlab' && s.settings['project'] === undefined && input.repository.host === 'gitlab') {
-      return { ...s, settings: { ...s.settings, project: target } };
+    if (s.provider === 'gitlab' && s.settings['project'] === undefined && input.repository?.host === 'gitlab') {
+      return { ...s, settings: { ...s.settings, project: target! } };
     }
     return s;
   });
@@ -298,7 +303,7 @@ export async function deployToCloud(
   // refused here rather than silently replaced by Claude, which activation
   // would then check while the deployed runs still call the declared CLI.
   const unsupported = requirements.harnesses.filter(harness => !(FLOW_AGENT_HARNESSES as readonly string[]).includes(harness));
-  if (input.agents === undefined && unsupported.length > 0) {
+  if (!manual && input.agents === undefined && unsupported.length > 0) {
     const uses = requirements.harnessUses.filter(use => unsupported.includes(use.harness));
     throw new CloudFlowError('unsupported_source',
       `This flow declares ${uses.map(use => `${use.harness} (${use.detail})`).join(', ')}, which Cloud deployments cannot run yet; `
@@ -307,7 +312,7 @@ export async function deployToCloud(
   const declaredAgents = requirements.harnesses.filter((harness): harness is FlowAgentHarness => !unsupported.includes(harness));
   const agents = input.agents ?? (declaredAgents.length > 0 ? declaredAgents : ['claude']);
   // A draft activates nothing, so Cloud checks nothing; match it here.
-  const connected = input.draft || input.checkConnections === false
+  const connected = manual || input.draft || input.checkConnections === false
     ? []
     : (await ensureIntegrationsConnected(requirements, {
         ...options, workspaceId: workspace.id, ...(input.connect === undefined ? {} : { prompt: input.connect }),

package/src/cloud-flow-source.ts

@@ -0,0 +1,58 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { isFlowName } from './bundle-transport.js';
+import { cloudFetch, CloudFlowError, isCloudRecord, type CloudConnectionOptions } from './cloud-http.js';
+import { prepareCachedFlowRuntime } from './cached-flow-runtime.js';
+
+export interface NamedFlowSource {
+  path: string;
+  flowId: string;
+  flowVersionId: string;
+  sourceSha256: string;
+  source: string;
+}
+
+/** Files win over names; paths and digest references retain their existing meaning. */
+export async function resolveNamedFlow(
+  value: string,
+  options: CloudConnectionOptions & { cacheRoot?: string } = {},
+): Promise<NamedFlowSource | undefined> {
+  if (!isFlowName(value)) return undefined;
+  try {
+    if ((await stat(value)).isFile()) return undefined;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+  }
+  const result = await cloudFetch(`/api/v1/flows/by-name/${encodeURIComponent(value)}`, options, { method: 'GET', detail: true });
+  if (!isCloudRecord(result) || result.name !== value || result.fileType !== 'ts'
+    || typeof result.source !== 'string' || Buffer.byteLength(result.source) > 256_000
+    || typeof result.sourceSha256 !== 'string' || !/^[0-9a-f]{64}$/u.test(result.sourceSha256)
+    || typeof result.flowId !== 'string' || !result.flowId
+    || typeof result.versionId !== 'string' || !result.versionId) {
+    throw new CloudFlowError('invalid_response', 'Cloud returned an invalid named .flow.ts source.');
+  }
+  const digest = (source: string | Buffer): string => createHash('sha256').update(source).digest('hex');
+  if (digest(result.source) !== result.sourceSha256) {
+    throw new CloudFlowError('invalid_response', `Source hash verification failed for flow "${value}".`);
+  }
+  const directory = join(options.cacheRoot ?? join(homedir(), '.agentworkforce', 'flows', 'cache'), value);
+  const path = join(directory, `${result.sourceSha256}.flow.ts`);
+  await mkdir(directory, { recursive: true, mode: 0o700 });
+  if (existsSync(path)) {
+    if (digest(await readFile(path)) !== result.sourceSha256) {
+      throw new CloudFlowError('invalid_input', `Cached source hash verification failed: ${path}. Remove this file and retry.`);
+    }
+  } else {
+    const temporary = `${path}.${randomUUID()}.tmp`;
+    try {
+      await writeFile(temporary, result.source, { mode: 0o600, flag: 'wx' });
+      await rename(temporary, path);
+    } finally { await rm(temporary, { force: true }); }
+  }
+  await prepareCachedFlowRuntime(directory);
+  return { path, flowId: result.flowId, flowVersionId: result.versionId,
+    sourceSha256: result.sourceSha256, source: result.source };
+}

package/src/cloud-mirror-transport.ts

@@ -69,6 +69,8 @@ export interface MirrorRunSource {
    * red "Needs review" row can see it was answered.
    */
   resumedFromRunId?: string;
+  flowId?: string;
+  flowVersionId?: string;
 }
 
 /** One lifecycle event, in the vocabulary Cloud's session event stream uses. */
@@ -98,6 +100,8 @@ export async function registerLocalRun(
     body: JSON.stringify({
       workflow: source.workflow,
       fileType: source.fileType,
+      ...(source.flowId === undefined ? {} : { flowId: source.flowId }),
+      ...(source.flowVersionId === undefined ? {} : { flowVersionId: source.flowVersionId }),
       relayflowVersion: 'v2',
       ...(source.inputs === undefined ? {} : { inputs: source.inputs }),
       ...(source.resumedFromRunId === undefined ? {} : { resumedFromRunId: source.resumedFromRunId }),

package/src/cloud-mirror.ts

@@ -304,6 +304,7 @@ export function createRunMirror(options: RunMirrorOptions): RunMirror {
   let stopped = false;
   /** Set immediately before the terminal callback; nothing may publish after it. */
   let terminalReported = false;
+  const pendingEvents = new Set<Promise<boolean>>();
   let sequence = 0;
   let acknowledged: string | undefined;
   let acknowledgedAt = now();
@@ -558,7 +559,10 @@ export function createRunMirror(options: RunMirrorOptions): RunMirror {
       timer.unref?.();
     },
     event(event) {
-      void options.client.publishEvent(event);
+      if (stopped || terminalReported || pendingEvents.size >= 256) return;
+      const pending = options.client.publishEvent(event);
+      pendingEvents.add(pending);
+      void pending.finally(() => pendingEvents.delete(pending));
     },
     async finish(outcome) {
       if (timer !== undefined) { clearInterval(timer); timer = undefined; }
@@ -592,6 +596,10 @@ export function createRunMirror(options: RunMirrorOptions): RunMirror {
         }
         await uploadTranscripts(deadline);
         await publishFinal(deadline);
+        await Promise.race([
+          Promise.allSettled(pendingEvents),
+          new Promise<void>(done => { setTimeout(done, remaining(deadline)).unref?.(); }),
+        ]);
         // Last, always: this transition revokes the credential every call
         // above depends on.
         terminalReported = true;

package/src/communication/broker-preflight.ts

@@ -0,0 +1,22 @@
+import { createRequire } from 'node:module';
+import { spawnSync } from 'node:child_process';
+import { pathToFileURL } from 'node:url';
+
+const require = createRequire(import.meta.url);
+
+/** Read-only SDK connection probe: never starts a broker or an agent harness. */
+export function checkBrokerEnvironment(cwd = process.cwd()): void {
+  let driver: string;
+  try {
+    require.resolve('@agent-relay/sdk');
+    driver = require.resolve('@agent-relay/harness-driver');
+  } catch {
+    throw new Error('Broker agents require optional @agent-relay/harness-driver and @agent-relay/sdk packages (>=12.3.1).');
+  }
+  const probe = spawnSync(process.execPath, ['--input-type=module', '-e',
+    'const { HarnessDriverClient } = await import(process.argv[1]); const client = HarnessDriverClient.connect({ cwd: process.argv[2] }); try { await client.healthCheck(); } finally { await client.shutdown(); }',
+    pathToFileURL(driver).href, cwd], { encoding: 'utf8', timeout: 10_000, maxBuffer: 64 * 1024 });
+  if (probe.status !== 0) {
+    throw new Error(`Broker agents require a reachable local Relay broker for ${JSON.stringify(cwd)}. Run agent-relay up in the run root or set AGENT_RELAY_STATE_DIR to its connection directory.`);
+  }
+}

package/src/communication/broker-spec.ts

@@ -0,0 +1,48 @@
+import { createHash } from 'node:crypto';
+import type { AgentOptions } from '@relayflows/surface';
+
+export const BROKER_TYPE = 'relayflows.broker.v1';
+export interface BrokerInstruction {
+  type: typeof BROKER_TYPE;
+  operation: 'spawn' | 'message' | 'release';
+  owner: string;
+  flow: string;
+  step: string;
+  agentName: string;
+  task: string;
+  cwd?: string;
+  skills: string[];
+  channel: string;
+  keepAlive: boolean;
+  timeoutMs: number;
+}
+export function brokerAgentName(flow: string, step: string, owner: string, id: string): string {
+  const label = `${flow}-${step}`.toLowerCase().replace(/[^a-z0-9_-]+/g, '-').replace(/^-+/, '') || 'flow-agent';
+  return `${label.slice(0, 46)}-${createHash('sha256').update(JSON.stringify([owner, id])).digest('hex').slice(0, 16)}`;
+}
+export function brokerOptionsError(options: AgentOptions): string | undefined {
+  if (options.transport !== 'broker') {
+    if (options.skills !== undefined || options.keepAlive !== undefined || options.channel !== undefined) {
+      return 'skills, keepAlive, and channel require transport: broker';
+    }
+    return;
+  }
+  if (options.resume !== undefined) return 'broker sessions use f.message instead of resume';
+  if (options.keepAlive !== undefined && typeof options.keepAlive !== 'boolean') return 'keepAlive must be a boolean';
+  if (options.channel !== undefined && (typeof options.channel !== 'string' || !/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,127}$/.test(options.channel))) return 'channel must be a channel name';
+  if (options.skills !== undefined && (!Array.isArray(options.skills)
+    || !options.skills.every(skill => typeof skill === 'string' && /^[a-z0-9][a-z0-9-]{0,99}$/.test(skill)))) return 'skills must be canonical skill names';
+  if (options.cwd !== undefined && (typeof options.cwd !== 'string' || !options.cwd.trim() || options.cwd.includes('\0'))) return 'cwd must be a nonempty directory path';
+}
+export function brokerInstruction(raw: unknown): BrokerInstruction | undefined {
+  if (typeof raw !== 'string' || !raw.startsWith('{')) return;
+  let value: any;
+  try { value = JSON.parse(raw); } catch { return; }
+  if (value?.type !== BROKER_TYPE) return;
+  if (!['spawn', 'message', 'release'].includes(value.operation)
+    || !['owner', 'flow', 'step', 'agentName', 'task', 'channel'].every(key => typeof value[key] === 'string' && value[key].length > 0)
+    || !Number.isSafeInteger(value.timeoutMs) || value.timeoutMs < 1 || value.timeoutMs > 3_600_000
+    || !Array.isArray(value.skills) || typeof value.keepAlive !== 'boolean'
+    || brokerOptionsError({ ...value, transport: 'broker' })) throw new Error('Invalid broker agent instruction');
+  return value;
+}

package/src/communication/broker-worker.ts

@@ -0,0 +1,198 @@
+import { realpath, stat } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import type { JournalClient } from '../journal-client.js';
+import type { StepDispatchEvent } from '../protocol.js';
+import type { ResolvedKernelAgentStep } from '../resolved-cli-identity.js';
+import { isLeaseLost, withWorkerLease } from '../worker-lease.js';
+import { isReadInterruptionError } from '../journal-read-policy.js';
+import { workerInstruction } from '../worker-input.js';
+import { connectLocalBroker, type LocalBroker } from './relay.js';
+import { spawnFlowPty, shellQuote } from './pty.js';
+import { installBrokerSkills } from './skills.js';
+import { openCommunicationTools } from './tools.js';
+import type { BrokerInstruction } from './broker-spec.js';
+
+interface Turn {
+  id: string;
+  completed?: boolean;
+  resolve(summary: string): void;
+  reject(error: unknown): void;
+}
+interface Session {
+  owner: string;
+  broker: LocalBroker;
+  pty?: Awaited<ReturnType<typeof spawnFlowPty>>;
+  tools?: Awaited<ReturnType<typeof openCommunicationTools>>;
+  turn?: Turn;
+  unsubscribe?: () => void;
+  exited?: string;
+  releasing?: Promise<void>;
+}
+
+/** Worker-owned live resources. Only journaled agent dispatches start a turn. */
+export class BrokerSessions {
+  private readonly sessions = new Map<string, Session>();
+  constructor(private readonly runRoot: string = process.cwd(), private readonly environment?: NodeJS.ProcessEnv) {}
+
+  async close(): Promise<void> {
+    const results = await Promise.allSettled([...this.sessions.keys()].map(name => this.release(name)));
+    const errors = results.flatMap(result => result.status === 'rejected' ? [result.reason] : []);
+    if (errors.length) throw new AggregateError(errors, 'Failed to release flow broker sessions');
+  }
+
+  private async release(name: string): Promise<void> {
+    const session = this.sessions.get(name);
+    if (!session) return;
+    if (session.releasing) return session.releasing;
+    session.releasing = Promise.resolve().then(() => this.releaseSession(name, session));
+    try { await session.releasing; }
+    finally { session.releasing = undefined; }
+  }
+
+  private async releaseSession(name: string, session: Session): Promise<void> {
+    session.turn?.reject(new Error('Broker session released'));
+    await session.pty?.handle.release('Flow broker session ended', { deleteIdentity: true });
+    session.unsubscribe?.();
+    try { await session.tools?.close(); }
+    finally { try { await session.pty?.close(); } finally { await session.broker.shutdown(); } }
+    this.sessions.delete(name);
+  }
+
+  async complete(client: JournalClient, dispatch: StepDispatchEvent, instruction: BrokerInstruction, dataDir: string): Promise<void> {
+    let output: unknown;
+    let reason: 'success' | 'worker_error' | 'timeout' = 'success';
+    try {
+      output = await withWorkerLease(client, dispatch, signal => this.run(dispatch, instruction, dataDir, signal,
+        client.supportsFeature?.('step_secret_scoping') ?? true));
+    } catch (error) {
+      if (isLeaseLost(error) || isReadInterruptionError(error)) throw error;
+      reason = error instanceof Error && error.name === 'TimeoutError' ? 'timeout' : 'worker_error';
+      output = { error: error instanceof Error ? error.message : String(error) };
+    }
+    try {
+      await client.stepComplete(dispatch.run_id, dispatch.step_id, dispatch.attempt, dispatch.idempotency_key,
+        reason, { output, usage: { tokens_in: 0, tokens_out: 0, dollars_unmetered: true },
+          started_pins: dispatch.pins, end_pins: dispatch.pins });
+    } catch (error) {
+      await this.release(instruction.agentName);
+      throw error;
+    }
+  }
+
+  private async run(dispatch: StepDispatchEvent, instruction: BrokerInstruction, dataDir: string, lease: AbortSignal,
+    scopeSecrets = true): Promise<unknown> {
+    const { agentName: name, owner } = instruction;
+    let session = this.sessions.get(name);
+    if (session && session.owner !== owner) throw new Error('Broker agent belongs to another flow');
+    if (session?.turn) throw new Error('Broker agent already has work in progress');
+    if (instruction.operation === 'release') {
+      await this.release(name);
+      return { released: true };
+    }
+    if (session?.exited) {
+      await this.release(name);
+      throw new Error(`Broker agent ${name}: ${session.exited}`);
+    }
+    if (instruction.operation === 'message' && !session) {
+      throw new Error(`Broker agent ${name} is no longer available; its worker session was lost or released`);
+    }
+    if (instruction.operation === 'spawn' && session) throw new Error(`Broker agent ${name} already exists`);
+    const deadline = AbortSignal.timeout(instruction.timeoutMs);
+    const signal = AbortSignal.any([lease, deadline]);
+    const turnId = `${dispatch.run_id}:${dispatch.step_id}:${dispatch.attempt}`;
+    let succeed!: (summary: string) => void;
+    let fail!: (error: unknown) => void;
+    const result = new Promise<string>((yes, no) => { succeed = yes; fail = no; });
+    void result.catch(() => {});
+    let abortWait!: (error: unknown) => void;
+    const aborted = new Promise<never>((_, reject) => { abortWait = reject; });
+    void aborted.catch(() => {});
+    const abort = () => { fail(signal.reason); abortWait(signal.reason); };
+    signal.addEventListener('abort', abort, { once: true });
+    if (signal.aborted) abort();
+    let succeeded = false;
+    try {
+      if (instruction.operation === 'spawn') {
+        const spec = dispatch.spec as ResolvedKernelAgentStep;
+        if (!spec.cli) throw new Error('Broker agent requires a declared CLI');
+        const cwd = await realpath(resolve(this.runRoot, instruction.cwd ?? '.'));
+        if (!(await stat(cwd)).isDirectory()) throw new Error(`Broker cwd is not a directory: ${cwd}`);
+        signal.throwIfAborted();
+        await installBrokerSkills(instruction.skills, spec.cli_identity ?? spec.cli, cwd, signal);
+        const broker = await connectLocalBroker(this.runRoot);
+        session = { owner, broker, turn: { id: turnId, resolve: succeed, reject: fail } };
+        this.sessions.set(name, session);
+        const current = session;
+        session.tools = await openCommunicationTools(async ({ operation, values }) => {
+          if (operation !== 'complete' || values.length !== 2 || values[0] !== current.turn?.id || current.turn?.completed) {
+            throw new Error('Use complete CURRENT_TURN_ID JSON_SUMMARY; stale and duplicate completions are refused');
+          }
+          const summary = JSON.stringify(JSON.parse(values[1]!));
+          const turn = current.turn;
+          turn!.completed = true;
+          // Allow the helper's response to flush before releasing the PTY.
+          setTimeout(() => turn!.resolve(summary), 100);
+          return { completed: true };
+        });
+        session.unsubscribe = broker.onEvent(event => {
+          if (event.name !== name || !['agent_exit', 'agent_exited', 'agent_released'].includes(event.kind)) return;
+          current.exited = event.kind;
+          if (!current.turn?.completed) current.turn?.reject(new Error(`Broker agent ${name}: ${event.kind}`));
+          // An idle exit retires resources immediately. A failed release stays
+          // in the map and is retried (and surfaced) on the next call or close.
+          if (!current.turn) void this.release(name).catch(() => {});
+        });
+        broker.connectEvents();
+        const task = `${workerInstruction(instruction.task, dispatch)}\n\n${this.completionPrompt(session, turnId)}\n${instruction.keepAlive ? 'Stay alive after completing; later flow steps can send more work.' : 'The flow releases this session after completion.'}`;
+        const spawned = spawnFlowPty(broker, { name, cli: spec.cli, identity: spec.cli_identity,
+          model: spec.model, task, cwd, dataDir, skipRelayPrompt: false, channels: [instruction.channel], team: `flow-${owner}`,
+          environment: this.environment, socket: session.tools.path, token: session.tools.token,
+          secrets: spec.secrets, scopeSecrets,
+          metadata: { runId: owner, flow: instruction.flow, step: instruction.step } });
+        let pty: Awaited<ReturnType<typeof spawnFlowPty>> | undefined;
+        try {
+          pty = await Promise.race([spawned, aborted]);
+          signal.throwIfAborted();
+          session.pty = pty;
+        } catch (error) {
+          // Spawn can resolve after the timeout. The session release below
+          // only sees a handle that was stored in time.
+          if (session.pty === undefined) void spawned.then(async late => {
+            try { await late.handle.release('Flow broker session ended', { deleteIdentity: true }); }
+            catch { /* The timed-out step is already journaled. */ }
+            try { await late.close(); }
+            catch { /* A failed link removal must not reject this detached cleanup. */ }
+          }, () => {});
+          throw error;
+        }
+        const ready = await Promise.race([session.pty.handle.waitForReady(Math.min(instruction.timeoutMs, 90_000)),
+          result.then(() => ({ reason: 'ready' }))]);
+        if (ready.reason !== 'ready') throw new Error(`Broker agent did not become ready: ${ready.reason}`);
+      } else {
+        session!.turn = { id: turnId, resolve: succeed, reject: fail };
+        signal.throwIfAborted();
+        const receipt = await Promise.race([session!.broker.sendMessage({ to: name, from: `flow-${owner}`,
+          text: `${instruction.task}\n\n${this.completionPrompt(session!, turnId)}`, mode: 'wait',
+          data: { runId: owner, flow: instruction.flow, step: instruction.step, turnId } }), aborted]);
+        if (!receipt.targets.includes(name) || receipt.event_id === 'unsupported_operation') {
+          throw new Error(`Broker did not accept the message for ${name}`);
+        }
+      }
+      const summary = await result;
+      signal.throwIfAborted();
+      succeeded = true;
+      return { completionReason: 'success', summary, artifacts: [], agentName: name };
+    } catch (error) {
+      if (signal.aborted) throw signal.reason;
+      throw error;
+    } finally {
+      signal.removeEventListener('abort', abort);
+      if (session) session.turn = undefined;
+      if (!succeeded || !instruction.keepAlive || session?.exited) await this.release(name);
+    }
+  }
+
+  private completionPrompt(session: Session, turn: string): string {
+    return `Report completion with your shell tool: node ${shellQuote(session.tools!.helperPath)} complete ${shellQuote(turn)} 'JSON_SUMMARY'. The summary must be valid JSON (object, array, or string). Call exactly once for this turn, after the work is finished.`;
+  }
+}

package/src/communication/pty.ts

@@ -0,0 +1,47 @@
+import { mkdir, mkdtemp, rm, symlink } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+import { agentEnvironment } from './environment.js';
+import { resolveCliModel } from '../cli-adapter.js';
+import type { RelayBroker } from './relay.js';
+
+export const shellQuote = (value: string) => "'" + value.replaceAll("'", "'\"'\"'") + "'";
+
+/** Both communication steps and retained sessions use Relay's PTY launch contract. */
+export async function spawnFlowPty(broker: Pick<RelayBroker, 'spawnPty'>, options: {
+  name: string; cli: string; identity?: string; model?: string; task: string;
+  skipRelayPrompt?: boolean;
+  cwd: string; dataDir: string; channels: string[]; team?: string;
+  environment?: NodeJS.ProcessEnv; socket: string; token: string;
+  secrets?: string[]; scopeSecrets?: boolean;
+  metadata?: { runId: string; flow: string; step: string };
+}) {
+  const identity = options.identity ?? options.cli;
+  const argv0 = basename(identity);
+  let command = options.cli;
+  let link: string | undefined;
+  try {
+    if (basename(command) !== argv0) {
+      const root = join(options.dataDir, 'communication');
+      await mkdir(root, { recursive: true, mode: 0o700 });
+      link = await mkdtemp(join(root, 'cli-'));
+      command = join(link, argv0);
+      await symlink(options.cli, command, 'file');
+    }
+    const handle = await broker.spawnPty({ name: options.name, cli: argv0.replace(/\.exe$/i, ''),
+      task: options.task, channels: options.channels, skipRelayPrompt: options.skipRelayPrompt ?? true,
+      ...(options.team === undefined ? {} : { team: options.team }),
+      model: resolveCliModel(identity, options.model), cwd: options.cwd,
+      harnessConfig: { runtime: 'pty', command: shellQuote(command), args: [], cwd: options.cwd,
+        env: { ...agentEnvironment(identity, options.environment ?? process.env,
+          options.secrets, options.scopeSecrets ?? true),
+          RELAYFLOW_COMMUNICATION_SOCKET: options.socket, RELAYFLOW_COMMUNICATION_TOKEN: options.token,
+          ...(options.metadata === undefined ? {} : {
+            RELAYFLOW_RUN_ID: options.metadata.runId, RELAYFLOW_FLOW_NAME: options.metadata.flow,
+            RELAYFLOW_STEP_NAME: options.metadata.step,
+          }) }, delivery: { mode: 'pty-injection', format: 'relay-block' } } });
+    return { handle, close: async () => { if (link) await rm(link, { recursive: true, force: true }); } };
+  } catch (error) {
+    if (link) await rm(link, { recursive: true, force: true });
+    throw error;
+  }
+}

package/src/communication/relay.ts

@@ -25,7 +25,8 @@ export interface RelayMessaging {
   };
 }
 interface RelayModules {
-  HarnessDriverClient: { spawn(options: Record<string, unknown>): Promise<RelayBroker> };
+  HarnessDriverClient: { spawn(options: Record<string, unknown>): Promise<RelayBroker>;
+    connect(options: { cwd: string }): LocalBroker };
   RelaycastMessagingClient: new (options: Record<string, unknown>) => RelayMessaging;
 }
 export async function loadRelayModules(): Promise<RelayModules> {
@@ -100,3 +101,13 @@ async function createRuntime(dataDir: string, runId: string): Promise<RelayRunti
     throw error;
   }
 }
+
+/** Connected clients disconnect on shutdown; they never terminate the user's broker. */
+export interface LocalBroker extends RelayBroker {
+  connectEvents(): void;
+  sendMessage(input: { to: string; text: string; from: string; mode: 'wait'; data: Record<string, unknown> }): Promise<{ event_id: string; targets: string[] }>;
+}
+export async function connectLocalBroker(cwd: string): Promise<LocalBroker> {
+  const { HarnessDriverClient } = await loadRelayModules();
+  return HarnessDriverClient.connect({ cwd });
+}

package/src/communication/skills.ts

@@ -0,0 +1,16 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { basename } from 'node:path';
+
+const execute = promisify(execFile);
+/** Install full skill directories (including references) using the canonical package. */
+export async function installBrokerSkills(skills: string[], cli: string, cwd: string, signal: AbortSignal): Promise<void> {
+  if (!skills.length) return;
+  const identity = basename(cli).replace(/\.exe$/i, '');
+  const harness = ({ claude: 'claude-code', codex: 'codex', gemini: 'gemini-cli',
+    'cursor-agent': 'cursor', opencode: 'opencode' } as Record<string, string>)[identity];
+  if (!harness) throw new Error(`Skill installation is unsupported for broker CLI ${identity}`);
+  await execute('npx', ['--yes', 'skills', 'add', 'https://github.com/AgentWorkforce/skills',
+    '--skill', ...skills, '--agent', harness, '--yes', '--copy'],
+  { cwd, signal, timeout: 120_000, maxBuffer: 1024 * 1024 });
+}

package/src/communication/worker.ts

@@ -1,6 +1,4 @@
 import { communicationHistory } from './history.js';
-import { mkdir, mkdtemp, rm, symlink } from 'node:fs/promises';
-import { basename, join } from 'node:path';
 import { setTimeout as delay } from 'node:timers/promises';
 import type { JournalClient } from '../journal-client.js';
 import type { StepDispatchEvent } from '../protocol.js';
@@ -8,13 +6,12 @@ import type { ResolvedKernelAgentStep } from '../resolved-cli-identity.js';
 import { isLeaseLost, withWorkerLease } from '../worker-lease.js';
 import { isReadInterruptionError } from '../journal-read-policy.js';
 import { workerInstruction } from '../worker-input.js';
-import { resolveCliModel } from '../cli-adapter.js';
 import { resolveAgentCwd } from '../agent-cwd.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';
+import { spawnFlowPty, shellQuote } from './pty.js';
 
 export function requireCommunicationCli(cli: string | undefined): void {
   if (!cli?.trim()) throw new Error('Agent communication requires a declared CLI executable');
@@ -62,7 +59,7 @@ async function run(client: JournalClient, dispatch: StepDispatchEvent, instructi
   let pumping: Promise<void> | undefined;
   let receipts = Promise.resolve();
   let unsubscribe: (() => void) | undefined;
-  let cliLinkDirectory: string | undefined;
+  let pty: Awaited<ReturnType<typeof spawnFlowPty>> | undefined;
   try {
     let resolve!: (value: unknown) => void;
     let reject!: (reason: unknown) => void;
@@ -74,8 +71,7 @@ async function run(client: JournalClient, dispatch: StepDispatchEvent, instructi
     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 helper = `node ${shellQuote(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}`;
@@ -89,24 +85,11 @@ async function run(client: JournalClient, dispatch: StepDispatchEvent, instructi
       });
       void receipts.catch(reject);
     });
-    // Relay supplies each CLI's launch flags and injection behavior.
-    const cliIdentity = spec.cli_identity ?? spec.cli!;
-    const argv0 = basename(cliIdentity);
-    let command = spec.cli!;
-    if (basename(command) !== argv0) {
-      const linkRoot = join(dataDir, 'communication');
-      await mkdir(linkRoot, { recursive: true, mode: 0o700 });
-      cliLinkDirectory = await mkdtemp(join(linkRoot, 'cli-'));
-      command = join(cliLinkDirectory, argv0);
-      await symlink(spec.cli!, command, 'file');
-    }
-    handle = await relay.broker.spawnPty({ name, cli: basename(cliIdentity).replace(/\.exe$/i, ''), task: prompt, channels: [], skipRelayPrompt: true,
-      model: resolveCliModel(cliIdentity, spec.model), cwd: directory,
-      harnessConfig: { runtime: 'pty', command: quote(command), args: [],
-        cwd: directory, env: { ...agentEnvironment(cliIdentity, environment ?? process.env,
-          spec.secrets, client.supportsFeature?.('step_secret_scoping') ?? true),
-          RELAYFLOW_COMMUNICATION_SOCKET: tools.path, RELAYFLOW_COMMUNICATION_TOKEN: tools.token },
-        delivery: { mode: 'pty-injection', format: 'relay-block' } } });
+    pty = await spawnFlowPty(relay.broker, { name, cli: spec.cli!, identity: spec.cli_identity,
+      model: spec.model, task: prompt, channels: [], cwd: directory, dataDir,
+      environment, socket: tools.path, token: tools.token,
+      secrets: spec.secrets, scopeSecrets: client.supportsFeature?.('step_secret_scoping') ?? true });
+    handle = pty.handle;
     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 () => {
@@ -123,7 +106,7 @@ async function run(client: JournalClient, dispatch: StepDispatchEvent, instructi
       finally { try { await handle?.release('Flow communication attempt ended', { deleteIdentity: true }); }
         finally { try { await tools?.close(); } finally {
           try { await relay.close(); }
-          finally { if (cliLinkDirectory) await rm(cliLinkDirectory, { recursive: true, force: true }); }
+          finally { await pty?.close(); }
         } } }
     }
   }

package/src/failure-kinds.ts

@@ -138,6 +138,8 @@ export const RUN_FAILURE_KINDS = [
   'unsafe_parallel_runtime',
   /** A predicate `.gate(fn)` judged false; the verdict is journaled as `<step>.gate`. */
   'gate_failed',
+  /** A resumed serial body reached a journaled step id with a different call; refused, not executed. */
+  'serial_replay_order_mismatch',
   /** `flows answer` named a wait the run is not asking: unknown, or already answered. */
   'human_wait_unknown',
   /** `f.memory.learn` was given a finding without non-empty string fields. */