@relayflows/sdk 2.0.54 → 2.0.56

package/src/cli/direct-run.ts

@@ -221,7 +221,8 @@ export async function runDirectFlow(
     // diagnostic carried up from `classifyOutcome` already names the step, its
     // exit code and its output tail; this branch is what lets it reach the
     // terminal. `resumeFlow` takes the same branch, through the same helper.
-    if (error instanceof AuthoredFlowExecutionError && (error.code === 'step_failed' || error.code === 'gate_failed')) {
+    if (error instanceof AuthoredFlowExecutionError && (error.code === 'step_failed' || error.code === 'gate_failed'
+      || error.code === 'serial_replay_order_mismatch')) {
       return authoredStepFailure('run', base, socketPath, error);
     }
     if (error instanceof AuthoredFlowExecutionError && error.code === 'result_unreadable') {

package/src/cli/run.ts

@@ -7,6 +7,7 @@ import { communicationInstruction } from '../communication/spec.js';
 import { checkCommunicationEnvironment, CommunicationEnvironmentError } from '../communication/preflight.js';
 import { parseHumanRecipient } from '../human-to.js';
 import { parseDigestReference } from '../bundle-transport.js';
+import { resolveNamedFlow } from '../cloud-flow-source.js';
 import { prepareDigestRun } from './run-digest.js';
 import { attachReuseSummary } from './reuse.js';
 import { resumeHelperEffect } from '../authored-helper-effect.js';
@@ -47,6 +48,7 @@ import { DEFAULT_LOCAL_AGENT_CAPACITY } from '../worker-slots.js';
 import { localAgentEnvironment } from '../local-agent-environment.js';
 import {
   checkFlow,
+  inputFailureReport,
   type CheckReport,
 } from './check.js';
 
@@ -182,6 +184,17 @@ export async function runFlow(
   dataDir: string,
   options: RunLifecycleOptions = {},
 ): Promise<RunExecution> {
+  try {
+    const named = await resolveNamedFlow(path);
+    if (named) {
+      const { runDirectFlow } = await import('./direct-run.js');
+      return runDirectFlow(named.path, '{}', dataDir, options);
+    }
+  } catch (error) {
+    return { exitCode: 2, report: fromCheckReport('run', inputFailureReport({
+      kind: 'input_unreadable', message: error instanceof Error ? error.message : String(error),
+    }, path)) };
+  }
   const agentEnvironment = localAgentEnvironment();
   const prepared = parseDigestReference(path) ? await prepareDigestRun(path, options.bucket) : undefined;
   if (prepared && 'exitCode' in prepared) return prepared;
@@ -432,7 +445,8 @@ export async function resumeFlow(
     // leaving it on `protocolFailure` meant `flows run` printed the evidence
     // while `flows resume` still printed `protocol_error` and
     // `RUN <id> unknown` for the identical failure.
-    if (error instanceof AuthoredFlowExecutionError && (error.code === 'step_failed' || error.code === 'gate_failed')) {
+    if (error instanceof AuthoredFlowExecutionError && (error.code === 'step_failed' || error.code === 'gate_failed'
+      || error.code === 'serial_replay_order_mismatch')) {
       return authoredStepFailure('resume', base, socketPath, error, runId);
     }
     if (error instanceof AuthoredFlowExecutionError && error.code === 'result_unreadable') {
@@ -632,10 +646,11 @@ export function authoredStepFailure(
         severity: 'failure',
         // A predicate gate that judged false is a run failure with its own
         // name, so the report says which kind of check the body did not pass.
-        kind: error.code === 'gate_failed' ? 'gate_failed' : 'step_failed',
+        // A refused out-of-order replay names itself the same way.
+        kind: error.code === 'gate_failed' || error.code === 'serial_replay_order_mismatch' ? error.code : 'step_failed',
         // The `step_failed: ` prefix `AuthoredFlowExecutionError` adds is
         // redundant once the diagnostic is labelled `[step_failed]`.
-        message: error.message.replace(/^(?:step_failed|gate_failed): /, ''),
+        message: error.message.replace(/^(?:step_failed|gate_failed|serial_replay_order_mismatch): /, ''),
       }],
     },
   };

package/src/cli.ts

@@ -1,4 +1,7 @@
 #!/usr/bin/env node
+import { resolveNamedFlow, type NamedFlowSource } from './cloud-flow-source.js';
+import { isFlowName } from './bundle-transport.js';
+import { CloudFlowError } from './cloud-http.js';
 import { unavailableValidation, validationAnnotation, type DaemonValidationMode } from './daemon-spec-validation.js';
 import { foldUnprovableEffects, type FoldOptions } from './cli/diagnostic-fold.js';
 import { startDetachedRun, emitDetachedHandle } from './cli/detached-run.js';
@@ -134,6 +137,7 @@ const USAGE = [
   'flows plugin update [--json] [--yes] [--to <ref>] [<name>]',
   'flows build [--out <dir>] <flow.yaml|flow.ts>',
   'flows build --verify <bundle-dir>',
+  'flows deploy <flow.ts> [--name <name>] [--json]',
   'flows deploy <flow.ts> --repo <owner/name|gitlab:group/project> --on <provider>[:key=value,...] [--on ...] --approver <handle> [--agents claude[,codex]] [--name <name>] [--draft] [--plugin <ref>] [--no-connect] [--json]',
   'flows deploy <flow.ts> --flow <name|listener-id> [--plugin <ref>] [--no-connect] [--json]',
   'flows deployments [--json]',
@@ -152,6 +156,7 @@ const USAGE = [
   'flows run --cloud [--json] [--wait] [--sync-code] [--no-connect] [--budget-minutes <n>] <flow.ts> --input <inline-json-or-file>',
   'flows sync [--json] [--dry-run] [--dir <path>] <run-id>',
   'flows run [--json] [--no-spawn] [--no-observer-link] [--cloud-mirror] [--detach] [--data-dir <dir>] [--local-agent [--agent-capacity <n>]] <flow.ts> --input <inline-json-or-file>',
+  'flows run <name> [--input <inline-json-or-file>]',
   'flows tick start --schedule-id <id> --interval-ms <ms> [--epoch-ms <ms>] [--max-catch-up <n>] [--poll-interval-ms <ms>] [--data-dir <dir>] <spec.json>',
   'flows resume [--allow-human-influenced] [--json] [--no-spawn] [--no-observer-link] [--cloud-mirror] [--detach] [--data-dir <dir>] [--local-agent [--agent-capacity <n>]] <run-id>',
   'flows answer --cloud [--json] [--note <text>] [--source <path>] <run-id> <yes|no>',
@@ -259,7 +264,7 @@ export async function runCli(
     const link = resolveObserverLinkEnv(process.env);
     if (!link.suppressed && link.workspaceKey === undefined) {
       io.stderr('Observer unavailable: no workspace key configured; set RELAYCAST_WORKSPACE_KEY or configure '
-        + '~/.agentworkforce/relay/workspaces.json for an Observer link, or pass --cloud-mirror for the Cloud dashboard');
+        + '~/.agentworkforce/relay/workspaces.json for an Observer link, or sign in with agent-relay cloud login for the Cloud dashboard');
     }
   }
 
@@ -379,6 +384,27 @@ export async function runCli(
     }, io) as CliExitCode);
   }
 
+  let named: NamedFlowSource | undefined;
+  if (parsed.command === 'run') {
+    try {
+      named = await resolveNamedFlow(parsed.value);
+      if (!named && parsed.input !== undefined && !isAuthoredFlowPath(parsed.value)) {
+        throw new CloudFlowError('invalid_input', '--input requires an authored .flow.ts or a saved flow name.');
+      }
+      if (named) {
+        if (parsed.reuseFromRunId !== undefined) throw new CloudFlowError('invalid_input', '--reuse-from is not supported for authored named flows.');
+        parsed.value = named.path;
+        parsed.input ??= '{}';
+      }
+    } catch (error) {
+      const code = error instanceof CloudFlowError ? error.refusal?.code ?? error.code : 'flow_resolution_failed';
+      const message = error instanceof Error ? error.message : String(error);
+      if (parsed.json) io.stdout(JSON.stringify({ ok: false, code, message }));
+      else io.stderr(`${code}: ${message}`);
+      return 2;
+    }
+  }
+
   // Attach-or-spawn runs inside `runFlow`/`resumeFlow`/`runDirectFlow`, at the
   // single `connect()` seam immediately before journal-client.ts is used --
   // not here. Hoisting it above the dispatch would start a daemon as a side
@@ -388,21 +414,13 @@ export async function runCli(
     onObserverUrl: url => options.detachedReceipt?.observerUrl(url),
   });
   const runnerLog: string[] = [];
-  // Opt-in, unlike the observer link beside it. The observer is the default
-  // way to watch a local run: it is free, it needs only a workspace key, and
-  // it carries a step projection. The dashboard is the richer, hosted view —
-  // it stores the flow source, every step's transcript and this invocation's
-  // own output — so a local run joins it because someone asked, never because
-  // a login happened to be lying around.
-  const mirror = !(parsed.cloudMirror || cloudMirrorRequested(process.env))
-    ? undefined
-    : createCloudMirrorSession({
+  const mirror = createCloudMirrorSession({
       source: parsed.command === 'run'
-        ? mirrorSourceFromPath(parsed.value, parsed.input, parsed.dataDir)
+        ? mirrorSourceFromPath(parsed.value, parsed.input, parsed.dataDir, named)
         : mirrorSourceFromJournal(parsed.dataDir),
       dataDir: parsed.dataDir,
       log: () => runnerLog,
-      requested: parsed.cloudMirror ? 'flag' : 'env',
+      requested: parsed.cloudMirror ? 'flag' : cloudMirrorRequested(process.env) ? 'env' : 'login',
     }, io);
   // Everything this invocation prints, kept in order, so the mirror can upload
   // it as the run's `runner.log` — the object the dashboard's log pane reads,
@@ -888,7 +906,7 @@ function parseArgs(args: readonly string[]): ParsedArgs | undefined {
   if (wait || syncCode || noConnect || budgetMinutes !== undefined) return undefined;
   if (reuseFromRunId !== undefined && isAuthoredFlowPath(positionals[0]!)) return undefined;
 
-  if (command === 'run' && input !== undefined && !isAuthoredFlowPath(positionals[0]!)) return undefined;
+  if (command === 'run' && input !== undefined && !isAuthoredFlowPath(positionals[0]!) && !isFlowName(positionals[0]!)) return undefined;
   return command === 'check'
     ? { command, json, watch, explainWarnings, value: positionals[0]!,
         daemonValidation: daemonValidation ?? (process.env['FLOWS_NO_DAEMON_CHECK'] === '1' ? 'off'

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.`;
+  }
+}