@agentswf/engine 0.1.0-beta.5 → 0.1.0

package/src/ops.ts

@@ -0,0 +1,270 @@
+import { mkdirSync } from "node:fs";
+import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import {
+  type Candidate,
+  isKnownOpFile,
+  OP_FILE_VERSIONS,
+  type OpFile,
+  type OpRecord,
+  type ResultRecord,
+} from "@agentswf/contract/records";
+import { nameProblem } from "@agentswf/contract/workflow";
+import { messageOf } from "./errors";
+import { isCode, linkNew, writeWholeSync } from "./files";
+import { appendLine, readLines } from "./jsonl";
+
+/**
+ * A run's `ops/`: one folder per operation, `ops/{key}.{n}/`, the `n`th turn, message operation or
+ * compaction of the agent keyed `{key}`, or the `n`th asking of the decision keyed `{key}`. It holds
+ * `op.json`, `answers.jsonl`, `result.json`, `decision.json`, `spend.json`, `live.jsonl` and
+ * `screen.txt`. The only module that knows where they are.
+ */
+
+/** An operation's folder. */
+function opDir(runDir: string, op: string): string {
+  return join(runDir, "ops", op);
+}
+
+/** What the operation is: `OpRecord`. */
+export function opFile(runDir: string, op: string): string {
+  return join(opDir(runDir, op), "op.json");
+}
+
+/** Its settled usage: billing, spend per model, reported cost. */
+export function spendFile(runDir: string, op: string): string {
+  return join(opDir(runDir, op), "spend.json");
+}
+
+/** Its delivery and nudge diagnostics, `OperationLivenessRecord` lines. */
+export function liveFile(runDir: string, op: string): string {
+  return join(opDir(runDir, op), "live.jsonl");
+}
+
+/** A decision's `DecisionArtifact`, relative to the run's folder, as `DecisionRecord.artifact` names it. */
+export function decisionArtifact(op: string): string {
+  return join("ops", op, "decision.json");
+}
+
+/**
+ * The keys earlier attempts numbered operations under: each one's last `n`, and whose it is when its
+ * `op.json` says.
+ */
+export type EarlierOps = ReadonlyMap<string, { last: number; of?: "agent" | "decision" }>;
+
+/**
+ * Lists `ops/` once, as an attempt claims its run: `n` is the digits after a folder's last `.`.
+ * Whose a key is is read from its highest-numbered `op.json` that can be read.
+ */
+export async function listOps(runDir: string): Promise<EarlierOps> {
+  let names: string[];
+  try {
+    names = await readdir(join(runDir, "ops"));
+  } catch (error) {
+    if (isCode(error, "ENOENT")) return new Map();
+    throw error;
+  }
+  const numbers = new Map<string, number[]>();
+  for (const name of names) {
+    const match = /^(.+)\.(\d+)$/.exec(name);
+    if (!match) continue;
+    const list = numbers.get(match[1]!) ?? [];
+    list.push(Number(match[2]));
+    numbers.set(match[1]!, list);
+  }
+  const earlier = new Map<string, { last: number; of?: "agent" | "decision" }>();
+  await Promise.all(
+    [...numbers].map(async ([key, list]) => {
+      const descending = list.sort((a, b) => b - a);
+      let kind: OpRecord["kind"] | undefined;
+      for (const n of descending) {
+        kind = (await readOpFile<OpRecord>(opFile(runDir, `${key}.${n}`), "op"))?.kind;
+        if (kind !== undefined) break;
+      }
+      earlier.set(key, {
+        last: descending[0]!,
+        ...(kind === undefined ? {} : { of: kind === "decision" ? "decision" : "agent" }),
+      });
+    }),
+  );
+  return earlier;
+}
+
+/**
+ * Why `key` can't be an agent's or a decision's: it names folders, so it is a name, as an event's
+ * or stage's is, and has no colon, which awf's own event names, `{key}:ended`, split at.
+ */
+function keyProblem(key: string): string | undefined {
+  if (key.includes(":"))
+    return `a colon is kept for awf's own event names, such as {key}:ended; take another key, such as ${key.replaceAll(":", "-")}`;
+  return nameProblem(key);
+}
+
+/**
+ * An attempt's operation ids, `{key}.{n}`, numbered on from the last `n` its claim listed, so no
+ * id is reused across attempts. Agents and decisions share the keys: `{key}.{n}` is one operation.
+ */
+export class OpIds {
+  readonly #last = new Map<string, number>();
+  readonly #agents = new Set<string>();
+  readonly #decisions = new Set<string>();
+
+  constructor(
+    readonly runDir: string,
+    readonly attempt: number,
+    earlier: EarlierOps,
+  ) {
+    for (const [key, { last, of }] of earlier) {
+      this.#last.set(key, last);
+      if (of) (of === "decision" ? this.#decisions : this.#agents).add(key);
+    }
+  }
+
+  /** Refuses a key that isn't a name, or that the other kind already holds in the run. */
+  claim(key: string, as: "agent" | "decision"): void {
+    const problem = keyProblem(key);
+    if (problem) throw new Error(`${as} key ${key} is not a name: ${problem}`);
+    const [mine, other] =
+      as === "agent" ? [this.#agents, this.#decisions] : [this.#decisions, this.#agents];
+    if (other.has(key))
+      throw new Error(
+        `${key} is ${as === "agent" ? "a decision's" : "an agent's"} key: agents and decisions share one set of names, as each operation's folder is ops/{key}.{n}; ${as === "agent" ? "an agent" : "a decision"} takes another key`,
+      );
+    mine.add(key);
+  }
+
+  /**
+   * The key's next operation id, its folder and `op.json` written at once, before any line names it,
+   * so a later claim numbers past it however the operation ends. Synchronous, so nothing waits
+   * between an operation's start and its cancellation being registered. `lost` says why `op.json`
+   * wasn't written, which fails the operation.
+   */
+  draw(key: string, what: OpStart): { id: string; lost?: string } {
+    const n = (this.#last.get(key) ?? 0) + 1;
+    this.#last.set(key, n);
+    const id = `${key}.${n}`;
+    const record = {
+      version: OP_FILE_VERSIONS.op,
+      id,
+      attempt: this.attempt,
+      at: new Date().toISOString(),
+      ...what,
+    } as OpRecord;
+    try {
+      mkdirSync(opDir(this.runDir, id), { recursive: true });
+      writeWholeSync(opFile(this.runDir, id), `${JSON.stringify(record, null, 2)}\n`);
+      return { id };
+    } catch (error) {
+      return { id, lost: `op.json not written: ${messageOf(error)}` };
+    }
+  }
+}
+
+/** What an operation is, as it is drawn: its `op.json` but its version, id, attempt and time. */
+type OpStart = OpRecord extends infer Each
+  ? Each extends OpRecord
+    ? Omit<Each, "version" | "id" | "attempt" | "at">
+    : never
+  : never;
+
+/** Appends an answer offered, accepted or not, to its operation's `answers.jsonl`. */
+export async function recordAnswer(runDir: string, op: string, answer: Candidate): Promise<void> {
+  await mkdir(opDir(runDir, op), { recursive: true });
+  await appendLine(answersFile(runDir, op), JSON.stringify(answer));
+}
+
+/** An operation's answers, as tests check them; a run never reads them back. */
+export async function readAnswers(runDir: string, op: string): Promise<Candidate[]> {
+  return readLines<Candidate>(answersFile(runDir, op));
+}
+
+/** Claims an operation's one accepted result with `value`; false when another holds it. */
+export async function writeAcceptedExclusive(
+  runDir: string,
+  op: string,
+  value: unknown,
+): Promise<boolean> {
+  await mkdir(opDir(runDir, op), { recursive: true });
+  const record = {
+    version: OP_FILE_VERSIONS.result,
+    value,
+    at: new Date().toISOString(),
+  } as ResultRecord;
+  return linkNew(join(opDir(runDir, op), "result.json"), record);
+}
+
+/**
+ * An operation's accepted result, as tests check it; a run never reads it back. Null
+ * distinguishes "no value yet" from an operation whose accepted value happens to be null. A
+ * result.json of another version throws: unlike a cost, an answer has no unknown to fall back on.
+ */
+export async function readAccepted(runDir: string, op: string): Promise<{ value: unknown } | null> {
+  let text: string;
+  try {
+    text = await readFile(join(opDir(runDir, op), "result.json"), "utf8");
+  } catch (error) {
+    if (isCode(error, "ENOENT")) return null;
+    throw error;
+  }
+  const record: unknown = JSON.parse(text);
+  if (!isKnownOpFile("result", record))
+    throw new Error(`${op}'s result.json is not version ${OP_FILE_VERSIONS.result}`);
+  return { value: (record as ResultRecord).value };
+}
+
+/**
+ * An operation's JSON `file` at `path`, or undefined when it is missing, can't be parsed, or has no
+ * version or one this reader doesn't know: each is read as a file that isn't there. With `refuse`,
+ * a file that parses at another version throws instead, for a reader whose figures it would
+ * otherwise leave looking complete.
+ */
+export async function readOpFile<T>(
+  path: string,
+  file: OpFile,
+  options: { refuse?: boolean } = {},
+): Promise<T | undefined> {
+  let value: unknown;
+  try {
+    value = JSON.parse(await readFile(path, "utf8"));
+  } catch {
+    return undefined;
+  }
+  if (isKnownOpFile(file, value)) return value as T;
+  if (options.refuse && typeof value === "object" && value !== null) {
+    const version = (value as { version?: unknown }).version;
+    throw new Error(
+      `${path} is ${version === undefined ? "of no version" : `version ${JSON.stringify(version)}`}; this awf reads version ${OP_FILE_VERSIONS[file]}`,
+    );
+  }
+  return undefined;
+}
+
+/** The most of a screen kept: its last lines, where a pane's scrollback came with it. */
+const SCREEN_BYTES = 64 * 1024;
+
+/** An operation's `screen.txt`: what its pane showed as it ended without an answer. */
+export function screenFile(runDir: string, op: string): string {
+  return join(opDir(runDir, op), "screen.txt");
+}
+
+export async function writeScreen(runDir: string, op: string, screen: string): Promise<void> {
+  const bytes = Buffer.from(screen);
+  const kept = bytes.length <= SCREEN_BYTES ? screen : tailOf(bytes);
+  await mkdir(opDir(runDir, op), { recursive: true });
+  await writeFile(screenFile(runDir, op), kept, { mode: 0o600 });
+}
+
+/** Its last whole lines within the bound, or its last bytes where one line is longer. */
+function tailOf(bytes: Buffer): string {
+  const tail = bytes.subarray(bytes.length - SCREEN_BYTES);
+  const line = tail.indexOf(10);
+  const whole = line === -1 || line === tail.length - 1 ? tail : tail.subarray(line + 1);
+  // A cut inside a character drops its continuation bytes.
+  let start = 0;
+  while (start < whole.length && (whole[start]! & 0xc0) === 0x80) start += 1;
+  return whole.subarray(start).toString();
+}
+
+function answersFile(runDir: string, op: string): string {
+  return join(opDir(runDir, op), "answers.jsonl");
+}

package/src/pane-layout.ts

@@ -11,77 +11,59 @@ import type {
 export const SESSION_NAME = /^[a-z0-9][a-z0-9-]{0,31}$/;
 
 const SHARE = { min: 0.2, max: 0.8 };
-const NEW_TAB_FIELDS = new Set(["session", "workspace", "tab"]);
 const BESIDE_FIELDS = new Set(["beside", "side", "share"]);
 export const KEEP_PANES: readonly KeepPane[] = ["never", "on-failure", "always"];
 
-type WrittenPane = { pane?: unknown; layout?: unknown; keepPane?: unknown };
-
 /**
- * Refuses, before anything is placed, what the agent's own spec fixes about its pane: what a
- * workflow, untyped at run time, could get wrong in `pane`, `layout` or `keepPane`, and any of them
- * on an agent with no pane of awf's to place (docs/design/pane-layout.md, "Refused at open").
+ * Refuses, before anything is placed, what a workflow, untyped at run time, could get wrong in an
+ * agent's `pane`, and a `pane` on an agent with no pane of awf's to place
+ * (docs/design/pane-layout.md, "Refused at open").
  */
 export function checkPaneOptions(
   key: string,
-  spec: WrittenPane,
+  spec: { pane?: unknown },
   agent: { headless: boolean; sandboxed: boolean },
 ): void {
   const refuse = (why: string): never => {
     throw new Error(`agent ${key}: ${why}`);
   };
-  if (spec.pane === undefined && spec.layout === undefined && spec.keepPane === undefined) return;
-  const old = spec.pane === undefined;
-  if (agent.headless) {
+  // Removed in 0.1.0-beta.6; refused, as they would place or keep a pane otherwise than written.
+  const given = spec as { layout?: unknown; keepPane?: unknown };
+  if (given.layout !== undefined)
     refuse(
-      `${old ? "layout and keepPane place" : "pane places"} a pane, and a headless agent has none`,
+      "layout was removed: give pane: { tab } or pane: { beside, side }; the workspace is awf run --workspace",
     );
-  }
+  if (given.keepPane !== undefined)
+    refuse("keepPane was removed: keeping panes is the operator's, awf run --keep-panes");
+  const { pane } = spec;
+  if (pane === undefined) return;
+  if (agent.headless) refuse("pane places a pane, and a headless agent has none");
   if (agent.sandboxed) {
-    refuse(
-      `${old ? "layout and keepPane are" : "pane is"} not yet for an agent in a sandbox, whose pane is in its own Herdr`,
-    );
+    refuse("pane is not yet for an agent in a sandbox, whose pane is in its own Herdr");
   }
-  if (spec.pane !== undefined && spec.layout !== undefined) {
-    refuse("give pane, not layout beside it: layout is deprecated");
+  if (typeof pane !== "object" || pane === null || Array.isArray(pane)) {
+    refuse(`a pane is an object, not ${JSON.stringify(pane)}`);
   }
-  if (spec.keepPane !== undefined && !KEEP_PANES.includes(spec.keepPane as KeepPane)) {
-    refuse(`keepPane is never, on-failure or always, not ${JSON.stringify(spec.keepPane)}`);
-  }
-  if (spec.pane !== undefined) checkShape(key, "pane", spec.pane, refuse);
-  if (spec.layout !== undefined) checkShape(key, "layout", spec.layout, refuse);
-}
-
-function checkShape(
-  key: string,
-  named: "pane" | "layout",
-  given: unknown,
-  refuse: (why: string) => never,
-): void {
-  const a = named === "pane" ? "a pane" : "a layout";
-  if (typeof given !== "object" || given === null || Array.isArray(given)) {
-    refuse(`${a} is an object, not ${JSON.stringify(given)}`);
-  }
-  const layout = given as Record<string, unknown>;
-  const fields = Object.keys(layout).filter(
-    (field) => layout[field] !== undefined && !(named === "pane" && field === "front"),
+  const shape = pane as Record<string, unknown>;
+  const fields = Object.keys(shape).filter(
+    (field) => shape[field] !== undefined && field !== "front",
   );
-  if (named === "pane" && layout.front !== undefined && typeof layout.front !== "boolean") {
-    refuse(`front is true or false, not ${JSON.stringify(layout.front)}`);
+  if (shape.front !== undefined && typeof shape.front !== "boolean") {
+    refuse(`front is true or false, not ${JSON.stringify(shape.front)}`);
   }
-  if (layout.beside !== undefined) {
+  if (shape.beside !== undefined) {
     const others = fields.filter((field) => !BESIDE_FIELDS.has(field));
     if (others.length > 0) {
-      refuse(`${a} beside another pane takes side and share, not ${others.join(", ")}`);
+      refuse(`a pane beside another pane takes side and share, not ${others.join(", ")}`);
     }
-    if (typeof layout.beside !== "string" || layout.beside === "") {
-      refuse(`beside names an agent's key, not ${JSON.stringify(layout.beside)}`);
+    if (typeof shape.beside !== "string" || shape.beside === "") {
+      refuse(`beside names an agent's key, not ${JSON.stringify(shape.beside)}`);
     }
-    if (layout.beside === key) refuse("a pane cannot be placed beside itself");
-    if (layout.side !== "right" && layout.side !== "below") {
-      refuse(`side is right or below, not ${JSON.stringify(layout.side)}`);
+    if (shape.beside === key) refuse("a pane cannot be placed beside itself");
+    if (shape.side !== "right" && shape.side !== "below") {
+      refuse(`side is right or below, not ${JSON.stringify(shape.side)}`);
     }
-    const share = layout.share;
+    const share = shape.share;
     if (
       share !== undefined &&
       (typeof share !== "number" || !(share >= SHARE.min && share <= SHARE.max))
@@ -90,53 +72,29 @@ function checkShape(
     }
     return;
   }
-  const allowed = named === "pane" ? new Set(["tab"]) : NEW_TAB_FIELDS;
-  const others = fields.filter((field) => !allowed.has(field));
+  const others = fields.filter((field) => field !== "tab");
   if (others.length > 0) {
     refuse(
-      named === "pane"
-        ? `a pane takes tab, or beside and side, and front; not ${others.join(", ")}${others.some((field) => field === "workspace" || field === "session") ? ": the workspace is the operator's, awf run --workspace" : ""}`
-        : `a layout takes session, workspace and tab, or beside and side; not ${others.join(", ")}`,
+      `a pane takes tab, or beside and side, and front; not ${others.join(", ")}${others.some((field) => field === "workspace" || field === "session") ? ": the workspace is the operator's, awf run --workspace" : ""}`,
     );
   }
-  const { session, workspace, tab } = layout;
-  if (session !== undefined && (typeof session !== "string" || !SESSION_NAME.test(session))) {
-    refuse(
-      `session ${JSON.stringify(session)} is not a session name: lowercase letters, digits and -, up to 32, not starting with -`,
-    );
+  if (shape.tab !== undefined && !nonEmpty(shape.tab)) {
+    refuse(`tab is a label, not ${JSON.stringify(shape.tab)}`);
   }
-  if (session !== undefined && workspace === "origin") {
-    refuse('"origin" is a workspace in its own session, so it takes no session');
-  }
-  if (
-    workspace !== undefined &&
-    workspace !== "run" &&
-    workspace !== "origin" &&
-    !(
-      typeof workspace === "object" &&
-      workspace !== null &&
-      !Array.isArray(workspace) &&
-      Object.keys(workspace).join() === "name" &&
-      nonEmpty((workspace as { name?: unknown }).name)
-    )
-  ) {
-    refuse(`workspace is "run", "origin" or { name }, not ${JSON.stringify(workspace)}`);
-  }
-  if (tab !== undefined && !nonEmpty(tab)) refuse(`tab is a label, not ${JSON.stringify(tab)}`);
 }
 
 /**
- * A checked `pane` or `layout` as it is kept and compared: fields given as `undefined` dropped, and
+ * A checked `pane` as it is kept and compared: fields given as `undefined` dropped, and
  * `front: false`, which is its absence, so a reopen that leaves one out matches.
  */
-export function storedLayout<T extends PaneLayout | PaneSpec>(layout: T): T {
+export function storedPane(pane: PaneSpec): PaneSpec {
   // Not an object, it is left for `checkPaneOptions` to refuse by name.
-  if (typeof layout !== "object" || layout === null || Array.isArray(layout)) return layout;
+  if (typeof pane !== "object" || pane === null || Array.isArray(pane)) return pane;
   return Object.fromEntries(
-    Object.entries(structuredClone(layout)).filter(
+    Object.entries(structuredClone(pane)).filter(
       ([field, value]) => value !== undefined && !(field === "front" && value === false),
     ),
-  ) as T;
+  ) as PaneSpec;
 }
 
 function nonEmpty(value: unknown): value is string {
@@ -159,22 +117,21 @@ export type PaneAsked = {
 
 /**
  * What the host is asked for an agent's pane: the workflow's tab or neighbour and `front`, in the
- * operator's workspace and kept as the operator says. The operator's flags win over a deprecated
- * `layout`'s session and workspace and a deprecated `keepPane`; absent, those apply as before. An
- * agent with no pane of awf's, headless or in a sandbox, is asked nothing.
+ * operator's workspace and kept as the operator says. An agent with no pane of awf's, headless or
+ * in a sandbox, is asked nothing.
  */
 export function paneAsked(
-  written: { pane?: PaneSpec; layout?: PaneLayout; keepPane?: KeepPane },
+  pane: PaneSpec | undefined,
   run: RunPanes | undefined,
   hasPane: boolean,
 ): PaneAsked {
   if (!hasPane) return {};
-  const keepPane = run?.keep ?? written.keepPane;
+  const keepPane = run?.keep;
   const workspace = run?.workspace;
-  const layout = placedLayout(written, workspace);
+  const layout = placedLayout(pane, workspace);
   return {
     ...(layout === undefined ? {} : { layout }),
-    ...(written.pane?.front ? { front: true as const } : {}),
+    ...(pane?.front ? { front: true as const } : {}),
     ...(keepPane === undefined ? {} : { keepPane }),
     ...(besideOf(layout) !== undefined && workspace !== undefined
       ? { fallbackWorkspace: workspace }
@@ -183,19 +140,15 @@ export function paneAsked(
 }
 
 function placedLayout(
-  { pane, layout }: { pane?: PaneSpec; layout?: PaneLayout },
+  pane: PaneSpec | undefined,
   workspace: PaneWorkspace | undefined,
 ): PaneLayout | undefined {
-  const written = pane ?? layout;
-  if (written?.beside !== undefined) {
-    const { beside, side, share } = written;
+  if (pane?.beside !== undefined) {
+    const { beside, side, share } = pane;
     return { beside, side, ...(share === undefined ? {} : { share }) };
   }
-  const tab = written?.tab;
-  if (workspace !== undefined) {
-    return { workspace, ...(tab === undefined ? {} : { tab }) };
-  }
-  if (layout !== undefined) return layout;
+  const tab = pane?.tab;
+  if (workspace !== undefined) return { workspace, ...(tab === undefined ? {} : { tab }) };
   return tab === undefined ? undefined : { tab };
 }
 

package/src/progress-view.ts

@@ -316,7 +316,7 @@ const GAP = "   ";
 
 const HOUR_MS = 60 * 60_000;
 
-/** The attempt that recorded a reused stage, and its record's age once that may make it stale. */
+/** The attempt that ran a reused stage, and its line's age once that may make it stale. */
 function reusedTail(stage: StageProgress, now: number): string {
   const age = stage.recordedAt === undefined ? 0 : now - stage.recordedAt;
   return [
@@ -404,7 +404,7 @@ function awaitingNote(turn: NonNullable<Agent["turn"]>, now: number): string {
 }
 
 /** A message admitted: who to whom, its size, and whether it asks or answers. */
-export function messageLine(message: WorkflowRunSnapshot["messages"][number]): string {
+function messageLine(message: WorkflowRunSnapshot["messages"][number]): string {
   const size =
     message.bytes < 1024 ? `${message.bytes} B` : `${(message.bytes / 1024).toFixed(1)} KB`;
   const kind = [message.answers ? "reply" : "", message.asks ? "reply owed" : ""].filter(Boolean);

package/src/project-engine.ts

@@ -0,0 +1,79 @@
+import { dirname } from "node:path";
+import manifest from "../package.json" with { type: "json" };
+import {
+  type InstalledEngine,
+  installedEngine,
+  type ProjectEngine,
+  projectEngine,
+} from "./hand-over";
+
+/** This engine's version, which every package of a release shares. */
+export const ENGINE_VERSION: string = manifest.version;
+
+/** Why an engine won't run a project's runs: `other-engine` or `no-engine`, as a client says it. */
+export class EngineRefused extends Error {
+  constructor(
+    readonly code: "other-engine" | "no-engine",
+    message: string,
+  ) {
+    super(message);
+    this.name = "EngineRefused";
+  }
+}
+
+/**
+ * The engine a project's runs run on (ADR 0015): the `agentswf` installed above it; else, for a
+ * project with none above it, the one its workflow files resolve, as in a workspace whose root
+ * holds `.awf/` and whose packages each have a `node_modules`. Files that resolve two versions, or
+ * one other than the project's, are refused: one project runs on one engine.
+ */
+export function engineOf(project: string, files: readonly string[] = []): ProjectEngine {
+  const engine = projectEngine(project);
+  let fromFiles: (InstalledEngine & { file: string }) | undefined;
+  for (const file of files) {
+    const found = installedEngine(dirname(file));
+    if (!found) continue;
+    const other = engine.kind === "installed" ? engine : fromFiles;
+    if (other && other.version !== found.version)
+      throw new EngineRefused(
+        "other-engine",
+        `${file} resolves agentswf ${found.version}, from ${found.root}, and ${engine.kind === "installed" ? `its project ${project}` : (fromFiles?.file ?? project)} ${other.version}: one project runs on one engine`,
+      );
+    fromFiles ??= { ...found, file };
+  }
+  if (engine.kind === "installed" || !fromFiles) return engine;
+  const { file: _file, ...installed } = fromFiles;
+  return { kind: "installed", ...installed };
+}
+
+/**
+ * Refuses `project` unless this engine is the one its runs run on, as `engineOf` finds it with
+ * `file`: at this version, or, for a project with none, any engine but a client's.
+ */
+export function checkProjectEngine(
+  project: string,
+  options: { file?: string; files?: readonly string[]; client?: boolean; version?: string } = {},
+): void {
+  const own = options.version ?? ENGINE_VERSION;
+  const engine = engineOf(project, [
+    ...(options.file === undefined ? [] : [options.file]),
+    ...(options.files ?? []),
+  ]);
+  if (engine.kind === "declared")
+    throw new EngineRefused(
+      "no-engine",
+      `${project} declares agentswf in ${engine.manifest} and has none installed: run bun install there`,
+    );
+  if (engine.kind === "installed" && engine.version !== own)
+    throw new EngineRefused(
+      "other-engine",
+      options.client
+        ? `${project} runs on its agentswf ${engine.version}, and this program's agentswf/client is ${own}: install one version in both`
+        : `${project} runs on its agentswf ${engine.version}, and this awf is ${own}: run the project's, bunx awf, from ${engine.root}`,
+    );
+  if (engine.kind === "none" && options.client)
+    throw new EngineRefused(
+      "no-engine",
+      `${project} has no agentswf installed, so it runs on whichever global awf is installed: bun add -d agentswf there`,
+    );
+}

package/src/projects.ts

@@ -1,5 +1,5 @@
 import { stat } from "node:fs/promises";
-import { dirname, join, resolve } from "node:path";
+import { basename, dirname, join, resolve } from "node:path";
 import { realPath } from "./files";
 import { appendLine } from "./jsonl";
 import { withRunLock } from "./run-lock";
@@ -34,7 +34,7 @@ export function projectRunRoot(project: string): string {
 }
 
 /** `~/.awf/projects`: each project awf has started an event run in, one absolute path a line. */
-export function projectsFile(home: string): string {
+function projectsFile(home: string): string {
   return join(home, ".awf", "projects");
 }
 
@@ -55,3 +55,14 @@ export async function recordProject(home: string, project: string): Promise<void
     await appendLine(file, project);
   });
 }
+
+/**
+ * The project a run root's runs belong to: the folder holding it as its `.awf/runs`, else, under a
+ * `--run-root` of the operator's, the directory the run works in.
+ */
+export function rootProject(runRoot: string, cwd: string): string {
+  const root = resolve(runRoot);
+  return basename(root) === "runs" && basename(dirname(root)) === ".awf"
+    ? dirname(dirname(root))
+    : cwd;
+}