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

package/src/deprecations.ts

@@ -0,0 +1,177 @@
+/**
+ * Every name deprecated before 0.1.0, with what replaces it: each is logged once per attempt it is
+ * used in, so a continued or woken run logs it again, and removed one beta after the beta that
+ * deprecated it (story 039).
+ */
+export const DEPRECATIONS = {
+  labels: {
+    old: "an agent's labels option",
+    instead: "drop them: nothing reads an agent's labels",
+  },
+  whenToUse: { old: "meta.whenToUse", instead: "drop it: nothing reads it" },
+  "stage-receive": {
+    old: "a stage around wf.receive()",
+    instead: "wait with wf.race(name, …), which is recorded under its name, outside a stage",
+  },
+  isAnswered: { old: "isAnswered(outcome)", instead: "check outcome.answered" },
+  defineExecutableWorkflow: {
+    old: "defineExecutableWorkflow",
+    instead: "use defineWorkflow, with meta and run beside prepare",
+  },
+  "call-id": {
+    old: "the id of one run, start, compact or set",
+    instead:
+      "drop it: a later attempt doesn't know it, and a stage keeps a call from running twice",
+  },
+  "turn-source": {
+    old: "a started turn as a wait's branch",
+    instead: "name the agent, { done: agent }, which has at most one started turn",
+  },
+  "turn-is": { old: "turn.is(e)", instead: "use agent.is(e)" },
+  "test-reply": {
+    old: "reply.… in a test's script",
+    instead: "use noAnswer.…, the same calls: a reply answers, these end a turn without an answer",
+  },
+  "message-silent": {
+    old: "message.silent() in a test's message script",
+    instead: "return nothing, which ends the turn without a reply",
+  },
+  "message-fail": {
+    old: "message.fail() in a test's message script",
+    instead: "return noAnswer.failed(reason), which fails the turn as a failed harness does",
+  },
+  "test-event-id": {
+    old: "an event's id in a test",
+    instead: "give it as eventId, as awf emit --event-id does",
+  },
+  "run-stopped": { old: "run.stopped", instead: 'read run.ending, whose kind is "stopped"' },
+  "run-parked": { old: "run.parked", instead: 'read run.ending, whose kind is "parked"' },
+  "colon-key": {
+    old: "a key with a colon",
+    instead: (key: string) =>
+      `${key === "" ? "use - in its place" : `name it ${key.replaceAll(":", "-")}`}: a colon is kept for awf's own event names`,
+  },
+  "agents-stop": {
+    old: "wf.agents.stop(key)",
+    instead: "call close(reason?) on the agent's ref",
+  },
+  "fork-runtime": {
+    old: "a fork's own placement, metered or effort",
+    instead:
+      "give them in its runtime, as open does: fork({ key, runtime: { placement, metered, effort } })",
+  },
+  "timeout-ms": {
+    old: "timeoutMs",
+    instead: 'give timeout, a Duration such as "90s" or "10m"',
+  },
+  "deadline-option": {
+    old: "a deadline: { unixMilliseconds } option",
+    instead: 'give timeout: a Date, or a Duration such as "20m"',
+  },
+  "nudge-deadline": {
+    old: "nudge.deadline",
+    instead: "drop it: the turn's timeout bounds its check-ins",
+  },
+  "keep-alive-timeout-ms": {
+    old: "keepAlive.timeoutMs",
+    instead: 'give keepAlive.window, a Duration such as "90s"',
+  },
+  "run-deadline-ms": {
+    old: "wf.deadline.unixMilliseconds",
+    instead: "wf.deadline is a Date: read wf.deadline.getTime()",
+  },
+  "stall-ms": { old: "a test's stallMs", instead: 'give stall, a Duration such as "2s"' },
+  "test-args": {
+    old: "testWorkflow(workflow, args, options)",
+    instead: "give args among the options: testWorkflow(workflow, { args, … })",
+  },
+  "test-recorded": { old: "a test's recorded", instead: "give it as earlier: { stages }" },
+  "test-mailbox": { old: "a test's mailbox", instead: "give it as earlier: { mailbox }" },
+  "to-code": {
+    old: 'to: "code"',
+    instead: (key: string) =>
+      `declare "${key}:reply": ParticipantReply in events and connect it without to: the code takes its messages as ${key}:reply`,
+  },
+  "undeclared-ended": {
+    old: "start() for an agent whose end isn't declared",
+    instead: (key: string) => {
+      const named = key.replaceAll(":", "-");
+      const declare = `declare "${named}:ended": AgentEnded in events: its end then arrives as ${named}:ended, not agent:ended`;
+      return key.includes(":")
+        ? `rename the key ${named}, which can name its end, and ${declare}`
+        : declare;
+    },
+  },
+  "participant-is": {
+    old: "is(e) on a participant",
+    instead: 'read e.name === "{key}:reply", declared in events',
+  },
+  "test-participant-reply": {
+    old: 'a scripted { name: "participant:reply", from } in a test',
+    instead: 'name the declared event, { name: "{key}:reply", data }',
+  },
+  "send-event-id": {
+    old: "awf send --event-id",
+    instead:
+      'use awf emit {run} {key}:reply \'{"text":…,"author":…}\' --event-id {id}, with {key}:reply declared in the workflow\'s events',
+  },
+  "pane-layout": {
+    old: "an agent's layout",
+    instead:
+      "give pane: { tab, front } or pane: { beside, side, front }; the workspace is the operator's, awf run --workspace, and the session AWF_HERDR_SESSION",
+  },
+  "keep-pane": {
+    old: "an agent's keepPane",
+    instead: "drop it: keeping panes is the operator's, awf run --keep-panes",
+  },
+  "duration-ms": {
+    old: "a duration in ms",
+    instead: (value: string) =>
+      `give ${Number.parseInt(value, 10) / 1000}s: a duration is a decimal and s, m, h or d`,
+  },
+  "wait-seconds": {
+    old: "a bare number for --wait",
+    instead: (value: string) => `give a duration, --wait ${value}s`,
+  },
+} as const satisfies Record<
+  string,
+  { old: string; instead: string | ((subject: string) => string) }
+>;
+
+export type Deprecated = keyof typeof DEPRECATIONS;
+
+/** One attempt's deprecated uses: each name said once, as a warning in the run's log. */
+export class RunDeprecations {
+  /** Each name said, with its subject where it has one: each key with a colon is named. */
+  readonly #said = new Set<string>();
+  /** The attempt has ended: an outcome kept past it reports to no log. */
+  #settled = false;
+
+  constructor(private readonly warn: (text: string) => void) {}
+
+  /** `subject`, where given, is what was used, and each subject is said once. */
+  used(name: Deprecated, subject?: string): void {
+    const said = subject === undefined ? name : `${name}\0${subject}`;
+    if (this.#said.has(said)) return;
+    this.#said.add(said);
+    this.warn(deprecationLine(name, subject));
+  }
+
+  settle(): void {
+    this.#settled = true;
+  }
+
+  /** As `used`, for a name the contract reports by its own spelling; one not listed is ignored. */
+  reported = (name: unknown): void => {
+    if (this.#settled) return;
+    if (typeof name === "string" && Object.hasOwn(DEPRECATIONS, name))
+      this.used(name as Deprecated);
+  };
+}
+
+/** The line a deprecated use logs. */
+export function deprecationLine(name: Deprecated, subject = ""): string {
+  const { old, instead } = DEPRECATIONS[name];
+  const named = subject === "" ? "" : `, ${subject},`;
+  return `awf: ${old}${named} is deprecated; ${typeof instead === "function" ? instead(subject) : instead}`;
+}

package/src/duration.ts

@@ -1,18 +1,48 @@
-/** A duration such as `500ms`, `30s`, `20m` or `2h`, in milliseconds. */
-export function parseDuration(value: string): number {
-  const matched = /^(\d+)(ms|s|m|h)$/.exec(value);
-  if (!matched) throw new Error(`invalid duration: ${value}`);
-  const amount = Number(matched[1]);
-  if (!Number.isSafeInteger(amount) || amount <= 0) throw new Error(`invalid duration: ${value}`);
-  const unit = matched[2];
-  const multiplier = unit === "ms" ? 1 : unit === "s" ? 1_000 : unit === "m" ? 60_000 : 3_600_000;
-  const milliseconds = amount * multiplier;
-  if (!Number.isSafeInteger(milliseconds)) throw new Error(`duration is too large: ${value}`);
+import { durationMilliseconds, positiveDurationMilliseconds } from "@agentswf/contract/workflow";
+import { deprecationLine } from "./deprecations";
+import { messageOf } from "./errors";
+
+/**
+ * A flag's duration in milliseconds, longer than none: the one grammar, `"90s"`, `"1.5h"`, `"1d"`.
+ * A whole number of `ms`, which the CLI took before, is read until 0.1.0 and `deprecated` told.
+ */
+export function parseDuration(
+  value: string,
+  flag: string,
+  deprecated: (line: string) => void,
+): number {
+  const ms = /^(\d+)ms$/.exec(value);
+  if (!ms) return positiveDurationMilliseconds(value, flag);
+  const milliseconds = Number(ms[1]);
+  if (!Number.isSafeInteger(milliseconds) || milliseconds <= 0)
+    throw new Error(`${flag} is a positive duration: not ${value}`);
+  deprecated(deprecationLine("duration-ms", value));
   return milliseconds;
 }
 
+/**
+ * `--wait`, in seconds from none to `maxSeconds`: a duration, `"90s"`. A bare number of seconds,
+ * which it took before, is read until 0.1.0 and `deprecated` told.
+ */
+export function parseWait(
+  value: string,
+  maxSeconds: number,
+  deprecated: (line: string) => void,
+): number {
+  const bare = /^\d+(\.\d+)?$/.test(value);
+  let seconds: number;
+  try {
+    seconds = bare ? Number(value) : durationMilliseconds(value) / 1000;
+  } catch (error) {
+    throw new Error(`--wait takes a duration up to ${maxSeconds}s: ${messageOf(error)}`);
+  }
+  if (seconds > maxSeconds) throw new Error(`--wait takes a duration up to ${maxSeconds}s`);
+  if (bare) deprecated(deprecationLine("wait-seconds", value));
+  return seconds;
+}
+
 /** `45s`, `6m40s`, `1h02m`. */
-export function duration(milliseconds: number): string {
+export function formatDuration(milliseconds: number): string {
   const seconds = Math.max(0, Math.round(milliseconds / 1000));
   if (seconds < 60) return `${seconds}s`;
   const minutes = Math.floor(seconds / 60);
@@ -22,8 +52,8 @@ export function duration(milliseconds: number): string {
 
 /**
  * When a timer given `when` is due, epoch ms, from `now`, and `when` as its record keeps it: a
- * duration of days, hours or minutes as given, or a `Date` as an ISO time. A workflow's grammar,
- * apart from the CLI's `parseDuration`: a wait is days long, and `1.5h` reads as written.
+ * `Duration` as given, or a `Date` as an ISO time. A workflow's grammar, apart from the CLI's
+ * `parseDuration`: a wait is days long, and `1.5h` reads as written.
  */
 export function parseWhen(when: unknown, now: number): { due: number; when: string } {
   if (when instanceof Date) {
@@ -31,11 +61,11 @@ export function parseWhen(when: unknown, now: number): { due: number; when: stri
     if (!Number.isFinite(due)) throw new Error("a timer's time is a valid Date");
     return { due, when: when.toISOString() };
   }
-  const matched = typeof when === "string" ? /^(\d+(?:\.\d+)?)(d|h|m)$/.exec(when) : null;
-  if (!matched)
-    throw new Error(
-      `a timer is due in days, hours or minutes, "14d", "4h", "1.5h", or at a Date; not ${String(when)}`,
-    );
-  const unit = matched[2] === "d" ? 86_400_000 : matched[2] === "h" ? 3_600_000 : 60_000;
-  return { due: now + Math.round(Number(matched[1]) * unit), when: when as string };
+  let milliseconds: number;
+  try {
+    milliseconds = durationMilliseconds(when);
+  } catch (error) {
+    throw new Error(`a timer is due in a duration or at a Date: ${messageOf(error)}`);
+  }
+  return { due: now + milliseconds, when: when as string };
 }

package/src/emit-command.ts

@@ -1,24 +1,22 @@
 import type { EmitResultJson } from "@agentswf/contract/records";
 import { isEventWorkflow, type JsonValue } from "@agentswf/contract/workflow";
-import { EmitError, emitEvent } from "./emit";
+import { EmitError, emitEvent, emitToRun } from "./emit";
 import { messageOf } from "./errors";
-import type { Out } from "./run-commands";
+import help from "./help/emit.txt" with { type: "text" };
+import { type Out, parsePlace, type ReadPlace } from "./run-commands";
+import { findRunByRef } from "./run-state";
 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();
+
+type Event = { name: string; data: JsonValue; id?: string };
+
+/** `--target {file} --id {id}`, which may start the run; or a run that is there, by its ref. */
+type Parsed = Event & { json: boolean } & (
+    | { target: string; run: string; ref?: undefined }
+    | { ref: string; place: ReadPlace; target?: undefined }
+  );
 
 export async function emitCommand(
   argv: readonly string[],
@@ -34,37 +32,35 @@ export async function emitCommand(
     out.stdout(emitUsage);
     return 0;
   }
-  let parsed: {
-    target: string;
-    run: string;
-    name: string;
-    data: JsonValue;
-    id?: string;
-    json: boolean;
-  };
+  let parsed: Parsed;
   try {
-    parsed = parse(argv);
+    parsed = parse(argv, shellCwd);
   } catch (error) {
     out.stderr(`awf: ${messageOf(error)}\n\n${emitUsage}`);
     return 2;
   }
+  const event = {
+    name: parsed.name,
+    data: parsed.data,
+    ...(parsed.id === undefined ? {} : { id: parsed.id }),
+  };
   let result: EmitResultJson;
   try {
-    const loaded = await loadWorkflowFile(parsed.target, shellCwd);
-    if (!isEventWorkflow(loaded.workflow)) {
-      out.stderr(`awf: ${loaded.file} declares no events; awf run starts it`);
-      return 2;
+    if (parsed.ref !== undefined) {
+      const status = await findRunByRef(parsed.ref, parsed.place, context.home);
+      result = await emitToRun(status, event, context);
+    } else {
+      const loaded = await loadWorkflowFile(parsed.target, shellCwd);
+      if (!isEventWorkflow(loaded.workflow)) {
+        out.stderr(`awf: ${loaded.file} declares no events; awf run starts it`);
+        return 2;
+      }
+      result = await emitEvent(
+        loaded.workflow,
+        { run: parsed.run, ...event },
+        { from: "operator", ...context },
+      );
     }
-    result = await emitEvent(
-      loaded.workflow,
-      {
-        run: parsed.run,
-        name: parsed.name,
-        data: parsed.data,
-        ...(parsed.id === undefined ? {} : { id: parsed.id }),
-      },
-      { from: "operator", ...context },
-    );
   } catch (error) {
     out.stderr(`awf: ${messageOf(error)}`);
     return error instanceof EmitError ? 2 : 1;
@@ -86,35 +82,42 @@ function emitLine(result: EmitResultJson): string {
   return `${result.outcome} ${result.ref}${did === undefined ? "" : `: ${did}`}`;
 }
 
-function parse(argv: readonly string[]): {
-  target: string;
-  run: string;
-  name: string;
-  data: JsonValue;
-  id?: string;
-  json: boolean;
-} {
+function parse(argv: readonly string[], shellCwd: string): Parsed {
+  const { place, json, rest } = parsePlace(argv, shellCwd);
   let target: string | undefined;
   let run: string | undefined;
   let id: string | undefined;
-  let json = false;
   const words: string[] = [];
-  for (let i = 0; i < argv.length; i++) {
-    const word = argv[i]!;
+  for (let i = 0; i < rest.length; i++) {
+    const word = rest[i]!;
     const value = () => {
-      const next = argv[++i];
+      const next = rest[++i];
       if (next === undefined) throw new Error(`${word} needs a value`);
       return next;
     };
     if (word === "--target") target = value();
     else if (word === "--id") run = value();
     else if (word === "--event-id") id = value();
-    else if (word === "--json") json = true;
     else if (word.startsWith("--")) throw new Error(`unknown option ${word}`);
     else words.push(word);
   }
-  if (target === undefined) throw new Error("--target names the workflow file the event is for");
-  if (run === undefined) throw new Error("--id names the run the event is for, by its id");
+  let form: { target: string; run: string } | { ref: string; place: ReadPlace };
+  if (target !== undefined) {
+    if (run === undefined) throw new Error("--id names the run the event is for, by its id");
+    if (place.repeat.length > 0)
+      throw new Error(
+        "--cwd and --run-root find a run by its ref; --target's file names its project",
+      );
+    form = { target, run };
+  } else {
+    if (run !== undefined) throw new Error("--id goes with --target; a run's ref names it alone");
+    const ref = words.shift();
+    if (ref === undefined)
+      throw new Error(
+        "name the run, <workflow>/<id> or <id>, or the workflow by --target and --id",
+      );
+    form = { ref, place };
+  }
   const [name, text, ...more] = words;
   if (name === undefined) throw new Error("the event's name is missing");
   if (more.length > 0) throw new Error(`one event at a time; also given: ${more.join(" ")}`);
@@ -126,5 +129,5 @@ function parse(argv: readonly string[]): {
       throw new Error(`the event's data is not JSON: ${messageOf(error)}`);
     }
   }
-  return { target, run, name, data, ...(id === undefined ? {} : { id }), json };
+  return { ...form, name, data, ...(id === undefined ? {} : { id }), json };
 }

package/src/emit.ts

@@ -1,12 +1,19 @@
 import { randomBytes } from "node:crypto";
 import { isAbsolute, join } from "node:path";
-import { type EmitResultJson, MAILBOX_RECORD_VERSION } from "@agentswf/contract/records";
+import {
+  type EmitResultJson,
+  MAILBOX_RECORD_VERSION,
+  type RunPanes,
+} from "@agentswf/contract/records";
 import { parseJsonSchema, validate } from "@agentswf/contract/schema";
 import {
   AWF_ID_PREFIX,
+  awfEventOf,
   eventWorkflowProblem,
+  isEventWorkflow,
   type JsonValue,
   nameProblem,
+  ParticipantReply,
 } from "@agentswf/contract/workflow";
 import { messageOf } from "./errors";
 import { exists } from "./files";
@@ -14,9 +21,10 @@ import { appendMailbox, foldMailbox, readMailbox } from "./mailbox";
 import { projectOf, projectRunRoot, recordProject } from "./projects";
 import { runLockFile, withRunLock } from "./run-lock";
 import { prepareArgs } from "./run-prepare";
-import { createRun, idProblem, openRun, type Run, readAttempts } from "./runs";
+import type { RunStatus } from "./run-state";
+import { createRun, idProblem, openRun, panesChanged, type Run, readAttempts } from "./runs";
 import { type WakeContext, type Woken, wake } from "./wake";
-import type { EventWorkflow } from "./workflow-loader";
+import { type EventWorkflow, loadWorkflowFile } from "./workflow-loader";
 
 /** An event awf refuses to take at all: a name, shape or id no run of the target could have. */
 export class EmitError extends Error {
@@ -43,12 +51,13 @@ export async function emitEvent(
   const workflow = target.meta.name;
   const { name, data } = event;
   checkEvent(target, event);
+  const file = fileOf(target);
   const id = event.id ?? `${AWF_ID_PREFIX}${randomBytes(8).toString("hex")}`;
   const at = new Date(context.now?.() ?? Date.now()).toISOString();
   const runId = event.run;
   const problem = idProblem(runId);
   if (problem) throw new EmitError(`the run's id: ${problem}`);
-  const project = await projectOf(target.file, context.home).catch((error: unknown) => {
+  const project = await projectOf(file, context.home).catch((error: unknown) => {
     throw new EmitError(messageOf(error));
   });
   const starts = target.starts?.includes(name) ?? true;
@@ -59,13 +68,69 @@ export async function emitEvent(
       runId,
       event: { id, name, data, from: context.from, at },
       deduplicate: event.id !== undefined,
-      file: target.file,
+      file,
       ...(starts ? { start: { project, target } } : {}),
     },
     context,
   );
 }
 
+/**
+ * `awf emit {ref} {key}:reply …`: a participant's message to the code of a run that is there,
+ * checked against the definition in the file a wake would run, its last attempt's, and delivered.
+ * It never starts a run, and doesn't ask whether the participant has connected: one sent before
+ * the run connects it waits in the mailbox for the run's next wait.
+ */
+export async function emitToRun(
+  status: RunStatus,
+  event: { name: string; data: JsonValue; id?: string },
+  context: Omit<WakeContext, "file">,
+): Promise<EmitResultJson> {
+  const { run, ref } = status;
+  const reply = awfEventOf(event.name);
+  if (reply?.kind !== "reply")
+    throw new EmitError(
+      `awf emit {run} sends a participant's message to the code, {key}:reply, not ${event.name}; the workflow's own events go by --target {file} --id {id}`,
+    );
+  if (!run.record.events) throw new EmitError(`${ref} is a run of a workflow without events`);
+  // A returned run takes nothing, so its file, since moved or changed, is not read: a late reply is
+  // refused as returned, not failed for a retry that never ends.
+  if (status.attempts.at(-1)?.outcome === "completed")
+    return deliverReply(status, reply.key, event, context);
+  const file = status.attempts.at(-1)?.file ?? run.record.file;
+  if (file === undefined) throw new Error(`${ref} has no file to check the event against`);
+  const { workflow } = await loadWorkflowFile(file, run.record.cwd);
+  if (!isEventWorkflow(workflow) || workflow.meta.name !== run.record.workflow)
+    throw new Error(`${file} is no longer ${run.record.workflow} with events, which ${ref} ran`);
+  checkEvent(workflow, event, true);
+  return deliverReply(status, reply.key, event, context);
+}
+
+/**
+ * `{key}:reply` appended to a run that is there, and the run woken: a duplicate id is a duplicate.
+ * The caller has checked it.
+ */
+export function deliverReply(
+  status: RunStatus,
+  key: string,
+  event: { data: JsonValue; id?: string },
+  context: Omit<WakeContext, "file">,
+): Promise<EmitResultJson> {
+  const { run } = status;
+  const at = new Date(context.now?.() ?? Date.now()).toISOString();
+  const id = event.id ?? `${AWF_ID_PREFIX}${randomBytes(8).toString("hex")}`;
+  return deliver(
+    {
+      runRoot: run.root,
+      workflow: run.record.workflow,
+      runId: run.record.id,
+      event: replyRecord(key, id, event.data, at),
+      deduplicate: event.id !== undefined,
+    },
+    context,
+  );
+}
+
 /** An event for a run of a workflow with events, as `deliver` takes it. */
 export type Delivery = {
   runRoot: string;
@@ -146,6 +211,7 @@ async function createEventRun(
   file: string | undefined,
   context: Pick<WakeContext, "home" | "environment">,
   argv: readonly string[] = [],
+  panes?: RunPanes,
 ): Promise<Run> {
   const run = await createRun(runRoot, {
     id,
@@ -156,6 +222,7 @@ async function createEventRun(
     events: true,
     env: { PATH: context.environment.PATH ?? "" },
     ...(file ? { file } : {}),
+    ...(panes ? { panes } : {}),
   });
   await recordProject(context.home, project);
   return run;
@@ -167,24 +234,27 @@ export type Opened = { run: string; created: boolean } & Woken;
 /**
  * `awf run --id` for a workflow with events: creates the run with no event, under its lock, and
  * starts it, so it runs to its first wait and parks there. One already there is only woken, as
- * `awf tick` would; one that returned is refused, as its events are.
+ * `awf tick` would; one that returned is refused, as its events are. `panes`, the operator's
+ * `--workspace` and `--keep-panes`, are recorded with a new run, and may not change one there.
  */
 export async function openEventRun(
   target: EventWorkflow,
   id: string,
   argv: readonly string[],
   context: Omit<WakeContext, "file">,
+  panes?: RunPanes,
 ): Promise<Opened> {
   const workflow = target.meta.name;
   const problem = idProblem(id);
   if (problem) throw new EmitError(problem);
-  const project = await projectOf(target.file, context.home).catch((error: unknown) => {
+  const file = fileOf(target);
+  const project = await projectOf(file, context.home).catch((error: unknown) => {
     throw new EmitError(messageOf(error));
   });
   const runRoot = projectRunRoot(project);
   const ref = `${workflow}/${id}`;
   return withRunLock(runLockFile(runRoot, workflow, id), async () => {
-    const woken = { ...context, file: target.file };
+    const woken = { ...context, file };
     if (await exists(join(runRoot, workflow, id, "run.json"))) {
       const run = await openRun(runRoot, workflow, id);
       if ((await readAttempts(run)).at(-1)?.outcome === "completed")
@@ -193,6 +263,8 @@ export async function openEventRun(
         throw new EmitError(
           `${ref} is there already, started with ${run.record.argv.length > 0 ? "arguments of its own" : "none"}; awf run --id ${id} with none wakes it`,
         );
+      const changed = panesChanged(run.record, panes);
+      if (changed) throw new EmitError(changed);
       return { run: ref, created: false, ...(await wake(run, woken)) };
     }
     try {
@@ -200,28 +272,65 @@ export async function openEventRun(
     } catch (error) {
       throw new EmitError(`prepare: ${messageOf(error)}`);
     }
-    const run = await createEventRun(runRoot, workflow, id, project, target.file, context, argv);
+    const run = await createEventRun(runRoot, workflow, id, project, file, context, argv, panes);
     return { run: ref, created: true, ...(await wake(run, woken)) };
   });
 }
 
-/** The event's name, shape and id, as the target declares them; an `EmitError` when they don't fit. */
+/**
+ * The target's file, which says which project its runs live in and which a start or wake runs:
+ * `file`, or the path awf loaded it from. Only a sender holding the workflow itself, as `wf.emit`
+ * does, can be without one.
+ */
+function fileOf(target: EventWorkflow): string {
+  if (target.file === undefined)
+    throw new EmitError(
+      `${target.meta.name} gives no file, by which a sender holding it finds it: file: import.meta.path`,
+    );
+  return target.file;
+}
+
+/**
+ * `{key}:reply`'s event as the mailbox records it: `participant:reply` from its key, whatever the
+ * workflow declares it as, so a wait takes it by one name.
+ */
+export function replyRecord(
+  key: string,
+  id: string,
+  data: JsonValue,
+  at: string,
+): Delivery["event"] {
+  return { id, name: "participant:reply", data, from: key, at };
+}
+
+/**
+ * The event's name, shape and id, as the target declares them; an `EmitError` when they don't fit.
+ * A name with a colon is awf's: only `{key}:reply`, from the operator (`replies`), is sent.
+ */
 export function checkEvent(
   target: EventWorkflow,
   event: { name: string; data: JsonValue; id?: string },
+  replies = false,
 ): void {
   const workflow = target.meta.name;
   const problem = eventWorkflowProblem(target);
   if (problem) throw new EmitError(`${workflow}: ${problem}`);
-  if (!isAbsolute(target.file))
+  if (target.file !== undefined && !isAbsolute(target.file))
     throw new EmitError(`${workflow}: its file, ${target.file}, is import.meta.path, absolute`);
-  if (event.name.includes(":"))
-    throw new EmitError(`${event.name}: a name with a colon is awf's own, and not sent`);
-  const schema = target.events[event.name];
-  if (!schema)
+  const reply = awfEventOf(event.name)?.kind === "reply";
+  if (event.name.includes(":") && !(replies && reply))
+    throw new EmitError(
+      reply
+        ? `${event.name}: a participant's message goes to a run that is there, awf emit ${workflow}/{id} ${event.name} '{"text":…}'`
+        : `${event.name}: a name with a colon is awf's own, and not sent`,
+    );
+  const declared = target.events[event.name];
+  if (!declared)
     throw new EmitError(
       `${workflow} declares no event ${event.name}; its events are ${Object.keys(target.events).join(", ")}`,
     );
+  // A reply is checked against awf's own schema, not the workflow's copy, which may be older.
+  const schema = reply ? ParticipantReply : declared;
   let parsed: ReturnType<typeof parseJsonSchema>;
   try {
     parsed = parseJsonSchema(schema);