@agentswf/engine 0.1.0-beta.2 → 0.1.0-beta.3

package/src/control-plane.ts

@@ -1,10 +1,19 @@
 import { chmod, mkdir, mkdtemp, rm } from "node:fs/promises";
 import { join } from "node:path";
-import { type ControlResponse, decodeControlRequest, WIRE_VERSION } from "@agentswf/contract/wire";
+import {
+  type ControlResponse,
+  decodeControlRequest,
+  type GivenInput,
+  WIRE_VERSION,
+} from "@agentswf/contract/wire";
 import { isCode } from "./files";
 import type { Messaging } from "./messaging/messaging";
 import { UNRECORDED } from "./messaging/text";
 import type { ResultSlotRegistry } from "./result-slots";
+import type { ToolCalls } from "./tools";
+
+/** What the control plane asks of the run's tools, by the agent whose socket asked. */
+export type ToolHandler = Pick<ToolCalls<unknown>, "call" | "running" | "accepted">;
 
 /** What the control plane asks of the run's messaging, by the agent whose socket asked. */
 export type MessagingHandler = Pick<
@@ -16,6 +25,7 @@ export type MessagingHandler = Pick<
 const MAX_RESULT_REQUEST_BYTES = 2 * 1024 * 1024 + 4 * 1024;
 const MAX_CONTROL_CONNECTIONS = 64;
 const CONNECTION_TIMEOUT_SECONDS = 30;
+const MAX_TIMER_MS = 2_147_483_647;
 
 export type ResultChannel = {
   /** The socket this agent's launcher connects to. */
@@ -36,6 +46,8 @@ export type ResultControlPlane = {
   openChannel(agentId: string, onSession?: (id: string) => void): Promise<ResultChannel>;
   /** The run's messaging, once it exists; until then `peers`, `send` and `reply` are refused. */
   attach(messaging: MessagingHandler): void;
+  /** The run's tools, once it has them; until then `tool` is refused. */
+  attachTools(tools: ToolHandler): void;
   close(): Promise<void>;
 };
 
@@ -91,6 +103,7 @@ export async function startResultControlPlane(options: {
   await chmod(directory, 0o300);
 
   let messaging: MessagingHandler | undefined;
+  let tools: ToolHandler | undefined;
   // Shared across channels: the budget protects the engine, not any one agent.
   let activeConnections = 0;
   let accepting = true;
@@ -175,13 +188,22 @@ export async function startResultControlPlane(options: {
             const { promise: written, resolve } = Promise.withResolvers<void>();
             socket.data.responded = resolve;
             const handling = Promise.race([
-              handleFrame(
-                Buffer.concat(socket.data.chunks).toString("utf8"),
-                options.slots,
+              handleFrame(Buffer.concat(socket.data.chunks).toString("utf8"), {
+                slots: options.slots,
                 messaging,
+                tools,
                 agentId,
                 onSession,
-              ),
+                // A tool call lasts as long as its budget, not the connection's 30 s.
+                lifetime: (milliseconds) => {
+                  if (socket.data.lifetime) clearTimeout(socket.data.lifetime);
+                  // One past a timer's range is as good as none: the call's own end closes it.
+                  socket.data.lifetime =
+                    milliseconds === undefined || milliseconds > MAX_TIMER_MS
+                      ? undefined
+                      : setTimeout(() => socket.terminate(), milliseconds);
+                },
+              }),
               written.then(() => undefined),
             ])
               .then((response) => {
@@ -249,6 +271,9 @@ export async function startResultControlPlane(options: {
     attach(handler) {
       messaging = handler;
     },
+    attachTools(handler) {
+      tools = handler;
+    },
     close() {
       closing ??= (async () => {
         accepting = false;
@@ -287,14 +312,18 @@ function emptyConnection(): ConnectionState {
   };
 }
 
-async function handleFrame(
-  frame: string,
-  slots: ResultSlotRegistry,
-  messaging: MessagingHandler | undefined,
-  agentId: string,
-  onSession: ((id: string) => void) | undefined,
-): Promise<ControlResponse> {
-  const response = await answerFrame(frame, slots, messaging, agentId, onSession);
+type Handlers = {
+  slots: ResultSlotRegistry;
+  messaging: MessagingHandler | undefined;
+  tools: ToolHandler | undefined;
+  agentId: string;
+  onSession: ((id: string) => void) | undefined;
+  lifetime: (milliseconds: number | undefined) => void;
+};
+
+async function handleFrame(frame: string, handlers: Handlers): Promise<ControlResponse> {
+  const { messaging, agentId } = handlers;
+  const response = await answerFrame(frame, handlers);
   // Leads every response, so what is owed comes back after a compaction; not one that already
   // says it, about the wait it began or the answer it is refused for.
   const repeats =
@@ -308,10 +337,7 @@ async function handleFrame(
 
 async function answerFrame(
   frame: string,
-  slots: ResultSlotRegistry,
-  messaging: MessagingHandler | undefined,
-  agentId: string,
-  onSession: ((id: string) => void) | undefined,
+  { slots, messaging, tools, agentId, onSession, lifetime }: Handlers,
 ): Promise<ControlResponse> {
   if (!frame.endsWith("\n") || frame.slice(0, -1).includes("\n")) {
     return rejected("invalid-request", "expected exactly one newline-delimited JSON request");
@@ -329,6 +355,17 @@ async function answerFrame(
   if (decoded.value.session) onSession?.(decoded.value.session);
 
   const request = decoded.value;
+  if (request.command === "tool") {
+    if (!tools) return rejected("unsupported-command", "tools are not available in this run");
+    let answer: Awaited<ReturnType<ToolHandler["call"]>>;
+    try {
+      answer = await tools.call(agentId, request, lifetime);
+    } catch {
+      return rejected("internal-error", "the tool call failed internally; it may have run");
+    }
+    if (answer.kind === "refused") return rejected(answer.code, answer.error);
+    return { version: WIRE_VERSION, ...answer };
+  }
   if (request.command !== "result" && request.command !== "waiting") {
     if (!messaging)
       return rejected("unsupported-command", "messaging is not available in this run");
@@ -358,6 +395,15 @@ async function answerFrame(
   }
   // Before the slot is asked: a message operation has none, and an answer owed comes first.
   const gate = messaging?.checkFinish(agentId, request.operationId, request.command);
+  const running = tools?.running(agentId);
+  if (running && gate?.kind !== "refused") {
+    const by =
+      running.settledBy === undefined ? "" : ` by ${new Date(running.settledBy).toISOString()}`;
+    return rejected(
+      "tool-running",
+      `your call of ${running.tool} is still running; it will have answered${by || " when it ends"}. Run this again then.`,
+    );
+  }
   if (gate?.kind === "refused") return rejected(gate.code, gate.error);
   if (gate?.kind === "awaiting" && request.command === "waiting") {
     const { peer, until, notice } = gate;
@@ -378,17 +424,22 @@ async function answerFrame(
     const result = await slots.submit({
       operationId: request.operationId,
       agentId,
-      raw: request.raw,
+      ...givenOf(request),
       source: "control-plane",
     });
-    return result.kind === "accepted"
-      ? { version: WIRE_VERSION, kind: "accepted" }
-      : rejected(result.code, result.error);
+    if (result.kind !== "accepted") return rejected(result.code, result.error);
+    tools?.accepted(request.operationId);
+    return { version: WIRE_VERSION, kind: "accepted" };
   } catch {
     return rejected("internal-error", "control request failed internally");
   }
 }
 
+/** The input as the wire decoded it, without the request's other fields. */
+function givenOf({ raw, args }: GivenInput): GivenInput {
+  return raw !== undefined ? { raw } : args !== undefined ? { args } : {};
+}
+
 function rejected(
   code: Extract<ControlResponse, { kind: "rejected" }>["code"],
   error: string,

package/src/coordinator-port.ts

@@ -0,0 +1,29 @@
+import type {
+  HolderRequest,
+  HolderResult,
+  MessagingEventBody,
+  OpenQuestion,
+} from "./messaging/messaging";
+
+/**
+ * Answers for a run's outside participants, as a holder does with `awf reply` and `awf send`. Its
+ * message numbers are the attempt's; `awf inbox` names them `{attempt}.{n}`.
+ */
+export type CoordinatorHolder = {
+  reply(request: HolderRequest): Promise<HolderResult>;
+  send(request: HolderRequest): Promise<HolderResult>;
+  /** Questions open to outside participants now, oldest first. */
+  open(): OpenQuestion[];
+};
+
+/**
+ * What answers for a run's outside participants plugs in here: `awf run`'s prompt, the socket, or a
+ * test's scripts. Told each messaging event once the run's log has it, and handed the holder before
+ * the workflow runs. Reachable through `RunWorkflowOptions`, as `awaitReply` is, but not a
+ * published surface: holders use `awf inbox`, `awf reply` and `awf send`.
+ * @internal
+ */
+export type CoordinatorPort = {
+  attach(holder: CoordinatorHolder): void;
+  recorded(event: MessagingEventBody): void;
+};

package/src/coordinator-prompt.ts

@@ -0,0 +1,237 @@
+import { createInterface, type Interface } from "node:readline/promises";
+import type { CoordinatorHolder, CoordinatorPort } from "./coordinator-port";
+import type { MessagingEventBody } from "./messaging/messaging";
+import { shellLine } from "./run-commands";
+
+/** Where the prompt reads a line: `awf run`'s terminal, or a test's script. */
+export type LineReader = {
+  /** The line typed after `prompt`; undefined when `signal` aborts first, or input ended. */
+  read(prompt: string, signal: AbortSignal): Promise<string | undefined>;
+  /** Writes a line above the prompt open, if any, and draws it again under it. */
+  above(line: string): void;
+  close(): void;
+};
+
+/** What the prompt shows beside the progress view, which holds its block while a prompt is open. */
+export type PromptOutput = {
+  /** A line in the run's log, above the progress block. */
+  log(line: string): void;
+  /** The progress block stops redrawing while a prompt waits for a line, and lines go above it. */
+  hold(above: ((line: string) => void) | undefined): void;
+};
+
+type Question = {
+  coordinator: string;
+  message: number;
+  asker: string;
+  text: string;
+  /** Asked after others, its text shown when it came in may have scrolled away: shown again. */
+  again: boolean;
+};
+
+/** What an agent wrote, safe on a terminal: no escape sequences or other control characters. */
+function shown(text: string): string[] {
+  // biome-ignore lint/suspicious/noControlCharactersInRegex: control characters are what it strips.
+  return text.replace(/[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/g, "").split("\n");
+}
+
+const indented = (text: string) => shown(text).map((line) => `                ${line}`);
+
+/**
+ * `awf run`'s interactive mode: each message to a coordinator is a line in the run's log, and each
+ * question is asked at the terminal, oldest first, for every coordinator. An empty line leaves it
+ * open for another holder; one another holder answers, or that closes, is passed over.
+ */
+export function promptCoordinator(
+  reader: LineReader,
+  output: PromptOutput,
+): CoordinatorPort & { close(): void; shows(message: { from: string; to: string }): boolean } {
+  let holder: CoordinatorHolder | undefined;
+  const connected = new Set<string>();
+  const queue: Question[] = [];
+  let asking: { question: Question; stop: AbortController } | undefined;
+  /** Questions this prompt answered: their answers are what was typed, shown already. */
+  const typed = new Set<number>();
+  /** Questions still open, by number: an end names its asker. */
+  const open = new Map<number, Question>();
+  let closed = false;
+
+  const ask = async (question: Question): Promise<void> => {
+    if (question.again)
+      output.log([`● ${question.asker} asked:`, ...indented(question.text)].join("\n"));
+    const stop = new AbortController();
+    asking = { question, stop };
+    output.hold((line) => reader.above(line));
+    let line: string | undefined;
+    try {
+      const as = connected.size > 1 ? ` as ${question.coordinator}` : "";
+      line = (await reader.read(`reply to ${question.asker}${as} › `, stop.signal))?.trim();
+    } finally {
+      // Released before the reply: what it records comes as lines, not under a prompt answered.
+      asking = undefined;
+      output.hold(undefined);
+    }
+    if (!line || !holder) return;
+    // Before the reply: its record arrives while it is being made.
+    typed.add(question.message);
+    const result = await holder.reply({
+      coordinator: question.coordinator,
+      agent: question.asker,
+      to: question.message,
+      text: line,
+      via: "terminal",
+    });
+    if (result.code !== "delivered") {
+      typed.delete(question.message);
+      output.log(`awf: not delivered: ${result.error}`);
+    }
+  };
+
+  const next = async (): Promise<void> => {
+    while (!asking && !closed && holder) {
+      const question = queue.shift();
+      if (!question) return;
+      // One that fails is said and passed over; the others are still asked.
+      await ask(question).catch((error: unknown) =>
+        output.log(`awf: the prompt failed: ${error instanceof Error ? error.message : error}`),
+      );
+    }
+  };
+
+  const ended = (message: number) => {
+    const at = queue.findIndex((each) => each.message === message);
+    if (at >= 0) queue.splice(at, 1);
+    if (asking?.question.message === message) asking.stop.abort();
+  };
+
+  return {
+    attach(given) {
+      holder = given;
+    },
+    recorded(event: MessagingEventBody) {
+      if (event.kind === "participant-connected") connected.add(event.participant);
+      if (event.kind === "request-ended" && connected.has(event.owedBy)) {
+        ended(event.message);
+        const question = open.get(event.message);
+        open.delete(event.message);
+        if (question && event.end !== "replied")
+          output.log(`● ${question.asker}'s question closed unanswered: ${event.end}`);
+        return;
+      }
+      if (event.kind !== "message-sent") return;
+      // The coordinator's answers and sends that came another way: a holder's, or a script's.
+      if (connected.has(event.from)) {
+        if (event.replyTo !== undefined && typed.has(event.replyTo)) return;
+        const how = "via" in event && event.via ? ` (${event.via})` : "";
+        output.log([`● ${event.from} → ${event.to}${how}:`, ...indented(event.text)].join("\n"));
+        return;
+      }
+      if (!connected.has(event.to)) return;
+      const asks = event.awaitsReply !== undefined;
+      output.log(
+        [`● ${event.from} ${asks ? "asks" : `→ ${event.to}`}:`, ...indented(event.text)].join("\n"),
+      );
+      if (!asks) return;
+      const question = {
+        coordinator: event.to,
+        message: event.message,
+        asker: event.from,
+        text: event.text,
+        again: asking !== undefined || queue.length > 0,
+      };
+      open.set(event.message, question);
+      queue.push(question);
+      void next();
+    },
+    shows: ({ from, to }) => connected.has(from) || connected.has(to),
+    close() {
+      closed = true;
+      queue.length = 0;
+      asking?.stop.abort();
+      reader.close();
+    },
+  };
+}
+
+/**
+ * Reads lines from this process's terminal, writing on stderr beside the progress view. It holds
+ * stdin only while a question is asked, so typing at any other time reaches nothing, and a run
+ * that asks none leaves the terminal as it found it.
+ */
+export function terminalReader(): LineReader {
+  let lines: Interface | undefined;
+  let closed = false;
+  const clearLine = () => process.stderr.write("\r\x1b[2K");
+  return {
+    async read(prompt, signal) {
+      if (closed) return undefined;
+      const current = createInterface({
+        input: process.stdin,
+        output: process.stderr,
+        terminal: true,
+      });
+      lines = current;
+      // Ctrl-C at the prompt asks the run to stop, as it does anywhere else.
+      current.on("SIGINT", () => process.kill(process.pid, "SIGINT"));
+      // Ctrl-D ends the input: the question is left open, as an empty line leaves it.
+      const ended = new Promise<undefined>((resolve) =>
+        current.once("close", () => resolve(undefined)),
+      );
+      // The progress view hides the cursor and clips long lines; typing needs both back.
+      process.stderr.write("\x1b[?7h\x1b[?25h");
+      try {
+        return await Promise.race([current.question(prompt, { signal }), ended]);
+      } catch (error) {
+        if (signal.aborted) return undefined;
+        throw error;
+      } finally {
+        if (signal.aborted || closed) clearLine();
+        lines = undefined;
+        current.close();
+        process.stderr.write("\x1b[?25l\x1b[?7l");
+      }
+    },
+    above(line) {
+      clearLine();
+      process.stderr.write(`${line}\n`);
+      lines?.prompt(true);
+    },
+    close() {
+      closed = true;
+      if (lines) clearLine();
+      lines?.close();
+    },
+  };
+}
+
+/**
+ * Without a prompt (`--json`, or no terminal): each question to a coordinator is a line with its
+ * text and the command that answers it, so a run awaiting one does not look stuck.
+ */
+export function replyHints(
+  run: string,
+  /** What finds the run from another command, such as `--run-root`. */
+  place: readonly string[],
+  attempt: number,
+  log: (line: string) => void,
+): CoordinatorPort & { shows(message: { to: string; asks?: boolean }): boolean } {
+  const connected = new Set<string>();
+  return {
+    attach() {},
+    recorded(event: MessagingEventBody) {
+      if (event.kind === "participant-connected") connected.add(event.participant);
+      if (event.kind !== "message-sent" || !connected.has(event.to) || !event.awaitsReply) return;
+      const id = `${attempt}.${event.message}`;
+      const as = connected.size > 1 ? ["--as", event.to] : [];
+      const command = ["awf", "reply", run, event.from, "--to", id, ...as, ...place];
+      log(
+        [
+          `● ${event.from} asks ${event.to} (${id}):`,
+          ...indented(event.text),
+          `  answer: ${shellLine(command)} '…'`,
+        ].join("\n"),
+      );
+    },
+    shows: ({ to, asks }) => asks === true && connected.has(to),
+  };
+}

package/src/coordinator-socket.ts

@@ -0,0 +1,236 @@
+import { createHash } from "node:crypto";
+import { chmod, mkdir, realpath, rm, stat } from "node:fs/promises";
+import { basename, dirname, isAbsolute, join, relative, sep } from "node:path";
+import type { ParticipantResultJson } from "@agentswf/contract/records";
+import { decodeHolderRequest, type NudgeWireResult } from "@agentswf/contract/wire";
+import type { CoordinatorHolder, CoordinatorPort } from "./coordinator-port";
+import { realPath } from "./files";
+import type { MessagingEventBody } from "./messaging/messaging";
+import type { RunStatus } from "./run-state";
+
+/** A request is a line of text and its JSON; well past a message's own 16 KB limit. */
+const MAX_REQUEST_BYTES = 256 * 1024;
+const CONNECTION_LIFETIME_MS = 30_000;
+
+type Connection = {
+  chunks: Buffer[];
+  bytes: number;
+  /** Its request was taken, answered or refused: nothing more is read. */
+  taken: boolean;
+  timer?: ReturnType<typeof setTimeout>;
+};
+
+/**
+ * A run's coordinator socket: named by a hash of its run directory, so any depth of directory fits
+ * `sun_path`'s 104 bytes, in a folder only the operator can open.
+ */
+export function coordinatorSocketPath(dir: string, runDir: string): string {
+  // Its real path: a holder reaching it through a symlink, or `/tmp` for `/private/tmp`, names it alike.
+  const name = createHash("sha256").update(realPath(runDir)).digest("hex").slice(0, 32);
+  return join(dir, `${name}.sock`);
+}
+
+/**
+ * Refuses a coordinator folder inside the workflow's directory, where its agents work, through
+ * symlinks too, and one given as a relative path, which each command would read from where it ran.
+ * Then makes it, the operator's alone, before any sandbox is resolved against it.
+ */
+export async function prepareCoordinatorDir(
+  dir: string,
+  workflowDir: string,
+  /** It was moved with `AWF_COORDINATOR_DIR`; `~/.awf`'s own is kept from sandboxes as `~/.awf` is. */
+  moved = true,
+): Promise<void> {
+  if (!isAbsolute(dir)) throw new Error(`AWF_COORDINATOR_DIR ${dir} is not an absolute path`);
+  const real = async (path: string): Promise<string> => {
+    try {
+      return await realpath(path);
+    } catch {
+      // Not there yet: its parent's real path, and its own name.
+      const parent = dirname(path);
+      return parent === path ? path : join(await real(parent), basename(path));
+    }
+  };
+  const inside = relative(await real(workflowDir), await real(dir));
+  const within =
+    inside === "" || !(inside === ".." || inside.startsWith(`..${sep}`) || isAbsolute(inside));
+  if (moved && within)
+    throw new Error(
+      `AWF_COORDINATOR_DIR ${dir} is inside the workflow's directory, where its agents work; move it out`,
+    );
+  await mkdir(dir, { recursive: true, mode: 0o700 });
+  await chmod(dir, 0o700);
+}
+
+/**
+ * The socket `awf reply` and `awf send` reach a live run through. It opens once the workflow
+ * connects an outside participant and goes when the run ends; each connection is one request
+ * line and one `ParticipantResultJson` line back.
+ */
+export function coordinatorSocket(options: {
+  dir: string;
+  runDir: string;
+  attempt: number;
+  /** Why the socket did not open: the run goes on, and no holder's command reaches it. */
+  failed(reason: string): void;
+  /** A nudge: the run's mailbox has a new event. Given, the socket opens at once, for awf's nudge. */
+  nudged?(): void;
+}): CoordinatorPort & { close(): Promise<void>; readonly path: string } {
+  const path = coordinatorSocketPath(options.dir, options.runDir);
+  let holder: CoordinatorHolder | undefined;
+  let listener: Bun.UnixSocketListener<{ chunks: Buffer[]; bytes: number }> | undefined;
+  let opening: Promise<void> | undefined;
+  let closed = false;
+  const id = (n: number) => `${options.attempt}.${n}`;
+
+  /** Undefined for a request no `awf` command makes: the connection closes unanswered. */
+  const answer = async (
+    frame: string,
+  ): Promise<ParticipantResultJson | NudgeWireResult | undefined> => {
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(frame);
+    } catch {
+      return undefined;
+    }
+    const decoded = decodeHolderRequest(parsed);
+    if (!decoded.ok) return undefined;
+    const request = decoded.value;
+    if (request.command === "nudge") {
+      if (!options.nudged) return undefined;
+      options.nudged();
+      return { v: 1, code: "nudged" };
+    }
+    if (!holder) return refused("no-participant", "the run has no participant connected");
+    // Another attempt's question is never open in this one: a number no message has.
+    const to =
+      request.to === undefined
+        ? undefined
+        : request.to.split(".")[0] === String(options.attempt)
+          ? Number(request.to.split(".")[1])
+          : 0;
+    const asked = {
+      ...(request.participant === undefined ? {} : { coordinator: request.participant }),
+      agent: request.agent,
+      ...(to === undefined ? {} : { to }),
+      text: request.text,
+      via: "command" as const,
+    };
+    const result =
+      request.command === "reply" ? await holder.reply(asked) : await holder.send(asked);
+    return result.code === "delivered"
+      ? { v: 1, code: "delivered", id: id(result.message) }
+      : {
+          v: 1,
+          code: result.code,
+          error: result.error,
+          ...(result.choices ? { choices: result.choices } : {}),
+        };
+  };
+
+  const open = async () => {
+    // A socket a killed run left here is no one's: this run's directory names it.
+    await rm(path, { force: true });
+    if (closed) return;
+    listener = Bun.listen<Connection>({
+      unix: path,
+      allowHalfOpen: true,
+      data: { chunks: [], bytes: 0, taken: false },
+      socket: {
+        open(socket) {
+          socket.data = {
+            chunks: [],
+            bytes: 0,
+            taken: false,
+            // Only while the request is read: an answer being made is never cut off.
+            timer: setTimeout(() => socket.terminate(), CONNECTION_LIFETIME_MS),
+          };
+        },
+        data(socket, data) {
+          if (socket.data.taken) return;
+          socket.data.bytes += data.byteLength;
+          if (socket.data.bytes > MAX_REQUEST_BYTES) {
+            take(socket);
+            socket.end(`${JSON.stringify(refused("too-large", "the request is too large"))}\n`);
+            return;
+          }
+          socket.data.chunks.push(Buffer.from(data));
+          // A request is one line: it is answered at its end, whether or not the client half-closes.
+          const text = Buffer.concat(socket.data.chunks).toString("utf8");
+          const newline = text.indexOf("\n");
+          if (newline >= 0) respond(socket, text.slice(0, newline));
+        },
+        end(socket) {
+          if (!socket.data.taken)
+            respond(socket, Buffer.concat(socket.data.chunks).toString("utf8"));
+        },
+        close(socket) {
+          clearTimeout(socket.data.timer);
+        },
+        error(socket) {
+          socket.terminate();
+        },
+      },
+    });
+    await chmod(path, 0o600);
+  };
+  const take = (socket: Bun.Socket<Connection>) => {
+    socket.data.taken = true;
+    clearTimeout(socket.data.timer);
+  };
+  const respond = (socket: Bun.Socket<Connection>, frame: string) => {
+    take(socket);
+    void answer(frame)
+      .catch(() => undefined)
+      .then((result) => socket.end(result ? `${JSON.stringify(result)}\n` : undefined));
+  };
+
+  if (options.nudged)
+    opening = open().catch((error: unknown) =>
+      options.failed(error instanceof Error ? error.message : String(error)),
+    );
+  return {
+    path,
+    attach(given) {
+      holder = given;
+    },
+    recorded(event: MessagingEventBody) {
+      if (event.kind === "participant-connected" && !opening) {
+        opening = open().catch((error: unknown) =>
+          options.failed(error instanceof Error ? error.message : String(error)),
+        );
+      }
+    },
+    async close() {
+      closed = true;
+      await opening;
+      listener?.stop(true);
+      if (listener) await rm(path, { force: true });
+    },
+  };
+}
+
+function refused(
+  code: Exclude<ParticipantResultJson["code"], "delivered">,
+  error: string,
+): ParticipantResultJson {
+  return { v: 1, code, error };
+}
+
+/**
+ * The socket of a run still live, or undefined: `run-state` decides, so a socket a killed run left
+ * behind is not trusted.
+ */
+export async function liveCoordinatorSocket(
+  dir: string,
+  status: Pick<RunStatus, "state" | "run">,
+): Promise<string | undefined> {
+  if (status.state !== "running") return undefined;
+  const path = coordinatorSocketPath(dir, status.run.dir);
+  return (await stat(path).then(
+    () => true,
+    () => false,
+  ))
+    ? path
+    : undefined;
+}