@agentswf/engine 0.1.0-beta.5 → 0.1.0

package/src/run-lines.ts

@@ -0,0 +1,159 @@
+import { open, readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { type RunLine, type RunView, readRun } from "@agentswf/contract/records";
+import { messageOf } from "./errors";
+import { isCode, syncDir } from "./files";
+import { queued } from "./jsonl";
+import { unendedTurns } from "./run-policy/waits";
+import { RunUnreachable } from "./run-unreachable";
+import { crashedEnd } from "./turn-ends";
+
+/** `run.jsonl`, what the run settled; resolved, as it keys the append queue. */
+export function runLinesFile(runDir: string): string {
+  return resolve(runDir, "run.jsonl");
+}
+
+/** Appends one attempt's lines to `run.jsonl`, in call order, each whole and synced. */
+export type RunLines = {
+  readonly attempt: number;
+  append(line: RunLine): Promise<void>;
+};
+
+/** Attempt `attempt`'s writer: made only by its claim, so nothing appends before the fence. */
+function runLines(runDir: string, attempt: number): RunLines {
+  const path = runLinesFile(runDir);
+  return {
+    attempt,
+    append(line) {
+      if (line.attempt !== attempt) {
+        return Promise.reject(
+          new Error(`attempt ${attempt} cannot append a line of attempt ${line.attempt}`),
+        );
+      }
+      return queued(path, () => appendSynced(path, `${JSON.stringify(line)}\n`));
+    },
+  };
+}
+
+/**
+ * The claim on `run.jsonl`: cuts a line a crash left torn, so it never merges with the next, then
+ * appends `claimed`, the fence after which a line of an earlier attempt is ignored, then ends each
+ * turn an earlier attempt began and never ended, failed, before any wait can look. Called once the
+ * previous attempt's process is gone.
+ */
+export async function claimRunLines(
+  runDir: string,
+  attempt: number,
+  at: string,
+): Promise<RunLines> {
+  const path = runLinesFile(runDir);
+  await queued(path, () => cutTorn(path));
+  // `run.jsonl` may be new here: its entry in the folder is made durable with the claim.
+  await syncDir(runDir);
+  const lines = runLines(runDir, attempt);
+  await lines.append({ kind: "claimed", attempt, at });
+  for (const turn of unendedTurns((await readRunLines(runDir)).lines))
+    await lines.append(crashedEnd(turn, attempt, at));
+  return lines;
+}
+
+/**
+ * `run.jsonl`'s complete lines, checked, and their reading. Text after the last newline is a line
+ * still being written or one a crash tore, which the next claim cuts: it is not read.
+ */
+export async function readRunLines(runDir: string): Promise<{ lines: RunLine[]; view: RunView }> {
+  const path = runLinesFile(runDir);
+  const text = await readFile(path, "utf8").catch((error) => {
+    if (isCode(error, "ENOENT")) return "";
+    throw error;
+  });
+  const complete = text.slice(0, text.lastIndexOf("\n") + 1).split("\n");
+  complete.pop();
+  const parsed = complete.map((line, index) => {
+    try {
+      return JSON.parse(line) as unknown;
+    } catch {
+      throw new RunUnreachable(`run.jsonl line ${index + 1}: not JSON`);
+    }
+  });
+  let view: RunView;
+  try {
+    view = readRun(parsed);
+  } catch (error) {
+    // A line of no kind this awf knows: the run's record can't be read, as a line not JSON.
+    throw new RunUnreachable(messageOf(error));
+  }
+  return { lines: parsed as RunLine[], view };
+}
+
+/**
+ * One `O_APPEND` write, then fsync; Bun's fsync on macOS is not `F_FULLFSYNC` (story 041, Q5). A
+ * write that fails part way is cut, so the next line isn't glued to its half.
+ */
+async function appendSynced(path: string, text: string): Promise<void> {
+  const handle = await open(path, "a", 0o600);
+  try {
+    const { size } = await handle.stat();
+    const bytes = new TextEncoder().encode(text);
+    let written = 0;
+    try {
+      while (written < bytes.byteLength) {
+        const { bytesWritten } = await handle.write(bytes, written, bytes.byteLength - written);
+        if (bytesWritten === 0) throw new Error("append made no progress");
+        written += bytesWritten;
+      }
+    } catch (error) {
+      // Only when the file ends with this write's bytes: a stale writer never cuts another's line.
+      const now = await handle.stat().catch(() => undefined);
+      if (written > 0 && now?.size === size + written) {
+        await handle.truncate(size).catch(() => undefined);
+      }
+      throw error;
+    }
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+}
+
+/** Truncates `path` to its last newline, creating it when absent. */
+async function cutTorn(path: string): Promise<void> {
+  const handle = await open(path, "a+", 0o600);
+  try {
+    const { size } = await handle.stat();
+    const end = await afterLastNewline(handle, size);
+    if (end < size) {
+      await handle.truncate(end);
+      await handle.sync();
+    }
+  } finally {
+    await handle.close();
+  }
+}
+
+type Reader = {
+  read(
+    buffer: Uint8Array,
+    offset: number,
+    length: number,
+    position: number,
+  ): Promise<{
+    bytesRead: number;
+  }>;
+};
+
+/** The offset just past the last newline before `size`, read backwards; 0 when there is none. */
+async function afterLastNewline(handle: Reader, size: number): Promise<number> {
+  const chunk = new Uint8Array(64 * 1024);
+  let end = size;
+  while (end > 0) {
+    const start = Math.max(0, end - chunk.byteLength);
+    const length = end - start;
+    const { bytesRead } = await handle.read(chunk, 0, length, start);
+    if (bytesRead !== length) throw new Error("run.jsonl changed while it was claimed");
+    const newline = chunk.subarray(0, length).lastIndexOf(10);
+    if (newline !== -1) return start + newline + 1;
+    end = start;
+  }
+  return 0;
+}

package/src/run-lock.ts

@@ -5,7 +5,8 @@ import { probeProcess, processStart, sameStart } from "./runs";
 
 /**
  * `{root}/{workflow}/{run id}.lock`: the lock on a run, beside its run's folder so it exists before
- * the run does. Every append to the run's mailbox, and each decision made from it, holds it.
+ * the run does. Every sender's append to `in.jsonl` holds it, and so does a wait's last look before
+ * it parks.
  */
 export function runLockFile(runRoot: string, workflow: string, runId: string): string {
   return join(runRoot, workflow, `${runId}.lock`);
@@ -79,6 +80,61 @@ async function claim(file: string): Promise<Holder> {
   }
 }
 
+/**
+ * `{root}/{workflow}/{run id}.open`: held by `awf open --no-fork` for as long as the session it
+ * opened is open, so no attempt starts and no second one opens it (story 042). Claimed as the
+ * run's lock is, but never waited for.
+ */
+export function runOpenFile(runRoot: string, workflow: string, runId: string): string {
+  return join(runRoot, workflow, `${runId}.open`);
+}
+
+/** Who holds a claim: its process, by pid and start. */
+export type ClaimHolder = Holder;
+
+/**
+ * Claims `file` once, without waiting: this process's holding, or the live process that holds it.
+ * A holder whose process is gone is taken over.
+ */
+export async function claimNow(file: string): Promise<{ held: Holder } | { heldBy: Holder }> {
+  const started = ownStart();
+  if (started === undefined) throw new Error(`no start time for this process (${process.pid})`);
+  const mine: Holder = { pid: process.pid, processStart: started, at: new Date().toISOString() };
+  await mkdir(dirname(file), { recursive: true, mode: 0o700 });
+  for (let tries = 0; tries < 5; tries += 1) {
+    if (await linkNew(file, mine)) return { held: mine };
+    const holder = await readHolder(file);
+    if (holder === "gone") continue;
+    if (holder && !gone(holder)) return { heldBy: holder };
+    await takeOver(file, holder);
+  }
+  throw new Error(`${file} changed hands as it was claimed; try again`);
+}
+
+/** Lets go of `file`, if `held` still holds it. */
+export async function releaseClaim(file: string, held: Holder): Promise<void> {
+  if (JSON.stringify(await readHolder(file)) === JSON.stringify(held))
+    await unlink(file).catch(() => undefined);
+}
+
+/**
+ * The live process holding `file`, read without taking it; none for a holder that is gone. A
+ * holder `ps` can't be asked about counts as live, as in `gone`: what it holds back waits for a
+ * later look, never runs beside it.
+ */
+export async function liveHolder(file: string): Promise<Holder | undefined> {
+  const holder = await readHolder(file);
+  return holder !== "gone" && holder !== undefined && !gone(holder) ? holder : undefined;
+}
+
+/**
+ * Whether a live process holds the lock, read without taking it. A holder whose process is gone,
+ * a sender killed mid-launch, holds nothing; nor does a torn file, which `claim` takes over.
+ */
+export async function lockHeld(file: string): Promise<boolean> {
+  return (await liveHolder(file)) !== undefined;
+}
+
 /**
  * Whether a holder's process is gone. Where `ps` can't be asked, it is taken as alive: taking a
  * live holder's lock over would let two writers in.

package/src/run-policy/stage-plan.ts

@@ -0,0 +1,154 @@
+import type { StageLine, StageNeed } from "@agentswf/contract/records";
+import { type JsonSchema, type SchemaError, validate } from "@agentswf/contract/schema";
+import type { JsonValue } from "@agentswf/contract/workflow";
+
+/**
+ * What a continue does with a stage it enters: until its start point, each is reused from its
+ * line, provided, or stops the attempt; from the start point on, every stage runs. The start
+ * point is `--from-stage`, or else the first stage entered with no succeeded line. Before a
+ * `--from-stage`, a stage whose line can't be reused takes its value from `--values`, one that
+ * returns nothing is passed, and one with nothing recorded needs a value. Pure: the line the run's
+ * reuse gives, the values, the result and the version come in, a decision goes out.
+ */
+type StagePlanDecision =
+  | { kind: "reuse"; line: StageLine; value: JsonValue | undefined }
+  /** A value given, checked by the stage's result; undefined for a stage that returns nothing. */
+  | { kind: "provide"; value: JsonValue | undefined }
+  /** `start` on the stage that is the start point. */
+  | { kind: "run"; start: boolean }
+  | { kind: "stop"; reason: string }
+  /** Nothing recorded, and no value given that fits: `--values` lets the attempt go on. */
+  | { kind: "need"; reason: string; need: StageNeed };
+
+export type StagePlanState = {
+  /** The stage's line as `StageReuse` gives it: its latest, unless a redo outdated it. */
+  line?: StageLine;
+  /** The `meta.version` of the attempt that wrote `line`. */
+  lineVersion?: string;
+  /** The stages the run has a line for. */
+  recorded: readonly string[];
+  fromStage?: string;
+  /** `--values`: each stage's value, to start at `fromStage`. */
+  values?: ReadonlyMap<string, JsonValue>;
+  /** The workflow's `meta.version` now. */
+  workflowVersion?: string;
+  /** Whether this attempt has reached its start point. */
+  started: boolean;
+  /** The stages this attempt has entered so far. */
+  entered: readonly string[];
+};
+
+/**
+ * Decides a stage entered, given its `result` as JSON Schema, absent for a stage that returns
+ * nothing. A stop's reason says why; the command that goes on names the stage to redo.
+ */
+export function planStage(
+  state: StagePlanState,
+  stage: string,
+  result: JsonSchema | undefined,
+): StagePlanDecision {
+  if (state.started) return { kind: "run", start: false };
+  if (stage === state.fromStage) return { kind: "run", start: true };
+  const { line } = state;
+  const succeeded = line?.outcome === "succeeded" ? line : undefined;
+  const stale = succeeded && unreusable(state, succeeded, result);
+  if (succeeded && stale === undefined) {
+    return { kind: "reuse", line: succeeded, value: succeeded.value };
+  }
+  if (state.fromStage === undefined) {
+    return stale === undefined ? { kind: "run", start: true } : { kind: "stop", reason: stale };
+  }
+  // A line there that failed or went stale is redone from its stage, as on any continue, unless a
+  // value given replaces it.
+  const redo = line && {
+    kind: "stop" as const,
+    reason: stale ?? `${stage} did not succeed in attempt ${line.attempt}`,
+  };
+  if (result === undefined) return redo ?? { kind: "provide", value: undefined };
+  const need = { stage, schema: result };
+  const given = state.values?.get(stage);
+  if (given !== undefined) {
+    const errors = validate(result, given);
+    if (errors.length === 0) return { kind: "provide", value: given };
+    const misfit = problems(`${stage}'s value in --values does not fit its result:`, errors);
+    return redo ? { kind: "stop", reason: misfit } : { kind: "need", reason: misfit, need };
+  }
+  return (
+    redo ?? {
+      kind: "need",
+      reason: `nothing recorded for ${stage}${unreached(state, stage)}`,
+      need,
+    }
+  );
+}
+
+/**
+ * Why a succeeded line can't be reused, as a stop says it, or undefined when it can: another major
+ * version wrote it, or its value no longer fits the stage's `result`.
+ */
+function unreusable(
+  state: StagePlanState,
+  line: StageLine,
+  result: JsonSchema | undefined,
+): string | undefined {
+  const recorded = majorOf(state.lineVersion);
+  const now = majorOf(state.workflowVersion);
+  if (recorded !== undefined && now !== undefined && recorded !== now) {
+    return `${line.name} was recorded by ${state.lineVersion}; this is ${state.workflowVersion}`;
+  }
+  return misfitOf(line, result);
+}
+
+/** Why a succeeded line's value no longer fits the stage's `result`; undefined when it does. */
+function misfitOf(line: StageLine, result: JsonSchema | undefined): string | undefined {
+  const stage = line.name;
+  if (result === undefined) {
+    return line.value === undefined
+      ? undefined
+      : `${stage}'s line holds a value, and the stage no longer has a result`;
+  }
+  if (line.value === undefined) {
+    return `${stage}'s line holds no value, and the stage's result now expects one`;
+  }
+  const errors = validate(result, line.value);
+  return errors.length === 0
+    ? undefined
+    : problems(`${stage}'s line no longer fits its result schema:`, errors);
+}
+
+/** A value's problems under what they are problems of, a line each. */
+function problems(heading: string, errors: readonly SchemaError[]): string {
+  return [heading, ...errors.map((error) => `  ${error.path}: ${error.message}`)].join("\n");
+}
+
+/** Recorded stages this attempt hasn't reached, which a rename in the code would leave behind. */
+function unreached(state: StagePlanState, stage: string): string {
+  const others = state.recorded.filter(
+    (name) => name !== stage && name !== state.fromStage && !state.entered.includes(name),
+  );
+  return others.length > 0 ? ` (recorded and not reached: ${others.join(", ")})` : "";
+}
+
+/** What must match for a line to be reused: the major, or `0.{minor}`, as semver has it. */
+function majorOf(version: string | undefined): string | undefined {
+  if (version === undefined) return 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 line is reused wherever
+ * and however often its name is entered, whatever version of the code wrote it, as long as its
+ * value still fits the stage's `result`. One that doesn't fit stops the attempt; a failed line, or
+ * none, runs.
+ */
+export function planStageByContent(
+  line: StageLine | undefined,
+  result: JsonSchema | undefined,
+): Extract<StagePlanDecision, { kind: "reuse" | "stop" }> | { kind: "run" } {
+  if (line?.outcome !== "succeeded") return { kind: "run" };
+  const misfit = misfitOf(line, result);
+  return misfit === undefined
+    ? { kind: "reuse", line, value: line.value }
+    : { kind: "stop", reason: misfit };
+}

package/src/run-policy/stages.ts

@@ -0,0 +1,113 @@
+import type { ClaimedAttempt, RunView, StageLine } from "@agentswf/contract/records";
+
+/**
+ * The stage attempt `attempt` started at, which its line says with `redo`: the one `--from-stage`
+ * named, or a plain run's first stage not reused. In that attempt and every later one, a stage
+ * entered after `stage` whose line an earlier attempt than `attempt` wrote runs again: it was made
+ * against the stage before. One never entered after the stage keeps its reuse.
+ */
+export type StageRedo = { stage: string; attempt: number };
+
+/**
+ * What an attempt may reuse of the run's stages, as it enters them: the engine's rule over
+ * `readRun`'s view. A stage stands for its latest line, unless the redo outdated it; the plan
+ * decides from that line whether it is reused, which it is only when that line succeeded: a
+ * continue reuses `settled` only when it is also `last`. One per attempt, told of each line it
+ * writes.
+ */
+export class StageReuse {
+  /** Each stage's latest line, this attempt's included. */
+  readonly #last: Map<string, StageLine>;
+  #redo: StageRedo | undefined;
+  /** Whether this attempt has entered the redo's stage, after which an older line is outdated. */
+  #afterRedo = false;
+  readonly #entered = new Set<string>();
+
+  constructor(
+    view: Pick<RunView, "stages" | "redo">,
+    private readonly attempt: number,
+  ) {
+    this.#last = new Map(Object.entries(view.stages).map(([name, { last }]) => [name, last]));
+    this.#redo = view.redo;
+  }
+
+  /**
+   * Enters `name`: the line it stands for now, of any outcome, or undefined when it has none or the
+   * redo outdated it. A stage entered already in this attempt keeps the line it had: one stage, one
+   * value.
+   */
+  enter(name: string): StageLine | undefined {
+    const line = this.#last.get(name);
+    const redo = this.#redo;
+    const outdated =
+      redo !== undefined &&
+      this.#afterRedo &&
+      line !== undefined &&
+      line.attempt < redo.attempt &&
+      !this.#entered.has(name);
+    this.#entered.add(name);
+    if (name === redo?.stage) this.#afterRedo = true;
+    return outdated ? undefined : line;
+  }
+
+  /** This attempt starts at `name`, entered now: a later stage with an older line runs again. */
+  redoFrom(name: string): void {
+    this.#redo = { stage: name, attempt: this.attempt };
+    this.#afterRedo = true;
+  }
+
+  /** A line this attempt wrote, which the stages it enters from now on see. */
+  wrote(line: StageLine): void {
+    this.#last.set(line.name, line);
+  }
+}
+
+/**
+ * Each stage's latest line, in the order they started, attempt then file order breaking a tie:
+ * what `--from-stage` chooses from, and what a stage not reached names.
+ */
+export function recordedStages(view: Pick<RunView, "stages">): StageLine[] {
+  return Object.values(view.stages)
+    .map(({ last }) => last)
+    .sort((a, b) => a.started.localeCompare(b.started) || a.attempt - b.attempt);
+}
+
+/**
+ * The stages a continue may still come to, in the order they started: each recorded stage but
+ * those the last redo left behind, such as a stage the code no longer has. The redo's attempt ran
+ * every stage it entered after its start point again, so a stage whose latest line is older than
+ * that attempt, and which started after the redo's stage in the attempt that wrote it, was never
+ * entered there. Where that attempt reused the redo's stage, and so wrote it no line, the redo
+ * stage's latest line from before it stands in: what that attempt ran came after the stage it
+ * reused. A stage before the redo's stage was reused, and is kept; so is one whose order can't be
+ * told, and a removed stage that came before it. A stage first run before the redo's stage, in an
+ * attempt that reused the redo's stage, is taken for one after it, and left out.
+ */
+export function upcomingStages(view: Pick<RunView, "stages" | "redo">): StageLine[] {
+  const { redo } = view;
+  return recordedStages(view).filter((line) => {
+    if (redo === undefined || line.attempt >= redo.attempt) return true;
+    const history = view.stages[redo.stage]?.history ?? [];
+    const start =
+      history.find((earlier) => earlier.attempt === line.attempt) ??
+      history.findLast((earlier) => earlier.attempt < line.attempt);
+    return start === undefined || Date.parse(line.started) <= Date.parse(start.started);
+  });
+}
+
+/**
+ * The `--from-stage` a continue goes on with when the attempt before it was one that crashed inside
+ * its start stage: it has no ending, named a `--from-stage`, and wrote no line for that stage. That
+ * redo isn't in the lines, so without it the old lines would stand. Undefined otherwise. The caller
+ * has already found the attempt's process gone.
+ */
+export function crashedRedo(
+  attempts: readonly Pick<ClaimedAttempt, "attempt" | "ended" | "flags">[],
+  view: Pick<RunView, "stages">,
+): string | undefined {
+  const last = attempts.at(-1);
+  const stage = last?.flags.fromStage;
+  if (!last || last.ended !== undefined || stage === undefined) return undefined;
+  const wrote = view.stages[stage]?.history.some((line) => line.attempt === last.attempt);
+  return wrote ? undefined : stage;
+}