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

package/src/logs-command.ts

@@ -3,6 +3,7 @@ import type { LogEventJson, LogsJson, RouteEnds, RunLogLine } from "@agentswf/co
 import type { JsonObject } from "@agentswf/contract/workflow";
 import { duration } from "./duration";
 import { messageOf } from "./errors";
+import help from "./help/logs.txt" with { type: "text" };
 import {
   clockTime,
   command,
@@ -34,21 +35,7 @@ import {
 import { findRun, findRunByRef, type RunStatus } from "./run-state";
 import { describeActivity } from "./run-view";
 
-export const logsUsage = [
-  "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.",
-].join("\n");
+export const logsUsage = help.trimEnd();
 
 const DEFAULT_LIMIT = 40;
 /**

package/src/mailbox.ts

@@ -26,7 +26,19 @@ export function mailboxFile(runDir: string): string {
 /** The run's mailbox in the order written, less a line a crash tore and kinds this awf doesn't know. */
 export async function readMailbox(runDir: string): Promise<MailboxRecord[]> {
   const lines = await readLines<MailboxRecord>(mailboxFile(runDir));
-  return lines.filter((line) => line.version === MAILBOX_RECORD_VERSION && KINDS.has(line.kind));
+  return lines
+    .filter((line) => line.version === MAILBOX_RECORD_VERSION && KINDS.has(line.kind))
+    .map(withAnswered);
+}
+
+/** A turn's end written before 0.1.0-beta.4 has no `answered`, which a workflow would read as false. */
+function withAnswered(line: MailboxRecord): MailboxRecord {
+  if (line.kind !== "event" || line.name !== "agent:ended") return line;
+  const end = line.data as { outcome?: { kind: string; answered?: boolean } };
+  if (end?.outcome === undefined || end.outcome.answered !== undefined) return line;
+  const answered = end.outcome.kind === "answered";
+  const data = { ...end, outcome: { ...end.outcome, answered } } as unknown as JsonValue;
+  return { ...line, data };
 }
 
 const KINDS = new Set<string>([
@@ -137,6 +149,7 @@ export async function recoverTurns(
           turn: turn.turn,
           meta: turn.meta,
           outcome: {
+            answered: false,
             kind: "failed",
             reason: `attempt ${turn.attempt} ended before this turn did; its work, if any, is in the agent's session`,
             retryable: true,
@@ -972,6 +985,6 @@ function checked(options: ReceiveOptions | undefined): {
     throw new Error("receive's label is a string");
   if (take !== "all" && take !== "oldest") throw new Error('receive\'s take is "all" or "oldest"');
   if ("until" in (options ?? {}))
-    throw new Error("receive has no until: a timer, workflow.timer(name, when), wakes it");
+    throw new Error("receive has no until: a timer, wf.timer(name, when), wakes it");
   return { ...(label === undefined ? {} : { label }), take };
 }

package/src/messaging/limits.ts

@@ -13,7 +13,7 @@ export const MESSAGE_LIMITS: MessageLimits = {
 /**
  * Where an asker may wait for an answer, by harness and placement: on where M2 passed
  * (`docs/findings/messaging-m2.md`), off elsewhere. A pane that is `confirmed` waits only where it
- * confirms what it was sent, as `wf waiting` needs. The fake harness always may. cursor is off:
+ * confirms what it was sent, as `wfa waiting` needs. The fake harness always may. cursor is off:
  * its turns ran past their deadline in M2.
  */
 export const AWAIT_REPLY: Readonly<Record<string, { headless?: true; pane?: true | "confirmed" }>> =

package/src/messaging/messaging.ts

@@ -47,7 +47,7 @@ export interface MessagingHost {
   agent(key: AgentKey): AgentView | undefined;
   /** Whether it may `--await-reply` where it runs. */
   canAwait(key: AgentKey): boolean;
-  /** The launcher it runs `wf` through. */
+  /** The launcher it runs `wfa` through. */
   launcher(key: AgentKey): string;
   /** Something is new for this agent: messages for it, or an end to its wait. */
   changed(key: AgentKey): void;
@@ -207,7 +207,7 @@ type Operation = OperationInfo & {
 /**
  * The messaging logic of one attempt: routes, admission, inboxes and owed answers. It decides every
  * case the design lists and writes the record; it starts nothing. The runner opens and continues
- * operations when it says, and the control plane hands it `wf`'s commands.
+ * operations when it says, and the control plane hands it `wfa`'s commands.
  */
 export class Messaging {
   readonly limits: MessageLimits;
@@ -702,8 +702,8 @@ export class Messaging {
   }
 
   /**
-   * A refusal of `wf result` or `wf waiting` given this call id, or the acknowledgement of a
-   * `wf waiting` while an answer is awaited; null when the command goes on as before.
+   * A refusal of `wfa result` or `wfa waiting` given this call id, or the acknowledgement of a
+   * `wfa waiting` while an answer is awaited; null when the command goes on as before.
    */
   checkFinish(
     agent: AgentKey,
@@ -715,7 +715,7 @@ export class Messaging {
     | null {
     const operation = this.#operations.get(id);
     if (!operation || operation.agent !== agent) return null;
-    const wf = this.#host.launcher(agent);
+    const wfa = this.#host.launcher(agent);
     // A message operation's call takes no result, ended or not.
     if (operation.kind === "message") {
       return {
@@ -733,8 +733,8 @@ export class Messaging {
         code: "owes-reply",
         error:
           command === "result"
-            ? `you owe ${peer} a reply. Send it with ${wf} reply ${peer}, then run ${wf} result ${id} again.`
-            : `you owe ${peer} a reply; send it with ${wf} reply ${peer} first.`,
+            ? `you owe ${peer} a reply. Send it with ${wfa} reply ${peer}, then run ${wfa} result ${id} again.`
+            : `you owe ${peer} a reply; send it with ${wfa} reply ${peer} first.`,
       };
     }
     const waited = operation.awaits;
@@ -743,7 +743,7 @@ export class Messaging {
         kind: "awaiting",
         peer: waited.owedBy,
         ...(waited.until === undefined ? {} : { until: waited.until }),
-        notice: `you already await ${waited.owedBy}'s reply${waited.until === undefined ? "" : `, until ${clock(waited.until, this.#host.now())}`}. End your turn, or finish with ${wf} result ${id}.`,
+        notice: `you already await ${waited.owedBy}'s reply${waited.until === undefined ? "" : `, until ${clock(waited.until, this.#host.now())}`}. End your turn, or finish with ${wfa} result ${id}.`,
       };
     }
     return null;
@@ -815,7 +815,7 @@ export class Messaging {
   ):
     | { kind: "ok"; operation: Operation; route: Route; bytes: number }
     | { kind: "refused"; code: SendCode; error: string } {
-    const wf = this.#host.launcher(from);
+    const wfa = this.#host.launcher(from);
     const operation = this.#current.get(from);
     if (!operation) return refuse("no-operation", "this agent has no open operation.");
     const { peer } = request;
@@ -826,14 +826,14 @@ export class Messaging {
       return refuse(
         "no-route",
         owes
-          ? `your route with ${peer} only answers its requests. Answer it with ${wf} reply ${peer}.`
+          ? `your route with ${peer} only answers its requests. Answer it with ${wfa} reply ${peer}.`
           : `your route with ${peer} only answers its requests, and it asked nothing. Nothing to send; end your turn.`,
       );
     };
     if (initiating.length === 0) {
       return this.#open(peer, from)
         ? replyOnly()
-        : refuse("no-route", `no route to ${peer}. Your routes: ${wf} peers`);
+        : refuse("no-route", `no route to ${peer}. Your routes: ${wfa} peers`);
     }
     const agent = this.#outside.has(peer) ? undefined : this.#host.agent(peer);
     if (agent?.state === "stopped")
@@ -889,7 +889,7 @@ export class Messaging {
   ):
     | { kind: "ok"; operation: Operation; owed: Obligation; bytes: number }
     | { kind: "refused"; code: ReplyCode; error: string } {
-    const wf = this.#host.launcher(from);
+    const wfa = this.#host.launcher(from);
     const operation = this.#current.get(from);
     if (!operation) return refuse("no-operation", "this agent has no open operation.");
     const { peer } = request;
@@ -898,7 +898,7 @@ export class Messaging {
       (each) => each.asker === peer && each.owedBy === from && each.request.shown,
     );
     if (!latest || latest.state === "replied") {
-      return refuse("none-owed", `you owe ${peer} nothing. Send it with ${wf} send ${peer}.`);
+      return refuse("none-owed", `you owe ${peer} nothing. Send it with ${wfa} send ${peer}.`);
     }
     if (latest.state !== "open" || latest.owingOperation !== operation) {
       const agent = this.#host.agent(peer);
@@ -906,7 +906,7 @@ export class Messaging {
         "expired",
         agent?.state === "stopped"
           ? `${peer} has stopped${agent.reason ? ` (${JSON.stringify(agent.reason)})` : ""}; nothing reaches it now.`
-          : `${peer} stopped waiting at ${clock(latest.endedAt ?? this.#host.now(), this.#host.now())}. Send it with ${wf} send ${peer}.`,
+          : `${peer} stopped waiting at ${clock(latest.endedAt ?? this.#host.now(), this.#host.now())}. Send it with ${wfa} send ${peer}.`,
       );
     }
     const route = latest.request.route;
@@ -950,7 +950,7 @@ export class Messaging {
     /** The question a reply answers, which counts as answered here. */
     answering?: Obligation,
   ): { kind: "refused"; code: "awaiting" | "unsupported" | "cycle"; error: string } | undefined {
-    const wf = this.#host.launcher(from);
+    const wfa = this.#host.launcher(from);
     if (operation.awaits?.state === "open") {
       return refuse(
         "awaiting",
@@ -984,7 +984,7 @@ export class Messaging {
         return refuse(
           "cycle",
           owing
-            ? `${who}, and you owe ${last === peer ? "it" : last} a reply. Answer with ${wf} reply ${last}; it may --await-reply.`
+            ? `${who}, and you owe ${last === peer ? "it" : last} a reply. Answer with ${wfa} reply ${last}; it may --await-reply.`
             : `${who}. Send without --await-reply and end your turn; ${last}'s request reaches you then.`,
         );
       }
@@ -1095,7 +1095,7 @@ export class Messaging {
   }
 
   /**
-   * Durable before `wf send` returns: a failed write rejects, and `wf` says it may have been
+   * Durable before `wfa send` returns: a failed write rejects, and `wfa` says it may have been
    * queued. An outside participant's message says what it came through instead of an operation.
    * A question to one carries when it closes unanswered, if it has a limit.
    */
@@ -1134,13 +1134,13 @@ export class Messaging {
   }
 
   #awaitNotice(operation: Operation, { until }: { until?: number }): string {
-    const wf = this.#host.launcher(operation.agent);
+    const wfa = this.#host.launcher(operation.agent);
     return [
       `Its reply starts your next turn (${until === undefined ? "no deadline" : `deadline ${clock(until, this.#host.now())}`}).`,
       "Go on with work that does not need the answer, then end your turn with one line saying what you await; do not poll or sleep.",
       ...(operation.kind === "workflow"
         ? [
-            `If you find the answer first, or decide not to wait, finish with ${wf} result ${operation.id}; the wait is dropped.`,
+            `If you find the answer first, or decide not to wait, finish with ${wfa} result ${operation.id}; the wait is dropped.`,
           ]
         : []),
     ].join("\n");
@@ -1323,7 +1323,7 @@ export class Messaging {
   /**
    * What is held for an operation whose turn has ended, deciding nothing: `continues` when its turn
    * end would go on with it, `held` when messages wait for a later operation or to cut a check-in's
-   * `wf waiting` short, `none` otherwise.
+   * `wfa waiting` short, `none` otherwise.
    */
   pending(id: string): Pending {
     const operation = this.#operations.get(id);
@@ -1405,7 +1405,7 @@ export class Messaging {
     };
   }
 
-  /** The line `wf` leads with while this agent's operation owes or awaits an answer. */
+  /** The line `wfa` leads with while this agent's operation owes or awaits an answer. */
   owing(agent: AgentKey): string | undefined {
     const { owes, awaits } = this.#standing(agent);
     return owingLine(owes, awaits, this.#host.launcher(agent), this.#host.now());
@@ -1476,7 +1476,7 @@ export class Messaging {
 
   /**
    * This agent's open routes, either end, in the order granted; with `stopped`, also those a peer's
-   * stop closed, so `wf peers` can say it stopped.
+   * stop closed, so `wfa peers` can say it stopped.
    */
   #routesOf(agent: AgentKey, stopped = false): Route[] {
     return [...new Set([...this.#routes.values()].flat())]

package/src/messaging/routes.ts

@@ -29,7 +29,7 @@ export type Route = {
   open: boolean;
   /** Why it closed. */
   closed?: "stage-ended" | "agent-stopped" | "released" | "attempt-ended";
-  /** Its place among the attempt's grants, which `wf peers` lists in. */
+  /** Its place among the attempt's grants, which `wfa peers` lists in. */
   readonly order: number;
 };
 

package/src/messaging/text.ts

@@ -4,7 +4,7 @@ import type { AgentKey } from "@agentswf/contract/workflow";
 
 /**
  * Everything an agent reads about messaging. The engine writes it all, since only it knows the
- * launcher's path, the routes' purposes and what closes a cycle; `wf` prints it as given. `wf`
+ * launcher's path, the routes' purposes and what closes a cycle; `wfa` prints it as given. `wfa`
  * here is always the launcher's full path: the command is not on the agent's PATH.
  */
 
@@ -13,7 +13,7 @@ export type Recipient = {
   launcher: string;
   /** The operation's call id. */
   callId: string;
-  /** A workflow's own operation finishes with `wf result`; a message operation ends its turn. */
+  /** A workflow's own operation finishes with `wfa result`; a message operation ends its turn. */
   kind: "workflow" | "message";
 };
 
@@ -92,7 +92,7 @@ export function envelope(
   } = {},
 ): string {
   const tag = options.tag ?? nonce();
-  const wf = to.launcher;
+  const wfa = to.launcher;
   const blocks: string[] = [];
   const owed = new Set<AgentKey>();
   for (const item of items) {
@@ -104,7 +104,7 @@ export function envelope(
     if (item.answers) {
       blocks.push(
         [
-          `The reply you were waiting for, from ${item.from}${item.asks ? `; it asks something back, so you owe it a reply: answer with ${wf} reply ${item.from}` : ""}.`,
+          `The reply you were waiting for, from ${item.from}${item.asks ? `; it asks something back, so you owe it a reply: answer with ${wfa} reply ${item.from}` : ""}.`,
           "",
           fenced("reply", item.from, item.text, tag),
         ].join("\n"),
@@ -114,13 +114,13 @@ export function envelope(
     const stop = /[.!?]$/.test(item.purpose) ? "" : ".";
     const head = `Message from ${item.from}, on the route ${quoted(item.purpose)}${stop}`;
     const lead = options.opens ? ` This is a message, not a new task (call ${to.callId}).` : "";
-    const asks = item.asks ? ` A reply is required: answer with ${wf} reply ${item.from}.` : "";
+    const asks = item.asks ? ` A reply is required: answer with ${wfa} reply ${item.from}.` : "";
     blocks.push(
       [`${head}${lead}${asks}`, "", fenced("message", item.from, item.text, tag)].join("\n"),
     );
   }
   const lines = [blocks.join("\n\n")];
-  if (options.announced?.length) lines.push(announcement(options.announced, wf));
+  if (options.announced?.length) lines.push(announcement(options.announced, wfa));
   const plain = items.some((item) => item.kind === "message" && !item.answers);
   if (plain) lines.push(GUARD);
   lines.push(next(items, to, owed));
@@ -129,7 +129,7 @@ export function envelope(
 
 /** The closing line: whether the task goes on, and how it ends. */
 function next(items: readonly Delivered[], to: Recipient, owed: ReadonlySet<AgentKey>): string {
-  const wf = to.launcher;
+  const wfa = to.launcher;
   const failed = items.some((item) => item.kind === "no-reply");
   const answered = items.some((item) => item.kind === "message" && item.answers);
   if (to.kind === "message") {
@@ -140,9 +140,9 @@ function next(items: readonly Delivered[], to: Recipient, owed: ReadonlySet<Agen
       return `Your work for call ${to.callId} continues; end your turn when it is done.`;
     return `No reply is required; end your turn once you have acted on it ${call}.`;
   }
-  const finish = `finish it with ${wf} result ${to.callId}`;
+  const finish = `finish it with ${wfa} result ${to.callId}`;
   if (owed.size > 0) return `Your task ${to.callId} goes on: once you have replied, ${finish}.`;
-  if (failed) return `Continue without it, or finish with ${wf} result ${to.callId}.`;
+  if (failed) return `Continue without it, or finish with ${wfa} result ${to.callId}.`;
   return `Your task ${to.callId} continues; ${finish}.`;
 }
 
@@ -162,12 +162,12 @@ function routeLine({ peer, can, purpose }: RouteLine): string {
 /** What an operation's prompt says about the agent's routes, once, in a few lines. */
 export function routeLesson(routes: readonly RouteLine[], launcher: string): string {
   if (routes.length === 0) return "";
-  const wf = launcher;
+  const wfa = launcher;
   return [
     "You can message other agents on these routes:",
     ...routes.map(routeLine),
-    `See them with ${wf} peers. Send with ${wf} send <peer> <<'EOF' ... EOF. To ask and wait for the answer, send with ${wf} send --await-reply <peer>; the answer starts your next turn, so end your turn then, and do not poll or sleep.`,
-    `Answer a question with ${wf} reply <peer> <<'EOF' ... EOF; only a reply counts as the answer.`,
+    `See them with ${wfa} peers. Send with ${wfa} send <peer> <<'EOF' ... EOF. To ask and wait for the answer, send with ${wfa} send --await-reply <peer>; the answer starts your next turn, so end your turn then, and do not poll or sleep.`,
+    `Answer a question with ${wfa} reply <peer> <<'EOF' ... EOF; only a reply counts as the answer.`,
   ].join("\n");
 }
 
@@ -181,14 +181,14 @@ function announcement(routes: readonly RouteLine[], launcher: string): string {
 
 /** The one reminder a turn that ends owing gets. */
 export function reminder(owed: readonly AgentKey[], to: Recipient): string {
-  const wf = to.launcher;
+  const wfa = to.launcher;
   const who = owed.join(" and ");
-  const how = owed.map((peer) => `${wf} reply ${peer}`).join(", then ");
-  const then = to.kind === "workflow" ? `then ${wf} result ${to.callId}` : "then end your turn";
+  const how = owed.map((peer) => `${wfa} reply ${peer}`).join(", then ");
+  const then = to.kind === "workflow" ? `then ${wfa} result ${to.callId}` : "then end your turn";
   return `You owe ${who} a reply; send it with ${how}, ${then}.`;
 }
 
-/** The line every `wf` command leads with while the operation owes or awaits an answer. */
+/** The line every `wfa` command leads with while the operation owes or awaits an answer. */
 export function owingLine(
   owes: readonly AgentKey[],
   awaits: { peer: AgentKey; until?: number } | undefined,
@@ -207,7 +207,7 @@ export function owingLine(
   return parts.length === 0 ? undefined : `${parts.join("; ")}.`;
 }
 
-/** `wf peers`'s table, the line about what is owed, and nothing for empty cells. */
+/** `wfa peers`'s table, the line about what is owed, and nothing for empty cells. */
 export function peersTable(
   peers: readonly PeerView[],
   awaits: { peer: AgentKey; until?: number } | undefined,

package/src/operation-liveness.ts

@@ -506,7 +506,7 @@ export async function superviseOperation(options: Options): Promise<SupervisedOu
           deliveryUntil === undefined &&
           receiptUntil === undefined;
         const messages = options.messages;
-        // Before any check-in: what continues it goes now, cutting a `wf waiting` short, and an
+        // Before any check-in: what continues it goes now, cutting a `wfa waiting` short, and an
         // operation awaiting an answer waits for it with no check-in.
         if (messages && settledTurn) {
           if (messages.pending() === "continues") {

package/src/operator-runtime.ts

@@ -56,7 +56,7 @@ export type OperatorRuntimeInstallation = {
   sandboxes?: SandboxProviders;
   /** The decision models workflows may ask, and their aliases. */
   decisions?: DecisionInstallation;
-  /** How `workflow.allowance` reads a harness's plan, as `awf allowance` does. */
+  /** How `wf.allowance` reads a harness's plan, as `awf allowance` does. */
   allowance?: (harness: Harness) => Promise<HarnessAllowance>;
   cleanup(): Promise<void>;
 };
@@ -181,7 +181,7 @@ export async function installOperatorRuntime(
     sandboxes: await installSandboxes(environment),
     decisions: installDecisions({ OPENROUTER_API_KEY: await openRouterKey(environment) }),
     allowance: allowanceReader(environment, run, undefined, home),
-    // Nothing to undo: the agent's `wf` is a launcher the control plane installs beside its own
+    // Nothing to undo: the agent's `wfa` is a launcher the control plane installs beside its own
     // socket, and the control plane removes both when the run closes.
     cleanup: async () => undefined,
   };
@@ -282,9 +282,8 @@ export function herdrConfig(session: string): HerdrConfig {
 
 /**
  * The sandbox providers this machine has: srt when its CLI is on `PATH`, docker when its CLI is;
- * its daemon is first asked when a sandbox opens. srt is the default when installed, as it runs
- * the project's own toolchain, which an image lacks (story 004), and when it is there but cannot
- * be set up: a spec naming none then fails saying why, rather than moving to docker unsaid.
+ * its daemon is first asked when a sandbox opens. There is no default: a spec names its provider,
+ * since the two give agents different machines, the host's toolchain or an image.
  */
 export async function installSandboxes(
   environment: Readonly<Record<string, string | undefined>>,
@@ -304,10 +303,8 @@ export async function installSandboxes(
     ...(srt ? { srt: createSrtProvider(srt) } : {}),
     ...(docker ? { docker: createDockerProvider(docker) } : {}),
   };
-  const fallback = srt || unavailable.srt ? "srt" : docker ? "docker" : undefined;
   return {
     installed,
-    ...(fallback ? { default: fallback } : {}),
     ...(Object.keys(unavailable).length > 0 ? { unavailable } : {}),
   };
 }

package/src/result-validation.ts

@@ -8,7 +8,7 @@ export type CandidateEvaluation =
   | { kind: "rejected"; error: string };
 
 /**
- * A result as `wf` sent it, validated without repairing or persisting; the result-slot transition
+ * A result as `wfa` sent it, validated without repairing or persisting; the result-slot transition
  * owns acceptance.
  */
 export async function evaluateGiven(

package/src/run-command.ts

@@ -3,52 +3,11 @@ import { resolve } from "node:path";
 import type { JsonValue } from "@agentswf/contract/workflow";
 import { parseDuration } from "./duration";
 import { messageOf } from "./errors";
+import help from "./help/run.txt" with { type: "text" };
 import { SESSION_CODE } from "./here";
 import { idProblem, runRootOf, stageNameProblem } from "./runs";
 
-export const usage = [
-  "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 stop exits 3. 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": {}}, 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.",
-  "",
-  "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.",
-].join("\n");
+export const usage = help.trimEnd();
 
 export type RunCommand = {
   /** Where paths typed on the command line resolve. */

package/src/run-usage.ts

@@ -31,7 +31,7 @@ export type AccountedAgent = {
   cwd: string;
   /** A sandboxed agent's own harness home, where its sessions are. */
   home?: string;
-  /** Every native session id seen for the agent so far, from its `wf` calls and its adapter. */
+  /** Every native session id seen for the agent so far, from its `wfa` calls and its adapter. */
   sessions(): readonly string[];
   /** When its host first prompted it, where that waits on the agent first; see `window`. */
   promptedAt?(): number | undefined;

package/src/runs-command.ts

@@ -2,6 +2,7 @@ import { homedir } from "node:os";
 import type { RunJson, RunsJson } from "@agentswf/contract/records";
 import { duration } from "./duration";
 import { messageOf } from "./errors";
+import help from "./help/runs.txt" with { type: "text" };
 import {
   clockTime,
   command,
@@ -23,19 +24,7 @@ import { encodeCursor } from "./run-read";
 import { findRunByRef, listRuns, type RunStatus, runStatus } from "./run-state";
 import { type AgentView, describeActivity, type RunView, viewRun } from "./run-view";
 
-export const runsUsage = [
-  "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.",
-].join("\n");
+export const runsUsage = help.trimEnd();
 
 const LISTED = 20;
 

package/src/sandboxes.ts

@@ -7,6 +7,7 @@ import type { SandboxRecord } from "@agentswf/contract/records";
 import type {
   AbsoluteDeadline,
   AgentExecution,
+  SandboxEnvironment,
   SandboxEnvironmentKey,
   SandboxRef,
 } from "@agentswf/contract/workflow";
@@ -141,7 +142,7 @@ export class RunSandboxes {
     return this.options.sandboxes?.run !== undefined;
   }
 
-  /** `workflow.sandboxes.open`. */
+  /** `wf.sandboxes.open`. */
   async open(spec: unknown): Promise<SandboxRef> {
     if (this.hasRunSandbox) throw new Error(RUN_SANDBOX_ONLY);
     const key = (spec as { key?: unknown } | null)?.key;
@@ -306,7 +307,7 @@ export class RunSandboxes {
           network: [...resolved.network],
           ...(resolved.sockets.length > 0 ? { sockets: [...resolved.sockets] } : {}),
           ...(resolved.webSearch ? { webSearch: true } : {}),
-          [provider]: resolved.environment,
+          ...({ [provider]: resolved.environment } as SandboxEnvironment),
         },
         directory,
         gitdirs: resolved.gitdirs.map((gitdir) => ({ ...gitdir })),

package/src/simple-input.ts

@@ -19,10 +19,18 @@ type Kind =
   | { type: "boolean" }
   | { type: "enum"; values: string[] };
 
-/** Said once in a prompt, under the first block taught with flags, and with every refusal of them. */
+/**
+ * Said once in a prompt, under the first block with a free-text flag, and with every refusal of
+ * flags that take text. Enum, number and boolean values are shell words as they stand.
+ */
 export const QUOTING_RULE =
   "Put every value in single quotes; a ' inside a value is written '\\''.";
 
+/** Whether a flag takes free text, the only value the shell can break. */
+export function takesText(simple: Simple): boolean {
+  return simple.some(({ kind }) => kind.type === "string");
+}
+
 const MAX_PROPERTIES = 6;
 const NAME = /^[a-z][a-z0-9_]*$/;
 /** An enum value the usage line can show between `|`s and the agent can type as it stands. */
@@ -137,7 +145,7 @@ export type ReadFlags = { ok: true; value: JsonObject } | { ok: false; error: st
 export type ReadGiven = { ok: true; value: unknown } | { ok: false; error: string };
 
 /**
- * An input as `wf` sent it, as a value: JSON parsed, flags read by the schema, nothing as `{}`.
+ * An input as `wfa` sent it, as a value: JSON parsed, flags read by the schema, nothing as `{}`.
  * The schema's own check comes after, in `checkGiven`.
  */
 export function readGiven(schema: JsonSchema | undefined, given: GivenInput): ReadGiven {
@@ -181,7 +189,9 @@ export function checkGiven(
 }
 
 function expected(simple: Simple): string {
-  return `expected: ${usageLine(simple)}\n${QUOTING_RULE}`;
+  return [`expected: ${usageLine(simple)}`, ...(takesText(simple) ? [QUOTING_RULE] : [])].join(
+    "\n",
+  );
 }
 
 /**

package/src/stage-ledger.ts

@@ -174,7 +174,7 @@ export class StageLedger {
   }
 
   /**
-   * `workflow.stop`, called in `stage` or between stages: what to throw. The first stop is kept,
+   * `wf.stop`, called in `stage` or between stages: what to throw. The first stop is kept,
    * and any later stop throws it again; once it was found caught, that instead. After the
    * workflow's body ended, a stop ends nothing.
    */

package/src/test-command.ts

@@ -4,21 +4,12 @@ import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { parseDuration } from "./duration";
 import { messageOf } from "./errors";
+import help from "./help/test.txt" with { type: "text" };
 import type { Out } from "./run-commands";
 
 const PRELOAD = fileURLToPath(new URL("./workflow-test-preload.ts", import.meta.url));
 
-export const testUsage = [
-  "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.",
-].join("\n");
+export const testUsage = help.trimEnd();
 
 export type TestCommand = { paths: string[]; bunArgs: string[] };