@agentswf/engine 0.1.0-beta.4 → 0.1.0

package/src/attempt-ending.ts

@@ -1,5 +1,5 @@
 import { constants } from "node:os";
-import type { StageNeed, StageRecord } from "@agentswf/contract/records";
+import type { StageLine } from "@agentswf/contract/records";
 import {
   type AbsoluteDeadline,
   type AttemptOutcome,
@@ -12,9 +12,9 @@ import {
 import { PUBLISHED_PRICES } from "./accounting/prices";
 import { summarizeRun } from "./accounting/summary";
 import { messageOf } from "./errors";
-import { RunParked } from "./mailbox";
 import type { Paint } from "./progress-view";
 import { FromStageUnreached, primaryFailure, WorkflowStopped } from "./stopped";
+import { RunParked } from "./waits";
 import {
   type SettledRun,
   WorkflowCancelledError,
@@ -36,9 +36,7 @@ export type AttemptEnd = {
    * Given when the attempt never reached its `--from-stage`, which no one command goes on from:
    * the run's stages to choose from.
    */
-  choose?: readonly StageRecord[];
-  /** The stages whose values `--values` gives, to start at a later one. */
-  needs?: readonly StageNeed[];
+  choose?: readonly StageLine[];
 };
 
 /** What a started run came to: the result it returned, or what it threw. */
@@ -107,12 +105,12 @@ export function decideEnding(
       reason: stop?.reason ?? errorDetail(error),
       stages,
       continue: goOn(stop, stages),
+      ...(stop?.needs ? { needs: [...stop.needs] } : {}),
     },
     ...(settled ? { settled } : {}),
     exitCode: cancellation ? signalExitCode(cancellation.reason) : OUTCOMES[kind].exitCode!,
     ...(beside ? { alsoFailed: beside } : {}),
     ...(stop instanceof FromStageUnreached ? { choose: stop.recorded } : {}),
-    ...(stop?.needs ? { needs: stop.needs } : {}),
   };
 }
 
@@ -181,7 +179,7 @@ export function runOutcome(
   const stop = failure instanceof WorkflowStopped ? failure : undefined;
   const timedOut =
     failure instanceof DeadlineExceededError &&
-    failure.deadline.unixMilliseconds === deadline?.unixMilliseconds;
+    failure.deadline.getTime() === deadline?.unixMilliseconds;
   const kind = cancellation ? "cancelled" : stop ? "stopped" : timedOut ? "timed-out" : "failed";
   return { kind, ...(stop ? { stop } : {}), ...(cancellation ? { cancellation } : {}) };
 }

package/src/attempt-output.ts

@@ -5,12 +5,10 @@ import {
   RUN_EVENT_VERSIONS,
 } from "@agentswf/contract/records";
 import type { Ending, JsonValue } from "@agentswf/contract/workflow";
-import { attemptAccounting } from "./accounting/summary";
 import type { AttemptEnd } from "./attempt-ending";
 import { messageOf } from "./errors";
 import { writeJson, writeWhole } from "./files";
-import { foldMailbox, readMailbox } from "./mailbox";
-import { type Attempt, appendEvent, endAttempt, outputFile, reportFile } from "./runs";
+import { type Attempt, appendEvent, endAttempt, outFile, reportFile } from "./runs";
 import { withoutValue } from "./stage-ledger";
 import type { AnyWorkflow, LoadedWorkflow } from "./workflow-loader";
 
@@ -18,15 +16,16 @@ import type { AnyWorkflow, LoadedWorkflow } from "./workflow-loader";
 export type Kept = {
   /** Absent when the run never settled, so there is nothing to record but its ending. */
   json?: string;
-  /** output.json, once written. */
+  /** out.json, once written. */
   output?: string;
   report?: string;
 };
 
 /**
- * Writes an attempt's records, each from its one ending: report.md, output.json, then the ending in
- * its attempt file. The ending goes last: an ended attempt lets the next start, whose report and
- * output this one's must not overwrite. A record that fails to write is said, and costs no other.
+ * Writes an attempt's records, each from its one ending: report.md and out.json, its views, then the
+ * ending in its attempt file, a completed one's with its value. The ending goes last: an ended
+ * attempt lets the next start, whose views this one's must not overwrite. A record that fails to
+ * write is said, and costs no other.
  */
 export async function keepRecords(
   end: AttemptEnd,
@@ -58,18 +57,19 @@ export async function keepRecords(
             outcome: ending.kind,
             reason: ending.reason,
             ...at,
-            ...(end.needs ? { needs: [...end.needs] } : {}),
+            ...(ending.needs ? { needs: ending.needs } : {}),
           };
   const kept: Kept = report ? { report } : {};
-  const output = outputFile(dir);
+  const output = outFile(dir);
   if (!settled) {
     // An earlier attempt's output is gone with it, as its report is.
     await rm(output, { force: true }).catch((error) =>
-      stderr(`awf: output.json: ${messageOf(error)}`),
+      stderr(`awf: out.json: ${messageOf(error)}`),
     );
   } else {
     const record: OutputRecord = {
       version: OUTPUT_RECORD_VERSION,
+      ref: `${context.loaded.workflow.meta.name}/${settled.runId}`,
       runId: settled.runId,
       attempt: attempt.record.attempt,
       workflow: { name: context.loaded.workflow.meta.name, file: context.loaded.file },
@@ -89,7 +89,7 @@ export async function keepRecords(
       await writeJson(output, record);
       kept.output = output;
     } catch (error) {
-      stderr(`awf: output.json: ${messageOf(error)}`);
+      stderr(`awf: out.json: ${messageOf(error)}`);
     }
   }
   // Before the ending: once the attempt has ended, the next may start appending.
@@ -101,30 +101,13 @@ export async function keepRecords(
     outcome: ending.kind,
   }).catch((error) => stderr(`awf: the run's event log was not written: ${messageOf(error)}`));
   // An event run's ending is written holding its run's lock, as parking's is: a sender after it sees
-  // the run returned and is refused, so what no wait took is counted whole. Its last batch was
-  // handled, as the code returned after it.
+  // the run returned and is refused, so what no wait took is what its lines say.
   const writeEnding = async () => {
-    const unacknowledged =
-      ending.kind === "completed" && attempt.run.record.events
-        ? await readMailbox(dir).then(
-            // 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;
-            },
-            (error: unknown) => {
-              stderr(`awf: what no wait took was not counted: ${messageOf(error)}`);
-              return undefined;
-            },
-          )
-        : undefined;
     await endAttempt(attempt, {
       outcome: ending.kind,
-      ...(unacknowledged === undefined ? {} : { unacknowledged }),
+      ...(ending.kind === "completed" ? { value: ending.value } : {}),
       ...(unfinished ? { reason: unfinished.reason } : {}),
       ...at,
-      ...(stages ? { stages } : {}),
-      ...(settled ? { accounting: attemptAccounting(settled.accounting) } : {}),
     });
   };
   try {
@@ -145,7 +128,7 @@ async function writeReport(
   // An earlier attempt's report is gone with it: report.md is the last ended attempt's.
   const none = () => rm(file, { force: true }).then(() => undefined);
   if (!workflow.report) return none();
-  // The result is still in output.json; a report that cannot be rendered or saved should not fail
+  // The result is still in out.json and the attempt file; a report that cannot be rendered or saved should not fail
   // the run, nor cost it its record.
   try {
     const markdown = workflow.report(
@@ -156,7 +139,7 @@ async function writeReport(
     await writeWhole(file, `${markdown.trimEnd()}\n`);
     return file;
   } catch (error) {
-    stderr(`awf: report: ${messageOf(error)}; see output.json instead`);
+    stderr(`awf: report: ${messageOf(error)}; see out.json instead`);
     return undefined;
   }
 }

package/src/attempt-view.ts

@@ -1,15 +1,17 @@
 import type {
   AgentPaneRecord,
-  AttemptRecord,
+  ClaimedAttempt,
   RunAccounting,
+  StageLine,
   StageNeed,
-  StageRecord,
 } from "@agentswf/contract/records";
 import type { Ending, JsonValue, StageSummary } from "@agentswf/contract/workflow";
 import { ago, describeAccounting, describeAttempts } from "./accounting/format";
-import { sumAttempts } from "./accounting/summary";
+import type { EarlierSpent } from "./accounting/spent";
+import { attemptAccounting, sumAttempts } from "./accounting/summary";
 import { type AttemptEnd, OUTCOMES } from "./attempt-ending";
 import type { Kept } from "./attempt-output";
+import { placeFlags, shellWord } from "./command-line";
 import { pathFrom } from "./display-path";
 import { messageOf } from "./errors";
 import { ANSI, type Paint, PLAIN } from "./progress-view";
@@ -32,7 +34,9 @@ export function printEnding(
     /** The run's id and folder. */
     run: { id: string; dir: string };
     n: number;
-    earlier: readonly AttemptRecord[];
+    earlier: readonly ClaimedAttempt[];
+    /** What the attempts before this one spent, from their operations, priced now. */
+    spentBefore?: EarlierSpent;
     json: boolean;
     /** Whether the attempt redid from a stage, which no repeated stop then hints at. */
     fromStage: boolean;
@@ -66,12 +70,12 @@ export function printEnding(
     named: `${context.workflow.meta.name} ${context.run.id}`,
     n: context.n,
     ...(settled ? { accounting: settled.accounting } : {}),
-    earlier: context.earlier,
+    ...(context.spentBefore ? { spentBefore: context.spentBefore } : {}),
     stages: context.terminal === undefined,
     records: pathFrom(shellCwd, context.run.dir, { home: context.home }),
     ...(kept.report ? { report: pathFrom(shellCwd, kept.report, { home: context.home }) } : {}),
     ...(end.choose?.length ? { choose: listRecorded(end.choose, context.now) } : {}),
-    ...(end.needs ? { needs: end.needs } : {}),
+    ...("needs" in end.ending && end.ending.needs ? { needs: end.ending.needs } : {}),
     ...(settled?.panes ? { panes: settled.panes } : {}),
     // As the run's Herdr workspace is labelled.
     runWorkspace: `awf ${context.workflow.meta.name} ${context.run.id} #${context.n}`,
@@ -105,7 +109,7 @@ function describeEnding(
     named: string;
     n: number;
     accounting?: RunAccounting;
-    earlier: readonly AttemptRecord[];
+    spentBefore?: EarlierSpent;
     stages: boolean;
     records: string;
     report?: string;
@@ -127,7 +131,9 @@ function describeEnding(
     context.named,
     ...(n > 1 ? [`attempt ${n}`] : []),
     ...(totals === undefined ? [] : [totals]),
-    ...(n > 1 && accounting ? [runTotal(n, accounting, context.earlier)] : []),
+    ...(n > 1 && accounting && context.spentBefore
+      ? [runTotal(n, accounting, context.spentBefore)]
+      : []),
   ].join(" · ");
   const word = OUTCOMES[ending.kind].word;
   if (ending.kind === "completed") {
@@ -229,14 +235,11 @@ function whereKept(
     : `${pane} in workspace "${label}" of herdr session ${session}`;
 }
 
-function runTotal(n: number, current: RunAccounting, earlier: readonly AttemptRecord[]): string {
-  const before = earlier.filter((record) => record.attempt < n);
-  const recorded = [...before.flatMap((record) => record.accounting ?? []), current];
-  const unknown = before.filter((record) => record.accounting === undefined);
-  const interrupted = unknown.filter((record) => record.ended === undefined).length;
-  return describeAttempts(sumAttempts(recorded), n, {
-    interrupted,
-    ended: unknown.length - interrupted,
+/** The run's total over its attempts: those before priced now, this one as it ran. */
+function runTotal(n: number, current: RunAccounting, before: EarlierSpent): string {
+  return describeAttempts(sumAttempts([...before.recorded, attemptAccounting(current)]), n, {
+    interrupted: before.interrupted,
+    ended: before.ended,
   });
 }
 
@@ -261,7 +264,7 @@ function present(
  */
 function sameStop(
   ending: Ending<JsonValue>,
-  earlier: readonly AttemptRecord[],
+  earlier: readonly ClaimedAttempt[],
 ): string | undefined {
   if (ending.kind !== "stopped" || ending.stage !== undefined) return undefined;
   const reused = ending.stages.at(-1)?.stage;
@@ -285,22 +288,25 @@ export function refusalMessage(id: string, refusal: AttemptRefusal, now: number)
   if (refusal.kind === "running") {
     return `attempt ${refusal.attempt.attempt} of ${id} is still running, as process ${refusal.attempt.pid}`;
   }
+  if (refusal.kind === "opened") {
+    return `${id} is open in awf open --no-fork (pid ${refusal.pid}); ${refusal.events ? "it is woken once that exits" : "continue it once that exits"}`;
+  }
   if (refusal.stages.length === 0) return `${id} completed; there is nothing to continue`;
   return `${id} completed; to redo from a stage, --from-stage one of:\n${listRecorded(refusal.stages, now).join("\n")}`;
 }
 
-/** Stage records, a line each, in the order given: summary, attempt, and how long ago. */
-function listRecorded(records: readonly StageRecord[], now: number): string[] {
-  const name = Math.max(0, ...records.map((record) => record.stage.length));
-  const summary = Math.max(0, ...records.map((record) => record.summary?.length ?? 0));
-  return records.map((record) =>
+/** Stage lines, one each, in the order given: summary, attempt, and how long ago. */
+function listRecorded(lines: readonly StageLine[], now: number): string[] {
+  const name = Math.max(0, ...lines.map((line) => line.name.length));
+  const summary = Math.max(0, ...lines.map((line) => line.summary?.length ?? 0));
+  return lines.map((line) =>
     [
-      `  ${record.stage.padEnd(name)}`,
-      ...(summary > 0 ? [(record.summary ?? "").padEnd(summary)] : []),
+      `  ${line.name.padEnd(name)}`,
+      ...(summary > 0 ? [(line.summary ?? "").padEnd(summary)] : []),
       [
-        ...(record.outcome === "succeeded" ? [] : [record.outcome]),
-        `attempt ${record.attempt}`,
-        ago(now - Date.parse(record.ended)),
+        ...(line.outcome === "succeeded" ? [] : [line.outcome]),
+        `attempt ${line.attempt}`,
+        ago(now - Date.parse(line.at)),
       ].join(" · "),
     ].join("   "),
   );
@@ -349,8 +355,7 @@ export function continueCommand(
   return [
     "awf",
     "run",
-    ...(command.runRootGiven ? ["--run-root", command.runRoot] : []),
-    ...(command.cwdGiven ? ["--cwd", command.cwd] : []),
+    ...placeFlags(command),
     pathFrom(command.shellCwd, command.workflowFile),
     "--id",
     id,
@@ -366,7 +371,3 @@ export function continueCommand(
 const STAGE = "{stage}";
 /** The placeholder for the file of values a go-on needs and none was given. */
 const FILE = "{file}";
-
-export function shellWord(word: string): string {
-  return /^[\w@%+=:,./-]+$/.test(word) ? word : `'${word.replaceAll("'", `'\\''`)}'`;
-}

package/src/author-typebox.ts

@@ -0,0 +1,13 @@
+// `agentswf/typebox`: a TypeBox schema carrying its type to `run()`, a tool's `input` and an
+// event's `data`. Here rather than in the contract, which imports no schema library.
+import type { JsonValue, OutputSchema } from "@agentswf/contract/workflow";
+import type Type from "typebox";
+
+type Typed<Schema extends Type.TSchema> = Extract<Type.Static<Schema>, JsonValue>;
+
+/** The schema itself, typed so awf infers its value; a schema of a non-JSON value is a type error. */
+export function typed<Schema extends Type.TSchema>(
+  schema: Schema & (Type.Static<Schema> extends JsonValue ? unknown : never),
+): Schema & OutputSchema<Typed<Schema>> {
+  return schema;
+}

package/src/client/checks.ts

@@ -0,0 +1,94 @@
+// The client's checks of what a program gives it that need no file: the fake client runs these
+// too, so a program's tests see the very `ClientError` the real client throws.
+import { isAbsolute } from "node:path";
+import { ClientError } from "@agentswf/contract/client";
+import { isEventWorkflow, isJsonValue, type JsonValue } from "@agentswf/contract/workflow";
+import { messageOf } from "../errors";
+import { idProblem } from "../runs";
+import { type AnyWorkflow, assertJsonValue, type EventWorkflow } from "../workflow-loader";
+
+/** `workflow`'s `file`, by which a program finds it and its runs. */
+export function fileOf(workflow: AnyWorkflow): string {
+  const file = (workflow as { file?: unknown })?.file;
+  if (typeof file !== "string" || !isAbsolute(file))
+    throw new ClientError(
+      "file",
+      `${workflow?.meta?.name ?? "the workflow"} gives no file, by which a program finds it and its runs: file: import.meta.path`,
+    );
+  return file;
+}
+
+/** `workflow`'s `meta.name`, checked as an id is. */
+export function nameOf(workflow: AnyWorkflow): string {
+  const name = workflow?.meta?.name;
+  const problem = idProblem(name);
+  if (problem) throw new ClientError("event", `meta.name: ${problem}`);
+  return name;
+}
+
+export function assertEventWorkflow(workflow: AnyWorkflow): asserts workflow is EventWorkflow {
+  if (!isEventWorkflow(workflow))
+    throw new ClientError("event", `${workflow?.meta?.name} declares no events; start runs it`);
+}
+
+/** What the types rule out in an emit, refused as the caller's mistake when it comes anyway. */
+export function checkEmit(
+  ref: string,
+  runId: string,
+  name: string,
+  data: unknown,
+  given: { eventId?: string; source?: string },
+): asserts data is JsonValue {
+  if (typeof name !== "string") throw new ClientError("event", "an event's name is a string", ref);
+  if (typeof runId !== "string") throw new ClientError("id", "a run's id is a string");
+  for (const [field, value] of [
+    ["eventId", given.eventId],
+    ["source", given.source],
+  ] as const)
+    if (value !== undefined && typeof value !== "string")
+      throw new ClientError(field === "eventId" ? "id" : "event", `${field} is a string`, ref);
+  // What tsc lets through in a value that isn't a literal: in.jsonl keeps JSON only.
+  if (!isJsonValue(data))
+    throw new ClientError("event", `${name}'s data must contain only JSON values`, ref);
+}
+
+export function checkArgs(name: string, args: unknown): asserts args is JsonValue {
+  try {
+    assertJsonValue(args, `${name} arguments`);
+  } catch (error) {
+    throw new ClientError("prepare", messageOf(error));
+  }
+}
+
+/** The id `id(args)` gives, checked; a workflow with `starts` and none is refused. */
+export function derivedId(workflow: AnyWorkflow, args: JsonValue): string | undefined {
+  const name = workflow.meta.name;
+  if (!workflow.id) {
+    if (isEventWorkflow(workflow) && workflow.starts !== undefined)
+      throw new ClientError(
+        "no-id",
+        `a run of ${name}, which starts on events, is named by its senders: start(${name}, args, { id }), or an id(args) on the workflow`,
+      );
+    return undefined;
+  }
+  let id: unknown;
+  try {
+    id = workflow.id(args as never);
+  } catch (error) {
+    throw new ClientError("prepare", `${name}'s id(args) failed: ${messageOf(error)}`);
+  }
+  const problem = typeof id === "string" ? idProblem(id) : `it returned a ${typeof id}`;
+  if (problem) throw new ClientError("id", `${name}'s id(args): ${problem}`);
+  return id as string;
+}
+
+export function checkRunId(id: string, ref: string): void {
+  const problem = idProblem(id);
+  if (problem) throw new ClientError("id", `the run's id: ${problem}`, ref);
+}
+
+/** A cursor is an item's, never an option of the command it is read with. */
+export function checkCursor(after: unknown): void {
+  if (after !== undefined && (typeof after !== "string" || after === "" || after.startsWith("-")))
+    throw new ClientError("cursor", `${JSON.stringify(after)} is no cursor an item carried`);
+}

package/src/client/exported.ts

@@ -0,0 +1,17 @@
+import { messageOf } from "../errors";
+
+/**
+ * Why `file` isn't the module whose default export is `workflow`, as awf loads it; undefined when
+ * it is. The program imported it already, so this import is its module cache's.
+ */
+export async function exportProblem(workflow: unknown, file: string): Promise<string | undefined> {
+  let exported: unknown;
+  try {
+    exported = ((await import(file)) as { default?: unknown }).default;
+  } catch (error) {
+    return `its file, ${file}, could not be imported: ${messageOf(error)}`;
+  }
+  return exported === workflow
+    ? undefined
+    : `its file, ${file}, doesn't export it as its default, as awf loads a workflow; file is the path of the module whose default export it is`;
+}

package/src/client/index.ts

@@ -0,0 +1,122 @@
+import { homedir } from "node:os";
+import { type Client, ClientError, type ClientOptions } from "@agentswf/contract/client";
+import type { EmitResultJson, InboxItemJson } from "@agentswf/contract/records";
+import { awfEventOf, type JsonValue } from "@agentswf/contract/workflow";
+import { checkEvent, deliverReply, emitEvent } from "../emit";
+import { inboxCommand } from "../inbox-command";
+import { asClientError, clientCode } from "../refusals";
+import type { WakeContext } from "../wake";
+import type { AnyWorkflow, EventWorkflow } from "../workflow-loader";
+import { assertEventWorkflow, checkCursor, checkEmit, checkRunId } from "./checks";
+import { locate } from "./locate";
+import { get, openExact, start } from "./runs";
+
+/** What the client runs each call with: the operator's home and environment, and how it launches. */
+export type ClientContext = Omit<WakeContext, "file"> & {
+  /** How often a wait reads the run's files. */
+  pollMs?: number;
+};
+
+/**
+ * A program's way to its workflows' runs, in its own process: the code `awf emit`, `awf inbox` and
+ * the run readers run, on the engine the workflow's project depends on (ADR 0015).
+ */
+export function client(options: ClientOptions = {}): Client {
+  return clientWith(options);
+}
+
+/**
+ * `client`, with what a test fakes: how an attempt is launched, a live run nudged, and the time.
+ * Not published: a program that launched nothing would record events no run ever takes.
+ */
+export function clientWith(
+  options: ClientOptions & Pick<WakeContext, "launch" | "nudge" | "now"> & { pollMs?: number },
+): Client {
+  const context: ClientContext = {
+    home: options.home ?? homedir(),
+    environment: options.environment ?? process.env,
+    ...(options.launch ? { launch: options.launch } : {}),
+    ...(options.nudge ? { nudge: options.nudge } : {}),
+    ...(options.now ? { now: options.now } : {}),
+    ...(options.pollMs === undefined ? {} : { pollMs: options.pollMs }),
+  };
+  return {
+    emit: (workflow, run, name, data, given) =>
+      emit(workflow as EventWorkflow, run, name, data as JsonValue, given ?? {}, context),
+    inbox: (workflow, given) => inbox(workflow as AnyWorkflow, given?.after, context),
+    start: (workflow, args, given) =>
+      start(workflow as AnyWorkflow, args, given ?? {}, context) as never,
+    get: (workflow, id) => get(workflow as AnyWorkflow, id, context) as never,
+  };
+}
+
+async function emit(
+  workflow: EventWorkflow,
+  runId: string,
+  name: string,
+  data: JsonValue,
+  given: { eventId?: string; source?: string },
+  context: ClientContext,
+): Promise<EmitResultJson> {
+  assertEventWorkflow(workflow);
+  const located = await locate(workflow, context.home);
+  const ref = `${workflow.meta.name}/${runId}`;
+  checkEmit(ref, runId, name, data, given);
+  const event = {
+    name,
+    data,
+    ...(given.eventId === undefined ? {} : { id: given.eventId }),
+    ...(given.source === undefined ? {} : { source: given.source }),
+  };
+  try {
+    const reply = awfEventOf(name);
+    if (reply?.kind !== "reply")
+      return await emitEvent(workflow, { run: runId, ...event }, { from: "operator", ...context });
+    // Checked against the value given, not the run's file: the program holds the workflow, and no
+    // author surface is served to it.
+    checkEvent(workflow, event, true);
+    checkRunId(runId, ref);
+    const run = await openExact(located.runRoot, workflow.meta.name, runId, "id");
+    if (!run)
+      throw new ClientError(
+        "no-run",
+        `no run ${ref} in ${located.project}: a reply never starts one`,
+        ref,
+      );
+    return await deliverReply({ run }, reply.key, event, context);
+  } catch (error) {
+    throw asClientError(error, ref);
+  }
+}
+
+async function inbox(
+  workflow: AnyWorkflow,
+  after: string | undefined,
+  context: ClientContext,
+): Promise<InboxItemJson[]> {
+  const located = await locate(workflow, context.home);
+  checkCursor(after);
+  const lines: string[] = [];
+  const errors: string[] = [];
+  // `awf inbox --workflow --json`'s own reader, so what a program reads is what the command lists.
+  const code = await inboxCommand(
+    [
+      "--workflow",
+      workflow.meta.name,
+      "--run-root",
+      located.runRoot,
+      "--json",
+      ...(after === undefined ? [] : ["--after", after]),
+    ],
+    located.project,
+    { stdout: (text) => lines.push(text), stderr: (text) => errors.push(text) },
+    { home: context.home },
+  );
+  const items = lines.flatMap((line) => line.split("\n")).filter((line) => line !== "");
+  if (code === 0) return items.map((line) => JSON.parse(line) as InboxItemJson);
+  const refused =
+    items.length > 0 ? (JSON.parse(items.at(-1)!) as { code?: string; error?: string }) : {};
+  const known = clientCode(refused.code);
+  if (known) throw new ClientError(known, refused.error ?? known);
+  throw new Error(refused.error ?? (errors.join("\n") || `awf inbox exited ${code}`));
+}

package/src/client/locate.ts

@@ -0,0 +1,34 @@
+import { ClientError } from "@agentswf/contract/client";
+import { messageOf } from "../errors";
+import { checkProjectEngine } from "../project-engine";
+import { projectOf, projectRunRoot } from "../projects";
+import { asClientError } from "../refusals";
+import type { AnyWorkflow } from "../workflow-loader";
+import { fileOf, nameOf } from "./checks";
+import { exportProblem } from "./exported";
+
+/** A workflow as the client finds it: its file, checked to export it, and its project's runs. */
+export type Found = { workflow: AnyWorkflow; file: string; project: string; runRoot: string };
+
+/**
+ * Where `workflow`'s runs are: its `file`, which must export it as its default, in a project that
+ * runs on this engine. `file` is imported, which the program's module cache already holds.
+ */
+export async function locate(workflow: AnyWorkflow, home: string): Promise<Found> {
+  const file = fileOf(workflow);
+  const exported = await exportProblem(workflow, file);
+  if (exported) throw new ClientError("file", `${workflow?.meta?.name}: ${exported}`);
+  nameOf(workflow);
+  let project: string;
+  try {
+    project = await projectOf(file, home);
+  } catch (error) {
+    throw new ClientError("project", messageOf(error));
+  }
+  try {
+    checkProjectEngine(project, { file, client: true });
+  } catch (error) {
+    throw asClientError(error);
+  }
+  return { workflow, file, project, runRoot: projectRunRoot(project) };
+}

package/src/client/published.ts

@@ -0,0 +1,3 @@
+// What `agentswf/client` publishes: the contract's types and `ClientError`, and `client`.
+export * from "@agentswf/contract/client";
+export { client } from "./index";