@agentswf/engine 0.0.0-stage → 0.1.0-beta.0

package/src/decisions/seam.ts

@@ -0,0 +1,70 @@
+import type { Money } from "@agentswf/contract/records";
+import type { JsonObject, JsonValue, Question } from "@agentswf/contract/workflow";
+
+/**
+ * A question's distribution, as awf shapes it, before the picks are derived: a choice's by option
+ * name, a score's by level index.
+ */
+export type ProviderAnswer =
+  | { type: "choice"; probabilities: Record<string, number> }
+  | { type: "score"; probabilities: number[] }
+  | { type: "yes-no"; yes: number };
+
+export type ProviderRequest = {
+  /** The call's key, as the workflow named it. */
+  key: string;
+  model: string;
+  state: string | JsonObject | JsonValue[];
+  questions: Record<string, Question>;
+};
+
+export type ProviderResponse = {
+  /** The versioned model that answered. */
+  snapshot: string;
+  answers: Record<string, ProviderAnswer>;
+  /** Absent when the provider did not report them: unknown, not zero. */
+  tokens?: { input: number; output: number };
+  charged?: Money;
+  requestId?: string;
+};
+
+/**
+ * One kind of decision model behind one API. It sends one request and translates both ways; the
+ * directory owns deadlines, retries and records.
+ */
+export interface DecisionProvider {
+  decide(request: ProviderRequest, signal: AbortSignal): Promise<ProviderResponse>;
+}
+
+/** A request the provider refused or could not complete. Whatever it reported spending is kept. */
+export class DecisionProviderError extends Error {
+  readonly retryable: boolean;
+  readonly tokens?: { input: number; output: number };
+  readonly charged?: Money;
+  readonly requestId?: string;
+
+  constructor(
+    message: string,
+    options: {
+      retryable: boolean;
+      tokens?: { input: number; output: number };
+      charged?: Money;
+      requestId?: string;
+    },
+  ) {
+    super(message);
+    this.name = "DecisionProviderError";
+    this.retryable = options.retryable;
+    if (options.tokens) this.tokens = options.tokens;
+    if (options.charged) this.charged = options.charged;
+    if (options.requestId) this.requestId = options.requestId;
+  }
+}
+
+/** What the operator runtime installed: providers by name, and the aliases workflows ask for. */
+export type DecisionInstallation = {
+  providers: Readonly<Record<string, DecisionProvider>>;
+  aliases: Readonly<Record<string, { provider: string; model: string }>>;
+  /** Aliases that could not be installed, and why, so asking for one says what to fix. */
+  unavailable?: Readonly<Record<string, string>>;
+};

package/src/display-path.ts

@@ -0,0 +1,16 @@
+import { isAbsolute, relative, resolve } from "node:path";
+
+/**
+ * `path` as typed from `cwd`: relative under it, absolute elsewhere, so it works from anywhere; with
+ * `home`, one under that home folder from `~`, shorter to read, though a quoted shell word won't
+ * expand it.
+ */
+export function pathFrom(cwd: string, path: string, options: { home?: string } = {}): string {
+  const absolute = resolve(cwd, path);
+  const inside = relative(cwd, absolute);
+  if (inside && !inside.startsWith("..") && !isAbsolute(inside)) return inside;
+  const { home } = options;
+  return home !== undefined && absolute.startsWith(`${home}/`)
+    ? `~${absolute.slice(home.length)}`
+    : absolute;
+}

package/src/duration.ts

@@ -0,0 +1,12 @@
+/** A duration such as `500ms`, `30s`, `20m` or `2h`, in milliseconds. */
+export function parseDuration(value: string): number {
+  const matched = /^(\d+)(ms|s|m|h)$/.exec(value);
+  if (!matched) throw new Error(`invalid duration: ${value}`);
+  const amount = Number(matched[1]);
+  if (!Number.isSafeInteger(amount) || amount <= 0) throw new Error(`invalid duration: ${value}`);
+  const unit = matched[2];
+  const multiplier = unit === "ms" ? 1 : unit === "s" ? 1_000 : unit === "m" ? 60_000 : 3_600_000;
+  const milliseconds = amount * multiplier;
+  if (!Number.isSafeInteger(milliseconds)) throw new Error(`duration is too large: ${value}`);
+  return milliseconds;
+}

package/src/errors.ts

@@ -0,0 +1,4 @@
+/** An error's message, or the thrown value as text. */
+export function messageOf(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/src/files.ts

@@ -0,0 +1,78 @@
+import { randomBytes } from "node:crypto";
+import { link, lstat, open, rename, unlink } from "node:fs/promises";
+import { dirname, join } from "node:path";
+
+/**
+ * Writes `value` to `path` whole: a temp file beside it, synced, then renamed into place. A crash
+ * leaves the old file or the new one, never half of either.
+ */
+export async function writeJson(path: string, value: unknown): Promise<void> {
+  await writeWhole(path, jsonText(value));
+}
+
+/** As `writeJson`, for text. */
+export async function writeWhole(path: string, text: string): Promise<void> {
+  const temporary = temporaryBeside(path);
+  try {
+    await writeSynced(temporary, text);
+    await rename(temporary, path);
+  } catch (error) {
+    await unlink(temporary).catch(() => undefined);
+    throw error;
+  }
+}
+
+/**
+ * Links a complete file holding `value` to `path`, which fails when `path` exists: the first to
+ * link holds it. False when it was taken.
+ */
+export async function linkNew(path: string, value: unknown): Promise<boolean> {
+  const temporary = temporaryBeside(path);
+  try {
+    await writeSynced(temporary, jsonText(value));
+    await link(temporary, path);
+    return true;
+  } catch (error) {
+    if (isCode(error, "EEXIST")) return false;
+    throw error;
+  } finally {
+    // The linked inode remains; one left behind is a private temp file a sweep removes.
+    await unlink(temporary).catch(() => undefined);
+  }
+}
+
+/** Creates `path`, which must not exist, holding `text`, synced. */
+async function writeSynced(path: string, text: string): Promise<void> {
+  const handle = await open(path, "wx", 0o600);
+  try {
+    await handle.writeFile(text);
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+}
+
+/** Whether `path` names anything, a dangling link included. */
+export async function exists(path: string): Promise<boolean> {
+  return lstat(path).then(
+    () => true,
+    () => false,
+  );
+}
+
+/** Whether `error` is a system error with one of `codes`, such as `ENOENT`. */
+export function isCode(error: unknown, ...codes: string[]): boolean {
+  return (
+    error instanceof Error &&
+    "code" in error &&
+    codes.includes(String((error as { code: unknown }).code))
+  );
+}
+
+function jsonText(value: unknown): string {
+  return `${JSON.stringify(value, null, 2)}\n`;
+}
+
+function temporaryBeside(path: string): string {
+  return join(dirname(path), `.tmp-${randomBytes(6).toString("hex")}`);
+}

package/src/herdr-placement.ts

@@ -0,0 +1,182 @@
+import { createHash } from "node:crypto";
+import { mkdir, rename, rmdir, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { HERDR_VERSION, type RunProcess } from "@agentswf/harness";
+import { messageOf } from "./errors";
+import { ensureRunSession, parseSessions, type RunSessionDeps } from "./herdr-run-session";
+import { machinePaths } from "./machine";
+
+/** Where a layout may open a session awf does not otherwise use: one named `awf-…` it starts. */
+const OWN_SESSION = /^awf(-|$)/;
+const LOCK_POLL_MS = 100;
+/** Held inside a session's queue: a short wait, then made anyway. */
+const LOCK_WAIT_MS = 5_000;
+/** A lock older than this was left by a run that died holding it. */
+const LOCK_STALE_MS = 30_000;
+
+/**
+ * Whether a session a layout names can be used: undefined when it can, else why not. One named
+ * `awf-…` is started, swept and restarted as the run session is; any other must be running. Either
+ * must answer, on the Herdr the adapter drives.
+ */
+export async function namedSession(
+  name: string,
+  deps: RunSessionDeps,
+): Promise<string | undefined> {
+  if (OWN_SESSION.test(name)) {
+    try {
+      await ensureRunSession(name, deps);
+    } catch (error) {
+      return messageOf(error);
+    }
+  } else {
+    const listed = await deps.run({
+      argv: ["herdr", "session", "list", "--json"],
+      timeoutMs: 10_000,
+    });
+    const found = parseSessions(listed.stdout).find((session) => session.name === name);
+    if (!found?.running) {
+      return "it is not running, and awf starts only sessions named awf-…";
+    }
+  }
+  return wrongVersion(name, deps.run);
+}
+
+/** Why the session's server is not the Herdr the adapter drives; undefined when it is. */
+async function wrongVersion(session: string, run: RunProcess): Promise<string | undefined> {
+  const status = await run({
+    argv: ["herdr", "--session", session, "status", "server", "--json"],
+    timeoutMs: 10_000,
+  });
+  if (status.exitCode !== 0) return "it does not answer";
+  let version: unknown;
+  try {
+    version = JSON.parse(status.stdout).version;
+  } catch {
+    return "its status could not be read";
+  }
+  const driven = HERDR_VERSION.replace(/^herdr /, "");
+  return version === driven ? undefined : `it runs Herdr ${String(version)}, not ${driven}`;
+}
+
+export type OriginDeps = {
+  run: RunProcess;
+  environment: Readonly<Record<string, string | undefined>>;
+  /** The run session, which `"origin"` must not be. */
+  runSession: string;
+  /** The calling session's pane under `--here`, found before the workflow started. */
+  callerPane?: string;
+  /** This process, whose ancestors include the shell `awf run` was typed in. */
+  pid?: number;
+};
+
+/**
+ * The workspace `awf run` was typed in, and its session; why not, where it can't be used. Read
+ * from Herdr, never from `HERDR_WORKSPACE_ID`, which a codex shell inherits from its daemon (E8).
+ */
+export async function findOrigin(
+  deps: OriginDeps,
+): Promise<{ session: string; workspaceId: string } | string> {
+  const { run, environment } = deps;
+  const socket = environment.HERDR_SOCKET_PATH;
+  if (!socket) return "awf run was not started in a Herdr pane";
+  const listed = await run({ argv: ["herdr", "session", "list", "--json"], timeoutMs: 10_000 });
+  const session = parseSessions(listed.stdout).find((found) => found.socketPath === socket)?.name;
+  if (!session) return `no Herdr session owns ${socket}`;
+  if (session === deps.runSession) {
+    return `it is the run session, ${session}, whose workspaces are runs'`;
+  }
+  const herdr = (args: string[]) =>
+    run({ argv: ["herdr", "--session", session, ...args], timeoutMs: 10_000 });
+  const stale = await wrongVersion(session, run);
+  if (stale) return `its session ${session}: ${stale}`;
+  let paneId = deps.callerPane;
+  if (!paneId) {
+    paneId = environment.HERDR_PANE_ID;
+    if (!paneId) return "HERDR_PANE_ID is not set";
+    // A codex shell inherits its daemon's HERDR_PANE_ID, which names another pane (E8).
+    const info = await herdr(["pane", "process-info", "--pane", paneId]);
+    const shell = info.exitCode === 0 ? readShell(info.stdout) : undefined;
+    if (shell === undefined) return `pane ${paneId} could not be read`;
+    if (!(await ancestors(run, deps.pid ?? process.pid)).includes(shell)) {
+      return `HERDR_PANE_ID names pane ${paneId}, which awf run was not typed in`;
+    }
+  }
+  const got = await herdr(["pane", "get", paneId]);
+  let workspaceId: unknown;
+  try {
+    workspaceId = JSON.parse(got.stdout).result?.pane?.workspace_id;
+  } catch {}
+  if (got.exitCode !== 0 || typeof workspaceId !== "string") {
+    return `pane ${paneId}'s workspace could not be read`;
+  }
+  return { session, workspaceId };
+}
+
+function readShell(stdout: string): number | undefined {
+  try {
+    const shell = JSON.parse(stdout).result?.process_info?.shell_pid;
+    return typeof shell === "number" ? shell : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** `pid`'s parent, its parent's, and so on, as `ps` gives them. */
+async function ancestors(run: RunProcess, pid: number): Promise<number[]> {
+  const found: number[] = [];
+  for (let current = pid; current > 1 && found.length < 64; ) {
+    const parent = await run({
+      argv: ["ps", "-o", "ppid=", "-p", String(current)],
+      timeoutMs: 5_000,
+    });
+    const next = Number(parent.stdout.trim());
+    if (parent.exitCode !== 0 || !Number.isInteger(next) || next <= 0) break;
+    found.push(next);
+    current = next;
+  }
+  return found;
+}
+
+/**
+ * Holds `name` in `session` against other runs while its workspace is looked for and made, so two
+ * runs make one. A directory, made or not in one step; one left by a run that died expires.
+ */
+export function workspaceLock(home: string) {
+  return async (session: string, name: string): Promise<() => Promise<void>> => {
+    const digest = createHash("sha256").update(name).digest("hex").slice(0, 16);
+    const dir = join(machinePaths(home).herdr, "locks", session);
+    const lock = join(dir, digest);
+    await mkdir(dir, { recursive: true });
+    const by = Date.now() + LOCK_WAIT_MS;
+    for (;;) {
+      try {
+        await mkdir(lock);
+        return () => rmdir(lock).catch(() => undefined);
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+      }
+      const made = await stat(lock).then(
+        (found) => found.mtimeMs,
+        () => undefined,
+      );
+      if (made !== undefined && Date.now() - made > LOCK_STALE_MS) {
+        // Moved aside first: of two waiters that saw it stale, only one moves it, and neither
+        // removes a lock the other has just taken.
+        const aside = `${lock}.${process.pid}.${Date.now()}`;
+        if (
+          await rename(lock, aside).then(
+            () => true,
+            () => false,
+          )
+        ) {
+          await rmdir(aside).catch(() => undefined);
+        }
+        continue;
+      }
+      // Taking it anyway makes at worst a second workspace of the name, which is still usable.
+      if (Date.now() >= by) return async () => undefined;
+      await Bun.sleep(LOCK_POLL_MS);
+    }
+  };
+}