@agentswf/engine 0.1.0-beta.4 → 0.1.0

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;
+}

package/src/refusals.ts

@@ -0,0 +1,119 @@
+import { ClientError, type ClientErrorCode } from "@agentswf/contract/client";
+import { REFUSAL_CODES, type RefusalCode, type RefusalJson } from "@agentswf/contract/records";
+import type { InboxCode, ParticipantCode } from "@agentswf/contract/wire";
+import { EmitError } from "./emit";
+import { messageOf } from "./errors";
+import { EngineRefused } from "./project-engine";
+import { RunNotFound } from "./run-state";
+import { isSystemError, RunUnreachable } from "./run-unreachable";
+import { RunRefused } from "./runs";
+import { WorkflowFileError } from "./workflow-loader";
+
+/** Every code a command refuses with. */
+type CommandCode = RefusalCode | ParticipantCode | InboxCode;
+
+/**
+ * The codes only a command prints: a program's call has no argv and reads no run's socket, and
+ * `internal-error` is the command's word for an error with no code, which the client throws as it
+ * is.
+ */
+const COMMAND_ONLY = new Set<RefusalCode>(
+  Object.keys({
+    usage: true,
+    ambiguous: true,
+    "not-started": true,
+    unreachable: true,
+    "internal-error": true,
+    "no-session": true,
+    live: true,
+    opened: true,
+    // Every code a client doesn't throw, so a new one is either a client's or listed here.
+  } satisfies Record<Exclude<RefusalCode, ClientErrorCode>, true>) as RefusalCode[],
+);
+
+/**
+ * The code an engine error is refused with, by a `--json` command and as a `ClientError` alike, so
+ * the two can't drift; none for an error that isn't the caller's.
+ */
+function refusalCode(error: unknown): RefusalCode | undefined {
+  return error instanceof EmitError ||
+    error instanceof EngineRefused ||
+    error instanceof RunNotFound ||
+    error instanceof WorkflowFileError ||
+    error instanceof RunUnreachable ||
+    error instanceof RunRefused
+    ? error.code
+    : undefined;
+}
+
+/** `code` as a client's word, when it is one: what a command refused with, read back. */
+export function clientCode(code: unknown): ClientErrorCode | undefined {
+  const known = (REFUSAL_CODES as readonly unknown[]).includes(code);
+  return known && !COMMAND_ONLY.has(code as RefusalCode) ? (code as ClientErrorCode) : undefined;
+}
+
+/**
+ * A failure while reading a run: the error's own code; else a system error, a file that couldn't
+ * be read, `unreachable`; else `internal-error`.
+ */
+export function readFailureCode(error: unknown): RefusalCode {
+  const cause = error instanceof Error ? error.cause : undefined;
+  return (
+    refusalCode(error) ??
+    (cause === undefined ? undefined : refusalCode(cause)) ??
+    (isSystemError(error) ? "unreachable" : "internal-error")
+  );
+}
+
+/** An engine error that is the caller's mistake as a `ClientError`; anything else as it is. */
+export function asClientError(error: unknown, ref?: string): unknown {
+  const code = refusalCode(error);
+  if (code === undefined || COMMAND_ONLY.has(code)) return error;
+  return new ClientError(code as ClientErrorCode, messageOf(error), ref);
+}
+
+/**
+ * A failure as a `--json` command prints it: the sentence on stderr, for people, and with `json`
+ * the refusal as stdout's last document. The code is the error's own, as `refusalCode` gives it;
+ * `otherwise` is the command's word for an error that has none. A caller's mistake never reaches a
+ * host as `internal-error`: it gets an error class `refusalCode` reads. `usage` follows the
+ * sentence.
+ */
+export function printRefusal(
+  out: { stdout(text: string): void; stderr(text: string): void },
+  json: { json: boolean; v: number },
+  error: unknown,
+  otherwise: CommandCode,
+  usage?: string,
+): void {
+  const sentence = messageOf(error);
+  if (json.json) out.stdout(refusalLine(json.v, refusalCode(error) ?? otherwise, sentence));
+  out.stderr(`awf: ${sentence}${usage === undefined ? "" : `\n\n${usage}`}`);
+}
+
+/** A refusal as its one line on stdout, for a command whose stderr says it in its own words. */
+export function refusalLine(
+  v: number,
+  code: CommandCode,
+  error: string,
+  choices?: string[],
+): string {
+  return JSON.stringify({
+    v,
+    code,
+    error,
+    ...(choices ? { choices } : {}),
+  } satisfies RefusalJson<CommandCode>);
+}
+
+/**
+ * Whether `argv` asks for `--json`, anywhere before `--`: what follows is a message's text or a
+ * workflow's arguments, which can't ask for it, and a usage error counts it before any parse.
+ */
+export function asksJson(argv: readonly string[]): boolean {
+  const end = argv.indexOf("--");
+  return (end < 0 ? argv : argv.slice(0, end)).includes("--json");
+}
+
+/** No `--json`: the failure on stderr only. */
+export const NO_JSON = { json: false, v: 0 };

package/src/result-slots.ts

@@ -4,11 +4,12 @@ import type { JsonSchema } from "@agentswf/contract/schema";
 import type { GivenInput, ResultSubmitCode } from "@agentswf/contract/wire";
 import type { AbsoluteDeadline } from "@agentswf/contract/workflow";
 import { scheduleAt } from "./deadlines";
+import { messageOf } from "./errors";
+import { recordAnswer, writeAcceptedExclusive } from "./ops";
 import { evaluateGiven } from "./result-validation";
-import { recordCandidate, writeAcceptedExclusive, writeCall } from "./runs";
 
-export type ResultRejectionCode = ResultSubmitCode;
-export type ResultSlotAccepted = {
+type ResultRejectionCode = ResultSubmitCode;
+type ResultSlotAccepted = {
   kind: "accepted";
   value: unknown;
   candidateRecorded: boolean;
@@ -18,8 +19,8 @@ export type ResultSlotAccepted = {
   acceptedAt: number;
 };
 type Rejected = { kind: "rejected"; code: ResultRejectionCode; error: string };
-export type ResultSubmission = ResultSlotAccepted | Rejected;
-export type WaitingGrant = { kind: "waiting"; waitUntil: number; deadline?: number };
+type ResultSubmission = ResultSlotAccepted | Rejected;
+type WaitingGrant = { kind: "waiting"; waitUntil: number; deadline?: number };
 export type ResultSlotSettlement =
   | ResultSlotAccepted
   | { kind: "closed" }
@@ -29,7 +30,7 @@ export type ResultSlotEvent =
   | { kind: "waiting"; reason: string; waitUntil: number; at: number; revision: number }
   | { kind: "admitted"; admittedAt: number; revision: number }
   | { kind: "persisted"; accepted: ResultSlotAccepted; revision: number };
-export type ResultSlotBinding = { operationId: string; settled: Promise<ResultSlotSettlement> };
+type ResultSlotBinding = { operationId: string; settled: Promise<ResultSlotSettlement> };
 export type ResultSlotSpec = {
   operationId: string;
   agentId: string;
@@ -52,8 +53,7 @@ export type ResultSlotRegistryOptions = {
   waitMinimumMs?: number;
 };
 interface ResultSlotPersistence {
-  writeCall: typeof writeCall;
-  recordCandidate: typeof recordCandidate;
+  recordAnswer: typeof recordAnswer;
   writeAcceptedExclusive: typeof writeAcceptedExclusive;
 }
 type SubmissionInput = {
@@ -84,7 +84,7 @@ type Slot = ResultSlotSpec & {
 export function createResultSlotRegistry(options: ResultSlotRegistryOptions): ResultSlotRegistry {
   const now = options.now ?? Date.now;
   const schedule = options.schedule ?? scheduleExpiry;
-  const persistence = options.persistence ?? { writeCall, recordCandidate, writeAcceptedExclusive };
+  const persistence = options.persistence ?? { recordAnswer, writeAcceptedExclusive };
   const persistenceMs = duration(options.persistenceMs, 5_000);
   const auditMs = duration(options.auditMs, 1_000);
   const waitDefaultMs = duration(options.waitDefaultMs, 120_000);
@@ -106,7 +106,7 @@ export function createResultSlotRegistry(options: ResultSlotRegistryOptions): Re
     try {
       await bounded(
         Promise.resolve().then(() =>
-          persistence.recordCandidate(options.runDir, slot.operationId, {
+          persistence.recordAnswer(options.runDir, slot.operationId, {
             at: new Date(now()).toISOString(),
             source: input.source,
             // Flags as given, whether or not they convert, so the record shows what the agent typed.
@@ -143,26 +143,6 @@ export function createResultSlotRegistry(options: ResultSlotRegistryOptions): Re
       });
       const slot: Slot = { ...spec, state: "open", settle, cancelExpiry: () => {}, revision: 0 };
       slots.set(spec.operationId, slot);
-      try {
-        await bounded(
-          Promise.resolve().then(() =>
-            persistence.writeCall(options.runDir, {
-              callId: spec.operationId,
-              question: spec.question,
-              ...(spec.schema ? { schema: spec.schema } : {}),
-            }),
-          ),
-          persistenceMs,
-          "call persistence timed out",
-        );
-      } catch (error) {
-        if (error instanceof SlotTimeoutError) {
-          // The old write may still publish; its operation ID must never be reused.
-          slot.state = "failed";
-          slot.settle({ kind: "failed", reason: error.message });
-        } else slots.delete(spec.operationId);
-        throw error;
-      }
       if (slot.state === "open") expireAt(slot);
       return { operationId: spec.operationId, settled };
     },
@@ -253,7 +233,7 @@ export function createResultSlotRegistry(options: ResultSlotRegistryOptions): Re
           },
           () => {},
         );
-        const reason = error instanceof Error ? error.message : String(error);
+        const reason = messageOf(error);
         if (slot.state === "committing") {
           slot.state = "failed";
           slot.settle({ kind: "failed", reason });

package/src/result-validation.ts

@@ -1,5 +1,5 @@
 import { acceptAny, type SemanticCheck } from "@agentswf/contract";
-import type { CallSpec } from "@agentswf/contract/records";
+import type { JsonSchema } from "@agentswf/contract/schema";
 import type { GivenInput } from "@agentswf/contract/wire";
 import { checkGiven, readGiven } from "./simple-input";
 
@@ -12,7 +12,7 @@ export type CandidateEvaluation =
  * owns acceptance.
  */
 export async function evaluateGiven(
-  call: Pick<CallSpec, "question" | "schema">,
+  call: { question: string; schema?: JsonSchema },
   given: GivenInput,
   semantic: SemanticCheck = acceptAny,
 ): Promise<CandidateEvaluation> {

package/src/run-command.ts

@@ -1,11 +1,16 @@
 import { readFileSync, statSync } from "node:fs";
 import { resolve } from "node:path";
-import type { JsonValue } from "@agentswf/contract/workflow";
+import type { RunPanes } from "@agentswf/contract/records";
+import type { JsonValue, KeepPane } from "@agentswf/contract/workflow";
 import { parseDuration } from "./duration";
 import { messageOf } from "./errors";
 import help from "./help/run.txt" with { type: "text" };
 import { SESSION_CODE } from "./here";
-import { idProblem, runRootOf, stageNameProblem } from "./runs";
+import { KEEP_PANES, parseWorkspace } from "./pane-layout";
+import { idProblem, RunRefused, runRootOf, stageNameProblem } from "./runs";
+
+/** `awf run --json`'s `"v"`, which its refusals carry too. */
+export const RUN_V = 1;
 
 export const usage = help.trimEnd();
 
@@ -37,18 +42,16 @@ export type RunCommand = {
   watch: boolean;
   /** The sandbox every agent runs in, as `--sandbox`'s file gave it. */
   sandbox?: unknown;
+  /** `--workspace` and `--keep-panes`, which the run records; absent, neither was given. */
+  panes?: RunPanes;
   /** Started from an agent's shell: start the run in a tab and take that session over. */
   here: boolean;
   /** The code the calling session replies with, which the run finds it by. */
   session?: string;
 };
 
-/** `awf run`'s options and workflow; `"help"` for a `-h` or `--help` anywhere before `--`. */
-export function parseCommand(argv: readonly string[], cwd: string): RunCommand | "help" {
-  if (argv[0] !== "run") throw new Error("expected the run command");
-  const end = argv.indexOf("--");
-  const own = end < 0 ? argv : argv.slice(0, end);
-  if (own.includes("-h") || own.includes("--help")) return "help";
+/** `awf run`'s options and workflow. */
+export function parseCommand(argv: readonly string[], cwd: string): RunCommand {
   let timeout: string | undefined;
   let timeoutMilliseconds: number | undefined;
   let runRoot: string | undefined;
@@ -63,6 +66,7 @@ export function parseCommand(argv: readonly string[], cwd: string): RunCommand |
   let sandbox: unknown;
   let here = false;
   let session: string | undefined;
+  const panes: RunPanes = {};
   let workflowFile: string | undefined;
   // awf's own options may come before or after the workflow file; only `--` ends them.
   let index = 1;
@@ -91,8 +95,8 @@ export function parseCommand(argv: readonly string[], cwd: string): RunCommand |
     }
     const value = argv[index + 1];
     if (option === "--timeout") {
-      if (!value) throw new Error("--timeout needs a duration such as 30m");
-      timeoutMilliseconds = parseDuration(value);
+      if (!value) throw new Error("--timeout needs a duration such as 30m or 1d");
+      timeoutMilliseconds = parseDuration(value, "--timeout");
       timeout = value;
     } else if (option === "--run-root") {
       if (!value) throw new Error("--run-root needs a directory");
@@ -107,7 +111,8 @@ export function parseCommand(argv: readonly string[], cwd: string): RunCommand |
     } else if (option === "--id") {
       if (!value) throw new Error("--id needs a run's id");
       const problem = idProblem(value);
-      if (problem) throw new Error(`--id: ${problem}`);
+      // Refused as any id the grammar refuses is, `id`, still a usage error's exit.
+      if (problem) throw new RunRefused(`--id: ${problem}`, "id");
       named = value;
     } else if (option === "--from-stage") {
       if (!value) throw new Error("--from-stage needs a stage's name");
@@ -122,6 +127,16 @@ export function parseCommand(argv: readonly string[], cwd: string): RunCommand |
       if (!value || !SESSION_CODE.test(value))
         throw new Error("--session needs the code --here printed");
       session = value;
+    } else if (option === "--workspace") {
+      if (!value?.trim() || value.startsWith("-"))
+        throw new Error("--workspace needs run, origin or a workspace's name");
+      if (panes.workspace !== undefined) throw new Error("--workspace given twice");
+      panes.workspace = parseWorkspace(value);
+    } else if (option === "--keep-panes") {
+      if (!KEEP_PANES.includes(value as KeepPane))
+        throw new Error("--keep-panes needs never, on-failure or always");
+      if (panes.keep !== undefined) throw new Error("--keep-panes given twice");
+      panes.keep = value as KeepPane;
     } else if (option === "--sandbox") {
       if (!value) throw new Error("--sandbox needs a JSON file");
       if (sandbox !== undefined) throw new Error("--sandbox given twice");
@@ -133,6 +148,10 @@ export function parseCommand(argv: readonly string[], cwd: string): RunCommand |
   }
   if (!workflowFile) throw new Error("run needs one workflow file");
   if (here && session !== undefined) throw new Error("--here and --session do not go together");
+  if (here && json)
+    throw new Error(
+      "--here prints what the calling agent does next, no document: leave out --json",
+    );
   if (continuing && named === undefined)
     throw new Error("--continue goes on with the run --id names");
   const id = continuing ? undefined : named;
@@ -160,20 +179,13 @@ export function parseCommand(argv: readonly string[], cwd: string): RunCommand |
     here,
     ...(session === undefined ? {} : { session }),
     ...(sandbox === undefined ? {} : { sandbox }),
+    ...(Object.keys(panes).length === 0 ? {} : { panes }),
   };
 }
 
 /** `--values`'s file: a JSON object of stage values, by stage name. */
 function readValues(file: string): NonNullable<RunCommand["values"]> {
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(readFileSync(file, "utf8"));
-  } catch (error) {
-    throw new Error(`--values: ${messageOf(error)}`);
-  }
-  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
-    throw new Error(`--values: ${file} must hold a JSON object, each stage's value by its name`);
-  }
+  const parsed = readJsonObject(file, "--values", "each stage's value by its name");
   for (const stage of Object.keys(parsed)) {
     const problem = stageNameProblem(stage);
     if (problem) throw new Error(`--values: ${problem}`);
@@ -181,17 +193,22 @@ function readValues(file: string): NonNullable<RunCommand["values"]> {
   return { file, stages: new Map(Object.entries(parsed as Record<string, JsonValue>)) };
 }
 
-/** `--sandbox`'s file: an inline sandbox spec, whose working directory is the run's. */
-function readSandboxSpec(file: string): object {
-  let spec: unknown;
+/** `flag`'s file, which must hold a JSON object: `what`, as its refusal says. */
+function readJsonObject(file: string, flag: string, what: string): object {
+  let parsed: unknown;
   try {
-    spec = JSON.parse(readFileSync(file, "utf8"));
+    parsed = JSON.parse(readFileSync(file, "utf8"));
   } catch (error) {
-    throw new Error(`--sandbox: ${messageOf(error)}`);
-  }
-  if (typeof spec !== "object" || spec === null || Array.isArray(spec)) {
-    throw new Error(`--sandbox: ${file} must hold a JSON object, a sandbox spec`);
+    throw new Error(`${flag}: ${messageOf(error)}`);
   }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+    throw new Error(`${flag}: ${file} must hold a JSON object, ${what}`);
+  return parsed;
+}
+
+/** `--sandbox`'s file: an inline sandbox spec, whose working directory is the run's. */
+function readSandboxSpec(file: string): object {
+  const spec = readJsonObject(file, "--sandbox", "a sandbox spec");
   for (const [field, why] of Object.entries(NOT_IN_A_RUN_SANDBOX)) {
     if (field in spec) throw new Error(`--sandbox: the run's sandbox names no ${field}; ${why}`);
   }