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

package/src/agent-cli/client.ts

@@ -0,0 +1,115 @@
+import { createConnection, type Socket } from "node:net";
+import {
+  type ControlRequest,
+  decodeResponseFor,
+  type ResponseFor,
+  type ResultSubmitRequest,
+  type ResultSubmitResponse,
+  type WaitingRequest,
+  type WaitingResponse,
+} from "@agentswf/contract/wire";
+
+const MAX_RESPONSE_BYTES = 256 * 1024;
+
+/** The connection never opened: nothing was written, so nothing reached the engine. */
+export class NotSentError extends Error {}
+
+export function submitResult(
+  endpoint: string,
+  request: ResultSubmitRequest,
+  timeoutSeconds = 30,
+  connect: (endpoint: string) => Socket = createConnection,
+): Promise<ResultSubmitResponse> {
+  return submitControl(endpoint, request, timeoutSeconds, connect);
+}
+
+export function submitWaiting(
+  endpoint: string,
+  request: WaitingRequest,
+  timeoutSeconds = 30,
+  connect: (endpoint: string) => Socket = createConnection,
+): Promise<WaitingResponse> {
+  return submitControl(endpoint, request, timeoutSeconds, connect);
+}
+
+/** Sends one request and resolves with a response that answers its command. */
+export function submitControl<R extends ControlRequest>(
+  endpoint: string,
+  request: R,
+  /** Null waits as long as the engine takes, as a tool call does: it answers once the call settles. */
+  timeoutSeconds: number | null = 30,
+  connect: (endpoint: string) => Socket = createConnection,
+): Promise<ResponseFor[R["command"]]> {
+  type Response = ResponseFor[R["command"]];
+  if (timeoutSeconds !== null && (!Number.isFinite(timeoutSeconds) || timeoutSeconds <= 0)) {
+    return Promise.reject(new Error("control-plane timeout must be positive"));
+  }
+  const outgoing = Buffer.from(`${JSON.stringify(request)}\n`);
+
+  return new Promise<Response>((resolve, reject) => {
+    const chunks: Buffer[] = [];
+    let bytes = 0;
+    let settled = false;
+    let connected = false;
+    const socket = connect(endpoint);
+    const lifetime =
+      timeoutSeconds === null
+        ? undefined
+        : setTimeout(
+            () => fail(new Error("control plane response timed out")),
+            timeoutSeconds * 1000,
+          );
+
+    const fail = (error: Error): void => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(lifetime);
+      socket.destroy();
+      reject(error);
+    };
+
+    socket.once("connect", () => {
+      connected = true;
+      socket.end(outgoing);
+    });
+    socket.on("data", (data) => {
+      if (settled) return;
+      const chunk = typeof data === "string" ? Buffer.from(data) : data;
+      bytes += chunk.byteLength;
+      if (bytes > MAX_RESPONSE_BYTES) {
+        fail(new Error("control-plane response exceeds the size limit"));
+        return;
+      }
+      chunks.push(chunk);
+    });
+    socket.once("end", () => {
+      if (settled) return;
+      const frame = Buffer.concat(chunks).toString("utf8");
+      if (!frame.endsWith("\n") || frame.slice(0, -1).includes("\n")) {
+        fail(new Error("control plane returned an invalid response frame"));
+        return;
+      }
+      let parsed: unknown;
+      try {
+        parsed = JSON.parse(frame.slice(0, -1));
+      } catch {
+        fail(new Error("control plane returned invalid JSON"));
+        return;
+      }
+      const decoded = decodeResponseFor<R["command"]>(request.command, parsed);
+      if (!decoded.ok) {
+        fail(new Error(decoded.error));
+        return;
+      }
+      settled = true;
+      clearTimeout(lifetime);
+      resolve(decoded.value);
+    });
+    socket.once("error", (error) =>
+      fail(connected ? error : new NotSentError(error.message, { cause: error })),
+    );
+    socket.once("close", () => {
+      if (!settled) fail(new Error("control plane closed without a response"));
+    });
+  });
+}

package/src/agent-launcher.ts

@@ -1,9 +1,11 @@
-import { chmod, mkdir, readFile, realpath, writeFile } from "node:fs/promises";
-import { createRequire } from "node:module";
-import { basename, dirname, join, resolve } from "node:path";
+import { chmod, mkdir, realpath, writeFile } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import { type AgentDoor, shellQuote } from "@agentswf/sandbox";
 
-/** bun loads the `.env` of the directory it starts in: an agent's, which is none of `wf`'s. */
+const AGENT_CLI = fileURLToPath(new URL("./agent-cli/cli.ts", import.meta.url));
+
+/** bun loads the `.env` of the directory it starts in: an agent's, which is none of `wfa`'s. */
 const NO_ENV = "--no-env-file";
 
 /**
@@ -27,19 +29,18 @@ export async function installAgentLauncher(
    */
   sessionEnv?: string,
 ): Promise<string> {
-  const command = await resolveAgentCommand();
-  return writeLauncher(directory, [process.execPath, NO_ENV, command], endpoint, sessionEnv);
+  return writeLauncher(directory, [process.execPath, NO_ENV, AGENT_CLI], endpoint, sessionEnv);
 }
 
 /**
- * A sandboxed agent's door: the same launcher, running the bundled `wf` with the host's bun by
+ * A sandboxed agent's door: the same launcher, running the bundled `wfa` with the host's bun by
  * its real path, since a sandbox reads neither the workspace's sources nor bun's links under `~`.
  * A box copies `boxScript` to the launcher's path, which runs the bundle with the box's own bun.
  */
 export async function installSandboxedDoor(
   directory: string,
   endpoint: string,
-  /** The bundled `wf`'s source, written beside the launcher. */
+  /** The bundled `wfa`'s source, written beside the launcher. */
   source: string,
   sessionEnv?: string,
 ): Promise<AgentDoor> {
@@ -50,7 +51,7 @@ export async function installSandboxedDoor(
   const socket = join(real, basename(endpoint));
   // In the agent's own directory: bun will not load a module from the control plane's, which is
   // not listable so that no agent can find another's socket.
-  const bundle = join(real, "wf.js");
+  const bundle = join(real, "wfa.js");
   await writeFile(bundle, source, { mode: 0o500 });
   const launcher = await writeLauncher(real, [bun, NO_ENV, bundle], socket, sessionEnv);
   return {
@@ -64,12 +65,12 @@ export async function installSandboxedDoor(
 }
 
 /**
- * `wf` as one file's source, which a sandbox can read where it cannot read this workspace. Built by
+ * `wfa` as one file's source, which a sandbox can read where it cannot read this workspace. Built by
  * a `bun build` of its own: in process, the bundler resolved packages against the test runner's
  * state and missed the workspace's links.
  */
 export async function buildAgentBundle(): Promise<string> {
-  const entry = await resolveAgentCommand();
+  const entry = AGENT_CLI;
   const built = Bun.spawn({
     cmd: [process.execPath, "build", entry, "--target=bun"],
     cwd: dirname(entry),
@@ -81,7 +82,7 @@ export async function buildAgentBundle(): Promise<string> {
     new Response(built.stdout).text(),
     new Response(built.stderr).text(),
   ]);
-  if (code !== 0) throw new Error(`could not bundle wf: ${stderr.trim().slice(0, 400)}`);
+  if (code !== 0) throw new Error(`could not bundle wfa: ${stderr.trim().slice(0, 400)}`);
   return bundle;
 }
 
@@ -93,7 +94,7 @@ async function writeLauncher(
 ): Promise<string> {
   await mkdir(directory, { recursive: true });
   await chmod(directory, 0o700);
-  const path = join(directory, "wf");
+  const path = join(directory, "wfa");
   // Not writable, so an agent that redirects into its own launcher fails rather than replacing its
   // only way to answer. A `chmod` still gets past it; a sandbox denies the write outright.
   await writeFile(path, launcherScript(command, endpoint, sessionEnv, path), { mode: 0o500 });
@@ -105,7 +106,7 @@ function launcherScript(
   command: readonly string[],
   endpoint: string,
   sessionEnv: string | undefined,
-  /** Its own path, which `wf` names in what it prints, as an agent must type it. */
+  /** Its own path, which `wfa` names in what it prints, as an agent must type it. */
   path: string,
 ): string {
   if (sessionEnv !== undefined && !/^[A-Za-z_][A-Za-z0-9_]*$/.test(sessionEnv)) {
@@ -114,14 +115,3 @@ function launcherScript(
   const session = sessionEnv ? ` --session "\${${sessionEnv}:-}"` : "";
   return `#!/bin/sh\nexec ${command.map(shellQuote).join(" ")} --at ${shellQuote(endpoint)} --as ${shellQuote(path)}${session} "$@"\n`;
 }
-
-async function resolveAgentCommand(): Promise<string> {
-  const require = createRequire(import.meta.url);
-  const manifestPath = require.resolve("@agentswf/wf/package.json");
-  const manifest = JSON.parse(await readFile(manifestPath, "utf8")) as {
-    bin?: string | Record<string, string>;
-  };
-  const relative = typeof manifest.bin === "string" ? manifest.bin : manifest.bin?.wf;
-  if (!relative) throw new Error("@agentswf/wf does not publish the wf command");
-  return resolve(dirname(manifestPath), relative);
-}

package/src/allowance-command.ts

@@ -4,24 +4,12 @@ import type {
   HarnessAllowance,
 } from "@agentswf/contract/records";
 import { HARNESS_NAMES, type Harness } from "@agentswf/harness";
-import { PLAN_BASIS, planPrice } from "./accounting/plans";
+import { planPrice } from "./accounting/plans";
 import { messageOf } from "./errors";
+import help from "./help/allowance.txt" with { type: "text" };
 import type { Out } from "./run-commands";
 
-export const allowanceUsage = [
-  "usage: awf allowance [harness...] [--json]",
-  "",
-  "What is left of each harness's plan, as the harness itself shows it: claude's /usage, codex's",
-  "/status, and cursor's /usage, read in a Herdr pane. Nothing asks a model. Every harness when",
-  `none is named: ${HARNESS_NAMES.join(", ")}.`,
-  "",
-  "A plan's monthly price is the vendor's list price as of the table's date, not what was",
-  `charged: ${PLAN_BASIS}.`,
-  "",
-  `--json prints one document, the interface for scripts, with the plan as the`,
-  "harness names it and no price; what it prints otherwise is for reading. A harness that could",
-  "not be read says why. Exits 0 once every harness was asked, 2 on a usage error.",
-].join("\n");
+export const allowanceUsage = help.trimEnd();
 
 export type AllowanceCommand = { harnesses: Harness[]; json: boolean } | "help";
 

package/src/attempt-output.ts

@@ -107,7 +107,7 @@ export async function keepRecords(
     const unacknowledged =
       ending.kind === "completed" && attempt.run.record.events
         ? await readMailbox(dir).then(
-            // The event that started the run is `workflow.started`'s, taken or not.
+            // The event that started the run is `wf.started`'s, taken or not.
             (records) => {
               const state = foldMailbox(records);
               return state.unacknowledged.filter((id) => id !== state.started?.id).length;

package/src/control-plane.ts

@@ -21,7 +21,7 @@ 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;

package/src/emit-command.ts

@@ -2,23 +2,12 @@ import type { EmitResultJson } from "@agentswf/contract/records";
 import { isEventWorkflow, type JsonValue } from "@agentswf/contract/workflow";
 import { EmitError, emitEvent } from "./emit";
 import { messageOf } from "./errors";
+import help from "./help/emit.txt" with { type: "text" };
 import type { Out } from "./run-commands";
 import type { Launch } from "./wake";
 import { loadWorkflowFile } from "./workflow-loader";
 
-export const emitUsage = [
-  "usage: awf emit --target <file> --id <id> <event> [<json>] [--event-id <id>] [--json]",
-  "",
-  "Sends an event to the run of a workflow with events that --id names. That run starts if it has",
-  "none and the event is one that starts one, and is woken if it has one: nudged while it runs, continued when it is",
-  "parked or crashed. The run lives in the project of <file>, the nearest directory above it",
-  "holding .awf/, whoever sends. --event-id names the occurrence: the same id again is a duplicate.",
-  "",
-  "Prints what became of the event, and what was done to the run: accepted, duplicate or refused.",
-  "--json prints one document. Exits 0 for any of the three, 1 when the run's attempt could not be",
-  "started (the event is kept, and the next event or awf tick tries again), 2 when the event is",
-  "wrong for its target: its name, its data, or its id.",
-].join("\n");
+export const emitUsage = help.trimEnd();
 
 export async function emitCommand(
   argv: readonly string[],

package/src/help/allowance.txt

@@ -0,0 +1,13 @@
+usage: awf allowance [harness...] [--json]
+
+What is left of each harness's plan, as the harness itself shows it: claude's /usage, as
+claude -p /usage prints it; codex's /status, as its app-server answers it; and cursor's /usage,
+read in a Herdr pane. pi has none of its own. Nothing asks a model. Every harness when
+none is named: claude, codex, pi, cursor.
+
+A plan's monthly price is an estimate at the vendor's list price as of the table's date:
+plans 2026-10-05.
+
+--json prints one document, the interface for scripts, with the plan as the
+harness names it and no price; what it prints otherwise is for reading. A harness that could
+not be read says why. Exits 0 once every harness was asked, 2 on a usage error.

package/src/help/emit.txt

@@ -0,0 +1,13 @@
+usage: awf emit --target <file> --id <id> <event> [<json>] [--event-id <id>] [--json]
+
+Sends an event to the run of a workflow with events that --id names. That run starts if it has
+none and the event is one that starts one, and is woken if it has one: told while it runs,
+continued when it is parked or crashed. The run lives in the project of <file>, the nearest
+directory above it holding .awf/, whoever sends. --event-id names the occurrence: the same id
+again is a duplicate.
+
+Prints what became of the event, and what was done to the run: accepted, duplicate or refused.
+--json prints one document. Exits 0 for any of the three; 1 when <file> could not be loaded, and
+nothing is kept, or when the run's attempt could not be started (the event is kept, and the next
+event or awf tick tries again); 2 on a usage error, for a workflow with no events, or when the
+event is wrong for its target: its name, its data, or its id.

package/src/help/inbox.txt

@@ -0,0 +1,12 @@
+usage: awf inbox [<run>] [--open] [--workflow <name>] [--as <key>] [--after <cursor>] [--wait <seconds>]
+                 [--cwd <directory>] [--run-root <directory>] [--json]
+
+What agents said to a participant outside the run, and what it said back: routes, messages,
+answers, questions that closed unanswered, and each attempt's end, oldest first. Without a run,
+every run here that connected one; --workflow narrows that. A run is <workflow>/<id>, or an <id>
+only one workflow has. --after reads on from a cursor the last answer gave; --wait
+waits up to that many seconds, at most 300, when nothing is new. --open lists the questions
+still waiting for an answer, a snapshot. --json prints one item per line.
+
+Exits 0 on a read that worked, 1 when there is no such run, it has no participant, or the
+cursor is another's, 2 on a usage error, 3 when the run's files could not be read.

package/src/help/init.txt

@@ -0,0 +1,12 @@
+usage: awf init [dir] [--no-install]
+
+Sets up the current directory, or dir, for writing workflows: hello/workflow.ts, a workflow
+with one agent, and hello/workflow.test.ts, its test; package.json, tsconfig.json, .gitignore
+and AGENTS.md. Then runs bun install, unless --no-install, for editor types: awf runs a
+workflow against its own copies either way.
+
+Never overwrites. A file that exists is skipped, except that package.json gains the
+devDependencies and scripts it lacks and .gitignore the lines it lacks.
+
+Exits 0; 1 when a file could not be written, or bun install failed (the files written are
+kept); 2 on a usage error.

package/src/help/logs.txt

@@ -0,0 +1,13 @@
+usage: awf logs [<run>] [@<handle>] [--agent <key>] [--stage <name>] [--after <cursor>]
+                [--limit <n>] [--wait <seconds> | --follow] [--full] [--cwd <directory>]
+                [--run-root <directory>] [--json]
+
+What a run did and is doing: its events and what its agents did, read from their own session
+files, merged by time. With no run, the newest here. Without --after, the last 40 events; with
+it, what came after, oldest first. Every answer ends with the command that gets only what is
+new. --wait: with nothing to show yet, wait for the first event, at most that many seconds, up
+to 300; --follow prints each event as it comes until the run ends. @<handle> names one event,
+and --full prints its text, with common credential shapes masked; --json carries it always.
+
+Exits 0 on any read that worked, 1 when there is no such run or the cursor or handle does not
+fit it, 2 on a usage error, 3 when the run's files could not be read.

package/src/help/reply.txt

@@ -0,0 +1,18 @@
+usage: awf reply <run> <agent> [--to <id>] [--as <participant>] [<text>]
+       awf send <run> <agent> [--as <participant>] [<text>]
+       awf send <run> --as <participant> --event-id <id> [--author <name>] [<text>]
+each takes [--cwd <directory>] [--run-root <directory>] [--json]
+
+A run is <workflow>/<id>, or an <id> only one workflow has, here or in a project awf knows.
+Answers a question an agent asked a participant outside the run, or messages an agent first,
+over a route the workflow allowed. The text is the argument, or stdin without one. --to names
+the question, as awf inbox prints it; it may be left out when the agent has one open. --as
+names the participant when the workflow connects more than one. Neither waits for an answer:
+it comes back in awf inbox. With --event-id, send is a reply on a participant the run routes to its
+code: no agent, it reaches the run whether it runs or is parked, and the same id again is a
+duplicate. The id is one the run has not had from anyone, as a chat's message ids are. It prints
+as awf emit does, and exits 0 for whatever the run did with it (accepted, duplicate, or refused
+by a run that returned); 1 when the run or participant isn't found, or its attempt didn't start.
+
+Exits 0 when delivered, 1 when refused (the code says why), 2 on a usage error, 3 when the run
+could not be reached.

package/src/help/run.txt

@@ -0,0 +1,44 @@
+usage: awf run [options] <workflow-file> [options] [-- workflow arguments...]
+       awf run [options] <workflow-file> --id <id> --continue
+run options: --id <id>, --continue, --from-stage <stage>, --values <file>,
+             --timeout <duration>, --run-root <directory>, --cwd <directory>, --sandbox <file>,
+             --json, --no-watch, --here
+
+Each awf run is an attempt of a run: a new run, with --id's id or a generated one, or, with
+--continue, the run --id names, with the arguments, --cwd and --sandbox it was started with. A continue reuses
+the stages that succeeded, up to the first with no record or to --from-stage, and runs the rest.
+A new run with --from-stage starts there. A stage before it with no record to reuse takes its
+value from --values, a JSON object by stage name, checked by its result; one that returns
+nothing is passed. Without one the attempt stops, naming the stage and its schema.
+A run is kept in .awf/runs/<workflow>/<id> under --cwd, unless --run-root names another folder
+for .awf/runs.
+A run has no deadline unless --timeout gives it one, per attempt.
+A workflow that knows how to present its result prints that; --json prints the full result instead.
+Either way the full result is kept as output.json in the run's folder, beside report.md
+when the workflow writes one. A run that fails or is cancelled once its agents have started keeps
+output.json too, with what it spent and why it ended; --json prints it. A second Ctrl-C stops
+awf at once, without it.
+--cwd sets the directory the workflow and its agents work in; it defaults to the current one.
+--sandbox puts every agent of the run in one sandbox, working in --cwd; the file is a JSON spec
+such as {"read": ["/data/request.md"], "srt": {}}, naming srt or docker, whose relative paths are
+from --cwd. A workflow that opens a sandbox of its own is refused.
+A sandbox with its own Herdr, as a docker box has, gets a tab in the run's workspace showing its
+panes; --no-watch leaves it out, and awf still prints the command that shows them.
+--here, run by an agent in a Herdr pane, starts the run in a new tab and has it take that agent's
+session over as one of its agents, from its next turn until the run ends. It prints a line for
+the agent to end its turn with, which is how the run finds the session.
+A run of a workflow with events is named by --id, or by the workflow's id(args). awf run starts it
+with its arguments and no event, detached in its project, as awf emit would, and the run waits at
+its first receive. A run already there is only woken. A run an event starts has no argv: its args
+are what prepare makes of none.
+Exits 0 when the run completed or parked, 1 when it failed or timed out, 2 on a usage error or
+when the run is refused, 3 when it stopped and can go on with --continue, and 128 plus the
+signal's number when it was interrupted.
+
+Examples:
+  awf run examples/minimum-review/review-loop.ts
+  awf run --timeout 20m examples/minimum-review/review-loop.ts
+  awf run examples/minimum-review/review-loop.ts -- packages/engine/src
+  awf run examples/minimum-review/review-loop.ts --cwd ../other-repo
+
+Workflow files are trusted code and run with your filesystem and process authority.

package/src/help/runs.txt

@@ -0,0 +1,11 @@
+usage: awf runs [--limit <n>] [--cwd <directory>] [--run-root <directory>] [--json]
+       awf runs <run> [--cwd <directory>] [--run-root <directory>] [--json]
+
+The runs here, newest first, or one run in depth: its attempts, the stages of the last, what
+each agent is doing, and what to run next. The list shows 20 unless --limit says another
+number. A run is <workflow>/<id>, or an <id> only one
+workflow has. Runs are listed under --cwd's .awf/runs, or --run-root, as awf run keeps them; a
+run named is found there first, then in each project awf has started a run with events in.
+
+--json prints one document, the interface for scripts. Exits 0 on any read that worked, 1 when
+there is no such run, 2 on a usage error, 3 when the run's files could not be read.

package/src/help/test.txt

@@ -0,0 +1,9 @@
+usage: awf test [paths...] [-t <pattern>] [--watch] [--timeout <duration>]
+
+Runs a workflow's tests (*.test.ts and *.spec.ts files) under the current directory, or under
+each file or directory given, with agentswf/workflow, agentswf/testing and typebox served as
+awf run serves them: nothing is installed. -t runs the tests whose names match the pattern;
+--watch reruns them on a change; --timeout bounds each test, 5s by default.
+
+Exits 0 when every test passed, 1 when one failed or none was found, 2 on a usage error. What
+it prints is for reading, not parsing.

package/src/help/tick.txt

@@ -0,0 +1,12 @@
+usage: awf tick [--cwd <directory>] [--run-root <directory>] [--json]
+       awf tick --all [--json]
+
+Wakes every run of a workflow with events under --cwd's .awf/runs, or --run-root, the runs awf
+runs lists there, as an event would: continues a parked run whose wait's timer is due, and a
+crashed or failed one until it has failed three times in a row. Runs of other workflows are left
+as they are. --all wakes them in every project awf has started one in, as ~/.awf/projects lists
+them. Run it on any schedule; a run is continued once however many wakers come at once.
+
+Prints a line for each run it woke, and nothing when it woke none. --json prints one document.
+Exits 0; 1 when a project is gone or a run could not be woken, the others still woken; 2 on a
+usage error.

package/src/here.ts

@@ -198,7 +198,7 @@ function passedSession(
 }
 
 /**
- * What lets a sandboxed session reach Herdr's socket, which `--here` and every `wf` call need: its
+ * What lets a sandboxed session reach Herdr's socket, which `--here` and every `wfa` call need: its
  * harness's own advice, for the harness whose session variable this shell has.
  */
 function sandboxFix(env: Readonly<Record<string, string | undefined>>): string {

package/src/holder-command.ts

@@ -6,6 +6,7 @@ import { deliver, eventIdProblem } from "./emit";
 import { printEmit } from "./emit-command";
 import { messageOf } from "./errors";
 import { isCode } from "./files";
+import help from "./help/reply.txt" with { type: "text" };
 import { ItemFold } from "./inbox-command";
 import { coordinatorDir } from "./machine";
 import { failed, type Out, parsePlace, type ReadPlace } from "./run-commands";
@@ -13,26 +14,7 @@ import { findRunByRef, RunNotFound, type RunStatus } from "./run-state";
 import { readAttempts, readEvents, readNumberedEvents } from "./runs";
 import { exchange } from "./socket-exchange";
 
-export const replyUsage = [
-  "usage: awf reply <run> <agent> [--to <id>] [--as <participant>] [<text>]",
-  "       awf send <run> <agent> [--as <participant>] [<text>]",
-  "       awf send <run> --as <participant> --event-id <id> [--author <name>] [<text>]",
-  "each takes [--cwd <directory>] [--run-root <directory>] [--json]",
-  "",
-  "A run is <workflow>/<id>, or an <id> only one workflow has, here or in a project awf knows.",
-  "Answers a question an agent asked a participant outside the run, or messages an agent first,",
-  "over a route the workflow allowed. The text is the argument, or stdin without one. --to names",
-  "the question, as awf inbox prints it; it may be left out when the agent has one open. --as",
-  "names the participant when the workflow connects more than one. Neither waits for an answer:",
-  "it comes back in awf inbox. With --event-id, send is a reply on a participant the run routes to its",
-  "code: no agent, it reaches the run whether it runs or is parked, and the same id again is a",
-  "duplicate. The id is one the run has not had from anyone, as a chat's message ids are. It prints",
-  "as awf emit does, and exits 0 for whatever the run did with it (delivered, duplicate, or refused",
-  "by a run that returned); 1 when the run or participant isn't found, or its attempt didn't start.",
-  "",
-  "Exits 0 when delivered, 1 when refused (the code says why), 2 on a usage error, 3 when the run",
-  "could not be reached.",
-].join("\n");
+export const replyUsage = help.trimEnd();
 
 type Options = {
   command: "reply" | "send";

package/src/inbox-command.ts

@@ -14,6 +14,7 @@ import { maskCredentials } from "@agentswf/harness";
 import { duration } from "./duration";
 import { messageOf } from "./errors";
 import { exists } from "./files";
+import help from "./help/inbox.txt" with { type: "text" };
 import { readMailbox } from "./mailbox";
 import {
   clockTime,
@@ -34,20 +35,7 @@ import {
   readEventsFrom,
 } from "./runs";
 
-export const inboxUsage = [
-  "usage: awf inbox [<run>] [--open] [--workflow <name>] [--as <key>] [--after <cursor>] [--wait <seconds>]",
-  "                 [--cwd <directory>] [--run-root <directory>] [--json]",
-  "",
-  "What agents said to a participant outside the run, and what it said back: routes, messages,",
-  "answers, questions that closed unanswered, and each attempt's end, oldest first. Without a run,",
-  "every run here that connected one; --workflow narrows that. A run is <workflow>/<id>, or an <id>",
-  "only one workflow has. --after reads on from a cursor the last answer gave; --wait",
-  "waits up to that many seconds, at most 300, when nothing is new. --open lists the questions",
-  "still waiting for an answer, a snapshot. --json prints one item per line.",
-  "",
-  "Exits 0 on a read that worked, 1 when there is no such run, it has no participant, or the",
-  "cursor is another's, 2 on a usage error, 3 when the run's files could not be read.",
-].join("\n");
+export const inboxUsage = help.trimEnd();
 
 const MAX_WAIT_SECONDS = 300;
 const POLL_MS = 1_000;

package/src/init-command.ts

@@ -2,19 +2,10 @@ import { existsSync, lstatSync, mkdirSync, readFileSync, statSync, writeFileSync
 import { basename, dirname, join, relative, resolve } from "node:path";
 import manifest from "../package.json" with { type: "json" };
 import { messageOf } from "./errors";
+import help from "./help/init.txt" with { type: "text" };
 import type { Out } from "./run-commands";
 
-export const initUsage = [
-  "usage: awf init [dir] [--no-install]",
-  "",
-  "Sets up the current directory, or dir, for writing workflows: hello/workflow.ts, a workflow",
-  "with one agent, and hello/workflow.test.ts, its test; package.json, tsconfig.json, .gitignore",
-  "and AGENTS.md. Then runs bun install, unless --no-install, for editor types: awf runs a",
-  "workflow against its own copies either way.",
-  "",
-  "Never overwrites. A file that exists is skipped, except that package.json gains the",
-  "devDependencies and scripts it lacks and .gitignore the lines it lacks.",
-].join("\n");
+export const initUsage = help.trimEnd();
 
 export type InitCommand = { dir: string; install: boolean };
 

package/src/init-template/AGENTS.md.template

@@ -1,13 +1,13 @@
 # Workflows
 
-This folder holds [agents.wf](https://github.com/romanlv/agentswf) workflows: TypeScript files
+This folder holds [agents.wf](https://agents.wf) workflows: TypeScript files
 that run coding agents, started with `awf`.
 
 - A workflow is a folder with a `workflow.ts`, which default-exports
   `defineWorkflow(…)` from `agentswf/workflow`, and a `workflow.test.ts` beside it.
   `hello/` is the smallest one; copy it to start another.
-- The API, with every option and outcome:
-  https://github.com/romanlv/agentswf/blob/main/docs/workflow-api.md
+- The API, with every option and outcome, as Markdown:
+  https://agents.wf/reference/workflow-api.md. Every other page is in https://agents.wf/llms.txt.
 - `awf test` runs the tests with each agent replaced by scripted answers: no agent starts, and it
   costs nothing. After a change, run it and `bun run check`, which typechecks.
 - `awf run hello/workflow.ts` starts real agents, on the operator's accounts. Don't run a workflow

package/src/init-template/hello/workflow.ts.template

@@ -1,14 +1,14 @@
-import { defineWorkflow, isAnswered } from "agentswf/workflow";
+import { defineWorkflow } from "agentswf/workflow";
 import Type from "typebox";
 
 export const ANSWER = Type.Object({ answer: Type.Integer() }, { additionalProperties: false });
 
 export default defineWorkflow({
   meta: { name: "hello", description: "Ask one agent a question with a known answer." },
-  async run(workflow) {
+  async run(wf) {
     // A headless agent needs neither Herdr nor a sandbox. Swap in any harness and model your
     // account has: "claude" in a pane, the default placement, runs on a subscription.
-    const agent = await workflow.agents.open({
+    const agent = await wf.agents.open({
       key: "hello",
       runtime: { harness: "codex", model: "gpt-6-luna", placement: "headless" },
     });
@@ -17,6 +17,6 @@ export default defineWorkflow({
       schema: ANSWER,
       timeoutMs: 3 * 60_000,
     });
-    return isAnswered(outcome) ? outcome.value : { unanswered: outcome.reason };
+    return outcome.answered ? outcome.value : { unanswered: outcome.reason };
   },
 });