@agentswf/engine 0.1.0-beta.2 → 0.1.0-beta.4

package/src/coordinator-socket.ts

@@ -0,0 +1,236 @@
+import { createHash } from "node:crypto";
+import { chmod, mkdir, realpath, rm, stat } from "node:fs/promises";
+import { basename, dirname, isAbsolute, join, relative, sep } from "node:path";
+import type { ParticipantResultJson } from "@agentswf/contract/records";
+import { decodeHolderRequest, type NudgeWireResult } from "@agentswf/contract/wire";
+import type { CoordinatorHolder, CoordinatorPort } from "./coordinator-port";
+import { realPath } from "./files";
+import type { MessagingEventBody } from "./messaging/messaging";
+import type { RunStatus } from "./run-state";
+
+/** A request is a line of text and its JSON; well past a message's own 16 KB limit. */
+const MAX_REQUEST_BYTES = 256 * 1024;
+const CONNECTION_LIFETIME_MS = 30_000;
+
+type Connection = {
+  chunks: Buffer[];
+  bytes: number;
+  /** Its request was taken, answered or refused: nothing more is read. */
+  taken: boolean;
+  timer?: ReturnType<typeof setTimeout>;
+};
+
+/**
+ * A run's coordinator socket: named by a hash of its run directory, so any depth of directory fits
+ * `sun_path`'s 104 bytes, in a folder only the operator can open.
+ */
+export function coordinatorSocketPath(dir: string, runDir: string): string {
+  // Its real path: a holder reaching it through a symlink, or `/tmp` for `/private/tmp`, names it alike.
+  const name = createHash("sha256").update(realPath(runDir)).digest("hex").slice(0, 32);
+  return join(dir, `${name}.sock`);
+}
+
+/**
+ * Refuses a coordinator folder inside the workflow's directory, where its agents work, through
+ * symlinks too, and one given as a relative path, which each command would read from where it ran.
+ * Then makes it, the operator's alone, before any sandbox is resolved against it.
+ */
+export async function prepareCoordinatorDir(
+  dir: string,
+  workflowDir: string,
+  /** It was moved with `AWF_COORDINATOR_DIR`; `~/.awf`'s own is kept from sandboxes as `~/.awf` is. */
+  moved = true,
+): Promise<void> {
+  if (!isAbsolute(dir)) throw new Error(`AWF_COORDINATOR_DIR ${dir} is not an absolute path`);
+  const real = async (path: string): Promise<string> => {
+    try {
+      return await realpath(path);
+    } catch {
+      // Not there yet: its parent's real path, and its own name.
+      const parent = dirname(path);
+      return parent === path ? path : join(await real(parent), basename(path));
+    }
+  };
+  const inside = relative(await real(workflowDir), await real(dir));
+  const within =
+    inside === "" || !(inside === ".." || inside.startsWith(`..${sep}`) || isAbsolute(inside));
+  if (moved && within)
+    throw new Error(
+      `AWF_COORDINATOR_DIR ${dir} is inside the workflow's directory, where its agents work; move it out`,
+    );
+  await mkdir(dir, { recursive: true, mode: 0o700 });
+  await chmod(dir, 0o700);
+}
+
+/**
+ * The socket `awf reply` and `awf send` reach a live run through. It opens once the workflow
+ * connects an outside participant and goes when the run ends; each connection is one request
+ * line and one `ParticipantResultJson` line back.
+ */
+export function coordinatorSocket(options: {
+  dir: string;
+  runDir: string;
+  attempt: number;
+  /** Why the socket did not open: the run goes on, and no holder's command reaches it. */
+  failed(reason: string): void;
+  /** A nudge: the run's mailbox has a new event. Given, the socket opens at once, for awf's nudge. */
+  nudged?(): void;
+}): CoordinatorPort & { close(): Promise<void>; readonly path: string } {
+  const path = coordinatorSocketPath(options.dir, options.runDir);
+  let holder: CoordinatorHolder | undefined;
+  let listener: Bun.UnixSocketListener<{ chunks: Buffer[]; bytes: number }> | undefined;
+  let opening: Promise<void> | undefined;
+  let closed = false;
+  const id = (n: number) => `${options.attempt}.${n}`;
+
+  /** Undefined for a request no `awf` command makes: the connection closes unanswered. */
+  const answer = async (
+    frame: string,
+  ): Promise<ParticipantResultJson | NudgeWireResult | undefined> => {
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(frame);
+    } catch {
+      return undefined;
+    }
+    const decoded = decodeHolderRequest(parsed);
+    if (!decoded.ok) return undefined;
+    const request = decoded.value;
+    if (request.command === "nudge") {
+      if (!options.nudged) return undefined;
+      options.nudged();
+      return { v: 1, code: "nudged" };
+    }
+    if (!holder) return refused("no-participant", "the run has no participant connected");
+    // Another attempt's question is never open in this one: a number no message has.
+    const to =
+      request.to === undefined
+        ? undefined
+        : request.to.split(".")[0] === String(options.attempt)
+          ? Number(request.to.split(".")[1])
+          : 0;
+    const asked = {
+      ...(request.participant === undefined ? {} : { coordinator: request.participant }),
+      agent: request.agent,
+      ...(to === undefined ? {} : { to }),
+      text: request.text,
+      via: "command" as const,
+    };
+    const result =
+      request.command === "reply" ? await holder.reply(asked) : await holder.send(asked);
+    return result.code === "delivered"
+      ? { v: 1, code: "delivered", id: id(result.message) }
+      : {
+          v: 1,
+          code: result.code,
+          error: result.error,
+          ...(result.choices ? { choices: result.choices } : {}),
+        };
+  };
+
+  const open = async () => {
+    // A socket a killed run left here is no one's: this run's directory names it.
+    await rm(path, { force: true });
+    if (closed) return;
+    listener = Bun.listen<Connection>({
+      unix: path,
+      allowHalfOpen: true,
+      data: { chunks: [], bytes: 0, taken: false },
+      socket: {
+        open(socket) {
+          socket.data = {
+            chunks: [],
+            bytes: 0,
+            taken: false,
+            // Only while the request is read: an answer being made is never cut off.
+            timer: setTimeout(() => socket.terminate(), CONNECTION_LIFETIME_MS),
+          };
+        },
+        data(socket, data) {
+          if (socket.data.taken) return;
+          socket.data.bytes += data.byteLength;
+          if (socket.data.bytes > MAX_REQUEST_BYTES) {
+            take(socket);
+            socket.end(`${JSON.stringify(refused("too-large", "the request is too large"))}\n`);
+            return;
+          }
+          socket.data.chunks.push(Buffer.from(data));
+          // A request is one line: it is answered at its end, whether or not the client half-closes.
+          const text = Buffer.concat(socket.data.chunks).toString("utf8");
+          const newline = text.indexOf("\n");
+          if (newline >= 0) respond(socket, text.slice(0, newline));
+        },
+        end(socket) {
+          if (!socket.data.taken)
+            respond(socket, Buffer.concat(socket.data.chunks).toString("utf8"));
+        },
+        close(socket) {
+          clearTimeout(socket.data.timer);
+        },
+        error(socket) {
+          socket.terminate();
+        },
+      },
+    });
+    await chmod(path, 0o600);
+  };
+  const take = (socket: Bun.Socket<Connection>) => {
+    socket.data.taken = true;
+    clearTimeout(socket.data.timer);
+  };
+  const respond = (socket: Bun.Socket<Connection>, frame: string) => {
+    take(socket);
+    void answer(frame)
+      .catch(() => undefined)
+      .then((result) => socket.end(result ? `${JSON.stringify(result)}\n` : undefined));
+  };
+
+  if (options.nudged)
+    opening = open().catch((error: unknown) =>
+      options.failed(error instanceof Error ? error.message : String(error)),
+    );
+  return {
+    path,
+    attach(given) {
+      holder = given;
+    },
+    recorded(event: MessagingEventBody) {
+      if (event.kind === "participant-connected" && !opening) {
+        opening = open().catch((error: unknown) =>
+          options.failed(error instanceof Error ? error.message : String(error)),
+        );
+      }
+    },
+    async close() {
+      closed = true;
+      await opening;
+      listener?.stop(true);
+      if (listener) await rm(path, { force: true });
+    },
+  };
+}
+
+function refused(
+  code: Exclude<ParticipantResultJson["code"], "delivered">,
+  error: string,
+): ParticipantResultJson {
+  return { v: 1, code, error };
+}
+
+/**
+ * The socket of a run still live, or undefined: `run-state` decides, so a socket a killed run left
+ * behind is not trusted.
+ */
+export async function liveCoordinatorSocket(
+  dir: string,
+  status: Pick<RunStatus, "state" | "run">,
+): Promise<string | undefined> {
+  if (status.state !== "running") return undefined;
+  const path = coordinatorSocketPath(dir, status.run.dir);
+  return (await stat(path).then(
+    () => true,
+    () => false,
+  ))
+    ? path
+    : undefined;
+}

package/src/deadlines.ts

@@ -7,23 +7,29 @@ export class WorkflowCancelledError extends Error {
   }
 }
 
-/** Races `execute` against `signal` and `deadline`; losing the race does not stop `execute`. */
+/**
+ * Races `execute` against `signal` and `deadline`, if there is one; losing the race does not stop
+ * `execute`.
+ */
 export async function runUntilStopped<T>(
   execute: () => Promise<T>,
   signal: AbortSignal | undefined,
-  deadline: AbsoluteDeadline,
+  deadline: AbsoluteDeadline | undefined,
 ): Promise<T> {
   if (signal?.aborted) throw new WorkflowCancelledError(signal.reason);
-  if (Date.now() >= deadline.unixMilliseconds) throw new DeadlineExceededError(deadline);
+  if (deadline && Date.now() >= deadline.unixMilliseconds)
+    throw new DeadlineExceededError(deadline);
   let rejectStopped!: (error: Error) => void;
   const stopped = new Promise<never>((_resolve, reject) => {
     rejectStopped = reject;
   });
   const abort = () => rejectStopped(new WorkflowCancelledError(signal?.reason));
   signal?.addEventListener("abort", abort, { once: true });
-  const cancelDeadline = scheduleAt(deadline, () => {
-    rejectStopped(new DeadlineExceededError(deadline));
-  });
+  const cancelDeadline = deadline
+    ? scheduleAt(deadline, () => {
+        rejectStopped(new DeadlineExceededError(deadline));
+      })
+    : () => undefined;
   try {
     return await Promise.race([execute(), stopped]);
   } finally {
@@ -32,7 +38,11 @@ export async function runUntilStopped<T>(
   }
 }
 
-export function waitForDeadline<T>(promise: Promise<T>, deadline: AbsoluteDeadline): Promise<T> {
+export function waitForDeadline<T>(
+  promise: Promise<T>,
+  deadline: AbsoluteDeadline | undefined,
+): Promise<T> {
+  if (!deadline) return promise;
   let cancelTimer: (() => void) | undefined;
   const expired = new Promise<never>((_resolve, reject) => {
     cancelTimer = scheduleAt(deadline, () => reject(new DeadlineExceededError(deadline)));
@@ -60,7 +70,20 @@ export function scheduleAt(deadline: AbsoluteDeadline, action: () => void): () =
   };
 }
 
-export function earlierDeadline(left: AbsoluteDeadline, right: AbsoluteDeadline): AbsoluteDeadline {
+/** The earlier of two deadlines, an absent one being none. */
+export function earlierDeadline(
+  left: AbsoluteDeadline,
+  right: AbsoluteDeadline | undefined,
+): AbsoluteDeadline;
+export function earlierDeadline(
+  left: AbsoluteDeadline | undefined,
+  right: AbsoluteDeadline | undefined,
+): AbsoluteDeadline | undefined;
+export function earlierDeadline(
+  left: AbsoluteDeadline | undefined,
+  right: AbsoluteDeadline | undefined,
+): AbsoluteDeadline | undefined {
+  if (!left || !right) return left ?? right;
   return left.unixMilliseconds <= right.unixMilliseconds ? left : right;
 }
 
@@ -68,14 +91,18 @@ export function laterDeadline(left: AbsoluteDeadline, right: AbsoluteDeadline):
   return left.unixMilliseconds >= right.unixMilliseconds ? left : right;
 }
 
-export function deadlineWithin(milliseconds: number, ceiling: AbsoluteDeadline): AbsoluteDeadline {
+export function deadlineWithin(
+  milliseconds: number,
+  ceiling: AbsoluteDeadline | undefined,
+): AbsoluteDeadline {
   if (!Number.isSafeInteger(milliseconds) || milliseconds <= 0) {
     throw new Error("timeoutMs must be a positive safe integer");
   }
   return earlierDeadline({ unixMilliseconds: Date.now() + milliseconds }, ceiling);
 }
 
-export function assertDeadline(deadline: AbsoluteDeadline): void {
+export function assertDeadline(deadline: AbsoluteDeadline | undefined): void {
+  if (!deadline) return;
   assertDeadlineValue(deadline);
   if (Date.now() >= deadline.unixMilliseconds) {
     throw new DeadlineExceededError(deadline);
@@ -88,6 +115,16 @@ export function assertDeadlineValue(deadline: AbsoluteDeadline): void {
   }
 }
 
+/**
+ * What a harness bounds a run, an agent or a turn by when nothing else does. Workflow code sees no
+ * deadline then; a harness needs one, and a timer cannot wait past about 24.8 days.
+ */
+const HARNESS_BOUND_MS = 7 * 24 * 60 * 60_000;
+
+export function harnessDeadline(deadline: AbsoluteDeadline | undefined): AbsoluteDeadline {
+  return deadline ?? { unixMilliseconds: Date.now() + HARNESS_BOUND_MS };
+}
+
 /** Waits `milliseconds`, or until `signal` aborts, whichever is first. */
 export function abortableSleep(milliseconds: number, signal: AbortSignal): Promise<void> {
   return new Promise((resolve) => {

package/src/decisions/directory.ts

@@ -34,9 +34,9 @@ import {
 const MAX_ATTEMPTS = 3;
 const FIRST_BACKOFF_MILLISECONDS = 500;
 
-/** Where a call runs: its scope's deadline, and the scope's way of cancelling what it owns. */
+/** Where a call runs: its scope's deadline, if any, and the scope's way of cancelling what it owns. */
 export type DecisionScope = {
-  deadline: AbsoluteDeadline;
+  deadline: AbsoluteDeadline | undefined;
   /** Returns the removal. */
   add?(cancel: (reason: string) => Promise<unknown>): () => void;
   /** The workflow stage it is asked in. */
@@ -48,7 +48,7 @@ type PreparedCall = {
   ids: string[];
   resolved: { provider: string; model: string };
   provider: DecisionProvider;
-  deadline: AbsoluteDeadline;
+  deadline: AbsoluteDeadline | undefined;
   slot: number;
 };
 
@@ -165,7 +165,9 @@ export class RunDecisions {
       controller.abort(next.outcome);
     };
     const cancel = (reason: string) => end({ outcome: "cancelled", reason });
-    const cancelTimer = scheduleAt(deadline, () => end({ outcome: "timed-out", deadline }));
+    const cancelTimer = deadline
+      ? scheduleAt(deadline, () => end({ outcome: "timed-out", deadline }))
+      : () => undefined;
     this.#cancellers.add(cancel);
     const removeFromScope = scope.add?.(async (reason) => cancel(reason));
 
@@ -217,7 +219,7 @@ export class RunDecisions {
             thrown instanceof DecisionProviderError &&
             thrown.retryable &&
             attempts < MAX_ATTEMPTS &&
-            Date.now() + backoff < deadline.unixMilliseconds;
+            (!deadline || Date.now() + backoff < deadline.unixMilliseconds);
           if (!retry) break;
           await (this.options.sleep ?? abortableSleep)(backoff, controller.signal);
           if (ending) break;
@@ -291,7 +293,7 @@ export class RunDecisions {
     const { charged: _charged, ...returned } = settled;
 
     if (returned.outcome === "answered") return { answers: answers!, record: returned };
-    if (returned.outcome === "timed-out") throw new DeadlineExceededError(deadline);
+    if (returned.outcome === "timed-out") throw new DeadlineExceededError(deadline!);
     throw new DecisionError(`decision ${spec.key}: ${returned.error}`, returned);
   }
 }

package/src/duration.ts

@@ -10,3 +10,32 @@ export function parseDuration(value: string): number {
   if (!Number.isSafeInteger(milliseconds)) throw new Error(`duration is too large: ${value}`);
   return milliseconds;
 }
+
+/** `45s`, `6m40s`, `1h02m`. */
+export function duration(milliseconds: number): string {
+  const seconds = Math.max(0, Math.round(milliseconds / 1000));
+  if (seconds < 60) return `${seconds}s`;
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) return `${minutes}m${String(seconds % 60).padStart(2, "0")}s`;
+  return `${Math.floor(minutes / 60)}h${String(minutes % 60).padStart(2, "0")}m`;
+}
+
+/**
+ * When a timer given `when` is due, epoch ms, from `now`, and `when` as its record keeps it: a
+ * duration of days, hours or minutes as given, or a `Date` as an ISO time. A workflow's grammar,
+ * apart from the CLI's `parseDuration`: a wait is days long, and `1.5h` reads as written.
+ */
+export function parseWhen(when: unknown, now: number): { due: number; when: string } {
+  if (when instanceof Date) {
+    const due = when.getTime();
+    if (!Number.isFinite(due)) throw new Error("a timer's time is a valid Date");
+    return { due, when: when.toISOString() };
+  }
+  const matched = typeof when === "string" ? /^(\d+(?:\.\d+)?)(d|h|m)$/.exec(when) : null;
+  if (!matched)
+    throw new Error(
+      `a timer is due in days, hours or minutes, "14d", "4h", "1.5h", or at a Date; not ${String(when)}`,
+    );
+  const unit = matched[2] === "d" ? 86_400_000 : matched[2] === "h" ? 3_600_000 : 60_000;
+  return { due: now + Math.round(Number(matched[1]) * unit), when: when as string };
+}

package/src/emit-command.ts

@@ -0,0 +1,119 @@
+import type { EmitResultJson } from "@agentswf/contract/records";
+import { isEventWorkflow, type JsonValue } from "@agentswf/contract/workflow";
+import { EmitError, emitEvent } from "./emit";
+import { messageOf } from "./errors";
+import help from "./help/emit.txt" with { type: "text" };
+import type { Out } from "./run-commands";
+import type { Launch } from "./wake";
+import { loadWorkflowFile } from "./workflow-loader";
+
+export const emitUsage = help.trimEnd();
+
+export async function emitCommand(
+  argv: readonly string[],
+  shellCwd: string,
+  out: Out,
+  context: {
+    home: string;
+    environment: Readonly<Record<string, string | undefined>>;
+    launch?: Launch;
+  },
+): Promise<number> {
+  if (argv.includes("-h") || argv.includes("--help")) {
+    out.stdout(emitUsage);
+    return 0;
+  }
+  let parsed: {
+    target: string;
+    run: string;
+    name: string;
+    data: JsonValue;
+    id?: string;
+    json: boolean;
+  };
+  try {
+    parsed = parse(argv);
+  } catch (error) {
+    out.stderr(`awf: ${messageOf(error)}\n\n${emitUsage}`);
+    return 2;
+  }
+  let result: EmitResultJson;
+  try {
+    const loaded = await loadWorkflowFile(parsed.target, shellCwd);
+    if (!isEventWorkflow(loaded.workflow)) {
+      out.stderr(`awf: ${loaded.file} declares no events; awf run starts it`);
+      return 2;
+    }
+    result = await emitEvent(
+      loaded.workflow,
+      {
+        run: parsed.run,
+        name: parsed.name,
+        data: parsed.data,
+        ...(parsed.id === undefined ? {} : { id: parsed.id }),
+      },
+      { from: "operator", ...context },
+    );
+  } catch (error) {
+    out.stderr(`awf: ${messageOf(error)}`);
+    return error instanceof EmitError ? 2 : 1;
+  }
+  return printEmit(result, parsed.json, out);
+}
+
+/** Prints an emit's result, as `awf emit` and `awf send` do: 1 when the run's attempt didn't start. */
+export function printEmit(result: EmitResultJson, json: boolean, out: Out): number {
+  out.stdout(json ? JSON.stringify(result) : emitLine(result));
+  if (result.why !== "launch-failed") return 0;
+  out.stderr(`awf: the run's attempt did not start: ${result.error}`);
+  return 1;
+}
+
+/** `accepted dd-case/kombo: started`. */
+function emitLine(result: EmitResultJson): string {
+  const did = result.did === "none" ? result.why : result.did;
+  return `${result.outcome} ${result.ref}${did === undefined ? "" : `: ${did}`}`;
+}
+
+function parse(argv: readonly string[]): {
+  target: string;
+  run: string;
+  name: string;
+  data: JsonValue;
+  id?: string;
+  json: boolean;
+} {
+  let target: string | undefined;
+  let run: string | undefined;
+  let id: string | undefined;
+  let json = false;
+  const words: string[] = [];
+  for (let i = 0; i < argv.length; i++) {
+    const word = argv[i]!;
+    const value = () => {
+      const next = argv[++i];
+      if (next === undefined) throw new Error(`${word} needs a value`);
+      return next;
+    };
+    if (word === "--target") target = value();
+    else if (word === "--id") run = value();
+    else if (word === "--event-id") id = value();
+    else if (word === "--json") json = true;
+    else if (word.startsWith("--")) throw new Error(`unknown option ${word}`);
+    else words.push(word);
+  }
+  if (target === undefined) throw new Error("--target names the workflow file the event is for");
+  if (run === undefined) throw new Error("--id names the run the event is for, by its id");
+  const [name, text, ...more] = words;
+  if (name === undefined) throw new Error("the event's name is missing");
+  if (more.length > 0) throw new Error(`one event at a time; also given: ${more.join(" ")}`);
+  let data: JsonValue = null;
+  if (text !== undefined) {
+    try {
+      data = JSON.parse(text) as JsonValue;
+    } catch (error) {
+      throw new Error(`the event's data is not JSON: ${messageOf(error)}`);
+    }
+  }
+  return { target, run, name, data, ...(id === undefined ? {} : { id }), json };
+}