@agentswf/engine 0.1.0-beta.5 → 0.1.0

package/src/holder-command.ts

@@ -1,56 +1,50 @@
-import { homedir } from "node:os";
-import type { ParticipantResultJson } from "@agentswf/contract/records";
-import { type ParticipantCode, WIRE_VERSION } from "@agentswf/contract/wire";
+import type { ParticipantResultJson, RefusalCode } from "@agentswf/contract/records";
+import { type HolderWireAnswer, type ParticipantCode, WIRE_VERSION } from "@agentswf/contract/wire";
+import { type Out, parsePlace, type ReadPlace } from "./command-line";
 import { liveCoordinatorSocket } from "./coordinator-socket";
-import { deprecationLine } from "./deprecations";
-import { deliverReply, emitToRun, 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";
+import { asksJson, printRefusal, refusalLine } from "./refusals";
+import { failed } from "./run-commands";
 import { findRunByRef, RunNotFound, type RunStatus } from "./run-state";
-import { readAttempts, readEvents, readNumberedEvents } from "./runs";
+import { RunUnreachable } from "./run-unreachable";
+import { readAttempts, readNumberedEvents } from "./runs";
 import { exchange } from "./socket-exchange";
 
+/** `awf reply --json`'s and `awf send --json`'s `"v"`, which their refusals carry too. */
+export const HOLDER_V = 3 satisfies ParticipantResultJson["v"];
+
 export const replyUsage = help.trimEnd();
 
 type Options = {
   command: "reply" | "send";
   ref: string;
-  author?: string;
   to?: string;
   text?: string;
-} & (
-  | { agent: string; as?: string; id?: undefined }
-  /**
-   * `--event-id`: the message's own id, which a participant routed to the code takes as its event's. It
-   * goes to no agent.
-   */
-  | { id: string; as: string; agent?: undefined }
-);
+  agent: string;
+  as?: string;
+};
 
-export type HolderIo = Out & {
+type HolderIo = Out & {
   /** Stdin, when no text is given as an argument. */
   stdin(): Promise<string>;
   /** Then there is nothing piped in to read: refused rather than waited on. */
   stdinIsTerminal?: boolean;
-  environment?: Readonly<Record<string, string | undefined>>;
-  home?: string;
+  environment: Readonly<Record<string, string | undefined>>;
+  home: string;
 };
 
+/** A refusal of `reply` or `send`: its document with `--json`, its sentence on stderr, exit 1. */
+type Refuse = (code: ParticipantCode | RefusalCode, error: string, choices?: string[]) => number;
+
 export async function holderCommand(
   argv: readonly string[],
   shellCwd: string,
   io: HolderIo,
 ): Promise<number> {
-  // Help only as the first word after the command: a message's text may say anything.
-  if (argv[1] === "-h" || argv[1] === "--help") {
-    io.stdout(replyUsage);
-    return 0;
-  }
   let place: ReadPlace;
   let json: boolean;
   let options: Options;
@@ -60,34 +54,34 @@ export async function holderCommand(
     json = parsed.json;
     options = parseHolder(argv[0] as "reply" | "send", parsed.rest);
   } catch (error) {
-    io.stderr(`awf: ${messageOf(error)}\n\n${replyUsage}`);
+    printRefusal(io, { json: asksJson(argv), v: HOLDER_V }, error, "usage", replyUsage);
     return 2;
   }
-  const say = (result: ParticipantResultJson, line: string): number => {
-    if (json) io.stdout(JSON.stringify(result));
-    else if (result.code === "delivered") io.stdout(line);
-    else
-      io.stderr(
-        `awf: ${options.command} refused (${result.code}): ${result.error}${result.choices ? ` Choose: ${result.choices.join(", ")}` : ""}`,
-      );
-    return result.code === "delivered" ? 0 : 1;
+  const delivered = (id: string, line: string): number => {
+    io.stdout(json ? JSON.stringify({ v: HOLDER_V, id } satisfies ParticipantResultJson) : line);
+    return 0;
+  };
+  const refused: Refuse = (code, error, choices) => {
+    if (json) io.stdout(refusalLine(HOLDER_V, code, error, choices));
+    io.stderr(
+      `awf: ${options.command} refused (${code}): ${error}${choices ? ` Choose: ${choices.join(", ")}` : ""}`,
+    );
+    return 1;
   };
-  const refused = (code: ParticipantCode, error: string) => say({ v: 2, code, error }, "");
   const usage = (problem: string) => {
-    io.stderr(`awf: ${problem}\n\n${replyUsage}`);
+    printRefusal(io, { json, v: HOLDER_V }, problem, "usage", replyUsage);
     return 2;
   };
   if (options.text !== undefined && options.text.trim() === "")
     return usage("nothing to say: the text is blank");
   if (options.text === undefined && io.stdinIsTerminal)
     return usage("nothing to say: give the text as an argument, or pipe it in");
-  if (options.id !== undefined) return toTheCode(options, place, json, io, { refused, usage });
   try {
     let status: RunStatus;
     try {
-      status = await findRunByRef(options.ref, place, io.home ?? homedir());
+      status = await findRunByRef(options.ref, place, io.home);
     } catch (error) {
-      if (error instanceof RunNotFound) return refused("not-found", error.message);
+      if (error instanceof RunNotFound) return refused(error.code, error.message);
       throw error;
     }
     if (status.state !== "running")
@@ -100,7 +94,7 @@ export async function holderCommand(
         "no-participant",
         `${status.ref} has no participant${options.as ? ` ${options.as}` : ""} to reach yet; try again once it connects one`,
       );
-    const dir = coordinatorDir(io.home ?? homedir(), io.environment ?? process.env);
+    const dir = coordinatorDir(io.home, io.environment);
     // Live with no socket: its attempt has not connected one yet, or is opening it.
     const socket = await liveCoordinatorSocket(dir, status);
     if (!socket) return unreachable();
@@ -119,23 +113,25 @@ export async function holderCommand(
       // A socket an attempt left when it was killed: this attempt has not opened its own yet.
       if (["ECONNREFUSED", "ENOENT", "ENOTSOCK"].some((code) => isCode(error, code)))
         return unreachable();
-      throw error;
+      // Open and silent, or gone mid-answer: the run doesn't answer.
+      throw new RunUnreachable(`${status.ref} did not answer: ${messageOf(error)}`);
     }
     if (!answer)
-      throw new Error(
+      throw new RunUnreachable(
         `${status.ref} did not answer, most likely as it runs an older awf than this one, which speaks wire version ${WIRE_VERSION}: reach it with the awf it started with, or let it end and continue it under this one.`,
       );
-    const result = JSON.parse(answer) as ParticipantResultJson;
-    if (result.code !== "delivered") return say(result, "");
-    if (options.command === "reply") return say(result, `answered ${result.id}`);
+    const result = JSON.parse(answer) as HolderWireAnswer;
+    if (result.code !== "delivered") return refused(result.code, result.error, result.choices);
+    if (options.command === "reply") return delivered(result.id, `answered ${result.id}`);
     // Held for an agent awaiting this participant's answer: it comes with that answer.
-    const awaited = await awaitedBy(status, options.agent, options.as);
-    return say(
-      result,
+    // Only the line's wording: the message is delivered, whatever reading this finds.
+    const awaited = await awaitedBy(status, options.agent, options.as).catch(() => undefined);
+    return delivered(
+      result.id,
       `delivered as ${result.id}${awaited ? `; ${options.agent} still awaits the reply to ${awaited}` : ""}`,
     );
   } catch (error) {
-    return failed(error, place, io, messageOf(error));
+    return failed(error, place, io, messageOf(error), { json, v: HOLDER_V });
   }
 }
 
@@ -143,8 +139,6 @@ function parseHolder(command: "reply" | "send", rest: readonly string[]): Option
   const words: string[] = [];
   let to: string | undefined;
   let as: string | undefined;
-  let id: string | undefined;
-  let author: string | undefined;
   for (let index = 0; index < rest.length; index += 1) {
     const arg = rest[index]!;
     const value = () => {
@@ -155,34 +149,19 @@ function parseHolder(command: "reply" | "send", rest: readonly string[]): Option
     };
     if (arg === "--to" && command === "reply") to = value();
     else if (arg === "--as") as = value();
-    else if (arg === "--event-id" && command === "send") id = value();
-    else if (arg === "--author" && command === "send") author = value();
+    else if ((arg === "--event-id" || arg === "--author") && command === "send")
+      throw new Error(
+        `send ${arg} was removed: a message on a participant to the run's code is awf emit {run} {participant}:reply '{"text":…,"author":…}' --event-id {id}, with {participant}:reply declared in the workflow's events`,
+      );
     else if (arg === "--") {
       words.push(...rest.slice(index + 1));
       break;
     } else if (arg.startsWith("--")) throw new Error(`unknown option: ${arg}`);
     else words.push(arg);
   }
-  // With --event-id, the participant's reply goes to the run's code: there is no agent to name.
-  let target: { agent: string; as?: string } | { id: string; as: string };
-  let ref: string | undefined;
-  let text: string | undefined;
-  let extra: string[];
-  if (id !== undefined) {
-    [ref, text, ...extra] = words;
-    if (!ref) throw new Error("send needs a run, <workflow>/<id> or <id>");
-    if (!as) throw new Error("--event-id sends as a participant routed to the code: --as names it");
-    const problem = eventIdProblem(id);
-    if (problem) throw new Error(`--event-id ${id}: ${problem}`);
-    target = { id, as };
-  } else {
-    let agent: string | undefined;
-    [ref, agent, text, ...extra] = words;
-    if (author !== undefined) throw new Error("--author goes with --event-id");
-    if (!ref || !agent?.trim())
-      throw new Error(`${command} needs a run, <workflow>/<id> or <id>, and an agent`);
-    target = { agent, ...(as === undefined ? {} : { as }) };
-  }
+  const [ref, agent, text, ...extra] = words;
+  if (!ref || !agent?.trim())
+    throw new Error(`${command} needs a run, <workflow>/<id> or <id>, and an agent`);
   if (extra.length > 0) throw new Error("the text is one argument: quote it, or pipe it in");
   if (as !== undefined && as.trim() === "") throw new Error("--as needs a participant's key");
   if (to !== undefined && !/^\d+\.\d+$/.test(to))
@@ -190,10 +169,10 @@ function parseHolder(command: "reply" | "send", rest: readonly string[]): Option
   return {
     command,
     ref,
-    ...target,
+    agent,
+    ...(as === undefined ? {} : { as }),
     ...(to === undefined ? {} : { to }),
     ...(text === undefined ? {} : { text }),
-    ...(author === undefined ? {} : { author }),
   };
 }
 
@@ -221,64 +200,3 @@ async function awaitedBy(
   );
   return open.at(-1);
 }
-
-/**
- * `awf send {ref} --as {participant} --event-id {message id} {text}`, deprecated: `awf emit {ref}
- * {participant}:reply`. It keeps its own refusals and exit codes for the beta: a participant the
- * run never connected is refused; one the run recorded as routed to the code, declared or by the
- * deprecated `to: "code"`, gets the reply as before, the workflow's file not loaded; any other is
- * `awf emit`'s to check against the definition.
- */
-async function toTheCode(
-  options: Extract<Options, { id: string }>,
-  place: ReadPlace,
-  json: boolean,
-  io: HolderIo,
-  say: { refused(code: ParticipantCode, error: string): number; usage(problem: string): number },
-): Promise<number> {
-  const home = io.home ?? homedir();
-  const environment = io.environment ?? process.env;
-  const { id, as } = options;
-  const { refused } = say;
-  io.stderr(deprecationLine("send-event-id"));
-  let found: RunStatus;
-  try {
-    found = await findRunByRef(options.ref, place, home);
-  } catch (error) {
-    if (error instanceof RunNotFound) return refused("not-found", error.message);
-    return failed(error, place, io, messageOf(error));
-  }
-  const connected = (await readEvents(found.run.dir)).filter(
-    (line) => line.kind === "participant-connected" && line.participant === as,
-  );
-  // As it always did: only a participant the run has connected; `awf emit` doesn't ask.
-  if (!found.run.record.events || connected.length === 0)
-    return refused(
-      "no-participant",
-      `${found.ref} has no participant ${as} connected to its code; --event-id is for one`,
-    );
-  const text = options.text ?? (await io.stdin());
-  if (text.trim() === "") return say.usage("nothing to say: stdin was empty");
-  const data = { text, ...(options.author === undefined ? {} : { author: options.author }) };
-  const context = { home, environment };
-  // Recorded as routed to the code, by either form: delivered as before, the file not loaded.
-  if (connected.some((line) => line.kind === "participant-connected" && line.to)) {
-    try {
-      return printEmit(await deliverReply(found, as, { data, id }, context), json, io);
-    } catch (error) {
-      return failed(error, place, io, messageOf(error));
-    }
-  }
-  // Connected to agents only, which send has always refused: whatever stops `awf emit`, a file
-  // that won't load included, is that refusal, with its reason.
-  let result: Awaited<ReturnType<typeof emitToRun>>;
-  try {
-    result = await emitToRun(found, { name: `${as}:reply`, data, id }, context);
-  } catch (error) {
-    return refused(
-      "no-participant",
-      `${found.ref} has no participant ${as} whose messages go to its code: ${messageOf(error)}`,
-    );
-  }
-  return printEmit(result, json, io);
-}

package/src/in-lines.ts

@@ -0,0 +1,28 @@
+import { stat } from "node:fs/promises";
+import { join } from "node:path";
+import type { EventLine } from "@agentswf/contract/records";
+import { appendLine, endTornLine, readLines } from "./jsonl";
+
+/** `in.jsonl`: the events senders gave the run, appended under the run's lock. */
+export function inFile(runDir: string): string {
+  return join(runDir, "in.jsonl");
+}
+
+/** The run's events in the order written, less a line a crash tore. */
+export async function readIn(runDir: string): Promise<EventLine[]> {
+  return readLines<EventLine>(inFile(runDir));
+}
+
+/** Appends an event; the caller holds the run's lock. */
+export async function appendIn(runDir: string, line: EventLine): Promise<void> {
+  await endTornLine(inFile(runDir));
+  await appendLine(inFile(runDir), JSON.stringify(line));
+}
+
+/** `in.jsonl`'s size, which a waiting run polls: a sender's append changes it. */
+export async function inSize(runDir: string): Promise<number> {
+  return stat(inFile(runDir)).then(
+    (stats) => stats.size,
+    () => 0,
+  );
+}

package/src/inbox-command.ts

@@ -2,30 +2,27 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import type {
   AttemptRecord,
-  InboxErrorJson,
   InboxExpiry,
   InboxItemJson,
+  RefusalCode,
   RequestEnd,
   RunLogLine,
 } from "@agentswf/contract/records";
 import type { InboxCode } from "@agentswf/contract/wire";
 import type { JsonObject } from "@agentswf/contract/workflow";
 import { maskCredentials } from "@agentswf/harness";
-import { formatDuration, parseWait } from "./duration";
+import { duration } from "./accounting/format";
+import { command, type Out, parsePlace, type ReadPlace, shellLine } from "./command-line";
+import { parseWait } 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,
-  command,
-  failed,
-  type Out,
-  parsePlace,
-  type ReadPlace,
-  shellLine,
-} from "./run-commands";
+import { asksJson, printRefusal } from "./refusals";
+import { failed, MAX_WAIT_SECONDS, POLL_MS } from "./run-commands";
+import { readRunLines } from "./run-lines";
+import { waitLabels as labelsOf } from "./run-policy/waits";
 import { findRunByRef, listRuns, RunNotFound, statusOf } from "./run-state";
+import { clockTime } from "./run-text";
 import {
   attemptsToken,
   type LogMark,
@@ -35,10 +32,10 @@ import {
   readEventsFrom,
 } from "./runs";
 
-export const inboxUsage = help.trimEnd();
+/** `awf inbox --json`'s `"v"`, which its refusals carry too. */
+export const INBOX_V = 2 satisfies InboxItemJson["v"];
 
-const MAX_WAIT_SECONDS = 300;
-const POLL_MS = 1_000;
+export const inboxUsage = help.trimEnd();
 
 /** The clock and the pause between polls, which tests drive. */
 export type InboxClock = { now(): number; sleep(ms: number): Promise<void> };
@@ -66,7 +63,7 @@ type CursorState = { f: string; r: Record<string, Position> };
 
 class Refused extends Error {
   constructor(
-    readonly code: InboxCode,
+    readonly code: InboxCode | RefusalCode,
     message: string,
   ) {
     super(message);
@@ -89,10 +86,6 @@ export async function inboxCommand(
     signal?: AbortSignal;
   } = {},
 ): Promise<number> {
-  if (argv.includes("-h") || argv.includes("--help")) {
-    out.stdout(inboxUsage);
-    return 0;
-  }
   let place: ReadPlace;
   let json: boolean;
   let options: Options;
@@ -100,14 +93,13 @@ export async function inboxCommand(
     const parsed = parsePlace(argv, shellCwd);
     place = parsed.place;
     json = parsed.json;
-    options = parseInbox(parsed.rest, (line) => out.stderr(line));
+    options = parseInbox(parsed.rest);
   } catch (error) {
-    out.stderr(`awf: ${messageOf(error)}\n\n${inboxUsage}`);
+    printRefusal(out, { json: asksJson(argv), v: INBOX_V }, error, "usage", inboxUsage);
     return 2;
   }
-  const refuse = (code: InboxCode, message: string) => {
-    if (json) out.stdout(JSON.stringify({ v: 1, code, error: message } satisfies InboxErrorJson));
-    else out.stderr(`awf: ${message}`);
+  const refuse = (code: InboxCode | RefusalCode, message: string) => {
+    printRefusal(out, { json, v: INBOX_V }, message, code);
     return 1;
   };
   try {
@@ -115,18 +107,19 @@ export async function inboxCommand(
       ? `all|${options.workflow ?? ""}|${options.as ?? ""}`
       : `run|${options.ref}|${options.as ?? ""}`;
     let state: CursorState = { f: filter, r: {} };
-    // Reading every run here, none is missing or unconnected, so a cursor is checked first, sparing a read.
     let checked = options.after === undefined;
-    if (!checked && options.all) {
+    const takeCursor = () => {
       const given = decodeCursor(options.after!);
       if (!given || given.f !== filter)
         throw new Refused(
-          "bad-cursor",
+          "cursor",
           `cursor ${options.after} was made with another run or filter; read again without --after`,
         );
       state = given;
       checked = true;
-    }
+    };
+    // Reading every run here, none is missing or unconnected, so a cursor is checked first, sparing a read.
+    if (!checked && options.all) takeCursor();
     const deadline = clock.now() + options.waitSeconds * 1000;
     // An event run lives in its project, found through ~/.awf/projects from anywhere (Q15).
     const found =
@@ -137,14 +130,7 @@ export async function inboxCommand(
       const runs = await readInbox(options, state, watch, one);
       // After a run that is not there, or never connected one: those come first.
       if (!checked) {
-        const given = decodeCursor(options.after!);
-        if (!given || given.f !== filter)
-          throw new Refused(
-            "bad-cursor",
-            `cursor ${options.after} was made with another run or filter; read again without --after`,
-          );
-        state = given;
-        checked = true;
+        takeCursor();
         continue;
       }
       if (options.open) {
@@ -165,7 +151,7 @@ export async function inboxCommand(
           state = { f: filter, r: { ...state.r, [ref]: item.position } };
           const { position: _position, ...shown } = item;
           const published = {
-            v: 1,
+            v: 2,
             ref,
             ...shown,
             cursor: encodeCursor(state),
@@ -178,13 +164,12 @@ export async function inboxCommand(
           const words = options.all
             ? ["awf", "inbox", ...(options.workflow ? ["--workflow", options.workflow] : [])]
             : ["awf", "inbox", options.ref!];
-          const again = command(
-            place,
-            ...words,
+          const again = [
+            ...command(place, ...words),
             ...(options.as ? ["--as", options.as] : []),
             "--after",
             encodeCursor(state),
-          );
+          ];
           out.stdout([...lines, `next: ${shellLine(again)}`].join("\n"));
         }
         return 0;
@@ -193,12 +178,12 @@ export async function inboxCommand(
     }
   } catch (error) {
     if (error instanceof Refused) return refuse(error.code, error.message);
-    if (error instanceof RunNotFound) return refuse("not-found", error.message);
-    return failed(error, place, out, messageOf(error));
+    if (error instanceof RunNotFound) return refuse(error.code, error.message);
+    return failed(error, place, out, messageOf(error), { json, v: INBOX_V });
   }
 }
 
-function parseInbox(rest: readonly string[], deprecated: (line: string) => void): Options {
+function parseInbox(rest: readonly string[]): Options {
   const options: Options = { all: false, open: false, waitSeconds: 0 };
   for (let index = 0; index < rest.length; index += 1) {
     const arg = rest[index]!;
@@ -212,8 +197,7 @@ function parseInbox(rest: readonly string[], deprecated: (line: string) => void)
     else if (arg === "--workflow") options.workflow = value();
     else if (arg === "--as") options.as = value();
     else if (arg === "--after") options.after = value();
-    else if (arg === "--wait")
-      options.waitSeconds = parseWait(value(), MAX_WAIT_SECONDS, deprecated);
+    else if (arg === "--wait") options.waitSeconds = parseWait(value(), MAX_WAIT_SECONDS);
     else if (arg.startsWith("-")) throw new Error(`unknown option: ${arg}`);
     else if (options.ref === undefined) options.ref = arg;
     else throw new Error(`one run at a time: ${options.ref} and ${arg}`);
@@ -268,7 +252,7 @@ type Watched = {
   /** The attempt files when `attempts` was read; undefined before the first read. */
   token?: string;
   attempts: AttemptRecord[];
-  /** Each attempt's last wait label, from the mailbox, read with `attempts`. */
+  /** Each attempt's last wait label, from `run.jsonl`, read with `attempts`. */
   labels: ReadonlyMap<number, string>;
   fold: ItemFold;
   mark: LogMark;
@@ -628,7 +612,7 @@ function openQuestions(runs: readonly RunItems[]): InboxItemJson[] {
   });
   return merged(open).map(({ ref, item }) => {
     const { position: _position, ...shown } = item;
-    return { v: 1, ref, ...shown } as InboxItemJson;
+    return { v: INBOX_V, ref, ...shown } as InboxItemJson;
   });
 }
 
@@ -655,7 +639,7 @@ function textOf(item: InboxItemJson, all: boolean): string {
             ? `${item.agent} → ${item.participant}`
             : `${item.participant} → ${item.agent}`;
       return item.state === "opened"
-        ? `${head}route ${arrow} opened  “${item.purpose}”${item.timeoutMs === undefined ? "" : `  ${formatDuration(item.timeoutMs)}`}`
+        ? `${head}route ${arrow} opened  “${item.purpose}”${item.timeoutMs === undefined ? "" : `  ${duration(item.timeoutMs)}`}`
         : `${head}route ${arrow} closed  ${item.reason}`;
     }
     case "message": {
@@ -702,11 +686,13 @@ function decodeCursor(text: string): CursorState | undefined {
   }
 }
 
-/** Each attempt's last wait label: what a parked attempt is waiting for. */
+/**
+ * Each attempt's last wait label: what a parked attempt is waiting for. A `run.jsonl` that can't be
+ * read gives none: the conversation is the log's.
+ */
 async function waitLabels(runDir: string): Promise<Map<number, string>> {
-  const labels = new Map<number, string>();
-  for (const record of await readMailbox(runDir))
-    if (record.kind === "wait" && record.label !== undefined)
-      labels.set(record.attempt, record.label);
-  return labels;
+  return readRunLines(runDir).then(
+    ({ lines }) => labelsOf(lines),
+    () => new Map(),
+  );
 }

package/src/index.ts

@@ -1,4 +1,4 @@
-// A finished run is re-priced from its `output.json` with another table.
+// A finished run is priced again from its operations' `spend.json`, or `out.json`'s `usage`, with another table.
 export { describeAccounting } from "./accounting/format";
 export { type ModelRate, type PriceTable, PUBLISHED_PRICES } from "./accounting/prices";
 export { summarizeRun } from "./accounting/summary";

package/src/init-command.ts

@@ -1,13 +1,14 @@
 import { existsSync, lstatSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { basename, dirname, join, relative, resolve } from "node:path";
 import manifest from "../package.json" with { type: "json" };
+import { type Out, shellWord } from "./command-line";
 import { messageOf } from "./errors";
 import help from "./help/init.txt" with { type: "text" };
-import type { Out } from "./run-commands";
+import { NO_JSON, printRefusal } from "./refusals";
 
 export const initUsage = help.trimEnd();
 
-export type InitCommand = { dir: string; install: boolean };
+type InitCommand = { dir: string; install: boolean };
 
 /** `awf init`: a folder set up for writing workflows. */
 export async function initCommand(
@@ -15,17 +16,13 @@ export async function initCommand(
   cwd: string,
   io: Out & { install?: (dir: string) => Promise<number> },
 ): Promise<number> {
-  let command: InitCommand | "help";
+  let command: InitCommand;
   try {
     command = parseInitCommand(argv, cwd);
   } catch (error) {
-    io.stderr(`awf: ${messageOf(error)}\n\n${initUsage}`);
+    printRefusal(io, NO_JSON, error, "usage", initUsage);
     return 2;
   }
-  if (command === "help") {
-    io.stdout(initUsage);
-    return 0;
-  }
   try {
     return await runInit(command, cwd, io, io.install);
   } catch (error) {
@@ -34,11 +31,10 @@ export async function initCommand(
   }
 }
 
-export function parseInitCommand(argv: readonly string[], cwd: string): InitCommand | "help" {
+export function parseInitCommand(argv: readonly string[], cwd: string): InitCommand {
   let dir: string | undefined;
   let install = true;
   for (const option of argv) {
-    if (option === "-h" || option === "--help") return "help";
     if (option === "--no-install") install = false;
     else if (option.startsWith("-")) throw new Error(`unknown option: ${option}`);
     else if (dir !== undefined) throw new Error(`one directory only, not ${dir} and ${option}`);
@@ -86,7 +82,7 @@ function targetOf(dir: string, path: string): Target {
  * Writes what `awf init` writes into `dir`, and says what it did to each file. Everything that
  * would stop it, such as a package.json that isn't a JSON object, is found before it writes.
  */
-export function initFolder(dir: string): Change[] {
+function initFolder(dir: string): Change[] {
   for (const parent of new Set(COPIED.map(dirname))) {
     const stat = lstatSync(join(dir, parent), { throwIfNoEntry: false });
     if (stat !== undefined && !stat.isDirectory()) {
@@ -213,13 +209,8 @@ function indentOf(text: string): string | number {
   return /^\{\s*\r?\n([ \t]+)"/.exec(text)?.[1] ?? 2;
 }
 
-/** As a shell reads it: bare when that's safe, otherwise single-quoted. */
-function shellWord(word: string): string {
-  return /^[\w./-]+$/.test(word) ? word : `'${word.replaceAll("'", "'\\''")}'`;
-}
-
 /** `awf init`: writes the folder, installs unless told not to, and says what to run next. */
-export async function runInit(
+async function runInit(
   command: InitCommand,
   cwd: string,
   output: { stdout(text: string): void; stderr(text: string): void },

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

@@ -1,7 +1,8 @@
+import { typed } from "agentswf/typebox";
 import { defineWorkflow } from "agentswf/workflow";
 import Type from "typebox";
 
-export const ANSWER = Type.Object({ answer: Type.Integer() }, { additionalProperties: false });
+export const ANSWER = typed(Type.Object({ answer: Type.Integer() }, { additionalProperties: false }));
 
 export default defineWorkflow({
   meta: { name: "hello", description: "Ask one agent a question with a known answer." },
@@ -12,7 +13,7 @@ export default defineWorkflow({
       key: "hello",
       runtime: { harness: "codex", model: "gpt-6-luna", placement: "headless" },
     });
-    const { outcome } = await agent.run<Type.Static<typeof ANSWER>>({
+    const { outcome } = await agent.run({
       prompt: "What is 17 multiplied by 23? Work it out yourself; do not run any code.",
       schema: ANSWER,
       timeout: "3m",