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

package/src/commands.ts

@@ -0,0 +1,176 @@
+import { allowanceUsage } from "./allowance-command";
+import { emitUsage } from "./emit-command";
+import { replyUsage } from "./holder-command";
+import { inboxUsage } from "./inbox-command";
+import { initUsage } from "./init-command";
+import { logsUsage } from "./logs-command";
+import { usage as runUsage } from "./run-command";
+import { shellLine } from "./run-commands";
+import { runsUsage } from "./runs-command";
+import { testUsage } from "./test-command";
+import { tickUsage } from "./tick-command";
+
+/**
+ * Every `awf` command: what the index, `awf help` and the suggestion read, and what the dispatch is
+ * keyed by. An entry's commands share its help; each has its own line in the index.
+ */
+export const COMMANDS = [
+  {
+    group: "Run a workflow",
+    commands: { run: "Start a run of a workflow file, or continue one" },
+    help: runUsage,
+  },
+  { group: "Run a workflow", commands: { test: "Run a workflow's tests" }, help: testUsage },
+  {
+    group: "Run a workflow",
+    commands: { init: "Set up a directory for writing workflows" },
+    help: initUsage,
+  },
+  {
+    group: "Run a workflow",
+    commands: { emit: "Send an event to a workflow with events, starting or waking its run" },
+    help: emitUsage,
+  },
+  {
+    group: "Run a workflow",
+    commands: { tick: "Wake the runs of workflows with events that are due" },
+    help: tickUsage,
+  },
+  {
+    group: "Look at runs",
+    commands: { runs: "The runs here, or one run in depth" },
+    help: runsUsage,
+  },
+  {
+    group: "Look at runs",
+    commands: { logs: "What a run did and is doing, merged by time" },
+    help: logsUsage,
+  },
+  {
+    group: "Coordinate a run from outside",
+    commands: { inbox: "What agents said to a participant outside the run, and what it said back" },
+    help: inboxUsage,
+  },
+  {
+    group: "Coordinate a run from outside",
+    commands: { reply: "Answer a question an agent asked", send: "Message an agent first" },
+    help: replyUsage,
+  },
+  {
+    group: "This machine",
+    commands: { allowance: "What is left of each harness's plan" },
+    help: allowanceUsage,
+  },
+] as const;
+
+type Entry = (typeof COMMANDS)[number];
+type NamesOf<Each> = Each extends { commands: infer Commands } ? keyof Commands & string : never;
+export type CommandName = NamesOf<Entry>;
+
+const NAMES = COMMANDS.flatMap((entry) => Object.keys(entry.commands)) as CommandName[];
+
+export function isCommand(word: string): word is CommandName {
+  return (NAMES as string[]).includes(word);
+}
+
+/** The help `awf help {name}` and `awf {name} -h` print. */
+export function helpOf(name: CommandName): string {
+  return COMMANDS.find((entry) => name in entry.commands)!.help;
+}
+
+const WIDTH = Math.max(...NAMES.map((name) => name.length)) + 2;
+
+function grouped(): [group: string, entries: Entry[]][] {
+  const groups = new Map<string, Entry[]>();
+  for (const entry of COMMANDS)
+    groups.set(entry.group, [...(groups.get(entry.group) ?? []), entry]);
+  return [...groups];
+}
+
+const lines = (entry: Entry) =>
+  Object.entries(entry.commands).map(([name, summary]) => `${name.padEnd(WIDTH)}${summary}`);
+
+/** What `awf`, `awf -h` and `awf help` print. */
+export function index(): string {
+  return [
+    "awf runs workflows of coding agents.",
+    "",
+    "usage: awf <command> [arguments]",
+    "",
+    ...grouped().flatMap(([group, entries]) => [
+      group,
+      ...entries.flatMap(lines).map((line) => `  ${line}`),
+      "",
+    ]),
+    "awf <command> -h      a command's usage, options and exit codes",
+    "awf help reference    every command's usage, on one page",
+    "awf --version",
+  ].join("\n");
+}
+
+/** A command's usage lines: its help up to the first blank line. */
+export function usageLines(help: string): string[] {
+  const end = help.indexOf("\n\n");
+  return (end < 0 ? help : help.slice(0, end)).split("\n");
+}
+
+/** What `awf help reference` prints: each command's summary and usage lines, grouped as the index. */
+export function reference(): string {
+  return [
+    ...grouped().flatMap(([group, entries]) => [
+      group,
+      ...entries.flatMap((entry) => [
+        ...lines(entry).map((line) => `  ${line}`),
+        ...usageLines(entry.help).map((line) => `    ${line}`),
+        "",
+      ]),
+    ]),
+    "awf <command> -h for what each does, and its exit codes",
+  ].join("\n");
+}
+
+const WORKFLOW_FILE = /\.(ts|mts|js|mjs)$/;
+
+/** The one line `awf {word}` gets when no command is named `word`. */
+export function unknownCommand(word: string): string {
+  const said = `awf: no command ${JSON.stringify(word)}`;
+  if (WORKFLOW_FILE.test(word)) return `${said}; did you mean: ${shellLine(["awf", "run", word])}`;
+  const meant = suggest(word);
+  const named =
+    meant.length === 0
+      ? ""
+      : ` did you mean ${meant.length === 1 ? meant[0] : `${meant.slice(0, -1).join(", ")} or ${meant.at(-1)}`}?`;
+  return `${said};${named} awf -h lists the commands`;
+}
+
+/**
+ * The commands `word` is the start of, else the closest within two edits; every one tied for
+ * closest.
+ */
+export function suggest(word: string): CommandName[] {
+  if (word === "") return [];
+  const started = NAMES.filter((name) => name.startsWith(word));
+  if (started.length > 0) return started;
+  const near = NAMES.map((name) => ({ name, distance: distance(word, name) })).filter(
+    (each) => each.distance <= 2,
+  );
+  const closest = Math.min(...near.map((each) => each.distance));
+  return near.filter((each) => each.distance === closest).map((each) => each.name);
+}
+
+/** Levenshtein distance. */
+function distance(a: string, b: string): number {
+  let previous = Array.from({ length: b.length + 1 }, (_, j) => j);
+  for (let i = 1; i <= a.length; i += 1) {
+    const current = [i];
+    for (let j = 1; j <= b.length; j += 1) {
+      current[j] = Math.min(
+        previous[j]! + 1,
+        current[j - 1]! + 1,
+        previous[j - 1]! + (a[i - 1] === b[j - 1] ? 0 : 1),
+      );
+    }
+    previous = current;
+  }
+  return previous[b.length]!;
+}

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<
@@ -12,10 +21,11 @@ export type MessagingHandler = Pick<
   "checkFinish" | "peers" | "send" | "reply" | "owing"
 >;
 
-/** `wf` accepts a 1 MiB value; escaped into the request's JSON it can double, plus the envelope. */
+/** `wfa` accepts a 1 MiB value; escaped into the request's JSON it can double, plus the envelope. */
 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),
+  };
+}