@agentswf/engine 0.1.0-beta.5 → 0.1.0

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

@@ -7,7 +7,10 @@ import { messageOf } from "./errors";
 import help from "./help/run.txt" with { type: "text" };
 import { SESSION_CODE } from "./here";
 import { KEEP_PANES, parseWorkspace } from "./pane-layout";
-import { idProblem, runRootOf, stageNameProblem } from "./runs";
+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();
 
@@ -47,17 +50,8 @@ export type RunCommand = {
   session?: string;
 };
 
-/** `awf run`'s options and workflow; `"help"` for a `-h` or `--help` anywhere before `--`. */
-export function parseCommand(
-  argv: readonly string[],
-  cwd: string,
-  /** Told each deprecated form given, once. */
-  deprecated: (line: string) => void = () => {},
-): 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;
@@ -102,7 +96,7 @@ export function parseCommand(
     const value = argv[index + 1];
     if (option === "--timeout") {
       if (!value) throw new Error("--timeout needs a duration such as 30m or 1d");
-      timeoutMilliseconds = parseDuration(value, "--timeout", deprecated);
+      timeoutMilliseconds = parseDuration(value, "--timeout");
       timeout = value;
     } else if (option === "--run-root") {
       if (!value) throw new Error("--run-root needs a directory");
@@ -117,7 +111,8 @@ export function parseCommand(
     } 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");
@@ -153,6 +148,10 @@ export function parseCommand(
   }
   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;
@@ -186,15 +185,7 @@ export function parseCommand(
 
 /** `--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}`);
@@ -202,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}`);
   }

package/src/run-commands.ts

@@ -1,98 +1,34 @@
+// What the commands that read runs say of one: its state, span and cost, and the commands that go
+// on from it.
 import { resolve } from "node:path";
-import type { AttemptRecord, RunLogLine } from "@agentswf/contract/records";
-import { maskCredentials } from "@agentswf/harness";
-import { continueCommand, shellWord } from "./attempt-view";
+import type { RunLogLine } from "@agentswf/contract/records";
+import { runEstimate, unknownOps } from "./accounting/spent";
+import { continueCommand } from "./attempt-view";
+import { command, type Out, placeFlags, type ReadPlace, shellLine } from "./command-line";
+import { NO_JSON, readFailureCode, refusalLine } from "./refusals";
 import type { RunCommand } from "./run-command";
 import { type Cursor, encodeCursor } from "./run-read";
 import { RunNotFound, type RunStatus } from "./run-state";
+import { clockTime } from "./run-text";
 import { runRootOf } from "./runs";
+import { readSpent } from "./spend";
 
-/** What `awf runs` and `awf logs` share: where they look, and how they say a run. */
-
-/** 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, with the place repeated. */
-export function command(place: ReadPlace, ...words: string[]): string[] {
-  const [first, second, ...rest] = words;
-  return [first!, second!, ...rest.slice(0, 1), ...place.repeat, ...rest.slice(1)];
-}
-
-/** A field whose name says it holds a credential, whatever its value looks like. */
-const SECRET_NAME =
-  /password|passwd|passphrase|passcode|secret|token|credential|cookie|bearer|authorization|(?:api|access|private|session|ssh|signing|encryption)[_-]?key|^(?:pwd|pass|pin|auth)$/i;
-
-/**
- * Every string in `value` masked, and everything under a credential's name hidden: a run's text,
- * errors and fields are its workflow's, its agents' and its tools'. Past `limit`, a string is cut.
- */
-export function masked(value: unknown, limit = Number.POSITIVE_INFINITY, hidden = false): unknown {
-  if (typeof value === "string") {
-    if (hidden) return "***";
-    const shown = maskCredentials(value);
-    return shown.length > limit ? `${shown.slice(0, limit - 1)}…` : shown;
-  }
-  if (hidden && value !== null && typeof value !== "object") return "***";
-  if (Array.isArray(value)) return value.map((each) => masked(each, limit, hidden));
-  if (value && typeof value === "object") {
-    return Object.fromEntries(
-      Object.entries(value).map(([key, each]) => [
-        key,
-        masked(each, limit, hidden || SECRET_NAME.test(key)),
-      ]),
-    );
-  }
-  return value;
-}
-
-/**
- * Text a run wrote, as one masked line of about `limit` characters, so it can never pass for a
- * line of its own or fill a page. `@{handle} --full` prints it whole.
- */
-export function said(text: string, limit = 120): string {
-  const line = maskCredentials(text).replace(/\s*[\r\n]+\s*/g, " ⏎ ");
-  return line.length > limit ? `${line.slice(0, limit - 1)}…` : line;
-}
-
-/** A suggested command as text to paste into a shell. */
-export function shellLine(words: readonly string[]): string {
-  return words.map(shellWord).join(" ");
-}
+/** The longest `--wait` the commands that read runs take. */
+export const MAX_WAIT_SECONDS = 300;
+/** How often they read a run while they wait. */
+export const POLL_MS = 1_000;
 
 /** Says a run that is not there, and exits 1; anything else is the run's files, exit 3. */
-export function failed(error: unknown, place: ReadPlace, out: Out, message: string): number {
+export function failed(
+  error: unknown,
+  place: ReadPlace,
+  out: Out,
+  message: string,
+  json: { json: boolean; v: number } = NO_JSON,
+): number {
+  // The error's own code; else a file that couldn't be read, exit 3's, or a failure of awf's.
+  const code = readFailureCode(error);
+  if (json.json) out.stdout(refusalLine(json.v, code, message));
   if (error instanceof RunNotFound) {
     out.stderr(`${error.message}; runs here: ${shellLine(command(place, "awf", "runs"))}`);
     return 1;
@@ -114,16 +50,6 @@ export function startedLine(
   return `awf: ${ref} started · watch: ${shellLine(["awf", "logs", ref, ...placeFlags(run)])}`;
 }
 
-/** 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] : []),
-  ];
-}
-
 /** `awf logs` from `cursor`: with `--wait` unless the page stopped short of the newest. */
 export function nextLogs(
   status: RunStatus,
@@ -205,22 +131,24 @@ export function span(
   return { started, ...(ended === undefined ? {} : { ended }), ms: (ended ?? now) - started };
 }
 
-/** At list prices, over the attempts that kept one: never what was billed. */
-export function estimateOf(attempts: readonly AttemptRecord[]): number | undefined {
-  const known = attempts.flatMap((each) =>
-    each.accounting?.totals.estimate === undefined ? [] : [each.accounting.totals.estimate],
+/**
+ * At list prices, today's, over the run's agent operations that recorded their spend, never what
+ * was billed; and how many operations' usage isn't known, which makes it a floor.
+ */
+export async function estimateOf(
+  status: RunStatus,
+): Promise<{ estimate?: number; unknown: number }> {
+  const spent = await readSpent(status.run.dir, status.attempts, { decisions: false }).catch(
+    () => undefined,
   );
-  return known.length > 0 ? known.reduce((total, each) => total + each, 0) : undefined;
-}
-
-/** `$6.10`; `<$0.01` for less, and nothing for none. */
-export function money(estimate: number | undefined): string[] {
-  if (!estimate) return [];
-  return [estimate < 0.005 ? "<$0.01" : `$${estimate.toFixed(2)}`];
-}
-
-export function clockTime(at: number | string): string {
-  const date = new Date(at);
-  const two = (n: number) => String(n).padStart(2, "0");
-  return `${two(date.getHours())}:${two(date.getMinutes())}:${two(date.getSeconds())}`;
+  if (!spent) return { unknown: 0 };
+  const estimate = runEstimate(spent);
+  // A running attempt's operations are read as it ends: not yet unknown.
+  const live = status.state === "running" ? status.attempts.at(-1)?.attempt : undefined;
+  return {
+    ...(estimate === undefined ? {} : { estimate }),
+    unknown: unknownOps(
+      spent.map((each) => (each.attempt === live ? { ...each, unsettled: 0 } : each)),
+    ),
+  };
 }

package/src/run-event-log.ts

@@ -41,7 +41,7 @@ export class RunEventLog {
     if (this.#closed) return;
     this.#writes.push(
       appendEvent(this.options.runDir, record).catch((error) =>
-        this.options.failed(`awf: a turn was not recorded in turns.jsonl: ${messageOf(error)}`),
+        this.options.failed(`awf: a turn was not recorded in log.jsonl: ${messageOf(error)}`),
       ),
     );
   }