@relayflows/sdk 2.0.54 → 2.0.56

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. */

package/src/plugin-manifest.ts

@@ -39,7 +39,7 @@ export interface PluginManifest {
   preflight: { credentials: readonly string[]; servers: readonly string[] };
 }
 const identifier = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
-const reserved = new Set(['run', 'llm', 'agent', 'human', 'dispatch', 'done', 'cloud', 'memory', 'mcp', 'slack', '__proto__', 'constructor', 'prototype', 'then']);
+const reserved = new Set(['run', 'llm', 'agent', 'message', 'release', 'human', 'dispatch', 'done', 'cloud', 'memory', 'mcp', 'slack', '__proto__', 'constructor', 'prototype', 'then']);
 const object = (v: unknown): v is Record<string, unknown> => typeof v === 'object' && v !== null && !Array.isArray(v);
 const strings = (v: unknown): v is string[] => Array.isArray(v) && v.every(s => typeof s === 'string' && s.trim().length > 0);
 export function pluginPackageName(name: string): string {

package/src/preflight.ts

@@ -1,3 +1,4 @@
+import { brokerInstruction } from './communication/broker-spec.js';
 import { communicationInstruction } from './communication/spec.js';
 import { loadPlugins, type LoadedPlugin } from './plugin-loader.js';
 import { PluginError } from './plugin-manifest.js';
@@ -340,7 +341,8 @@ function preflightSync(flow: unknown, options: PreflightOptions): PreflightResul
     }
     const resolution = resolutionByStep.get(step.id)!;
     probeResolvedCli(resolution, options.probes, cliProbeResults, diagnostics,
-      step.type === 'agent' && communicationInstruction(step.instruction) !== undefined, step.secrets);
+      step.type === 'agent' && (communicationInstruction(step.instruction) !== undefined || brokerInstruction(step.instruction) !== undefined),
+      step.secrets);
   }
 
   for (const trigger of compiled.triggers ?? []) {

package/src/worker.ts

@@ -1,3 +1,5 @@
+import { brokerInstruction } from './communication/broker-spec.js';
+import { BrokerSessions } from './communication/broker-worker.js';
 import { communicationInstruction } from './communication/spec.js';
 import { workerSpend } from './worker-spend.js';
 import { reportedCost } from './reported-cost.js';
@@ -60,6 +62,7 @@ export interface AgentWorkerOptions {
  * shutdown.
  */
 export class AgentWorker extends EventEmitter {
+  private readonly brokerSessions: BrokerSessions;
   private attached = false;
   private closing = false;
   private readonly inFlight: Set<Promise<void>> = new Set();
@@ -69,6 +72,7 @@ export class AgentWorker extends EventEmitter {
     private readonly options: AgentWorkerOptions,
   ) {
     super();
+    this.brokerSessions = new BrokerSessions(options.runRoot, options.environment);
   }
 
   async attach(): Promise<void> {
@@ -107,6 +111,7 @@ export class AgentWorker extends EventEmitter {
     if (pending.length > 0) {
       await Promise.allSettled(pending);
     }
+    await this.brokerSessions.close();
     this.attached = false;
   }
 
@@ -128,6 +133,12 @@ export class AgentWorker extends EventEmitter {
       await completeHelperDispatch(this.client, dispatch, helper, this.options.dataDir);
       return;
     }
+    const broker = brokerInstruction(spec.instruction);
+    if (broker) {
+      if (!this.options.dataDir) throw new Error('Broker agents require a worker data directory');
+      await this.brokerSessions.complete(this.client, dispatch, broker, this.options.dataDir);
+      return;
+    }
     const communication = communicationInstruction(spec.instruction);
     if (communication) {
       if (!this.options.dataDir) throw new Error('Agent communication requires a worker data directory');