@agentswf/engine 0.1.0-beta.5 → 0.1.0

package/src/testing/operation-events.ts

@@ -1,19 +1,12 @@
 import { open } from "node:fs/promises";
-import { join } from "node:path";
 import {
-  OPERATION_LIVENESS_KINDS,
   OPERATION_LIVENESS_RECORD_VERSION,
   type OperationLivenessRecord,
 } from "@agentswf/contract/records";
+import { validEvent } from "../operation-events";
+import { liveFile } from "../ops";
 
-type OperationEvent = Pick<
-  OperationLivenessRecord,
-  "kind" | "at" | "sequence" | "reason" | "until" | "peer"
->;
 const MAX_BYTES = 1024 * 1024;
-function eventFile(runDir: string, operationId: string): string {
-  return join(runDir, "calls", operationId, "liveness.jsonl");
-}
 
 export async function readOperationEvents(
   runDir: string,
@@ -25,7 +18,7 @@ export async function readOperationEvents(
   let text: string;
   let clipped = false;
   try {
-    const file = await open(eventFile(runDir, operationId), "r");
+    const file = await open(liveFile(runDir, operationId), "r");
     try {
       const buffer = Buffer.alloc(MAX_BYTES + 1);
       let size = 0;
@@ -63,19 +56,6 @@ export async function readOperationEvents(
   return { records, incomplete };
 }
 
-function validEvent(value: OperationEvent): boolean {
-  return (
-    typeof value.kind === "string" &&
-    (OPERATION_LIVENESS_KINDS as readonly string[]).includes(value.kind) &&
-    Number.isSafeInteger(value.at) &&
-    value.at >= 0 &&
-    Number.isSafeInteger(value.sequence) &&
-    value.sequence >= 0 &&
-    (value.reason === undefined || typeof value.reason === "string") &&
-    (value.until === undefined || (Number.isSafeInteger(value.until) && value.until >= 0)) &&
-    (value.peer === undefined || (typeof value.peer === "string" && value.peer.trim() !== ""))
-  );
-}
 function isRecord(value: unknown, operationId: string): value is OperationLivenessRecord {
   if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
   const item = value as OperationLivenessRecord;

package/src/testing.ts

@@ -2,7 +2,7 @@ import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:
 import { createConnection } from "node:net";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import type { AttemptRecord } from "@agentswf/contract/records";
+import type { AttemptRecord, StageLine } from "@agentswf/contract/records";
 import { type ResultSubmitResponse, WIRE_VERSION } from "@agentswf/contract/wire";
 import {
   defineWorkflow,
@@ -14,9 +14,12 @@ import { createSingleSessionHostFactory } from "@agentswf/harness";
 import type { AgentSessionAdapter } from "@agentswf/harness/adapter";
 import { createFakeAdapter } from "@agentswf/harness/testing";
 import Type from "typebox";
+import type { DecisionInstallation } from "./decisions/seam";
 import { writeJson } from "./files";
 import { OPERATOR_ALIASES } from "./operator-aliases";
-import { createRun, openRun, type Run, readAttempts } from "./runs";
+import { listOps } from "./ops";
+import { claimRunLines, readRunLines } from "./run-lines";
+import { createRun, openRun, type Run, readAttemptFiles } from "./runs";
 import type { RunnableWorkflow } from "./workflow-runner";
 import { type RunWorkflowOptions, runWorkflow, startWorkflow } from "./workflow-runner";
 
@@ -61,13 +64,28 @@ export async function until(check: () => Promise<boolean>, ms = 20_000): Promise
   }
 }
 
+/**
+ * Attempt `attempt`'s writer on the run's `run.jsonl`, claimed now, and its listing of `ops/`, as
+ * `awf run` claims them.
+ */
+export async function claimLines(runDir: string, attempt: number) {
+  const ops = await listOps(runDir);
+  return { lines: await claimRunLines(runDir, attempt, new Date().toISOString()), ops };
+}
+
+/** Each stage's latest line in the run's `run.jsonl`, by name, in the order first written. */
+export async function lastLines(runDir: string): Promise<Map<string, StageLine>> {
+  const { stages } = (await readRunLines(runDir)).view;
+  return new Map(Object.entries(stages).map(([name, { last }]) => [name, last]));
+}
+
 /** 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;
+  const n = (await readAttemptFiles(run)).length + 1;
   mkdirSync(join(run.dir, "attempts"), { recursive: true });
   await writeJson(join(run.dir, "attempts", `${n}.json`), {
-    version: 1,
     attempt: n,
+    kind: "attempt",
     file: "/flows/case.ts",
     flags: {},
     started: new Date().toISOString(),
@@ -164,7 +182,8 @@ export function answering(): AgentSessionAdapter {
 
 /**
  * One attempt of run r1 of `workflow` under `runRoot`, created by the first, its agents answered by
- * `answering()`. Its folder is `{runRoot}/{workflow}/r1`.
+ * `answering()`. Its folder is `{runRoot}/{workflow}/r1`. It claims `run.jsonl` as a claim does, and
+ * writes its attempt's file once it ends, as a later attempt reads its version there.
  */
 export async function runAttempt<Result extends JsonValue>(
   workflow: RunnableWorkflow<null, Result>,
@@ -174,10 +193,12 @@ export async function runAttempt<Result extends JsonValue>(
     fromStage?: string;
     values?: Record<string, JsonValue>;
     adapter?: AgentSessionAdapter;
+    decisions?: DecisionInstallation;
     signal?: AbortSignal;
   },
 ) {
   const { runRoot, attempt = 1, fromStage, values, adapter = answering(), signal } = options;
+  const { decisions } = options;
   const name = workflow.meta.name;
   const run = existsSync(join(runRoot, name, "r1"))
     ? await openRun(runRoot, name, "r1")
@@ -188,19 +209,46 @@ export async function runAttempt<Result extends JsonValue>(
         cwd: process.cwd(),
         sandbox: null,
       });
-  return runWorkflow(workflow, null, {
-    runRoot,
-    run: {
-      dir: run.dir,
-      id: run.record.id,
+  const started = new Date().toISOString();
+  const ops = await listOps(run.dir);
+  const lines = await claimRunLines(run.dir, attempt, started);
+  const ended = (outcome: AttemptRecord["outcome"]) =>
+    writeJson(join(run.dir, "attempts", `${attempt}.json`), {
       attempt,
-      ...(fromStage === undefined ? {} : { fromStage }),
-      ...(values === undefined ? {} : { values: new Map(Object.entries(values)) }),
-    },
-    runtime: { aliases: OPERATOR_ALIASES, host: createSingleSessionHostFactory(adapter) },
-    deadline: future(),
-    ...(signal === undefined ? {} : { signal }),
-  });
+      kind: "attempt",
+      file: name,
+      ...(workflow.meta.version === undefined ? {} : { workflowVersion: workflow.meta.version }),
+      flags: fromStage === undefined ? {} : { fromStage },
+      pid: process.pid,
+      processStart: started,
+      started,
+      ended: new Date().toISOString(),
+      outcome,
+    } satisfies AttemptRecord);
+  mkdirSync(join(run.dir, "attempts"), { recursive: true });
+  try {
+    const result = await runWorkflow(workflow, null, {
+      runRoot,
+      run: {
+        dir: run.dir,
+        id: run.record.id,
+
+        lines,
+        ops,
+        ...(fromStage === undefined ? {} : { fromStage }),
+        ...(values === undefined ? {} : { values: new Map(Object.entries(values)) }),
+      },
+      runtime: { aliases: OPERATOR_ALIASES, host: createSingleSessionHostFactory(adapter) },
+      deadline: future(),
+      ...(decisions === undefined ? {} : { decisions }),
+      ...(signal === undefined ? {} : { signal }),
+    });
+    await ended("completed");
+    return result;
+  } catch (error) {
+    await ended("failed");
+    throw error;
+  }
 }
 
 /** `startWorkflow` as the first attempt of a new run of the workflow under `options.runRoot`. */
@@ -217,7 +265,7 @@ export async function startNew<Args extends JsonValue, Result extends JsonValue>
   });
   return startWorkflow(definition, args, {
     ...options,
-    run: { dir: run.dir, id: run.record.id, attempt: 1 },
+    run: { dir: run.dir, id: run.record.id, ...(await claimLines(run.dir, 1)) },
   });
 }
 

package/src/tick-command.ts

@@ -1,14 +1,22 @@
+import { realpathSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
 import type { TickResultJson } from "@agentswf/contract/records";
+import { type Out, parsePlace } from "./command-line";
 import { messageOf } from "./errors";
 import { exists } from "./files";
+import { ENGINE_VARIABLE, type InstalledEngine, type ProjectEngine } from "./hand-over";
 import help from "./help/tick.txt" with { type: "text" };
+import { ENGINE_VERSION, EngineRefused, engineOf } from "./project-engine";
 import { listProjects, projectRunRoot } from "./projects";
-import type { Out } from "./run-commands";
-import { parsePlace } from "./run-commands";
+import { asksJson, printRefusal } from "./refusals";
 import { runLockFile, withRunLock } from "./run-lock";
-import { listRuns } from "./run-state";
+import { listRunEntries, listRuns } from "./run-state";
+import { RunUnreadable, readAttempts } from "./runs";
 import { type Launch, wake } from "./wake";
 
+/** `awf tick --json`'s `"v"`, which its refusals carry too. */
+export const TICK_V = 1 satisfies TickResultJson["v"];
+
 export const tickUsage = help.trimEnd();
 
 export async function tickCommand(
@@ -22,10 +30,6 @@ export async function tickCommand(
     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);
@@ -34,24 +38,72 @@ export async function tickCommand(
     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}`);
+    printRefusal(out, { json: asksJson(argv), v: TICK_V }, error, "usage", tickUsage);
     return 2;
   }
   const { place, json } = parsed;
   const woke: TickResultJson["woke"] = [];
+  const unreadable: string[] = [];
   let failed = false;
   const roots: string[] = [];
-  if (!parsed.rest.includes("--all")) roots.push(place.runRoot);
-  else
+  /** Each project's runs on its own engine (ADR 0015): this one, or its own in a child. */
+  const onItsEngine = async (project: string, root: string) => {
+    let engine: ProjectEngine;
+    try {
+      engine = engineOf(project, await runFiles(root));
+    } catch (error) {
+      if (!(error instanceof EngineRefused)) throw error;
+      failed = true;
+      out.stderr(`awf: ${error.message}; its runs are not woken`);
+      return;
+    }
+    if (engine.kind === "declared") {
+      failed = true;
+      out.stderr(
+        `awf: ${project} declares agentswf in ${engine.manifest} and has none installed, so its runs are not woken: run bun install there`,
+      );
+    } else if (engine.kind === "installed" && engine.version !== ENGINE_VERSION) {
+      // This is the engine the project's agentswf runs, and they disagree: another child would find
+      // the same, without end.
+      if (isOwnEngine(engine)) {
+        failed = true;
+        out.stderr(
+          `awf: ${project}'s agentswf is ${engine.version} and its engine ${ENGINE_VERSION}, so its runs are not woken: run bun install there`,
+        );
+        return;
+      }
+      const ticked = await tickElsewhere(project, root, engine, context.environment, out);
+      woke.push(...ticked.woke);
+      if (!ticked.ok) failed = true;
+    } else roots.push(root);
+  };
+  if (!parsed.rest.includes("--all")) {
+    // A project's own run root is its engine's to tick; any other, the operator's, this one's.
+    const root = resolve(place.runRoot);
+    if (basename(root) === "runs" && basename(dirname(root)) === ".awf")
+      await onItsEngine(dirname(dirname(root)), root);
+    else roots.push(root);
+  } else
     for (const project of await listProjects(context.home)) {
-      if (await exists(project)) roots.push(projectRunRoot(project));
-      else {
+      if (!(await exists(project))) {
         failed = true;
         out.stderr(`awf: ${project}, in ~/.awf/projects, is gone; its runs are not woken`);
+        continue;
       }
+      // A project a plain run registered (ADR 0016) has nothing for a tick to wake; one on another
+      // engine is that engine's to judge, whose records this one may not read.
+      const root = projectRunRoot(project);
+      if (!(await listRuns(root)).some((run) => run.record.events) && onThisEngine(project))
+        continue;
+      await onItsEngine(project, root);
     }
   for (const root of roots) {
-    for (const run of await listRuns(root)) {
+    for (const run of await listRunEntries(root)) {
+      if (run instanceof RunUnreadable) {
+        // One with events is one a tick would have woken: it is named, not an error.
+        if (run.events) unreadable.push(run.ref);
+        continue;
+      }
       if (!run.record.events) continue;
       const ref = `${run.record.workflow}/${run.record.id}`;
       try {
@@ -70,7 +122,85 @@ export async function tickCommand(
       }
     }
   }
-  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}`);
+  if (unreadable.length > 0 && !json) {
+    const runs = unreadable.length === 1 ? "1 run" : `${unreadable.length} runs`;
+    out.stderr(
+      `awf: ${runs} with events can't be read and ${unreadable.length === 1 ? "is" : "are"} not woken; awf runs says why`,
+    );
+  }
+  if (json) {
+    const result: TickResultJson = {
+      v: TICK_V,
+      woke,
+      ...(unreadable.length ? { unreadable } : {}),
+    };
+    out.stdout(JSON.stringify(result));
+  } else for (const each of woke) out.stdout(`${each.did} ${each.ref}: ${each.why}`);
   return failed ? 1 : 0;
 }
+
+/** The files the event runs under `root` last ran, by which a project with no engine finds one. */
+async function runFiles(root: string): Promise<string[]> {
+  const files: string[] = [];
+  for (const run of await listRuns(root)) {
+    if (!run.record.events) continue;
+    const file = (await readAttempts(run).catch(() => [])).at(-1)?.file ?? run.record.file;
+    if (file !== undefined) files.push(file);
+  }
+  return files;
+}
+
+/**
+ * `awf tick` of one project's runs on its own engine, as the hand-over runs it: in the project,
+ * with `AWF_ENGINE` naming it, so it never hands over by its directory.
+ */
+async function tickElsewhere(
+  project: string,
+  root: string,
+  engine: InstalledEngine,
+  environment: Readonly<Record<string, string | undefined>>,
+  out: Out,
+): Promise<{ ok: boolean; woke: TickResultJson["woke"] }> {
+  const child = Bun.spawn({
+    cmd: [process.execPath, "--no-env-file", engine.bin, "tick", "--run-root", root, "--json"],
+    cwd: project,
+    env: { ...environment, [ENGINE_VARIABLE]: engine.dir },
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  const [stdout, stderr, code] = await Promise.all([
+    new Response(child.stdout).text(),
+    new Response(child.stderr).text(),
+    child.exited,
+  ]);
+  for (const line of stderr.trimEnd().split("\n")) if (line) out.stderr(line);
+  try {
+    const result = JSON.parse(stdout) as Partial<TickResultJson>;
+    if (!Array.isArray(result.woke)) throw new Error("no woke");
+    return { ok: code === 0, woke: result.woke };
+  } catch {
+    out.stderr(
+      `awf: ${project}'s agentswf ${engine.version} did not say what it woke (exit ${code})`,
+    );
+    return { ok: false, woke: [] };
+  }
+}
+
+/** Whether `engine`'s agentswf runs on this very engine package. */
+function isOwnEngine(engine: InstalledEngine): boolean {
+  try {
+    const theirs = Bun.resolveSync("@agentswf/engine/package.json", engine.dir);
+    return realpathSync(theirs) === realpathSync(join(import.meta.dir, "..", "package.json"));
+  } catch {
+    return false;
+  }
+}
+
+/** Whether a project's runs would run on this engine, or none is installed there to run them. */
+function onThisEngine(project: string): boolean {
+  try {
+    const engine = engineOf(project);
+    return engine.kind !== "installed" || engine.version === ENGINE_VERSION;
+  } catch {
+    return false;
+  }
+}

package/src/tools.ts

@@ -25,7 +25,7 @@ import {
 } from "./simple-input";
 
 /** How long a handler that ignores its aborted signal is waited for before its call is settled. */
-export const TOOL_SETTLE_MS = 5_000;
+const TOOL_SETTLE_MS = 5_000;
 
 /**
  * The agents whose handlers the current code runs in, innermost last: one of them can't be given
@@ -59,8 +59,6 @@ export type ToolHost<Scope> = {
   /** Runs `fn` in the operation's scope, or in none. */
   runIn<T>(scope: Scope | undefined, fn: () => T): T;
   now?(): number;
-  /** A tool given its deprecated `timeoutMs`. */
-  deprecated?(name: "timeout-ms", call: string): void;
 };
 
 /** An operation as tool calls bind to it. */
@@ -125,7 +123,7 @@ export class ToolCalls<Scope> {
 
   /** An agent opened or forked with these tools; checked against the limits first. */
   give(agent: AgentKey, tools: AgentTools): void {
-    this.#held.set(agent, held(agent, tools, this.#host.deprecated));
+    this.#held.set(agent, held(agent, tools));
   }
 
   /**
@@ -134,7 +132,7 @@ export class ToolCalls<Scope> {
    */
   reopen(agent: AgentKey, tools: AgentTools | undefined): void {
     if (tools === undefined) return;
-    const next = held(agent, tools, this.#host.deprecated);
+    const next = held(agent, tools);
     const existing = this.#held.get(agent);
     if (!existing || !sameTools(existing, next)) {
       throw new Error(`agent ${agent} is already open with different tools`);
@@ -573,11 +571,7 @@ export function toolsLesson(
   ].join("\n");
 }
 
-function held(
-  agent: AgentKey,
-  tools: AgentTools,
-  deprecated: ToolHost<unknown>["deprecated"],
-): Held {
+function held(agent: AgentKey, tools: AgentTools): Held {
   if (typeof tools !== "object" || tools === null || Array.isArray(tools)) {
     throw new Error(`agent ${agent}'s tools are an object of tools by name`);
   }
@@ -600,7 +594,7 @@ function held(
     if (Buffer.byteLength(spec.description) > TOOL_LIMITS.descriptionBytes) {
       throw new Error(`${where}: its description is over ${TOOL_LIMITS.descriptionBytes} bytes`);
     }
-    budgets.set(name, budgetOf(where, spec, deprecated));
+    budgets.set(name, budgetOf(where, spec));
     if (spec.input === undefined) {
       schemas.set(name, undefined);
       continue;
@@ -629,25 +623,12 @@ function held(
   return { specs: { ...tools }, schemas, budgets };
 }
 
-/** A tool's `timeout`, or its deprecated `timeoutMs`, checked; absent, the default. */
-function budgetOf(
-  where: string,
-  spec: ToolSpec,
-  deprecated: ToolHost<unknown>["deprecated"],
-): Budget {
-  const { timeout, timeoutMs } = spec;
-  if (timeout != null) {
-    if (timeoutMs != null)
-      throw new Error(`${where}: give timeout alone: timeoutMs is its deprecated form`);
-    if (timeout === false) return false;
-    return positiveDurationMilliseconds(timeout, `${where}: its timeout`);
-  }
-  if (timeoutMs == null) return TOOL_LIMITS.defaultTimeoutMs;
-  if (timeoutMs !== false && !(Number.isSafeInteger(timeoutMs) && timeoutMs > 0)) {
-    throw new Error(`${where}: timeoutMs is a positive integer, or false for none`);
-  }
-  deprecated?.("timeout-ms", "on a tool");
-  return timeoutMs;
+/** A tool's `timeout`, checked; absent, the default. */
+function budgetOf(where: string, spec: ToolSpec): Budget {
+  const { timeout } = spec;
+  if (timeout == null) return TOOL_LIMITS.defaultTimeoutMs;
+  if (timeout === false) return false;
+  return positiveDurationMilliseconds(timeout, `${where}: its timeout`);
 }
 
 function sameTools(a: Held, b: Held): boolean {

package/src/turn-ends.ts

@@ -0,0 +1,37 @@
+import type { RunLine } from "@agentswf/contract/records";
+import type { AgentExecution, OperationRecord } from "@agentswf/contract/workflow";
+import { endIdOf } from "./event-ids";
+import type { TurnStartedLine } from "./run-policy/waits";
+
+/** The usage of a turn no delivery settled: one refused, cancelled while queued, or cut off by a crash. */
+export function unrunUsage(
+  agent: string,
+  operationId: string,
+  execution: AgentExecution,
+): OperationRecord {
+  return { callPath: [], agent, operationId, execution, sessions: [] };
+}
+
+/** The failed `turn-ended` attempt `attempt`'s claim writes for `turn`, which its attempt left running. */
+export function crashedEnd(turn: TurnStartedLine, attempt: number, at: string): RunLine {
+  return {
+    kind: "turn-ended",
+    attempt,
+    at,
+    id: endIdOf(turn.agent, turn.turn, turn.attempt),
+    agent: turn.agent,
+    turn: turn.turn,
+    began: turn.attempt,
+    end: {
+      turn: turn.turn,
+      meta: turn.meta,
+      outcome: {
+        answered: false,
+        kind: "failed",
+        reason: `attempt ${turn.attempt} ended before this turn did; its work, if any, is in the agent's session`,
+        retryable: true,
+        usage: unrunUsage(turn.agent, turn.turn, turn.execution),
+      },
+    },
+  };
+}