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

package/src/run-read.ts

@@ -0,0 +1,425 @@
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+import type { Activity, RunLogLine } from "@agentswf/contract/records";
+import type { AgentKey, HarnessKind } from "@agentswf/contract/workflow";
+import { findHarness, harnessState, readActivity } from "@agentswf/harness";
+import { readNumberedEvents } from "./runs";
+
+/**
+ * A native session the run's log names, numbered by the line that first named it, so a session
+ * named later never renumbers the others. Its files are found under its agent's home and working
+ * directory: a sandbox's, for an agent in one.
+ */
+export type NativeSession = {
+  n: number;
+  harness: HarnessKind;
+  id: string;
+  agent?: AgentKey;
+};
+
+/** A span of time, open while it has no end. */
+type Span = { from: number; to?: number };
+
+/** What the log says of an agent: where its files are, and the spans its activity is the run's. */
+export type RunAgent = {
+  key: AgentKey;
+  cwd?: string;
+  home?: string;
+  caller: boolean;
+  operations: (Span & { id: string })[];
+  /**
+   * Each time the run held it: from its opening, its fork, or, in a log an earlier awf wrote, its
+   * first delivery, to its stop or its attempt's last line.
+   */
+  windows: Span[];
+};
+
+export type RunLog = {
+  lines: { number: number; line: RunLogLine }[];
+  sessions: NativeSession[];
+  agents: Map<AgentKey, RunAgent>;
+};
+
+/** `ended`: no attempt is running, so a span still open on the calling session ended with it. */
+export async function readRunLog(
+  runDir: string,
+  options: { ended?: boolean } = {},
+): Promise<RunLog> {
+  const lines = await readNumberedEvents(runDir);
+  const sessions: NativeSession[] = [];
+  const agents = new Map<AgentKey, RunAgent>();
+  const agentOf = new Map<string, AgentKey>();
+  const agent = (key: AgentKey) => {
+    const found = agents.get(key) ?? { key, caller: false, operations: [], windows: [] };
+    agents.set(key, found);
+    return found;
+  };
+  const open = (held: RunAgent, from: number) => {
+    if (held.windows.at(-1)?.to === undefined && held.windows.length > 0) return;
+    held.windows.push({ from });
+  };
+  const name = (harness: HarnessKind, id: string, key?: AgentKey) => {
+    const known = sessions.find((each) => each.harness === harness && each.id === id);
+    if (known) {
+      if (key && !known.agent) known.agent = key;
+      return;
+    }
+    sessions.push({ n: sessions.length + 1, harness, id, ...(key ? { agent: key } : {}) });
+  };
+  // An attempt that died left its spans open. An agent's end where the next attempt begins; the
+  // calling session's at the dead attempt's last line, past which its file is the operator's.
+  let attempt: number | undefined;
+  let lastAt: number | undefined;
+  const closeAll = (at: number, callerAt = at) => {
+    for (const held of agents.values()) {
+      const end = held.caller ? callerAt : at;
+      for (const span of [...held.windows, ...held.operations]) span.to ??= end;
+    }
+  };
+  for (const { line } of lines) {
+    const at = Date.parse(timeOf(line));
+    if (attempt !== undefined && line.attempt !== attempt && lastAt !== undefined) {
+      closeAll(at, lastAt);
+    }
+    attempt = line.attempt;
+    if (!Number.isNaN(at)) lastAt = at;
+    switch (line.kind) {
+      case "agent-opened": {
+        const opened = agent(line.agent);
+        opened.cwd = line.cwd;
+        if (line.home !== undefined) opened.home = line.home;
+        if (line.caller) opened.caller = true;
+        else open(opened, at);
+        break;
+      }
+      case "agent-forked":
+        open(agent(line.agent), at);
+        break;
+      case "agent-stopped": {
+        const window = agent(line.agent).windows.at(-1);
+        if (window && window.to === undefined) window.to = at;
+        break;
+      }
+      case "operation-started": {
+        const started = agent(line.agent);
+        // Its own operations say so too, should its opening line be lost.
+        if (line.execution.caller) started.caller = true;
+        const from = Date.parse(line.deliveredAt ?? line.at);
+        if (!started.caller) open(started, from);
+        started.operations.push({ id: line.operationId, from });
+        agentOf.set(line.operationId, line.agent);
+        for (const session of line.sessions) name(session.harness, session.id, line.agent);
+        break;
+      }
+      case "session-known": {
+        const key = line.agent ?? (line.operationId ? agentOf.get(line.operationId) : undefined);
+        name(line.session.harness, line.session.id, key);
+        break;
+      }
+      case "turn":
+      case "compact": {
+        const settled = agent(line.agent);
+        if (line.execution.caller) settled.caller = true;
+        const to = line.settledAt ? Date.parse(line.settledAt) : undefined;
+        const started = settled.operations.find((each) => each.id === line.operationId);
+        // A line an earlier awf wrote has no start before it: its span is its own times.
+        if (started) started.to = to ?? at;
+        else if (line.deliveredAt) {
+          const from = Date.parse(line.deliveredAt);
+          if (!settled.caller) open(settled, from);
+          settled.operations.push({ id: line.operationId, from, to: to ?? at });
+        }
+        for (const session of line.sessions) name(session.harness, session.id, line.agent);
+        break;
+      }
+      case "operation-failed": {
+        const failed = agents
+          .get(line.agent)
+          ?.operations.find((each) => each.id === line.operationId);
+        if (failed) failed.to = at;
+        break;
+      }
+      case "attempt-ended":
+        closeAll(at);
+        break;
+    }
+  }
+  if (options.ended && lastAt !== undefined) closeAll(Number.POSITIVE_INFINITY, lastAt);
+  return { lines, sessions, agents };
+}
+
+const within = (span: Span, at: number) =>
+  span.from <= at && (span.to === undefined || at <= span.to);
+
+/** The operation an agent's activity at `at` belongs to: null between them, undefined outside the run. */
+function operationAt(agent: RunAgent, at: number): string | null | undefined {
+  const inside = agent.operations.find((each) => within(each, at));
+  if (inside) return inside.id;
+  // The calling session's file is the operator's own conversation outside the run's operations.
+  if (agent.caller) return undefined;
+  return agent.windows.some((each) => within(each, at)) ? null : undefined;
+}
+
+/**
+ * A session's files as found, kept between the reads of one command: finding them can list a
+ * harness's whole session store. Found again soon when none were, as a session's file can come
+ * after its name, and now and then after, for the files a session adds as it runs.
+ */
+export type FileCache = Map<number, { files: SessionFile[]; at: number }>;
+
+const REFIND_MS = 30_000;
+const REFIND_NONE_MS = 5_000;
+
+/** Without a cursor, a native file is read from this far before its end: a read shows its last events. */
+const TAIL_BYTES = 4 * 1024 * 1024;
+
+/** With a cursor, how far one read goes on in a native file: a page needs little of it. */
+const READ_BYTES = 4 * 1024 * 1024;
+
+/** One native file of a session, by a key its name gives, so a late file renumbers nothing. */
+export type SessionFile = { session: NativeSession; key: string; path: string };
+
+/** A session's files, the first its own and keyed `""`; none where they cannot be found. */
+async function sessionFiles(
+  session: NativeSession,
+  agent: RunAgent | undefined,
+  runCwd: string,
+): Promise<SessionFile[]> {
+  const spec = findHarness(session.harness);
+  if (!spec?.sessionFiles || !spec.activityRow) return [];
+  const home =
+    agent?.home ?? harnessState()[session.harness as keyof ReturnType<typeof harnessState>];
+  if (!home) return [];
+  const found = await spec
+    .sessionFiles(home, session.id, agent?.cwd ?? runCwd)
+    .catch(() => undefined);
+  // A codex fork's files name the sessions it was forked from after its own, whose rows are
+  // theirs; a session's own files, a claude subagent's too, carry its id in their path.
+  const own = (found ?? []).filter(
+    (relative, index) => index === 0 || relative.includes(session.id),
+  );
+  return own.map((relative, index) => ({
+    session,
+    key: index === 0 ? "" : createHash("sha256").update(relative).digest("hex").slice(0, 12),
+    path: join(home, relative),
+  }));
+}
+
+/**
+ * Where a read stopped: the event log's last line number, and each native file's byte offset.
+ * Opaque to its holder, who copies it back; versioned, so a later awf can refuse an old one.
+ */
+export type Cursor = { log: number; files: Record<string, number> };
+
+export function encodeCursor(cursor: Cursor): string {
+  return `c1.${Buffer.from(JSON.stringify([cursor.log, cursor.files])).toString("base64url")}`;
+}
+
+export function decodeCursor(text: string): Cursor | undefined {
+  if (!text.startsWith("c1.")) return undefined;
+  try {
+    const [log, files] = JSON.parse(Buffer.from(text.slice(3), "base64url").toString("utf8"));
+    if (!Number.isSafeInteger(log) || log < 0 || typeof files !== "object" || files === null) {
+      return undefined;
+    }
+    const offsets = Object.entries(files as Record<string, unknown>);
+    if (!offsets.every(([, offset]) => Number.isSafeInteger(offset) && (offset as number) >= 0)) {
+      return undefined;
+    }
+    return { log, files: Object.fromEntries(offsets) as Record<string, number> };
+  } catch {
+    return undefined;
+  }
+}
+
+/** A file's name in cursors and handles: its session's number, and its key when not the first. */
+function fileName(file: Pick<SessionFile, "session" | "key">): string {
+  return `a${file.session.n}${file.key ? `-${file.key}` : ""}`;
+}
+
+/** An event's handle: its line in the log, or its file and its place in that file. */
+export type Handle =
+  | { kind: "event"; line: number }
+  | { kind: "activity"; file: string; offset: number; index: number };
+
+export function encodeHandle(handle: Handle): string {
+  if (handle.kind === "event") return `e${handle.line}`;
+  const index = handle.index > 0 ? `.${handle.index}` : "";
+  return `${handle.file}.${handle.offset.toString(16)}${index}`;
+}
+
+export function decodeHandle(text: string): Handle | undefined {
+  const plain = text.startsWith("@") ? text.slice(1) : text;
+  const event = /^e([1-9]\d*)$/.exec(plain);
+  if (event) return { kind: "event", line: Number(event[1]) };
+  const activity = /^(a[1-9]\d*(?:-[0-9a-f]{12})?)\.([0-9a-f]+)(?:\.([1-9]\d*))?$/.exec(plain);
+  if (!activity) return undefined;
+  return {
+    kind: "activity",
+    file: activity[1]!,
+    offset: Number.parseInt(activity[2]!, 16),
+    index: activity[3] ? Number(activity[3]) : 0,
+  };
+}
+
+/** One event of a read: a line of the log, or an agent's activity, with its handle. */
+export type ReadEvent = {
+  handle: string;
+  at: string;
+  /** Sorts by time, then by where it was read. */
+  time: number;
+} & (
+  | { source: "log"; line: RunLogLine }
+  | {
+      source: "activity";
+      agent?: AgentKey;
+      operation: string | null;
+      activity: Activity;
+      text?: string;
+    }
+);
+
+/**
+ * Everything after `cursor`: the log's lines and each session's activity that is the run's, merged
+ * by time. The cursor returned is where this read stopped, past nothing torn.
+ */
+export async function readRun(
+  runDir: string,
+  runCwd: string,
+  cursor: Cursor = { log: 0, files: {} },
+  options: {
+    full?: boolean;
+    ended?: boolean;
+    files?: FileCache;
+    /** Reads only this native file's first line from the cursor, by its name in handles; `""` reads none. */
+    only?: string;
+    /** A read of the newest: each file not in the cursor from its tail, `cut` where it had more. */
+    tail?: boolean;
+    /** The command's clock, for when to look for files again. */
+    now?: number;
+    /** With a cursor, at most this many lines of each native file: a page needs few. */
+    lines?: number;
+  } = {},
+): Promise<{ events: ReadEvent[]; cursor: Cursor; log: RunLog; cut: boolean; more: boolean }> {
+  const log = await readRunLog(runDir, options);
+  const cache = options.files ?? new Map();
+  const now = options.now ?? Date.now();
+  let cut = false;
+  // Where the files that stopped short stopped: what comes after it is left for the next read.
+  let horizon = Number.POSITIVE_INFINITY;
+  const events: ReadEvent[] = [];
+  let last = cursor.log;
+  // The log's lines keep their order among the activity: a turn line's time is its settling,
+  // which can come before the line written ahead of it.
+  let after = Number.NEGATIVE_INFINITY;
+  for (const { number, line } of log.lines) {
+    if (number <= cursor.log) continue;
+    last = number;
+    const at = timeOf(line);
+    after = Math.max(after, Date.parse(at) || after);
+    events.push({
+      handle: encodeHandle({ kind: "event", line: number }),
+      at,
+      time: after,
+      source: "log",
+      line,
+    });
+  }
+  const files = { ...cursor.files };
+  // A pane's pi names its session twice, by id and by path: one file, read once.
+  const seen = new Set<string>();
+  for (const session of log.sessions) {
+    const agent = session.agent ? log.agents.get(session.agent) : undefined;
+    const only = options.only;
+    if (only !== undefined && only !== `a${session.n}` && !only.startsWith(`a${session.n}-`)) {
+      continue;
+    }
+    let found = cache.get(session.n);
+    const stale = found && now - found.at >= (found.files.length ? REFIND_MS : REFIND_NONE_MS);
+    if (!found || stale) {
+      found = { files: await sessionFiles(session, agent, runCwd), at: now };
+      cache.set(session.n, found);
+    }
+    for (const file of found.files) {
+      const name = fileName(file);
+      if (options.only !== undefined && name !== options.only) continue;
+      if (seen.has(file.path)) continue;
+      seen.add(file.path);
+      const bounded = options.only === undefined && !(options.tail && files[name] === undefined);
+      const readFrom = (from: number) =>
+        readActivity(session.harness, file.path, from, {
+          ...(options.full ? { full: true } : {}),
+          ...(options.tail && files[name] === undefined ? { tail: TAIL_BYTES } : {}),
+          // One file read for one handle: its line is the first.
+          ...(options.only !== undefined ? { lines: 1 } : {}),
+          ...(bounded
+            ? { bytes: READ_BYTES, ...(options.lines ? { lines: options.lines } : {}) }
+            : {}),
+        });
+      let read = await readFrom(files[name] ?? 0);
+      // A stretch with no row of the run's, untimed or outside its windows, as the operator's own
+      // conversation in a calling session's file, shows nothing: read on past it.
+      const ours = (row: { at: string }) => {
+        const time = Date.parse(row.at);
+        return !Number.isNaN(time) && agent !== undefined && operationAt(agent, time) !== undefined;
+      };
+      while (bounded && read.more && !read.rows.some(ours)) read = await readFrom(read.offset);
+      if (read.cut) cut = true;
+      if (bounded && read.more) {
+        let reached = Number.NEGATIVE_INFINITY;
+        for (const row of read.rows) reached = Math.max(reached, Date.parse(row.at) || reached);
+        horizon = Math.min(horizon, reached);
+      }
+      files[name] = read.offset;
+      for (const row of read.rows) {
+        const time = Date.parse(row.at);
+        const operation = agent ? operationAt(agent, time) : undefined;
+        if (operation === undefined) continue;
+        events.push({
+          handle: encodeHandle({
+            kind: "activity",
+            file: name,
+            offset: row.offset,
+            index: row.index,
+          }),
+          at: row.at,
+          time,
+          source: "activity",
+          ...(session.agent ? { agent: session.agent } : {}),
+          operation,
+          activity: row.activity,
+          ...(row.text === undefined ? {} : { text: row.text }),
+        });
+      }
+    }
+  }
+  events.sort((a, b) => a.time - b.time);
+  const more = horizon < Number.POSITIVE_INFINITY;
+  const beyond = events.findIndex((event) => event.time > horizon);
+  if (beyond < 0) return { events, cursor: { log: last, files }, log, cut, more };
+  const next = cutCursor(events, beyond, { log: last, files });
+  return { events: events.slice(0, beyond), cursor: next, log, cut, more };
+}
+
+/**
+ * Where a page cut before `cut` leaves off: before every event it did not show. Events are in
+ * time order and the log's lines in line order among them, so nothing shown is read again.
+ */
+export function cutCursor(all: readonly ReadEvent[], cut: number, end: Cursor): Cursor {
+  const next: Cursor = { log: end.log, files: { ...end.files } };
+  for (const event of all.slice(cut)) {
+    const handle = decodeHandle(event.handle)!;
+    if (handle.kind === "event") next.log = Math.min(next.log, handle.line - 1);
+    else
+      next.files[handle.file] = Math.min(next.files[handle.file] ?? handle.offset, handle.offset);
+  }
+  return next;
+}
+
+/** When a line happened: an event's time, or a turn's settling. */
+export function timeOf(line: RunLogLine): string {
+  if ("at" in line && typeof line.at === "string") return line.at;
+  return (
+    ("settledAt" in line && line.settledAt) || ("deliveredAt" in line && line.deliveredAt) || ""
+  );
+}

package/src/run-state.ts

@@ -0,0 +1,120 @@
+import { join } from "node:path";
+import type { AttemptRecord } from "@agentswf/contract/records";
+import type { AttemptOutcome } from "@agentswf/contract/workflow";
+import { exists } from "./files";
+import {
+  entries,
+  idProblem,
+  openRun,
+  probeProcess,
+  type Run,
+  readAttempts,
+  sameStart,
+} from "./runs";
+
+/** What `ps` says of a process: its start, `gone`, or `unknown`. */
+export type ProcessStatus = (pid: number) => string | "gone" | "unknown";
+
+/**
+ * A run as `awf runs` and `awf logs` see it: its last attempt still open and its process there,
+ * `running`; open and its process gone, `interrupted`; or how its last attempt ended. Read from
+ * `run.json` and the attempt files, never the event log, so a run an older awf wrote reads too.
+ */
+export type RunState = "running" | "interrupted" | AttemptOutcome;
+
+export type RunStatus = {
+  run: Run;
+  /** `{workflow}/{id}`. */
+  ref: string;
+  attempts: AttemptRecord[];
+  state: RunState;
+  /** False for a `running` whose process could not be asked about. */
+  checked: boolean;
+};
+
+/** How long a run folder with no attempt yet may be an `awf run` still starting. */
+const STARTING_MS = 60_000;
+
+export async function runStatus(
+  run: Run,
+  probe: ProcessStatus = probeProcess,
+  at = Date.now(),
+): Promise<RunStatus> {
+  const attempts = await readAttempts(run);
+  const last = attempts.at(-1);
+  const ref = `${run.record.workflow}/${run.record.id}`;
+  // Between its folder and its first attempt's claim: an `awf run` starting, or, past a minute,
+  // one refused or killed before it claimed one.
+  if (!last) {
+    const starting = at - Date.parse(run.record.created) < STARTING_MS;
+    return { run, ref, attempts, state: starting ? "running" : "interrupted", checked: !starting };
+  }
+  if (last.outcome !== undefined) return { run, ref, attempts, state: last.outcome, checked: true };
+  const now = probe(last.pid);
+  if (now === "unknown") return { run, ref, attempts, state: "running", checked: false };
+  const same = now !== "gone" && sameStart(now, last.processStart);
+  return { run, ref, attempts, state: same ? "running" : "interrupted", checked: true };
+}
+
+const ALSO_RUNNING_CHECKED = 20;
+
+/** A reference the commands take, or why there is none to read. */
+export class RunNotFound extends Error {}
+
+/**
+ * Every run under `runRoot`, newest `created` first. A folder whose `run.json` cannot be read is
+ * not a run this awf can show, and is passed over.
+ */
+export async function listRuns(runRoot: string): Promise<Run[]> {
+  const runs: Run[] = [];
+  for (const workflow of await entries(runRoot).catch(() => [])) {
+    for (const id of await entries(join(runRoot, workflow)).catch(() => [])) {
+      const run = await openRun(runRoot, workflow, id).catch(() => undefined);
+      if (run) runs.push(run);
+    }
+  }
+  return runs.sort((a, b) => b.record.created.localeCompare(a.record.created));
+}
+
+/**
+ * The run `ref` names, `{workflow}/{id}` or an `{id}` only one workflow here has; with none, the
+ * newest here, and whichever others are still running beside it.
+ */
+export async function findRun(
+  runRoot: string,
+  ref: string | undefined,
+  probe: ProcessStatus = probeProcess,
+): Promise<{ status: RunStatus; alsoRunning: string[] }> {
+  if (ref === undefined) {
+    const [newest, ...older] = await listRuns(runRoot);
+    if (!newest) throw new RunNotFound(`no runs under ${runRoot}`);
+    const alsoRunning: string[] = [];
+    // The newest few: each open attempt is a `ps`, and a run root is never pruned.
+    for (const run of older.slice(0, ALSO_RUNNING_CHECKED)) {
+      // One that cannot be read is no reason to fail a read of another.
+      const status = await runStatus(run, probe).catch(() => undefined);
+      if (status?.state === "running") alsoRunning.push(status.ref);
+    }
+    return { status: await runStatus(newest, probe), alsoRunning };
+  }
+  const slash = ref.indexOf("/");
+  if (slash >= 0) {
+    const [workflow, id] = [ref.slice(0, slash), ref.slice(slash + 1)];
+    const problem = idProblem(workflow) ?? idProblem(id);
+    if (problem) throw new RunNotFound(`no run ${ref}: ${problem}`);
+    // A record that is there but cannot be read is not a missing run, and says why itself.
+    if (!(await exists(join(runRoot, workflow, id, "run.json")))) {
+      const missing = await openRun(runRoot, workflow, id).catch((error: unknown) => error);
+      throw new RunNotFound(missing instanceof Error ? missing.message : `no run ${ref}`);
+    }
+    const run = await openRun(runRoot, workflow, id);
+    return { status: await runStatus(run, probe), alsoRunning: [] };
+  }
+  const found = (await listRuns(runRoot)).filter((run) => run.record.id === ref);
+  if (found.length === 0) throw new RunNotFound(`no run ${ref} under ${runRoot}`);
+  if (found.length > 1) {
+    const refs = found.map((run) => `${run.record.workflow}/${ref}`).join(", ");
+    throw new RunNotFound(`${ref} names a run of more than one workflow: ${refs}`);
+  }
+  return { status: await runStatus(found[0]!, probe), alsoRunning: [] };
+}