@agentswf/engine 0.1.0-beta.5 → 0.1.0

package/src/sandbox-homes.ts

@@ -1,11 +1,12 @@
 import { randomUUID } from "node:crypto";
 import { constants } from "node:fs";
 import { copyFile, mkdir, open, readdir, readFile, rename, rm, writeFile } from "node:fs/promises";
-import { dirname, isAbsolute, join, relative } from "node:path";
+import { dirname, join, relative } from "node:path";
 import { isDeepStrictEqual } from "node:util";
 import { isRecord } from "@agentswf/contract";
 import type { HarnessSandboxNeeds } from "@agentswf/sandbox";
 import { messageOf } from "./errors";
+import { isInside } from "./files";
 
 /** A seeded home's credentials, and a way to hand a refreshed one back to the operator. */
 export type SeededHome = {
@@ -39,21 +40,12 @@ export async function seedHome(
   populate?: (staged: string) => Promise<void>,
 ): Promise<SeededHome> {
   const staged = (path: string) => {
-    const inside = relative(home, path);
-    if (inside === "" || inside.startsWith("..") || isAbsolute(inside)) {
-      throw new Error(`${path} is not in the agent's home ${home}`);
-    }
-    return join(staging, inside);
+    if (!isInside(home, path)) throw new Error(`${path} is not in the agent's home ${home}`);
+    return join(staging, relative(home, path));
   };
   await mkdir(dirname(staging), { recursive: true, mode: 0o700 });
   await mkdir(staging, { mode: 0o700 });
-  const seeds: {
-    from: string;
-    to: string;
-    refreshes: string[][];
-    baseline: Buffer;
-    refused?: Buffer;
-  }[] = [];
+  const seeds: Seed[] = [];
   try {
     for (const { from, to, refreshes } of needs.seed) {
       let bytes: Buffer;
@@ -82,6 +74,66 @@ export async function seedHome(
     await rm(staging, { recursive: true, force: true });
     throw error;
   }
+  return writingBack(seeds, locks);
+}
+
+type Seed = {
+  from: string;
+  to: string;
+  refreshes: string[][];
+  baseline: Buffer;
+  refused?: Buffer;
+};
+
+/**
+ * Refreshes the credentials of a home an agent had before, for `awf open` (story 042): each seed's
+ * file written over with the operator's, never through a link, and handed back as `seedHome`'s
+ * are. Nothing else in the home changes: its sessions and skills are the agent's.
+ */
+export async function refreshHome(
+  home: string,
+  needs: Pick<HarnessSandboxNeeds, "seed">,
+  locks: CredentialLocks,
+): Promise<SeededHome> {
+  const seeds: Seed[] = [];
+  for (const { from, to, refreshes } of needs.seed) {
+    let bytes: Buffer;
+    try {
+      bytes = await readFile(from);
+    } catch {
+      throw new Error(`cannot refresh ${to}: ${from} is missing; log the harness in first`);
+    }
+    // Only a file at the home's top, which the engine made: never through a directory the agent
+    // made. Written as a new file and renamed over whatever is there, so a link, hard or soft, or
+    // a FIFO the agent left in its place is replaced, never written through or waited on.
+    if (dirname(to) !== home)
+      throw new Error(`${to} is not at the top of the agent's home ${home}`);
+    const fresh = join(home, `.awf-${randomUUID()}.tmp`);
+    const handle = await open(
+      fresh,
+      constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW,
+      0o600,
+    );
+    try {
+      await handle.writeFile(bytes);
+    } finally {
+      await handle.close();
+    }
+    await rename(fresh, to).catch(async (error: unknown) => {
+      await rm(fresh, { force: true });
+      throw error;
+    });
+    seeds.push({
+      from,
+      to,
+      refreshes: refreshes.map((field) => field.split(".")),
+      baseline: bytes,
+    });
+  }
+  return writingBack(seeds, locks);
+}
+
+function writingBack(seeds: Seed[], locks: CredentialLocks): SeededHome {
   return {
     async writeBack() {
       // Every seed is tried: one refused leaves the others' refreshes to go back.

package/src/sandboxes.ts

@@ -1,9 +1,9 @@
 import { randomUUID } from "node:crypto";
-import { mkdir, realpath } from "node:fs/promises";
+import { lstat, mkdir, realpath } from "node:fs/promises";
 import { homedir } from "node:os";
-import { join, relative } from "node:path";
+import { dirname, join, relative } from "node:path";
 import { isDeepStrictEqual } from "node:util";
-import type { SandboxRecord } from "@agentswf/contract/records";
+import type { SandboxRecord, SessionSandbox } from "@agentswf/contract/records";
 import type {
   AbsoluteDeadline,
   AgentExecution,
@@ -11,7 +11,13 @@ import type {
   SandboxEnvironmentKey,
   SandboxRef,
 } from "@agentswf/contract/workflow";
-import { type AgentSkills, harnessState, sandboxNeeds, skillsLayout } from "@agentswf/harness";
+import {
+  type AgentSkills,
+  type HarnessHomes,
+  harnessState,
+  OPERATOR_HOMES,
+  skillsLayout,
+} from "@agentswf/harness";
 import {
   type AgentDoor,
   type HarnessSandboxNeeds,
@@ -27,7 +33,13 @@ import { CONTROL_PLANE_ROOT } from "./control-plane";
 import { harnessDeadline } from "./deadlines";
 import { messageOf } from "./errors";
 import { machinePaths } from "./machine";
-import { type CredentialLocks, placeCarried, type SeededHome, seedHome } from "./sandbox-homes";
+import {
+  type CredentialLocks,
+  placeCarried,
+  refreshHome,
+  type SeededHome,
+  seedHome,
+} from "./sandbox-homes";
 import { placeSkills, type ResolvedSkill } from "./skills/run-skills";
 
 /** The providers a run may open sandboxes with, and where their directories are made. */
@@ -47,6 +59,8 @@ export type RunSandboxOptions = {
    * agent's harness is found on and claude's token. Defaults to the engine's.
    */
   environment?: Readonly<Record<string, string | undefined>>;
+  /** Where an agent's home and its harness's needs come from; the operator's installs and logins by default. */
+  homes?: HarnessHomes;
   /**
    * The operator's sandbox for the whole run (`awf run --sandbox`): every agent runs in it, at the
    * run's working directory, and the workflow opens none of its own. Unresolved, as a file gave it.
@@ -102,6 +116,37 @@ type RunSandbox = {
   watched?: true;
 };
 
+/** A sandbox's record as it stands, its agents admitted so far with it. */
+function recordOf({
+  key,
+  provider,
+  resolved,
+  directory,
+  opened,
+  agents,
+}: RunSandbox): SandboxRecord {
+  const domains = new Set([...resolved.network, ...agents.flatMap((agent) => agent.domains)]);
+  return {
+    callPath: [],
+    key,
+    provider,
+    spec: {
+      cwd: resolved.cwd,
+      read: [...resolved.read],
+      write: [...resolved.write],
+      network: [...resolved.network],
+      ...(resolved.sockets.length > 0 ? { sockets: [...resolved.sockets] } : {}),
+      ...(resolved.webSearch ? { webSearch: true } : {}),
+      ...({ [provider]: resolved.environment } as SandboxEnvironment),
+    },
+    directory,
+    gitdirs: resolved.gitdirs.map((gitdir) => ({ ...gitdir })),
+    domains: [...domains].sort(),
+    ...(opened.record ? { provided: structuredClone(opened.record) } : {}),
+    agents: agents.map(({ agent, home }) => ({ callPath: [], agent, home })),
+  };
+}
+
 /**
  * One run's sandboxes: the ones the workflow opens, and the private ones inline specs make. The
  * engine keeps them here, apart from any provider: it resolves a spec, opens it through the
@@ -131,6 +176,8 @@ export class RunSandboxes {
       /** The run's credential write-backs, which a host agent's own home shares. */
       locks: CredentialLocks;
       log(message: string): void;
+      /** A sandbox as it opened, before any agent is admitted to it. */
+      opened?(record: SandboxRecord): void;
     },
   ) {
     this.#providers = options.sandboxes?.providers ?? { installed: {} };
@@ -196,7 +243,7 @@ export class RunSandboxes {
       const home = join(sandbox.directory, "homes", id);
       // Beside `homes/`, which every agent in the sandbox can write, and out of their reach.
       const staging = join(sandbox.directory, "staging", id);
-      const needs = await sandboxNeeds(
+      const needs = await (this.options.sandboxes?.homes ?? OPERATOR_HOMES).sandboxed(
         agent.execution.harness,
         home,
         agent.execution.model,
@@ -292,30 +339,28 @@ export class RunSandboxes {
     return settled.flatMap((result) => (result.status === "rejected" ? [result.reason] : []));
   }
 
+  /** The sandbox `agent` was last admitted to, by key, and the model domains its harness added. */
+  admitted(agent: string): { sandbox: string; domains: string[] } | undefined {
+    for (const sandbox of [...this.#opened].reverse()) {
+      const found = sandbox.agents.findLast((each) => each.agent === agent);
+      if (found) return { sandbox: sandbox.key, domains: [...found.domains] };
+    }
+    return undefined;
+  }
+
+  /** The sandbox `agent` was last admitted to, as its sessions' lines record it (story 042). */
+  sessionSandbox(agent: string): SessionSandbox | undefined {
+    for (const sandbox of [...this.#opened].reverse()) {
+      if (!sandbox.agents.some((each) => each.agent === agent)) continue;
+      const { provider, spec, directory, provided } = recordOf(sandbox);
+      return { provider, spec, directory, ...(provided ? { provided } : {}) };
+    }
+    return undefined;
+  }
+
   /** Each sandbox the run opened, a private one closed after its agent failed too, with its agents. */
   records(): SandboxRecord[] {
-    return this.#opened.map(({ key, provider, resolved, directory, opened, agents }) => {
-      const domains = new Set([...resolved.network, ...agents.flatMap((agent) => agent.domains)]);
-      return {
-        callPath: [],
-        key,
-        provider,
-        spec: {
-          cwd: resolved.cwd,
-          read: [...resolved.read],
-          write: [...resolved.write],
-          network: [...resolved.network],
-          ...(resolved.sockets.length > 0 ? { sockets: [...resolved.sockets] } : {}),
-          ...(resolved.webSearch ? { webSearch: true } : {}),
-          ...({ [provider]: resolved.environment } as SandboxEnvironment),
-        },
-        directory,
-        gitdirs: resolved.gitdirs.map((gitdir) => ({ ...gitdir })),
-        domains: [...domains].sort(),
-        ...(opened.record ? { provided: structuredClone(opened.record) } : {}),
-        agents: agents.map(({ agent, home }) => ({ callPath: [], agent, home })),
-      };
-    });
+    return this.#opened.map(recordOf);
   }
 
   /**
@@ -370,6 +415,7 @@ export class RunSandboxes {
       throw error;
     }
     this.#opened.push(sandbox);
+    this.options.opened?.(recordOf(sandbox));
     // Landed after the run's sandboxes closed: it closes at once, and is still recorded.
     if (this.#closed) {
       await this.#close(sandbox).catch(() => undefined);
@@ -526,3 +572,111 @@ function assertWithin(
     );
   }
 }
+
+/** A sandbox reopened where an agent ran, its home admitted again: `awf open`'s (story 042). */
+export type ReopenedPlace = {
+  occupant: Occupant;
+  /** What the sandbox's spec keeps of web search: a turn inside drops the harness's otherwise. */
+  webSearch: boolean;
+  /** Releases the agent, hands refreshed credentials back, and closes the sandbox. Never rejects. */
+  close(): Promise<string[]>;
+};
+
+/**
+ * Opens a session's recorded sandbox again, in the directory it ran in, and admits the agent with
+ * the home it had: its credentials refreshed, nothing else reseeded. docker runs the image the run
+ * ran, by digest. `door` is the agent's way back, which reaches no run.
+ */
+export async function reopenSandbox(
+  recorded: SessionSandbox,
+  agent: { harness: string; model?: string; cwd: string; home: string },
+  options: {
+    providers: SandboxProviders;
+    runRoot: string;
+    door: AgentDoor;
+    deadline: AbsoluteDeadline;
+    environment: Readonly<Record<string, string | undefined>>;
+    /** The operator's home, whose machine and coordinator paths a spec may not reach. */
+    machineHome: string;
+    coordinatorRoot: string;
+  },
+): Promise<ReopenedPlace> {
+  // The sandbox could write `homes/`: a home it swapped for a link would have the refresh and the
+  // admit write through it, outside. Nothing runs in it now, so a check before use holds.
+  const entry = await lstat(agent.home).catch(() => undefined);
+  if (
+    !entry?.isDirectory() ||
+    dirname(agent.home) !== join(recorded.directory, "homes") ||
+    (await realpath(agent.home)) !== agent.home
+  )
+    throw new Error(`${agent.home} is not a home in ${recorded.directory}: it was moved or linked`);
+  const { provider } = recorded;
+  const spec: Record<string, unknown> = structuredClone(recorded.spec);
+  const image = recorded.provided?.image;
+  if (provider === "docker" && typeof image === "string")
+    spec.docker = { ...(spec.docker as object | undefined), image };
+  const { sandbox: resolved } = await resolveSandbox(spec, {
+    key: "awf-open",
+    cwd: recorded.spec.cwd,
+    runRoot: await realpath(options.runRoot),
+    machineRoot: machinePaths(options.machineHome).root,
+    providers: options.providers,
+    harnessState: Object.values(harnessState(options.environment)),
+    controlRoot: CONTROL_PLANE_ROOT,
+    coordinatorRoot: options.coordinatorRoot,
+    inline: false,
+  });
+  const installed = options.providers.installed[provider];
+  if (!installed) throw new Error(`the ${provider} sandbox provider is not installed`);
+  const opened = await installed
+    .open(resolved, {
+      runRoot: await realpath(options.runRoot),
+      directory: recorded.directory,
+      deadline: options.deadline,
+    })
+    .catch((error: unknown) => {
+      // A local image id cannot be pulled: the image the run ran was rebuilt or removed.
+      if (provider === "docker" && typeof image === "string" && messageOf(error).includes(image))
+        throw new Error(
+          `the image the run ran, ${image}, is no longer here: it was rebuilt or removed`,
+        );
+      throw error;
+    });
+  const locks: CredentialLocks = new Map();
+  let refreshed: SeededHome | undefined;
+  try {
+    const needs = await OPERATOR_HOMES.sandboxed(
+      agent.harness,
+      agent.home,
+      agent.model,
+      options.environment,
+    );
+    refreshed = await refreshHome(agent.home, needs, locks);
+    const occupant = await opened.admit({
+      cwd: agent.cwd,
+      home: agent.home,
+      harness: needs,
+      door: options.door,
+    });
+    return {
+      occupant,
+      webSearch: resolved.webSearch,
+      async close() {
+        const failures: string[] = [];
+        const said = (error: unknown) => void failures.push(messageOf(error));
+        await occupant.release().catch(said);
+        await refreshed?.writeBack().catch(said);
+        await opened.close().catch(said);
+        // What the provider moved aside as it closed, which would vanish without a word.
+        const quarantined = opened.record?.quarantined;
+        if (Array.isArray(quarantined) && quarantined.length > 0)
+          failures.push(`it moved aside ${quarantined.join(", ")}`);
+        return failures;
+      },
+    };
+  } catch (error) {
+    await refreshed?.writeBack().catch(() => undefined);
+    await opened.close().catch(() => undefined);
+    throw error;
+  }
+}

package/src/session-lines.ts

@@ -0,0 +1,93 @@
+import type { SessionSandbox, SessionSkills } from "@agentswf/contract/records";
+import type { NativeSessionRef } from "@agentswf/contract/workflow";
+import { messageOf } from "./errors";
+import type { RunLines } from "./run-lines";
+
+/** Where a session lives: the agent's own home, its sandbox and its skills (story 042). */
+export type SessionPlace = { home?: string; sandbox?: SessionSandbox; skills?: SessionSkills };
+type SessionFields = SessionPlace & { operation?: string };
+type Seen = { harness: string; fields: SessionFields };
+
+/**
+ * An attempt's `session` lines in `run.jsonl`: each native session an agent is seen with, once per
+ * attempt, as it becomes known. The latest one of an agent is what a continue resumes it on.
+ */
+export class SessionLines {
+  /** By agent, each session asked for and not failed, in the order seen. */
+  readonly #written = new Map<string, Map<string, Seen>>();
+  readonly #writes = new Set<Promise<void>>();
+  /** Sessions a failed write dropped, which `flushed()` tries once more. */
+  readonly #dropped: { agent: string; id: string; seen: Seen }[] = [];
+
+  constructor(
+    private readonly options: {
+      lines: RunLines;
+      /**
+       * A line that could not be written: tried again when the session is next seen, and once
+       * more as the attempt flushes; a second failure there stays a warning. Until one is written,
+       * a continue reopens the agent on its last session recorded, or anew if none was.
+       */
+      failed(message: string): void;
+    },
+  ) {}
+
+  /** `operation` is the operation the sessions were seen in; the rest, where the session lives. */
+  known(agent: string, sessions: readonly NativeSessionRef[], fields: SessionFields = {}): void {
+    let written = this.#written.get(agent);
+    if (!written) {
+      written = new Map();
+      this.#written.set(agent, written);
+    }
+    for (const { harness, id } of sessions) {
+      if (written.has(id)) continue;
+      written.set(id, { harness, fields });
+      const write = this.options.lines
+        .append({
+          kind: "session",
+          attempt: this.options.lines.attempt,
+          at: new Date().toISOString(),
+          agent,
+          harness,
+          session: id,
+          ...(fields.operation === undefined ? {} : { operation: fields.operation }),
+          ...(fields.home === undefined ? {} : { home: fields.home }),
+          ...(fields.sandbox === undefined ? {} : { sandbox: fields.sandbox }),
+          ...(fields.skills === undefined ? {} : { skills: fields.skills }),
+        })
+        .catch((error) => {
+          // It and those seen after it are written again, in order, when next seen: the latest
+          // line stays the newest session.
+          const seen = [...written];
+          const at = seen.findIndex(([each]) => each === id);
+          if (at >= 0) {
+            for (const [later, how] of seen.slice(at)) {
+              written.delete(later);
+              this.#dropped.push({ agent, id: later, seen: how });
+            }
+          }
+          this.options.failed(
+            `awf: agent ${agent}'s session was not recorded: ${messageOf(error)}`,
+          );
+        })
+        .finally(() => this.#writes.delete(write));
+      this.#writes.add(write);
+    }
+  }
+
+  /**
+   * Once every line asked for so far is written, or has failed; a session a failed write dropped,
+   * and not seen since, is tried once more first.
+   */
+  async flushed(): Promise<void> {
+    const settled = async () => {
+      while (this.#writes.size > 0) await Promise.all(this.#writes);
+    };
+    await settled();
+    const dropped = this.#dropped.splice(0);
+    for (const { agent, id, seen } of dropped) {
+      this.known(agent, [{ harness: seen.harness, id }], seen.fields);
+    }
+    await settled();
+    this.#dropped.length = 0;
+  }
+}

package/src/skills/run-skills.ts

@@ -4,6 +4,7 @@ import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 import type { AgentSkillsRecord, SkillRecord } from "@agentswf/contract/records";
 import type { SkillSource } from "@agentswf/contract/workflow";
+import { workDir } from "../runs";
 import { cachedRepository, extract, fetchCommit, findSkill } from "./fetch";
 import { parseSkillFile, repositoryUrl } from "./sources";
 import { copySkillTree, digestTree } from "./tree";
@@ -38,7 +39,7 @@ export class RunSkills {
   constructor(options: { runDir: string; cacheRoot?: string; environment?: Environment }) {
     this.#environment = options.environment ?? process.env;
     // Absolute: git runs in the cache's repository, and a harness is pointed at these paths.
-    this.#root = resolve(options.runDir, "skills");
+    this.#root = resolve(workDir(options.runDir), "skills");
     this.#cache = resolve(options.cacheRoot ?? defaultCacheRoot(this.#environment));
   }
 
@@ -67,6 +68,12 @@ export class RunSkills {
     return this.#records.map((record) => structuredClone(record));
   }
 
+  /** What `agent` was given, as last recorded. */
+  of(agent: string): AgentSkillsRecord | undefined {
+    const found = this.#records.findLast((record) => record.agent === agent);
+    return found && structuredClone(found);
+  }
+
   #one(source: SkillSource): Promise<ResolvedSkill> {
     const key = JSON.stringify(source);
     let resolving = this.#resolved.get(key);

package/src/sources.ts

@@ -1,5 +1,6 @@
 import type { WaitTake } from "@agentswf/contract/records";
-import { awfEventOf, type JsonValue, type WorkflowEvent } from "@agentswf/contract/workflow";
+import type { JsonValue, WorkflowEvent } from "@agentswf/contract/workflow";
+import { matches, recordName } from "./run-policy/waits";
 
 /** What each source the run issued takes: only awf makes a source, so only these are. */
 const takes = new WeakMap<object, WaitTake>();
@@ -35,16 +36,6 @@ export function isSignal(value: unknown): boolean {
 
 type Looked = { name: string; from: string; data?: unknown };
 
-/**
- * The name the mailbox records an event under: awf's keep `agent:ended` and `participant:reply`,
- * from their key, whatever name the workflow declares and is handed, `{key}:ended` or `{key}:reply`.
- */
-export function recordName(event: { name: string; from: string }): string {
-  const awf = awfEventOf(event.name);
-  if (!awf || awf.key !== event.from) return event.name;
-  return awf.kind === "ended" ? "agent:ended" : "participant:reply";
-}
-
 /** `event` under the name the workflow declares for it, where it declares one. */
 export function presented<E extends WorkflowEvent<string, JsonValue>>(
   event: E,
@@ -55,39 +46,11 @@ export function presented<E extends WorkflowEvent<string, JsonValue>>(
   return Object.freeze({ ...event, name: `${event.from}:${kind}` });
 }
 
-/** The first of `branches` that takes `event`. */
-export function branchOf(
-  branches: readonly (readonly [string, WaitTake])[],
-  event: Looked,
-): string | undefined {
-  return branches.find(([, take]) => matches(event, take))?.[0];
-}
-
 /** What a source takes; undefined for anything the run didn't issue as one. */
 export function takeOf(value: unknown): WaitTake | undefined {
   return typeof value === "object" && value !== null ? takes.get(value) : undefined;
 }
 
-/** Whether a wait that takes `take` takes `event`, under its recorded name or its declared one. */
-export function matches(
-  event: { name: string; from: string; data?: unknown },
-  take: WaitTake,
-): boolean {
-  if (recordName(event) !== take.name) return false;
-  if (take.from !== undefined && event.from !== take.from) return false;
-  if (take.turn === undefined) return true;
-  const data = event.data as { turn?: unknown } | null | undefined;
-  return typeof data === "object" && data !== null && data.turn === take.turn;
-}
-
-/** Whether a wait taking `wanted`, or everything when it names nothing, takes `event`. */
-export function wouldTake(
-  event: { name: string; from: string; data?: unknown },
-  wanted: readonly WaitTake[] | undefined,
-): boolean {
-  return wanted === undefined || wanted.some((take) => matches(event, take));
-}
-
 /**
  * What a branch hands back of the event it took: awf's own events as their data with the event's id
  * and arrival, and a workflow's own event, or any a signal takes, whole.