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

package/src/emit.ts

@@ -0,0 +1,246 @@
+import { randomBytes } from "node:crypto";
+import { isAbsolute, join } from "node:path";
+import { type EmitResultJson, MAILBOX_RECORD_VERSION } from "@agentswf/contract/records";
+import { parseJsonSchema, validate } from "@agentswf/contract/schema";
+import {
+  AWF_ID_PREFIX,
+  eventWorkflowProblem,
+  type JsonValue,
+  nameProblem,
+} from "@agentswf/contract/workflow";
+import { messageOf } from "./errors";
+import { exists } from "./files";
+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 WakeContext, type Woken, wake } from "./wake";
+import type { EventWorkflow } 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 {
+  constructor(message: string) {
+    super(message);
+    this.name = "EmitError";
+  }
+}
+
+export type EmitContext = Omit<WakeContext, "file"> & {
+  /** As `WorkflowEvent.from`: the sending run's ref, or `operator`. */
+  from: string;
+};
+
+/**
+ * A sender's way in: checks the event against its target and delivers it to the run it names. A wrong name,
+ * shape or id throws an `EmitError`; the run's state is the outcome.
+ */
+export async function emitEvent(
+  target: EventWorkflow,
+  event: { run: string; name: string; data: JsonValue; id?: string },
+  context: EmitContext,
+): Promise<EmitResultJson> {
+  const workflow = target.meta.name;
+  const { name, data } = event;
+  checkEvent(target, event);
+  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) => {
+    throw new EmitError(messageOf(error));
+  });
+  const starts = target.starts?.includes(name) ?? true;
+  return deliver(
+    {
+      runRoot: projectRunRoot(project),
+      workflow,
+      runId,
+      event: { id, name, data, from: context.from, at },
+      deduplicate: event.id !== undefined,
+      file: target.file,
+      ...(starts ? { start: { project, target } } : {}),
+    },
+    context,
+  );
+}
+
+/** An event for a run of a workflow with events, as `deliver` takes it. */
+export type Delivery = {
+  runRoot: string;
+  workflow: string;
+  runId: string;
+  event: { id: string; name: string; data: JsonValue; from: string; at: string };
+  /** False for an id awf made at random, which nothing repeats. */
+  deduplicate: boolean;
+  /** Given when the event may start the run: what a new run records, and the workflow it prepares. */
+  start?: { project: string; target: EventWorkflow };
+  /** The file a sender named, which a start or continue runs; absent, the run's last. */
+  file?: string;
+};
+
+/**
+ * The one way in, for every event a run of a workflow with events gets: a sender's, a participant's reply, or awf's
+ * own. Under the run's lock it finds a duplicate, refuses the event, or creates the run, appends
+ * the event and wakes the run.
+ */
+export async function deliver(
+  delivery: Delivery,
+  context: Omit<WakeContext, "file">,
+): Promise<EmitResultJson> {
+  const { runRoot, workflow, runId, event, start, file } = delivery;
+  const woken = { ...context, ...(file ? { file } : {}) };
+  const ref = `${workflow}/${runId}`;
+  return withRunLock(runLockFile(runRoot, workflow, runId), async () => {
+    let run: Run | undefined = (await exists(join(runRoot, workflow, runId, "run.json")))
+      ? await openRun(runRoot, workflow, runId)
+      : undefined;
+    // What was due is `awf tick`'s to say; an emit's caller knows it sent an event.
+    const result = (outcome: EmitResultJson["outcome"], { cause: _, ...woken }: Woken) =>
+      ({ v: 1, outcome, ref, eventId: event.id, ...woken }) satisfies EmitResultJson;
+    if (run) {
+      // Not appended again, but it still wakes the run: a sender retrying after a launch that failed
+      // sends the same id.
+      if (delivery.deduplicate && foldMailbox(await readMailbox(run.dir)).events.has(event.id))
+        return result("duplicate", await wake(run, { ...woken, nudgeLive: false }));
+      if ((await readAttempts(run)).at(-1)?.outcome === "completed")
+        return result("refused", { did: "none", why: "returned" });
+    }
+    const starts = !run;
+    if (!run) {
+      if (!start) return result("refused", { did: "none", why: "not-a-start" });
+      checkStartArgs(start.target, start.project);
+      run = await createEventRun(runRoot, workflow, runId, start.project, file, context);
+    }
+    await appendMailbox(run.dir, {
+      version: MAILBOX_RECORD_VERSION,
+      kind: "event",
+      ...event,
+      ...(starts ? { starts: true as const } : {}),
+    });
+    return result("accepted", await wake(run, woken));
+  });
+}
+
+/**
+ * A run an event starts has no argv: its args are what `prepare` makes of none, checked before the
+ * run is made, so a workflow that needs args refuses the sender and leaves no run.
+ */
+function checkStartArgs(target: EventWorkflow, project: string): void {
+  try {
+    prepareArgs(target, [], project);
+  } catch (error) {
+    throw new EmitError(
+      `${target.meta.name}: a run an event starts has no arguments, which its prepare refuses: ${messageOf(error)}`,
+    );
+  }
+}
+
+/** A new run of a workflow with events, in `project`, recorded so `awf tick` finds it. */
+async function createEventRun(
+  runRoot: string,
+  workflow: string,
+  id: string,
+  project: string,
+  file: string | undefined,
+  context: Pick<WakeContext, "home" | "environment">,
+  argv: readonly string[] = [],
+): Promise<Run> {
+  const run = await createRun(runRoot, {
+    id,
+    workflow,
+    argv: [...argv],
+    cwd: project,
+    sandbox: null,
+    events: true,
+    env: { PATH: context.environment.PATH ?? "" },
+    ...(file ? { file } : {}),
+  });
+  await recordProject(context.home, project);
+  return run;
+}
+
+/** What `awf run --id` did to a run of a workflow with events: started it, or found it there. */
+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.
+ */
+export async function openEventRun(
+  target: EventWorkflow,
+  id: string,
+  argv: readonly string[],
+  context: Omit<WakeContext, "file">,
+): 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) => {
+    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 };
+    if (await exists(join(runRoot, workflow, id, "run.json"))) {
+      const run = await openRun(runRoot, workflow, id);
+      if ((await readAttempts(run)).at(-1)?.outcome === "completed")
+        return { run: ref, created: false, did: "none", why: "returned" };
+      if (argv.length > 0 && JSON.stringify(argv) !== JSON.stringify(run.record.argv))
+        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`,
+        );
+      return { run: ref, created: false, ...(await wake(run, woken)) };
+    }
+    try {
+      prepareArgs(target, argv, project);
+    } catch (error) {
+      throw new EmitError(`prepare: ${messageOf(error)}`);
+    }
+    const run = await createEventRun(runRoot, workflow, id, project, target.file, context, argv);
+    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. */
+export function checkEvent(
+  target: EventWorkflow,
+  event: { name: string; data: JsonValue; id?: string },
+): void {
+  const workflow = target.meta.name;
+  const problem = eventWorkflowProblem(target);
+  if (problem) throw new EmitError(`${workflow}: ${problem}`);
+  if (!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)
+    throw new EmitError(
+      `${workflow} declares no event ${event.name}; its events are ${Object.keys(target.events).join(", ")}`,
+    );
+  let parsed: ReturnType<typeof parseJsonSchema>;
+  try {
+    parsed = parseJsonSchema(schema);
+  } catch (error) {
+    throw new EmitError(`${workflow}'s schema for ${event.name}: ${String(error)}`);
+  }
+  const errors = validate(parsed, event.data);
+  if (errors.length > 0)
+    throw new EmitError(
+      `${event.name}'s data does not fit its schema: ${errors.map((e) => `${e.path || "/"}: ${e.message}`).join("; ")}`,
+    );
+  const badId = event.id === undefined ? undefined : eventIdProblem(event.id);
+  if (badId) throw new EmitError(`the id ${JSON.stringify(event.id)}: ${badId}`);
+}
+
+/** What is wrong with an id a sender gives an event, if anything: ids starting `awf.` are awf's. */
+export function eventIdProblem(id: string): string | undefined {
+  return (
+    nameProblem(id) ??
+    (id.startsWith(AWF_ID_PREFIX) ? `ids starting ${AWF_ID_PREFIX} are awf's own` : undefined)
+  );
+}

package/src/files.ts

@@ -1,6 +1,16 @@
 import { randomBytes } from "node:crypto";
+import { realpathSync } from "node:fs";
 import { link, lstat, open, rename, unlink } from "node:fs/promises";
-import { dirname, join } from "node:path";
+import { dirname, join, resolve } from "node:path";
+
+/** `path` with its symlinks resolved, or only made absolute when it doesn't exist. */
+export function realPath(path: string): string {
+  try {
+    return realpathSync(resolve(path));
+  } catch {
+    return resolve(path);
+  }
+}
 
 /**
  * Writes `value` to `path` whole: a temp file beside it, synced, then renamed into place. A crash

package/src/help/allowance.txt

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

package/src/help/emit.txt

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

package/src/help/inbox.txt

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

package/src/help/init.txt

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

package/src/help/logs.txt

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

package/src/help/reply.txt

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

package/src/help/run.txt

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

package/src/help/runs.txt

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

package/src/help/test.txt

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

package/src/help/tick.txt

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

package/src/here.ts

@@ -53,6 +53,12 @@ export async function startHere(
     stderr(`awf: ${ready.refused}`);
     return 2;
   }
+  if ("opens" in ready) {
+    stderr(
+      "awf: a workflow with events runs detached, in its project; awf run --id starts it, without --here",
+    );
+    return 2;
+  }
   for (const line of ready.prepared.continued?.warnings ?? []) notice(line);
   const env = environment.environment ?? process.env;
   const run = environment.herdr ?? runProcess;
@@ -99,7 +105,7 @@ export async function startHere(
       // Under codex this can be another pane's workspace (E8); the run's tab still works from it.
       workspace,
       cwd: command.shellCwd,
-      label: tabLabel(ready.loaded.executable.definition.meta.name, id),
+      label: tabLabel(ready.loaded.workflow.meta.name, id),
       argv: [
         ...self,
         "run",
@@ -125,7 +131,7 @@ export async function startHere(
       "Run the workflow from a shell with awf run instead.",
     );
   }
-  notice(startedLine(ready.loaded.executable.definition.meta.name, id, command));
+  notice(startedLine(ready.loaded.workflow.meta.name, id, command));
   stdout(
     [
       `awf: ${basename(ready.loaded.file)} is starting in Herdr tab ${started.tabId}. Once this turn ends it takes this session over: each of its steps arrives here as a prompt, and a last message hands the session back.`,
@@ -192,7 +198,7 @@ function passedSession(
 }
 
 /**
- * What lets a sandboxed session reach Herdr's socket, which `--here` and every `wf` call need: its
+ * What lets a sandboxed session reach Herdr's socket, which `--here` and every `wfa` call need: its
  * harness's own advice, for the harness whose session variable this shell has.
  */
 function sandboxFix(env: Readonly<Record<string, string | undefined>>): string {

package/src/hold-run-lock.fixture.ts

@@ -0,0 +1,8 @@
+// Holds a run's lock from another process for `emit.test.ts`: `bun hold-run-lock.fixture.ts {file} {ms}`.
+import { withRunLock } from "./run-lock";
+
+const [file, ms] = process.argv.slice(2);
+await withRunLock(file!, async () => {
+  console.log("held");
+  await Bun.sleep(Number(ms));
+});