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

package/src/stage-ledger.ts

@@ -8,7 +8,7 @@ import type { JsonSchema } from "@agentswf/contract/schema";
 import type { JsonValue, StageOutcome, StageSummary } from "@agentswf/contract/workflow";
 import type { RunEventBody } from "./run-event-log";
 import { replaceRecord, replaceStale, stageNameProblem, writeStageRecord } from "./runs";
-import { planStage } from "./stage-plan";
+import { planStage, planStageByContent } from "./stage-plan";
 import { placeholderOf } from "./stage-schema";
 import { primaryFailure, WorkflowStopped } from "./stopped";
 
@@ -86,6 +86,8 @@ export class StageLedger {
    */
   readonly #looked = new Set<string>();
   #needed: WorkflowStopped | undefined;
+  /** The run's stage records as they stand, this attempt's included: what a stage by content reuses. */
+  readonly #records: Map<string, StageRecord>;
 
   constructor(
     private readonly options: {
@@ -100,11 +102,23 @@ export class StageLedger {
       fromStage?: string;
       /** `--values`: the values of stages before `fromStage` that have no record to reuse. */
       values?: ReadonlyMap<string, JsonValue>;
+      /**
+       * A run of a workflow with `events`: a stage runs once ever, reused wherever it is entered,
+       * as `planStageByContent` says; no start point, and no `fromStage` or `values`.
+       */
+      byContent?: boolean;
       /** Writes the run's event log. */
       event?(body: RunEventBody, at?: number): void;
       now?: () => Date;
     },
-  ) {}
+  ) {
+    this.#records = new Map(options.records);
+  }
+
+  /** The stage open now, if one is. */
+  get openStage(): string | undefined {
+    return this.#open?.name;
+  }
 
   /** A `--from-stage` the attempt never reached: a typo, or a branch not taken. */
   get fromStageUnreached(): string | undefined {
@@ -144,9 +158,10 @@ export class StageLedger {
    * entered yet, in the order they first started.
    */
   progress(): { stages: StageProgress[]; upcoming: string[] } {
-    const upcoming = this.recorded
-      .map((record) => record.stage)
-      .filter((stage) => !this.#stages.has(stage));
+    // By content, an earlier event's stage may never be entered again: none is upcoming.
+    const upcoming = this.options.byContent
+      ? []
+      : this.recorded.map((record) => record.stage).filter((stage) => !this.#stages.has(stage));
     const recorded = (stage: string) => this.options.records?.get(stage)?.ended;
     return {
       stages: [...this.#stages.values()].map((entered) => {
@@ -196,6 +211,7 @@ export class StageLedger {
     if (caught) throw caught;
     this.#check(name);
     const at = this.#now().getTime();
+    if (this.options.byContent) return this.#enterByContent(name, entry, at);
     const decision = planStage(
       {
         records: this.options.records ?? new Map(),
@@ -295,6 +311,42 @@ export class StageLedger {
     return { kind: "run", stage };
   }
 
+  /**
+   * Enters a stage by content: reused from its succeeded record, this attempt's included, run when
+   * it has none or a failed one, which its own record then replaces.
+   */
+  async #enterByContent(name: string, entry: StageEntry, at: number): Promise<EnteredStage> {
+    const decision = planStageByContent(this.#records.get(name), entry.result);
+    if (decision.kind === "stop") {
+      this.#stopped = new WorkflowStopped(decision.reason, name, true);
+      this.#stoppedAt(name, at);
+      throw this.#stopped;
+    }
+    if (decision.kind === "reuse") {
+      const held = this.#hold(name, decision.value);
+      this.#reused.add(name);
+      // Entered again in the attempt that ran or reused it: nothing more to show or log.
+      if (this.#stages.get(name)?.outcome === "succeeded") return held;
+      const { attempt, summary } = decision.record;
+      this.options.event?.(
+        { kind: "stage-ended", stage: name, outcome: "succeeded", source: "reused" },
+        at,
+      );
+      this.#stages.set(name, {
+        stage: name,
+        source: "reused",
+        outcome: "succeeded",
+        attempt,
+        startedAt: at,
+        endedAt: at,
+        ...(summary === undefined ? {} : { summary }),
+        ...(decision.value === undefined ? {} : { value: decision.value }),
+      });
+      return held;
+    }
+    return { kind: "run", stage: this.#opened(name, at) };
+  }
+
   /** A stage the plan stopped as it was entered: shown stopped, though it ran nothing. */
   #stoppedAt(name: string, at: number): void {
     this.options.event?.({ kind: "stage-ended", stage: name, outcome: "stopped" }, at);
@@ -411,7 +463,7 @@ export class StageLedger {
         `stage ${name} was entered while stage ${this.#open.name} is open; one stage runs at a time, and parallel work goes inside one`,
       );
     }
-    if (this.#stages.has(name) || this.#looked.has(name)) {
+    if (!this.options.byContent && (this.#stages.has(name) || this.#looked.has(name))) {
       throw new Error(`stage ${name} was entered twice; a loop goes inside one stage`);
     }
   }
@@ -452,13 +504,26 @@ export class StageLedger {
         ...(record.summary === undefined ? {} : { summary: record.summary }),
         ...(record.value === undefined ? {} : { value: record.value }),
       });
-      ended = writeStageRecord(this.options.runDir, record).then(
-        () => undefined,
-        (error: unknown) => {
-          entered.outcome = "failed";
-          throw error;
-        },
-      );
+      // By content, a failed record this one replaces is kept, as a redone stage's is.
+      const replacing = this.options.byContent && this.#records.has(name);
+      ended = (
+        replacing
+          ? replaceRecord(this.options.runDir, name).then(() => {
+              // Moved: a write that fails now leaves nothing in `stages/` to move again.
+              this.#records.delete(name);
+            })
+          : Promise.resolve()
+      )
+        .then(() => writeStageRecord(this.options.runDir, record))
+        .then(
+          () => {
+            this.#records.set(name, record);
+          },
+          (error: unknown) => {
+            entered.outcome = "failed";
+            throw error;
+          },
+        );
       // Its outcome once the record is written: one that is not fails the stage.
       const logEnd = () =>
         this.options.event?.(
@@ -484,6 +549,16 @@ export class StageLedger {
     return stage;
   }
 
+  /**
+   * Leaves the open stage `name` unended and unrecorded, as the run parked at a wait in it: the
+   * next attempt runs it again.
+   */
+  abandon(name: string): void {
+    if (this.#open?.name !== name) return;
+    this.#open = undefined;
+    this.#stages.delete(name);
+  }
+
   /** Once the workflow's body has ended, why: no stage is entered after it. */
   seal(reason: string): void {
     if (this.#sealed !== undefined) return;

package/src/stage-plan.ts

@@ -92,6 +92,12 @@ function unreusable(
   if (recorded !== undefined && now !== undefined && recorded !== now) {
     return `${stage} was recorded by ${record.workflowVersion}; this is ${state.workflowVersion}`;
   }
+  return misfitOf(record, result);
+}
+
+/** Why a succeeded record's value no longer fits the stage's `result`; undefined when it does. */
+function misfitOf(record: StageRecord, result: JsonSchema | undefined): string | undefined {
+  const { stage } = record;
   if (result === undefined) {
     return record.value === undefined
       ? undefined
@@ -125,3 +131,20 @@ function majorOf(version: string | undefined): string | undefined {
   const [major, minor] = version.split(".");
   return major === "0" ? `0.${minor}` : major;
 }
+
+/**
+ * In a run of a workflow with `events`, a stage runs once ever: a succeeded record is reused
+ * wherever and however often its name is entered, whatever version of the code recorded it, as
+ * long as its value still fits the stage's `result`. One that doesn't fit stops the attempt; a
+ * failed record, or none, runs.
+ */
+export function planStageByContent(
+  record: StageRecord | undefined,
+  result: JsonSchema | undefined,
+): Extract<StagePlanDecision, { kind: "reuse" | "stop" }> | { kind: "run" } {
+  if (record?.outcome !== "succeeded") return { kind: "run" };
+  const misfit = misfitOf(record, result);
+  return misfit === undefined
+    ? { kind: "reuse", record, value: record.value }
+    : { kind: "stop", reason: misfit };
+}

package/src/stop-crashed.ts

@@ -0,0 +1,39 @@
+import type { AttemptRecord } from "@agentswf/contract/records";
+import { runProcess } from "@agentswf/harness";
+import { ensureRunSession, runSessionName } from "./herdr-run-session";
+import { readMarks } from "./herdr-workspace-marks";
+import { probeProcess } from "./runs";
+
+/**
+ * Stops what a crashed attempt left working before a continue writes its turns' failed ends (Q17):
+ * what is left of its process group, which a detached `awf run` leads, and its panes, by sweeping
+ * its Herdr session, which closes the workspaces of runs whose process is gone. A run whose attempt
+ * opened no pane starts no Herdr. A harness's own process runs in a session of its own, so one the
+ * attempt orphaned isn't reached here; it is not stopped yet.
+ */
+export async function stopCrashed(
+  previous: AttemptRecord,
+  label: string,
+  context: { home: string; environment: Readonly<Record<string, string | undefined>> },
+): Promise<void> {
+  // Only once its leader is gone for good: a live group's id is never handed out again, so a group
+  // still there is the attempt's leftovers, never another process that took its pid since. One an
+  // `awf run` typed in a terminal led is its pipeline's, which goes with it.
+  if (probeProcess(previous.pid) === "gone") {
+    try {
+      process.kill(-previous.pid, "SIGTERM");
+      await Bun.sleep(500);
+      process.kill(-previous.pid, "SIGKILL");
+    } catch {
+      // No such group, or it ended at the first signal.
+    }
+  }
+  const name = runSessionName(context.environment);
+  const marks = await readMarks(context.home, name);
+  if (!marks.some((mark) => mark.label === label)) return;
+  await ensureRunSession(name, {
+    run: runProcess,
+    environment: context.environment,
+    home: context.home,
+  });
+}

package/src/test-command.ts

@@ -3,6 +3,8 @@ import { constants } from "node:os";
 import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { parseDuration } from "./duration";
+import { messageOf } from "./errors";
+import type { Out } from "./run-commands";
 
 const PRELOAD = fileURLToPath(new URL("./workflow-test-preload.ts", import.meta.url));
 
@@ -20,6 +22,32 @@ export const testUsage = [
 
 export type TestCommand = { paths: string[]; bunArgs: string[] };
 
+/**
+ * `awf test`: the workflow tests under the given paths, with Bun's test runner. Their output goes
+ * to `io.output` when given, else straight to this process's.
+ */
+export async function testCommand(
+  argv: readonly string[],
+  cwd: string,
+  io: Out & { output?: Out; signal?: AbortSignal },
+): Promise<number> {
+  let tests: TestCommand | "help";
+  try {
+    tests = parseTestCommand(argv, cwd);
+  } catch (error) {
+    io.stderr(`awf: ${messageOf(error)}\n\n${testUsage}`);
+    return 2;
+  }
+  if (tests === "help") {
+    io.stdout(testUsage);
+    return 0;
+  }
+  return runWorkflowTests(tests, cwd, {
+    ...(io.signal ? { signal: io.signal } : {}),
+    ...(io.output ? { output: io.output } : {}),
+  });
+}
+
 /**
  * Only these flags pass through, so the published command is awf's, not the whole of `bun test`'s,
  * and a later runner can take its place. A path must exist; Bun would take it as a filter.
@@ -91,6 +119,9 @@ export async function runWorkflowTests(
     );
   if (signal?.aborted) stop();
   signal?.addEventListener("abort", stop, { once: true });
+  // awf exiting at a second signal does not wait for the tests, which would outlive it.
+  const orphaned = () => child.kill("SIGKILL");
+  process.on("exit", orphaned);
   try {
     if (output) {
       const [out, err] = await Promise.all([
@@ -106,5 +137,6 @@ export async function runWorkflowTests(
     return ended ? 128 + constants.signals[ended] : code;
   } finally {
     signal?.removeEventListener("abort", stop);
+    process.off("exit", orphaned);
   }
 }

package/src/testing.ts

@@ -1,15 +1,24 @@
-import { existsSync, mkdtempSync, rmSync } from "node:fs";
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { createConnection } from "node:net";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import type { AttemptRecord } from "@agentswf/contract/records";
 import { type ResultSubmitResponse, WIRE_VERSION } from "@agentswf/contract/wire";
-import type { JsonValue, WorkflowContext, WorkflowDefinition } from "@agentswf/contract/workflow";
+import {
+  defineWorkflow,
+  type EventWorkflowContext,
+  type JsonValue,
+  type OutputSchema,
+  type WorkflowContext,
+  type WorkflowDefinition,
+} from "@agentswf/contract/workflow";
 import { createSingleSessionHostFactory } from "@agentswf/harness";
 import type { AgentSessionAdapter } from "@agentswf/harness/adapter";
 import { createFakeAdapter } from "@agentswf/harness/testing";
 import Type from "typebox";
+import { writeJson } from "./files";
 import { OPERATOR_ALIASES } from "./operator-aliases";
-import { createRun, openRun } from "./runs";
+import { createRun, openRun, type Run, readAttempts } from "./runs";
 import { type RunWorkflowOptions, runWorkflow, startWorkflow } from "./workflow-runner";
 
 export function createTempRunDirs(): {
@@ -30,6 +39,65 @@ export function createTempRunDirs(): {
   };
 }
 
+/** A project, `.awf/` at its root, with `source` at `flows/{name}`, and a home of its own. */
+export function eventProject(
+  dirs: ReturnType<typeof createTempRunDirs>,
+  name: string,
+  source: string,
+): { root: string; file: string; home: string } {
+  const root = dirs.tempRunDir();
+  mkdirSync(join(root, ".awf"));
+  mkdirSync(join(root, "flows"));
+  const file = join(root, "flows", name);
+  writeFileSync(file, source);
+  return { root, file, home: dirs.tempRunDir() };
+}
+
+/** Polls `check` until it holds; throws after `ms`. */
+export async function until(check: () => Promise<boolean>, ms = 20_000): Promise<void> {
+  const end = Date.now() + ms;
+  while (!(await check())) {
+    if (Date.now() > end) throw new Error("timed out");
+    await Bun.sleep(50);
+  }
+}
+
+/** Writes the run's next attempt record, as `awf run` claims one, with `fields` over defaults. */
+export async function writeAttempt(run: Run, fields: Partial<AttemptRecord>): Promise<void> {
+  const n = (await readAttempts(run)).length + 1;
+  mkdirSync(join(run.dir, "attempts"), { recursive: true });
+  await writeJson(join(run.dir, "attempts", `${n}.json`), {
+    version: 1,
+    attempt: n,
+    file: "/flows/case.ts",
+    flags: {},
+    started: new Date().toISOString(),
+    ...fields,
+  });
+}
+
+const Changes: OutputSchema<{ case: string }> = {
+  type: "object",
+  properties: { case: { type: "string" } },
+  required: ["case"],
+};
+const caseEvents = { "dd.changes": Changes };
+
+/** A workflow with one event, `dd.changes`, keyed by its case, whose body is `run`. */
+export const caseRun = (
+  run: (workflow: EventWorkflowContext<typeof caseEvents>) => Promise<JsonValue>,
+) =>
+  defineWorkflow({
+    meta: { name: "dd-case", description: "A case." },
+    file: import.meta.path,
+    events: caseEvents,
+    starts: ["dd.changes"],
+    run,
+  });
+
+/** The options that start a `caseRun` under the key `k`. */
+export const startCase = { id: "k", event: { name: "dd.changes" as const, data: { case: "k" } } };
+
 export { COUNT_SCHEMA } from "@agentswf/contract/testing";
 
 export function future(milliseconds = 60_000): { unixMilliseconds: number } {

package/src/tick-command.ts

@@ -0,0 +1,87 @@
+import type { TickResultJson } from "@agentswf/contract/records";
+import { messageOf } from "./errors";
+import { exists } from "./files";
+import { listProjects, projectRunRoot } from "./projects";
+import type { Out } from "./run-commands";
+import { parsePlace } from "./run-commands";
+import { runLockFile, withRunLock } from "./run-lock";
+import { listRuns } from "./run-state";
+import { type Launch, wake } from "./wake";
+
+export const tickUsage = [
+  "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, or 1 when a project is gone or a run could not be woken; the others are still woken.",
+].join("\n");
+
+export async function tickCommand(
+  argv: readonly string[],
+  shellCwd: string,
+  out: Out,
+  context: {
+    home: string;
+    environment: Readonly<Record<string, string | undefined>>;
+    launch?: Launch;
+    now?: () => number;
+  },
+): Promise<number> {
+  if (argv.includes("-h") || argv.includes("--help")) {
+    out.stdout(tickUsage);
+    return 0;
+  }
+  let parsed: ReturnType<typeof parsePlace>;
+  try {
+    parsed = parsePlace(argv, shellCwd);
+    const unknown = parsed.rest.find((word) => word !== "--all");
+    if (unknown !== undefined) throw new Error(`tick takes no ${unknown}`);
+    if (parsed.rest.includes("--all") && parsed.place.repeat.length > 0)
+      throw new Error("--all wakes every project's runs; it takes no --cwd or --run-root");
+  } catch (error) {
+    out.stderr(`awf: ${messageOf(error)}\n\n${tickUsage}`);
+    return 2;
+  }
+  const { place, json } = parsed;
+  const woke: TickResultJson["woke"] = [];
+  let failed = false;
+  const roots: string[] = [];
+  if (!parsed.rest.includes("--all")) roots.push(place.runRoot);
+  else
+    for (const project of await listProjects(context.home)) {
+      if (await exists(project)) roots.push(projectRunRoot(project));
+      else {
+        failed = true;
+        out.stderr(`awf: ${project}, in ~/.awf/projects, is gone; its runs are not woken`);
+      }
+    }
+  for (const root of roots) {
+    for (const run of await listRuns(root)) {
+      if (!run.record.events) continue;
+      const ref = `${run.record.workflow}/${run.record.id}`;
+      try {
+        const { workflow, id } = run.record;
+        const why = await withRunLock(runLockFile(root, workflow, id), async () => {
+          const woken = await wake(run, { ...context, nudgeLive: false });
+          if (woken.why === "launch-failed") throw new Error(woken.error ?? "launch failed");
+          if ((woken.did !== "started" && woken.did !== "continued") || !woken.cause)
+            return undefined;
+          return { did: woken.did, why: woken.cause };
+        });
+        if (why) woke.push({ ref, ...why });
+      } catch (error) {
+        failed = true;
+        out.stderr(`awf: ${ref}: ${messageOf(error)}`);
+      }
+    }
+  }
+  if (json) out.stdout(JSON.stringify({ v: 1, woke } satisfies TickResultJson));
+  else for (const each of woke) out.stdout(`${each.did} ${each.ref}: ${each.why}`);
+  return failed ? 1 : 0;
+}