@relayflows/sdk 2.0.55 → 2.0.57

package/src/communication/skills.ts

@@ -0,0 +1,17 @@
+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, '');
+  // Devin reads .windsurf/skills, which the canonical skills installer supports.
+  const harness = ({ claude: 'claude-code', codex: 'codex', gemini: 'gemini-cli',
+    'cursor-agent': 'cursor', opencode: 'opencode', devin: 'windsurf' } 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/devin-runtime.ts

@@ -0,0 +1,33 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import type { CliInvocation } from './adapters/base.js';
+
+/** Private attempt/probe state, never the user's interactive Devin login. */
+export function prepareDevinRuntime(environment: NodeJS.ProcessEnv, invocation?: CliInvocation) {
+  let root: string | undefined;
+  const env = { ...environment };
+  const args = [...(invocation?.args ?? [])];
+  const directory = () => root ??= mkdtempSync(join(environment.TMPDIR ?? tmpdir(), 'relayflows-devin-'));
+  const close = () => { if (root !== undefined) rmSync(root, { recursive: true, force: true }); };
+  try {
+    if (env.DEVIN_API_KEY !== undefined) {
+      const key = env.DEVIN_API_KEY.trim();
+      if (!key) throw new Error('DEVIN_API_KEY must not be empty');
+      const data = join(directory(), 'data');
+      mkdirSync(join(data, 'devin'), { recursive: true, mode: 0o700 });
+      writeFileSync(join(data, 'devin', 'credentials.toml'),
+        `windsurf_api_key = ${JSON.stringify(key)}\n`, { mode: 0o600 });
+      env.XDG_DATA_HOME = data;
+      env.XDG_CONFIG_HOME = join(directory(), 'config');
+      env.XDG_CACHE_HOME = join(directory(), 'cache');
+      delete env.DEVIN_API_KEY;
+    }
+    if (invocation?.promptFile !== undefined) {
+      const path = join(directory(), 'prompt.txt');
+      writeFileSync(path, invocation.promptFile, { mode: 0o600 });
+      args.push('--prompt-file', path);
+    }
+    return { env, args, close };
+  } catch (error) { close(); throw error; }
+}

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';
@@ -10,7 +11,7 @@ import type { TriggerSource } from '@relayflows/surface';
 import { acceptsAnyOutput, inspectStepGate, type StepGateInspection } from './gate-contract.js';
 import { compileSpec, CompileError } from './compile.js';
 import { helperCall } from './yaml-helpers.js';
-import { resolveCliModelSelection, type CliModelSource } from './cli-adapter.js';
+import { cliAdapterKind, resolveCliModelSelection, type CliModelSource } from './cli-adapter.js';
 import { isNamedGate, NAMED_GATE_FAILURE_KINDS, type NamedGateFailureKind } from './named-gates.js';
 import { namedGateScanCoverageDiagnostics } from './named-gate-preflight.js';
 import { compileScopes, type ScopeInput, type MountRegistry } from './scope-compiler.js';
@@ -64,6 +65,7 @@ export interface CliProbeResult {
 
 export type CliProbeFailureDetail =
   | 'spawn_failed'
+  | 'devin_api_key_empty'
   | `timeout:${number}ms`
   | `signal:${string}`;
 
@@ -285,6 +287,10 @@ export function resolvePreflight(flow: unknown, options: ResolutionOptions): Pre
         message: unresolvedCliMessage(step.id, options),
       });
     } else {
+      if (step.type === 'llm' && cliAdapterKind(resolution.cli) === 'devin') {
+        cliResolutionDiagnostics.push({ severity: 'refusal', kind: 'cli_unsupported', stepId: step.id,
+          cli: resolution.cli, message: `Step "${step.id}" uses Devin for an llm step; Devin supports agent steps only.` });
+      }
       resolutions.push(resolution);
       resolutionByStep.set(step.id, resolution);
     }
@@ -340,7 +346,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 ?? []) {
@@ -592,13 +599,16 @@ function probeResolvedCli(
       kind: 'cli_unsupported',
       stepId: resolution.stepId,
       cli: resolution.cli,
-      message: `Step "${resolution.stepId}" declares CLI "${resolution.cli}", but it is neither a supported raw Claude/Codex executable nor a conforming Relayflows wrapper; custom wrappers must identify with the relayflows-agent-cli-v1 contract.`,
+      message: `Step "${resolution.stepId}" declares CLI "${resolution.cli}", but it is neither a supported raw Claude/Codex/Devin executable nor a conforming Relayflows wrapper; custom wrappers must identify with the relayflows-agent-cli-v1 contract.`,
     });
   } else if (managed && result.authenticated === 'unverified') {
     diagnostics.push({ severity: 'warning', kind: 'managed_cli_unverified', stepId: resolution.stepId,
       message: `Step "${resolution.stepId}" uses Relay's interactive CLI transport. The executable exists, but authentication${resolution.model ? ' and access to model "' + resolution.model + '"' : ''} could not be verified before startup. The managed session must execute its task and report completion; startup or task failure fails the step.` });
   } else if (result.authenticated !== true) {
     const command = result.authCommand ?? `${resolution.cli} auth status`;
+    const loginHint = cliAdapterKind(resolution.cli) === 'devin'
+      ? ' For hosted flows, set FLOW_DEVIN_API_KEY to a Devin CLI login token; local runs use DEVIN_API_KEY. A REST API key is a different credential.'
+      : '';
     // Say what the probe reported. A refusal that names only the command turns
     // a transient provider rejection and a genuinely unauthenticated CLI into
     // the same message, and the difference decides whether retrying is
@@ -614,7 +624,7 @@ function probeResolvedCli(
       kind: 'cli_unauthenticated',
       stepId: resolution.stepId,
       cli: resolution.cli,
-      message: `Step "${resolution.stepId}" declares CLI "${resolution.cli}", but "${command}" exited non-zero${exitCode}; authenticate it or repair that adapter's authentication probe.${detail}`,
+      message: `Step "${resolution.stepId}" declares CLI "${resolution.cli}", but "${command}" exited non-zero${exitCode}; authenticate it or repair that adapter's authentication probe.${detail}${loginHint}`,
     });
   } else if (resolution.model !== undefined && result.modelAvailable !== true) {
     diagnostics.push(modelProbeRefusal(resolution as CliResolution & { model: string }, result));
@@ -666,6 +676,7 @@ function probeFailedMessage(
 ): string {
   const prefix = `Could not verify CLI "${resolution.cli}" for step "${resolution.stepId}"`;
   if (detail === undefined) return `${prefix}.`;
+  if (detail === 'devin_api_key_empty') return `${prefix}: DEVIN_API_KEY must contain a non-empty Devin CLI login token. For hosted flows, set FLOW_DEVIN_API_KEY.`;
   if (detail === 'spawn_failed') return `${prefix}: the probe process could not be started.`;
   if (detail.startsWith('signal:')) {
     return `${prefix}: the probe was terminated by signal "${detail.slice('signal:'.length)}".`;

package/src/step-secrets.ts

@@ -47,6 +47,7 @@ const CLI_LOGIN: Record<CliAdapterKind, readonly string[]> = {
     'AWS_SESSION_TOKEN', 'AWS_REGION', 'AWS_DEFAULT_REGION',
   ],
   codex: ['CODEX_HOME', 'OPENAI_API_KEY', 'OPENAI_BASE_URL', 'OPENAI_API_BASE', 'OPENROUTER_API_KEY'],
+  devin: ['DEVIN_API_KEY', 'DEVIN_MODEL'],
   'relayflows-wrapper-v1': [],
 };
 

package/src/worker-cli.ts

@@ -45,6 +45,7 @@ import {
   type AgentTransport,
 } from './agent-relay-transport.js';
 import { pinCliAlias } from './cli/pinned-cli-alias.js';
+import { prepareDevinRuntime } from './devin-runtime.js';
 import { promptOperand } from './adapters/base.js';
 
 export type { CliTransportCause, CliTransportEvidence, CliTransportPhase } from './cli-transport-evidence.js';
@@ -277,15 +278,22 @@ export async function runAgentCli(
   // The flags go before the `--` that ends the task operand (promptOperand):
   // after it they would reach the CLI as task text, not options.
   const args = [...invocation.args];
-  args.splice(args.length - promptOperand('').length, 0, ...(kind === 'claude' ? ['--output-format', 'stream-json', '--verbose'] : ['--json']));
+  if (kind !== 'devin') args.splice(args.length - promptOperand('').length, 0, ...(kind === 'claude' ? ['--output-format', 'stream-json', '--verbose'] : ['--json']));
   const completion = kind === 'claude' ? claudeResultOutcome : undefined;
   // Retain the source values for output redaction even though the child
   // receives only its filtered environment. A provider can echo a value from
   // its prompt or fixture that was not granted as an environment variable.
-  const redactionEnvironment = { ...processEnvironment, ...env };
-  return requirePricedUsage(decodeProviderResult(await spawnInvocation(
-    cli, { ...invocation, args }, env, signal, sidechannel, cwd, completion, argv0, kind, redactionEnvironment,
-  ), kind, redactionEnvironment), effectiveModel);
+  const redactionEnvironment = { ...processEnvironment, ...env,
+    ...(kind === 'devin' && env.DEVIN_API_KEY !== undefined ? { DEVIN_API_KEY: env.DEVIN_API_KEY.trim() } : {}) };
+  const prepared = kind === 'devin' ? prepareDevinRuntime(env, { ...invocation, args }) : undefined;
+  try {
+    const result = await spawnInvocation(cli,
+      { ...invocation, args: prepared?.args ?? args }, prepared?.env ?? env,
+      signal, sidechannel, cwd, completion, argv0, kind, redactionEnvironment);
+    // Print mode has neither provider frames nor authoritative token counts.
+    return kind === 'devin' ? { ...result, stdout_tail: redactText(result.stdout_tail, redactionEnvironment) }
+      : requirePricedUsage(decodeProviderResult(result, kind, redactionEnvironment), effectiveModel);
+  } finally { prepared?.close(); }
   }
 }
 

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');