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

package/src/herdr-workspace-marks.ts

@@ -0,0 +1,194 @@
+import { randomBytes } from "node:crypto";
+import { mkdir, readdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { machinePaths } from "./machine";
+import { type ProcessProbe, processStart, sameProcess } from "./runs";
+
+export const WORKSPACE_MARK_VERSION = 2;
+
+/**
+ * A run's claim on its workspace in a shared Herdr session: the run's process, and when that
+ * started, which tells a reused pid apart. Written before the workspace exists, so a session in
+ * use is never taken for empty, and given the workspace's id once it does: only that id is ever
+ * closed by it, as a label is unique only within its project's runs.
+ */
+export type WorkspaceMark = {
+  /** 1 names only the workspace; an older awf reads only 1, and leaves a newer run's alone. */
+  version: 1 | typeof WORKSPACE_MARK_VERSION;
+  label: string;
+  pid: number;
+  processStart: string;
+  workspaceId?: string;
+  /**
+   * Every pane the run made and has not closed, by the session it is in, its own workspace's
+   * included: a pane closes by id and terminal id both, as Herdr's pane ids repeat.
+   */
+  panes?: Record<string, MarkedPane[]>;
+  /** The run ended, leaving the panes it kept: this mark outlives it until they are gone. */
+  ended?: true;
+};
+
+/** As the Herdr host reports a pane it made (`MadePane`); kept apart, as this is the record. */
+export type MarkedPane = { paneId: string; terminalId?: string; workspaceId: string; kept?: true };
+
+export type Liveness = "live" | "dead" | "unknown";
+
+export type HeldMark = {
+  /** The workspace this run created. */
+  bind(workspaceId: string): Promise<void>;
+  /** Every pane the run has made in `session` and not closed. */
+  panes(session: string, panes: readonly MarkedPane[]): Promise<void>;
+  /** At the run's end: removed, or, where it kept panes, rewritten to name only those. */
+  release(): Promise<void>;
+};
+
+export function marksDir(home: string, session: string): string {
+  return join(machinePaths(home).herdr, "sessions", session, "workspaces");
+}
+
+/**
+ * Marks the workspace labelled `label` as this process's, a file of its own. Best effort: a run
+ * whose mark can't be written still runs, and its workspace reads as nobody's, which is kept.
+ */
+export async function markWorkspace(
+  home: string,
+  session: string,
+  label: string,
+  probe: ProcessProbe = processStart,
+): Promise<HeldMark> {
+  const unmarked: HeldMark = {
+    bind: async () => undefined,
+    panes: async () => undefined,
+    release: async () => undefined,
+  };
+  const started = probe(process.pid);
+  if (started === undefined) return unmarked;
+  const dir = marksDir(home, session);
+  const file = join(dir, `${process.pid}-${randomBytes(4).toString("hex")}.json`);
+  const mark: WorkspaceMark = {
+    version: WORKSPACE_MARK_VERSION,
+    label,
+    pid: process.pid,
+    processStart: started,
+  };
+  try {
+    await mkdir(dir, { recursive: true });
+    await writeWhole(file, mark);
+  } catch {
+    return unmarked;
+  }
+  let current = mark;
+  // One write at a time, each of the mark as it is then: a later one never lands before an earlier.
+  let writing = Promise.resolve();
+  /** Once released, nothing writes it again: a late write would bring a removed mark back. */
+  let released = false;
+  const write = (next: WorkspaceMark) => {
+    if (released) return writing;
+    current = next;
+    writing = writing.then(() => writeWhole(file, current).catch(() => undefined));
+    return writing;
+  };
+  return {
+    bind: (workspaceId) => write({ ...current, workspaceId }),
+    panes: (session, panes) =>
+      write({ ...current, panes: { ...current.panes, [session]: [...panes] } }),
+    release: async () => {
+      if (released) return writing;
+      const kept = Object.fromEntries(
+        Object.entries(current.panes ?? {})
+          .map(([session, panes]) => [session, panes.filter((pane) => pane.kept)] as const)
+          .filter(([, panes]) => panes.length > 0),
+      );
+      if (Object.keys(kept).length === 0) {
+        released = true;
+        await writing;
+        return removeMark(file);
+      }
+      await write({ ...current, panes: kept, ended: true });
+      released = true;
+    },
+  };
+}
+
+/** Renamed into place, so a reader never sees half a mark and skips a live run. */
+async function writeWhole(file: string, mark: WorkspaceMark): Promise<void> {
+  const temporary = `${file}.${randomBytes(4).toString("hex")}.tmp`;
+  try {
+    await writeFile(temporary, JSON.stringify(mark));
+    await rename(temporary, file);
+  } finally {
+    await rm(temporary, { force: true }).catch(() => undefined);
+  }
+}
+
+export async function readMarks(
+  home: string,
+  session: string,
+): Promise<(WorkspaceMark & { file: string })[]> {
+  const dir = marksDir(home, session);
+  const files = await readdir(dir).catch(() => [] as string[]);
+  const marks: (WorkspaceMark & { file: string })[] = [];
+  for (const name of files.filter((file) => file.endsWith(".json"))) {
+    const file = join(dir, name);
+    try {
+      const mark = JSON.parse(await readFile(file, "utf8"));
+      if (
+        (mark?.version === 1 || mark?.version === WORKSPACE_MARK_VERSION) &&
+        typeof mark.label === "string" &&
+        typeof mark.pid === "number" &&
+        typeof mark.processStart === "string" &&
+        (mark.workspaceId === undefined || typeof mark.workspaceId === "string")
+      ) {
+        marks.push({ ...mark, file });
+      }
+    } catch {}
+  }
+  return marks;
+}
+
+/** Every session's marks, by the session whose directory holds them. */
+export async function readAllMarks(
+  home: string,
+): Promise<(WorkspaceMark & { file: string; session: string })[]> {
+  const sessions = await readdir(join(machinePaths(home).herdr, "sessions")).catch(
+    () => [] as string[],
+  );
+  const all = await Promise.all(
+    sessions.map(async (session) =>
+      (await readMarks(home, session)).map((mark) => ({ ...mark, session })),
+    ),
+  );
+  return all.flat();
+}
+
+/** Rewrites a mark read from `file`, as one sweep leaves it. */
+export function rewriteMark(file: string, mark: WorkspaceMark): Promise<void> {
+  return writeWhole(file, mark).catch(() => undefined);
+}
+
+export function removeMark(file: string): Promise<void> {
+  return rm(file, { force: true }).catch(() => undefined);
+}
+
+/**
+ * Dead only when its process is gone, or another holds its pid. One `ps` can't see, as from a
+ * sandbox, is unknown: closing a live run's workspace loses its work.
+ */
+export function liveness(
+  mark: Pick<WorkspaceMark, "pid" | "processStart">,
+  probe: ProcessProbe = processStart,
+  exists: (pid: number) => boolean = processExists,
+): Liveness {
+  if (!exists(mark.pid)) return "dead";
+  if (probe(mark.pid) === undefined) return "unknown";
+  return sameProcess(mark.pid, mark.processStart, probe) ? "live" : "dead";
+}
+
+function processExists(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code !== "ESRCH";
+  }
+}

package/src/here.ts

@@ -0,0 +1,289 @@
+import { randomBytes } from "node:crypto";
+import { rmSync } from "node:fs";
+import { mkdir, readFile, rm } from "node:fs/promises";
+import { basename, join } from "node:path";
+import {
+  type CallerPane,
+  focusTab,
+  HARNESSES,
+  herdrReachable,
+  runProcess,
+  searchCaller,
+  startInNewTab,
+} from "@agentswf/harness";
+import { messageOf } from "./errors";
+import { linkNew } from "./files";
+import { runSessionName } from "./herdr-run-session";
+import type { OperatorEnvironment } from "./operator-cli";
+import { callerSession, herdrConfig } from "./operator-runtime";
+import type { RunCommand } from "./run-command";
+import { startedLine } from "./run-commands";
+import { loadAndPrepare } from "./run-prepare";
+import { generateId, processStart, sameProcess } from "./runs";
+
+/** What `--here` and `--session` reach Herdr and the calling session through. */
+type HereEnvironment = Pick<
+  OperatorEnvironment,
+  "herdr" | "environment" | "self" | "callerSearchMs" | "signal" | "now"
+>;
+
+export type Caller = { pane: CallerPane; session: string };
+
+export const SESSION_CODE = /^awf-here-[0-9a-f]{8}$/;
+const CALLER_SEARCH_MS = 120_000;
+
+/**
+ * `awf run --here`, in an agent's shell: checks the workflow loads and its run can start, and that
+ * the session can be driven, then has Herdr start the run in a new tab, outside this shell and any
+ * sandbox it is in, and prints the code the agent ends its turn with (ADR 0010). Nothing is started
+ * when a check fails.
+ */
+export async function startHere(
+  argv: readonly string[],
+  command: RunCommand,
+  environment: HereEnvironment,
+  stdout: (text: string) => void,
+  stderr: (text: string) => void,
+  notice: (text: string) => void,
+): Promise<number> {
+  // In this shell, before any tab opens: a workflow that will not load or a run that will not
+  // start is said here, where the agent reads it, and not in a tab nobody is looking at.
+  const ready = await loadAndPrepare(command, (environment.now ?? Date.now)());
+  if ("refused" in ready) {
+    stderr(`awf: ${ready.refused}`);
+    return 2;
+  }
+  for (const line of ready.prepared.continued?.warnings ?? []) notice(line);
+  const env = environment.environment ?? process.env;
+  const run = environment.herdr ?? runProcess;
+  const refuse = (why: string, instead: string) => {
+    stderr(`awf: --here: ${why}. ${instead}`);
+    return 1;
+  };
+  const workspace = env.HERDR_WORKSPACE_ID;
+  if (env.HERDR_ENV !== "1" || !workspace) {
+    return refuse(
+      "this session is not in a Herdr pane, so a run cannot drive it",
+      "Start the agent in a Herdr pane, or run the workflow from a shell with awf run and no --here.",
+    );
+  }
+  try {
+    // Said in this shell: the run's own tab would find it only after taking the session over.
+    runSessionName(env);
+  } catch (error) {
+    stderr(`awf: --here: ${messageOf(error)}`);
+    return 2;
+  }
+  let session: string;
+  try {
+    session = await callerSession(run, env);
+  } catch (error) {
+    return refuse(`Herdr did not answer: ${messageOf(error)}`, sandboxFix(env));
+  }
+  const unreachable = await herdrReachable(herdrConfig(session), run);
+  if (unreachable) {
+    return refuse(`this session cannot reach Herdr: ${unreachable.trim()}`, sandboxFix(env));
+  }
+  const code = `awf-here-${randomBytes(4).toString("hex")}`;
+  // Chosen here, so this shell, which the agent reads, can name the run its tab starts.
+  const id = command.continueId ?? ready.prepared.id ?? generateId();
+  const end = argv.indexOf("--");
+  const options = (end === -1 ? argv.slice(1) : argv.slice(1, end)).filter(
+    (arg) => arg !== "--here",
+  );
+  const rest = end === -1 ? [] : argv.slice(end);
+  const self = environment.self ?? [process.execPath, "--no-env-file", process.argv[1]!];
+  const started = await startInNewTab(
+    herdrConfig(session),
+    {
+      // Under codex this can be another pane's workspace (E8); the run's tab still works from it.
+      workspace,
+      cwd: command.shellCwd,
+      label: tabLabel(ready.loaded.executable.definition.meta.name, id),
+      argv: [
+        ...self,
+        "run",
+        "--session",
+        code,
+        ...((command.continueId ?? ready.prepared.id) ? [] : ["--id", id]),
+        ...options,
+        ...rest,
+      ],
+      // The tab takes the Herdr server's environment, not this shell's: the operator's choice of
+      // where the run's agents open is passed on, and the session's own id, which only this shell
+      // has, for a fork of it.
+      env: {
+        ...(env.AWF_HERDR_SESSION ? { AWF_HERDR_SESSION: env.AWF_HERDR_SESSION } : {}),
+        ...callerSessions(env),
+      },
+    },
+    run,
+  );
+  if (!started.ok) {
+    return refuse(
+      `Herdr did not open the run's tab: ${started.error}`,
+      "Run the workflow from a shell with awf run instead.",
+    );
+  }
+  notice(startedLine(ready.loaded.executable.definition.meta.name, id, command));
+  stdout(
+    [
+      `awf: ${basename(ready.loaded.file)} is starting in Herdr tab ${started.tabId}. Once this turn ends it takes this session over: each of its steps arrives here as a prompt, and a last message hands the session back.`,
+      "",
+      "End your turn now by replying with only this line, exactly:",
+      code,
+    ].join("\n"),
+  );
+  return 0;
+}
+
+/**
+ * `awf run --session`: the session showing `code`, marked as driven by this process until the
+ * release, under `callers`. The reason when it can't be had, said in this run's own tab too.
+ */
+export async function takeCaller(
+  code: string,
+  callers: string,
+  environment: HereEnvironment,
+): Promise<{ caller: Caller; release: () => void } | string> {
+  const found = await findCaller(code, environment);
+  let refused: string;
+  if (found.kind === "found") {
+    const release = await claimCaller(callers, found.caller.pane.paneId);
+    if (typeof release !== "string") return { caller: found.caller, release };
+    refused = release;
+  } else {
+    refused = found.reason;
+  }
+  // The session that started this waits on a run that will not come, and this tab opened
+  // unfocused: it is the one place that says why.
+  await showOwnTab(environment);
+  return refused;
+}
+
+/** Carries the calling session's ids, by harness, from `--here`'s shell to the run's tab. */
+const CALLER_SESSIONS = "AWF_CALLER_SESSIONS";
+
+/**
+ * Each harness's session variable this shell has, which a harness sets in its own tool calls'
+ * shells: the session's native id, by harness, since which harness the pane runs is found later.
+ */
+function callerSessions(env: Readonly<Record<string, string | undefined>>): Record<string, string> {
+  const sessions = Object.fromEntries(
+    Object.entries(HARNESSES).flatMap(([harness, spec]) => {
+      const id = spec.sessionEnv ? env[spec.sessionEnv]?.trim() : undefined;
+      return id ? [[harness, id]] : [];
+    }),
+  );
+  return Object.keys(sessions).length ? { [CALLER_SESSIONS]: JSON.stringify(sessions) } : {};
+}
+
+/** The calling session's id `--here` passed on for `harness`, where it had one. */
+function passedSession(
+  env: Readonly<Record<string, string | undefined>>,
+  harness: string,
+): string | undefined {
+  try {
+    const id = JSON.parse(env[CALLER_SESSIONS] ?? "{}")?.[harness];
+    return typeof id === "string" && id ? id : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * What lets a sandboxed session reach Herdr's socket, which `--here` and every `wf` call need: its
+ * harness's own advice, for the harness whose session variable this shell has.
+ */
+function sandboxFix(env: Readonly<Record<string, string | undefined>>): string {
+  const harness = Object.values(HARNESSES).find(
+    (spec) => spec.sessionEnv && env[spec.sessionEnv] && spec.localSockets,
+  );
+  return harness?.localSockets
+    ? `${harness.localSockets}.`
+    : "If this session runs in a sandbox, let it reach Herdr's socket and local sockets, or run the workflow from a shell with awf run.";
+}
+
+/**
+ * Marks `paneId` as driven by this process until the returned release, under `~/.awf`, which every
+ * run on this machine shares whatever its run root: a second run started from a driven session is
+ * refused, as ADR 0010 allows one at a time. A mark whose process is gone, or is another process
+ * with its pid, is taken over. The reason when refused.
+ */
+async function claimCaller(marks: string, paneId: string): Promise<(() => void) | string> {
+  const mark = join(marks, `${paneId.replace(/[^A-Za-z0-9_-]/g, "_")}.json`);
+  const started = processStart(process.pid);
+  if (started === undefined) return `ps gave no start time for this process (${process.pid})`;
+  const holder: CallerMark = { pid: process.pid, processStart: started };
+  try {
+    await mkdir(marks, { recursive: true });
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+      if (await linkNew(mark, holder)) return () => rmSync(mark, { force: true });
+      const other = await readMark(mark);
+      if (other && sameProcess(other.pid, other.processStart)) {
+        return `another run (process ${other.pid}) is already driving the session in ${paneId}; one run drives a session at a time`;
+      }
+      await rm(mark, { force: true });
+    }
+    return `could not mark the session in ${paneId} as driven`;
+  } catch (error) {
+    return messageOf(error);
+  }
+}
+
+/** The run driving a session: its process, and when that started, which tells a reused pid apart. */
+type CallerMark = { pid: number; processStart: string };
+
+/** A mark as written, or undefined for one gone or unreadable, which nothing holds. */
+async function readMark(file: string): Promise<CallerMark | undefined> {
+  try {
+    const mark = JSON.parse(await readFile(file, "utf8"));
+    return typeof mark?.pid === "number" && typeof mark.processStart === "string"
+      ? mark
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Brings the tab this process runs in forward, where Herdr says which one that is. */
+export async function showOwnTab(environment: HereEnvironment): Promise<void> {
+  const env = environment.environment ?? process.env;
+  if (!env.HERDR_TAB_ID) return;
+  const session = await callerSession(environment.herdr ?? runProcess, env).catch(() => undefined);
+  if (session) await focusTab(herdrConfig(session), env.HERDR_TAB_ID, environment.herdr);
+}
+
+/** The pane showing `code`, in the Herdr session this run's tab is in, for `--session`. */
+async function findCaller(
+  code: string,
+  environment: HereEnvironment,
+): Promise<{ kind: "found"; caller: Caller } | { kind: "refused"; reason: string }> {
+  const run = environment.herdr ?? runProcess;
+  let session: string;
+  try {
+    session = await callerSession(run, environment.environment ?? process.env);
+  } catch (error) {
+    return { kind: "refused", reason: messageOf(error) };
+  }
+  const found = await searchCaller(
+    herdrConfig(session),
+    code,
+    {
+      by: (environment.now ?? Date.now)() + (environment.callerSearchMs ?? CALLER_SEARCH_MS),
+      ...(environment.signal ? { signal: environment.signal } : {}),
+    },
+    run,
+  );
+  if (found.kind !== "found") return found;
+  const id = passedSession(environment.environment ?? process.env, found.pane.harness);
+  return {
+    kind: "found",
+    caller: { pane: { ...found.pane, ...(id ? { session: id } : {}) }, session },
+  };
+}
+
+/** The run's tab, named as its Herdr workspace is, but for the attempt, which isn't claimed yet. */
+function tabLabel(workflow: string, id: string | undefined): string {
+  return `awf ${workflow}${id === undefined ? "" : ` ${id}`}`;
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+// A finished run is re-priced from its `output.json` with another table.
+export { describeAccounting } from "./accounting/format";
+export { type ModelRate, type PriceTable, PUBLISHED_PRICES } from "./accounting/prices";
+export { summarizeRun } from "./accounting/summary";
+export * from "./workflow-runner";