@agentswf/engine 0.1.0-beta.4 → 0.1.0

package/src/client/runs.ts

@@ -0,0 +1,337 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import {
+  ClientError,
+  type Ending,
+  type Run as RunHandle,
+  type RunStatus,
+  type StartResult,
+} from "@agentswf/contract/client";
+import type { AttemptRecord, ClaimedAttempt, OutputRecord } from "@agentswf/contract/records";
+import { isEventWorkflow, type JsonValue } from "@agentswf/contract/workflow";
+import { canonical } from "../canonical-json";
+import { shellLine } from "../command-line";
+import { messageOf } from "../errors";
+import { exists } from "../files";
+import { recordProject } from "../projects";
+import { lockHeld, runLockFile, withRunLock } from "../run-lock";
+import { type RunState, runStatus, statusOf, stuckOf } from "../run-state";
+import {
+  claimedOf,
+  createRun,
+  generateId,
+  openRun,
+  outFile,
+  type Run,
+  RunRefused,
+  RunTaken,
+  readAttemptFiles,
+  takenInCase,
+} from "../runs";
+import { wake } from "../wake";
+import type { AnyWorkflow } from "../workflow-loader";
+import { checkArgs, checkRunId, derivedId } from "./checks";
+import type { ClientContext } from "./index";
+import { locate } from "./locate";
+
+/** How often a wait reads the run's files. */
+const POLL_MILLISECONDS = 500;
+
+/**
+ * `start`: makes sure the run with these args exists and has been launched. A run there with the
+ * same args is `exists`, launched only if it never had an attempt; with other args, or none
+ * recorded, `other-args`.
+ */
+export async function start(
+  workflow: AnyWorkflow,
+  args: JsonValue,
+  given: { id?: string },
+  context: ClientContext,
+): Promise<StartResult<JsonValue>> {
+  const found = await locate(workflow, context.home);
+  const name = workflow.meta.name;
+  checkArgs(name, args);
+  const named = given.id ?? derivedId(workflow, args);
+  if (named !== undefined) checkRunId(named, `${name}/${named}`);
+  // Without one, a new id, as awf run makes one: no sender names this run.
+  const id = named ?? (await unusedId(found.runRoot, name));
+  const create = async (id: string): Promise<StartResult<JsonValue> | undefined> => {
+    let run: Run;
+    try {
+      run = await createRun(found.runRoot, {
+        id,
+        workflow: name,
+        argv: [],
+        args,
+        cwd: found.project,
+        sandbox: null,
+        ...(isEventWorkflow(workflow) ? { events: true as const } : {}),
+        env: { PATH: context.environment.PATH ?? "" },
+        file: found.file,
+      });
+    } catch (error) {
+      // A generated id an `awf run` took meanwhile, which takes no lock: drawn again.
+      if (named === undefined && error instanceof RunTaken) return undefined;
+      // A named id an `awf run` took meanwhile: begun with no args recorded, as a moment later.
+      if (error instanceof RunTaken && (await exists(join(found.runRoot, name, id, "run.json"))))
+        throw new ClientError(
+          "other-args",
+          `${name}/${id} is there already, begun by awf run or an event, with no args recorded`,
+          `${name}/${id}`,
+        );
+      // An id taken in another case is the caller's; a disk that fails is not.
+      if (error instanceof RunRefused)
+        throw new ClientError("id", messageOf(error), `${name}/${id}`);
+      throw error;
+    }
+    await recordProject(context.home, found.project);
+    return launched(run, "started");
+  };
+  const launched = async (run: Run, did: "started" | "exists"): Promise<StartResult<JsonValue>> => {
+    const woken = await wake(run, { ...context, file: found.file });
+    const handle = runHandle(run, context);
+    if (woken.why === "launch-failed")
+      return {
+        ok: false,
+        run: handle,
+        did: "launch-failed",
+        ...(woken.error ? { error: woken.error } : {}),
+      };
+    if (woken.why === "stuck") return { ok: false, run: handle, did: "stuck" };
+    return { ok: true, run: handle, did };
+  };
+  const ref = `${name}/${id}`;
+  if (named === undefined)
+    // A generated id another caller drew the same minute is drawn again, never taken as theirs.
+    for (let candidate = id; ; candidate = await unusedId(found.runRoot, name)) {
+      const made = await withRunLock(runLockFile(found.runRoot, name, candidate), async () =>
+        (await exists(join(found.runRoot, name, candidate))) ? undefined : create(candidate),
+      );
+      if (made) return made;
+    }
+  return withRunLock(runLockFile(found.runRoot, name, id), async () => {
+    const run = await openExact(found.runRoot, name, id, "id");
+    // Named, so never drawn again: create returns a result or throws.
+    if (!run) return (await create(id))!;
+    if (run.record.args === undefined)
+      throw new ClientError(
+        "other-args",
+        `${ref} is there already, started by an event or by awf run, with no args recorded; get reads it`,
+        ref,
+      );
+    if (JSON.stringify(canonical(run.record.args)) !== JSON.stringify(canonical(args)))
+      throw new ClientError(
+        "other-args",
+        `${ref} is there already, started with other args; another id starts these`,
+        ref,
+      );
+    const files = await readAttemptFiles(run);
+    if (claimedOf(files).length > 0)
+      return { ok: true, run: runHandle(run, context), did: "exists" };
+    // Never launched, or its launch failed: launched now, as a wake would, unless it is stuck.
+    if (stuckOf(files)) return { ok: false, run: runHandle(run, context), did: "stuck" };
+    return launched(run, "exists");
+  });
+}
+
+async function unusedId(runRoot: string, workflow: string): Promise<string> {
+  for (;;) {
+    const id = generateId();
+    if (!(await exists(join(runRoot, workflow, id)))) return id;
+  }
+}
+
+/** `get`: the run `id` of `workflow`, or `no-run`. */
+export async function get(
+  workflow: AnyWorkflow,
+  id: string,
+  context: ClientContext,
+): Promise<RunHandle<JsonValue>> {
+  const found = await locate(workflow, context.home);
+  const ref = `${workflow.meta.name}/${id}`;
+  checkRunId(id, ref);
+  const run = await openExact(found.runRoot, workflow.meta.name, id, "no-run");
+  if (!run) throw new ClientError("no-run", `no run ${ref} in ${found.project}`, ref);
+  return runHandle(run, context);
+}
+
+/**
+ * The run `{workflow}/{id}` in `runRoot`, or undefined when there is none; one there whose id
+ * differs from `id` only in case is refused with `differing`.
+ */
+export async function openExact(
+  runRoot: string,
+  workflow: string,
+  id: string,
+  differing: "id" | "no-run",
+): Promise<Run | undefined> {
+  const ref = `${workflow}/${id}`;
+  const refuse = (other: string) =>
+    differing === "id"
+      ? new ClientError("id", `${ref} differs only in case from ${other}`, ref)
+      : new ClientError("no-run", `no run ${ref}; ${other} differs only in case`, ref);
+  if (!(await exists(join(runRoot, workflow, id, "run.json")))) {
+    // A file system that tells case apart, as Linux's does, finds no folder at all.
+    const other = await takenInCase(join(runRoot, workflow), id);
+    if (other === undefined) return undefined;
+    throw refuse(other);
+  }
+  const run = await openRun(runRoot, workflow, id);
+  if (run.record.id === id) return run;
+  throw refuse(run.record.id);
+}
+
+/** A run, read from its files whenever asked. */
+function runHandle(run: Run, context: Pick<ClientContext, "pollMs">): RunHandle<JsonValue> {
+  const { id, workflow } = run.record;
+  return {
+    id,
+    ref: `${workflow}/${id}`,
+    status: () => statusNow(run),
+    wait: (options = {}) =>
+      waitFor(run, options.final === true, options.signal, context.pollMs ?? POLL_MILLISECONDS),
+  };
+}
+
+/** Whether nothing continues a run in `state` on its own. */
+export function isFinal(state: RunState, events: boolean): boolean {
+  switch (state) {
+    case "completed":
+    case "stopped":
+    case "cancelled":
+    case "stuck":
+      return true;
+    case "failed":
+    case "timed-out":
+    case "interrupted":
+      // An event run's next event, or awf tick, continues it.
+      return !events;
+    case "parked":
+    case "running":
+      return false;
+  }
+}
+
+async function statusNow(run: Run): Promise<RunStatus<JsonValue>> {
+  const status = await runStatus(run);
+  const last = status.attempts.at(-1);
+  const ending = last?.outcome === undefined ? undefined : await endingOf(run, last);
+  return {
+    state: status.state,
+    final: isFinal(status.state, run.record.events === true),
+    ...(ending ? { ending } : {}),
+  };
+}
+
+/** An ended attempt's ending, from its record and, for the last one, `out.json`. */
+async function endingOf(run: Run, attempt: ClaimedAttempt): Promise<Ending<JsonValue> | undefined> {
+  const output = await readFile(outFile(run.dir), "utf8")
+    .then((text) => JSON.parse(text) as OutputRecord)
+    .catch(() => undefined);
+  const own = output?.attempt === attempt.attempt ? output : undefined;
+  const stages = own?.stages ?? [];
+  switch (attempt.outcome) {
+    case undefined:
+      return undefined;
+    case "completed":
+      if (attempt.value !== undefined) return { kind: "completed", value: attempt.value, stages };
+      return own?.outcome === "completed"
+        ? { kind: "completed", value: own.value, stages }
+        : undefined;
+    case "parked":
+      return {
+        kind: "parked",
+        stages,
+        ...(own?.outcome === "parked" && own.label !== undefined ? { label: own.label } : {}),
+        ...(own?.outcome === "parked" && own.until !== undefined ? { until: own.until } : {}),
+      };
+    default:
+      return {
+        kind: attempt.outcome,
+        ...(attempt.stage === undefined ? {} : { stage: attempt.stage }),
+        reason: attempt.reason ?? "",
+        stages,
+        continue: shellLine(["awf", "run", attempt.file, "--id", run.record.id, "--continue"]),
+        ...(own && "needs" in own && own.needs ? { needs: own.needs } : {}),
+      };
+  }
+}
+
+/**
+ * Waits for the run's next rest after the call, or, with `final`, the first rest nothing will
+ * continue on its own. A rest is read from the attempt records, not by sampling the state: an
+ * attempt current at the call, or any later one, ending or found dead; or a launch that failed
+ * after the call, with the run's lock free.
+ */
+async function waitFor(
+  run: Run,
+  final: boolean,
+  signal: AbortSignal | undefined,
+  pollMs: number,
+): Promise<RunStatus<JsonValue>> {
+  signal?.throwIfAborted();
+  const failedLaunches = (files: readonly AttemptRecord[]) =>
+    files.filter((file) => file.kind === "failed-launch").length;
+  // Read before the status: an attempt that rests and is continued between the two is still seen.
+  const files = await readAttemptFiles(run);
+  const at = claimedOf(files);
+  let launches = failedLaunches(files);
+  const now = await statusNow(run);
+  if (final ? now.final : now.state !== "running") return now;
+  const lockFile = runLockFile(run.root, run.record.workflow, run.record.id);
+  // The attempt current at the call, or the first one after it.
+  let watching =
+    at.at(-1)?.outcome === undefined && at.length > 0
+      ? at.at(-1)!.attempt
+      : (files.at(-1)?.attempt ?? 0) + 1;
+  for (;;) {
+    await pause(pollMs, signal);
+    const all = await readAttemptFiles(run);
+    const attempts = claimedOf(all);
+    let rested: ClaimedAttempt | undefined;
+    for (let i = 0; i < attempts.length; i++) {
+      const attempt = attempts[i]!;
+      if (attempt.attempt < watching) continue;
+      const state = statusOf(run, attempts.slice(0, i + 1)).state;
+      if (state === "running") break;
+      rested = attempt;
+      watching = attempt.attempt + 1;
+    }
+    // A launch that failed is a rest once its sender has let the run go; a sender holding the lock
+    // is launching it again.
+    const launchFailed = failedLaunches(all) > launches && !(await lockHeld(lockFile));
+    if (launchFailed) launches = failedLaunches(all);
+    const current = await statusNow(run);
+    if (final) {
+      if (current.final) return current;
+      continue;
+    }
+    if (current.state !== "running") return current;
+    const events = run.record.events === true;
+    if (rested) {
+      // Rested, and continued since: the rest as it was.
+      const state: RunState = rested.outcome ?? "interrupted";
+      const ending = await endingOf(run, rested);
+      return { state, final: isFinal(state, events), ...(ending ? { ending } : {}) };
+    }
+    // Unless an attempt has started since, by a sender that launched it again.
+    if (launchFailed && !attempts.some((attempt) => attempt.attempt >= watching))
+      return { state: "interrupted", final: isFinal("interrupted", events) };
+  }
+}
+
+function pause(ms: number, signal: AbortSignal | undefined): Promise<void> {
+  return new Promise((resolve, reject) => {
+    // Aborted meanwhile: a listener added now would never hear it.
+    if (signal?.aborted) return reject(signal.reason);
+    const done = () => {
+      clearTimeout(timer);
+      reject(signal?.reason);
+    };
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", done);
+      resolve();
+    }, ms);
+    signal?.addEventListener("abort", done, { once: true });
+  });
+}

package/src/command-line.ts

@@ -0,0 +1,64 @@
+// The operator commands' words: where the commands that read runs look, and the commands they
+// suggest, as text to paste into a shell.
+import { resolve } from "node:path";
+import type { RunCommand } from "./run-command";
+import { runRootOf } from "./runs";
+
+/** Where the commands that read runs look, and the options their suggested commands repeat. */
+export type ReadPlace = { shellCwd: string; runRoot: string; repeat: string[] };
+
+export type Out = { stdout(text: string): void; stderr(text: string): void };
+
+/** `--cwd`, `--run-root` and `--json`, taken out of `argv`; the rest is left for the command. */
+export function parsePlace(
+  argv: readonly string[],
+  shellCwd: string,
+): { place: ReadPlace; json: boolean; rest: string[] } {
+  let cwd = shellCwd;
+  let runRoot: string | undefined;
+  let json = false;
+  const repeat: string[] = [];
+  const rest: string[] = [];
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index]!;
+    // What follows is the command's own, a message's text included.
+    if (arg === "--") {
+      rest.push(...argv.slice(index));
+      break;
+    }
+    if (arg === "--json") json = true;
+    else if (arg === "--cwd" || arg === "--run-root") {
+      const value = argv[index + 1];
+      if (!value || value.startsWith("--")) throw new Error(`${arg} needs a directory`);
+      index += 1;
+      if (arg === "--cwd") cwd = resolve(shellCwd, value);
+      else runRoot = resolve(shellCwd, value);
+      repeat.push(arg, value);
+    } else rest.push(arg);
+  }
+  return { place: { shellCwd, runRoot: runRoot ?? runRootOf(cwd), repeat }, json, rest };
+}
+
+/** A suggested command, `words` and then the place repeated, before any options added after. */
+export function command(place: ReadPlace, ...words: string[]): string[] {
+  return [...words, ...place.repeat];
+}
+
+/** The flags that find this run again from another command: the folder or run root given. */
+export function placeFlags(
+  run: Pick<RunCommand, "cwd" | "cwdGiven" | "runRoot" | "runRootGiven">,
+): string[] {
+  return [
+    ...(run.cwdGiven ? ["--cwd", run.cwd] : []),
+    ...(run.runRootGiven ? ["--run-root", run.runRoot] : []),
+  ];
+}
+
+/** A suggested command as text to paste into a shell. */
+export function shellLine(words: readonly string[]): string {
+  return words.map(shellWord).join(" ");
+}
+
+export function shellWord(word: string): string {
+  return /^[\w@%+=:,./-]+$/.test(word) ? word : `'${word.replaceAll("'", `'\\''`)}'`;
+}

package/src/commands.ts

@@ -1,11 +1,12 @@
 import { allowanceUsage } from "./allowance-command";
+import { shellLine } from "./command-line";
 import { emitUsage } from "./emit-command";
 import { replyUsage } from "./holder-command";
 import { inboxUsage } from "./inbox-command";
 import { initUsage } from "./init-command";
 import { logsUsage } from "./logs-command";
+import { openUsage } from "./open-command";
 import { usage as runUsage } from "./run-command";
-import { shellLine } from "./run-commands";
 import { runsUsage } from "./runs-command";
 import { testUsage } from "./test-command";
 import { tickUsage } from "./tick-command";
@@ -46,6 +47,11 @@ export const COMMANDS = [
     commands: { logs: "What a run did and is doing, merged by time" },
     help: logsUsage,
   },
+  {
+    group: "Look at runs",
+    commands: { open: "Open a copy of an agent's session in its harness, or ask it one question" },
+    help: openUsage,
+  },
   {
     group: "Coordinate a run from outside",
     commands: { inbox: "What agents said to a participant outside the run, and what it said back" },

package/src/control-plane.ts

@@ -6,6 +6,7 @@ import {
   type GivenInput,
   WIRE_VERSION,
 } from "@agentswf/contract/wire";
+import { DOORS_PREFIX } from "@agentswf/sandbox";
 import { isCode } from "./files";
 import type { Messaging } from "./messaging/messaging";
 import { UNRECORDED } from "./messaging/text";
@@ -13,13 +14,10 @@ import type { ResultSlotRegistry } from "./result-slots";
 import type { ToolCalls } from "./tools";
 
 /** What the control plane asks of the run's tools, by the agent whose socket asked. */
-export type ToolHandler = Pick<ToolCalls<unknown>, "call" | "running" | "accepted">;
+type ToolHandler = Pick<ToolCalls<unknown>, "call" | "running" | "accepted">;
 
 /** What the control plane asks of the run's messaging, by the agent whose socket asked. */
-export type MessagingHandler = Pick<
-  Messaging,
-  "checkFinish" | "peers" | "send" | "reply" | "owing"
->;
+type MessagingHandler = Pick<Messaging, "checkFinish" | "peers" | "send" | "reply" | "owing">;
 
 /** `wfa` accepts a 1 MiB value; escaped into the request's JSON it can double, plus the envelope. */
 const MAX_RESULT_REQUEST_BYTES = 2 * 1024 * 1024 + 4 * 1024;
@@ -97,7 +95,7 @@ export async function startResultControlPlane(options: {
   );
   const root = options.socketRoot ?? CONTROL_PLANE_ROOT;
   await mkdir(root, { recursive: true });
-  const directory = await mkdtemp(join(root, "awf-"));
+  const directory = await mkdtemp(join(root, DOORS_PREFIX));
   // Traversable but not listable: an agent reaches the one path it was given and cannot read the
   // directory to discover its siblings'. Close puts the read bit back so the tree can be removed.
   await chmod(directory, 0o300);
@@ -321,16 +319,17 @@ type Handlers = {
   lifetime: (milliseconds: number | undefined) => void;
 };
 
-async function handleFrame(frame: string, handlers: Handlers): Promise<ControlResponse> {
+async function handleFrame(frame: string, handlers: Handlers): Promise<Answer> {
   const { messaging, agentId } = handlers;
   const response = await answerFrame(frame, handlers);
+  if (inOtherVersion(response)) return response;
   // Leads every response, so what is owed comes back after a compaction; not one that already
   // says it, about the wait it began or the answer it is refused for.
   const repeats =
     response.kind === "awaiting-reply" ||
     (response.kind === "sent" && response.until !== undefined) ||
     (response.kind === "rejected" &&
-      (response.code === "owes-reply" || response.code === "awaiting"));
+      (response.code === "owes-reply" || response.code === "already-awaiting"));
   const owing = repeats ? undefined : messaging?.owing(agentId);
   return owing ? { ...response, owing } : response;
 }
@@ -338,7 +337,7 @@ async function handleFrame(frame: string, handlers: Handlers): Promise<ControlRe
 async function answerFrame(
   frame: string,
   { slots, messaging, tools, agentId, onSession, lifetime }: Handlers,
-): Promise<ControlResponse> {
+): Promise<Answer> {
   if (!frame.endsWith("\n") || frame.slice(0, -1).includes("\n")) {
     return rejected("invalid-request", "expected exactly one newline-delimited JSON request");
   }
@@ -350,7 +349,10 @@ async function answerFrame(
     return rejected("invalid-request", "request is not valid JSON");
   }
   const decoded = decodeControlRequest(parsed);
-  if (!decoded.ok) return rejected(decoded.code, decoded.error);
+  if (!decoded.ok)
+    return decoded.code === "unsupported-version"
+      ? otherVersion((parsed as { version: number }).version)
+      : rejected(decoded.code, decoded.error);
   // Before the result is judged: a rejected submission still proves which session sent it.
   if (decoded.value.session) onSession?.(decoded.value.session);
 
@@ -447,7 +449,35 @@ function rejected(
   return { version: WIRE_VERSION, kind: "rejected", code, error };
 }
 
-function queueResponse(socket: Bun.Socket<ConnectionState>, response: ControlResponse): void {
+/** A refusal in another wire version than this engine's: the one answer not a `ControlResponse`. */
+type OtherVersion = {
+  version: number;
+  kind: "rejected";
+  code: "unsupported-version";
+  error: string;
+};
+type Answer = ControlResponse | OtherVersion;
+
+function inOtherVersion(answer: Answer): answer is OtherVersion {
+  return answer.version !== WIRE_VERSION;
+}
+
+/**
+ * Refused in the version the request gave: a `wfa` of version 4 or 5 decodes a rejection of that
+ * shape and prints its error, where it would refuse this engine's version unread. They meet when
+ * awf is installed anew in place while a run is live: a launcher runs the `wfa` on disk, which is
+ * no longer the one the engine in memory shipped with.
+ */
+function otherVersion(version: number): OtherVersion {
+  return {
+    version,
+    kind: "rejected",
+    code: "unsupported-version",
+    error: `this wfa speaks wire version ${version} and the workflow engine ${WIRE_VERSION}: awf was installed anew while the run was live. Nothing was done; the run must go on under one version of awf.`,
+  };
+}
+
+function queueResponse(socket: Bun.Socket<ConnectionState>, response: Answer): void {
   socket.data.outgoing = Buffer.from(`${JSON.stringify(response)}\n`);
   socket.data.written = 0;
   flushResponse(socket);

package/src/coordinator-prompt.ts

@@ -1,7 +1,8 @@
 import { createInterface, type Interface } from "node:readline/promises";
+import { shellLine } from "./command-line";
 import type { CoordinatorHolder, CoordinatorPort } from "./coordinator-port";
+import { messageOf } from "./errors";
 import type { MessagingEventBody } from "./messaging/messaging";
-import { shellLine } from "./run-commands";
 
 /** Where the prompt reads a line: `awf run`'s terminal, or a test's script. */
 export type LineReader = {
@@ -13,7 +14,7 @@ export type LineReader = {
 };
 
 /** What the prompt shows beside the progress view, which holds its block while a prompt is open. */
-export type PromptOutput = {
+type PromptOutput = {
   /** A line in the run's log, above the progress block. */
   log(line: string): void;
   /** The progress block stops redrawing while a prompt waits for a line, and lines go above it. */
@@ -93,7 +94,7 @@ export function promptCoordinator(
       if (!question) return;
       // One that fails is said and passed over; the others are still asked.
       await ask(question).catch((error: unknown) =>
-        output.log(`awf: the prompt failed: ${error instanceof Error ? error.message : error}`),
+        output.log(`awf: the prompt failed: ${messageOf(error)}`),
       );
     }
   };