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

package/src/skills/fetch.ts

@@ -0,0 +1,305 @@
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { exists } from "../files";
+import { parseSkillFile } from "./sources";
+import { MAX_BYTES, MAX_FILES } from "./tree";
+
+type Environment = Readonly<Record<string, string | undefined>>;
+type GitResult = { ok: boolean; out: string; err: string };
+
+/** Past this, a fetch is stuck, not slow: a skill is a few files. */
+const GIT_TIMEOUT_MS = 5 * 60_000;
+const HEX = /^[0-9a-f]{7,40}$/i;
+
+/** A bare repository per URL in `cache`, shared by every run: git locks its own refs and objects. */
+export async function cachedRepository(
+  cache: string,
+  url: string,
+  environment: Environment,
+): Promise<string> {
+  const directory = join(
+    cache,
+    "repos",
+    createHash("sha256").update(url).digest("hex").slice(0, 24),
+  );
+  if (!(await exists(join(directory, "HEAD")))) {
+    await mkdir(join(cache, "repos"), { recursive: true });
+    const staged = `${directory}.${randomUUID()}`;
+    await git(["init", "--quiet", "--bare", staged], environment);
+    // Two runs may create it at once; the one that lands second keeps the first's.
+    await rename(staged, directory).catch(() => rm(staged, { recursive: true, force: true }));
+  }
+  return directory;
+}
+
+/**
+ * The commit `ref` names, or the default branch's, in `repository`: fetched unless it is a commit
+ * an earlier fetch kept. Every commit resolved is kept under `refs/awf/commits/`, so its objects
+ * stay and a run that pins it again needs no network.
+ */
+export async function fetchCommit(
+  repository: string,
+  url: string,
+  ref: string | undefined,
+  environment: Environment,
+): Promise<string> {
+  const kept = ref && HEX.test(ref) ? await commitOf(repository, ref, environment) : undefined;
+  if (kept) return kept;
+  // A ref of our own per fetch: two agents or runs fetching at once never read each other's.
+  const into = `refs/awf/fetch/${randomUUID()}`;
+  try {
+    const shallow = await unlocked(() =>
+      git(
+        ["-C", repository, "fetch", "--quiet", "--depth", "1", url, `+${ref ?? "HEAD"}:${into}`],
+        environment,
+        { allowFailure: true },
+      ),
+    );
+    if (shallow.ok) return await keep(repository, into, environment);
+    if (ref === undefined || !HEX.test(ref)) {
+      throw new Error(`cannot fetch ${ref ?? "the default branch"} of ${url}: ${shallow.err}`);
+    }
+    // A commit, which a server need not serve alone, and a short one it cannot: every branch and
+    // tag with their history, past any shallow boundary an earlier fetch left.
+    const shallowed = await git(
+      ["-C", repository, "rev-parse", "--is-shallow-repository"],
+      environment,
+    );
+    const full = await unlocked(() =>
+      git(
+        [
+          "-C",
+          repository,
+          "fetch",
+          "--quiet",
+          ...(shallowed.out === "true" ? ["--unshallow"] : []),
+          url,
+          `+refs/heads/*:${into}/heads/*`,
+          `+refs/tags/*:${into}/tags/*`,
+        ],
+        environment,
+        { allowFailure: true },
+      ),
+    );
+    if (!full.ok) throw new Error(`cannot fetch ${url}: ${full.err}`);
+    if (!(await commitOf(repository, ref, environment))) {
+      throw new Error(`${url} has no commit ${ref}`);
+    }
+    return await keep(repository, ref, environment);
+  } finally {
+    const refs = await git(
+      ["-C", repository, "for-each-ref", "--format=%(refname)", into, `${into}/`],
+      environment,
+      { allowFailure: true },
+    );
+    const names = refs.out.split("\n").filter(Boolean);
+    if (names.length > 0) {
+      await git(["-C", repository, "update-ref", "--stdin"], environment, {
+        allowFailure: true,
+        stdin: names.map((name) => `delete ${name}\n`).join(""),
+      });
+    }
+  }
+}
+
+/** The commit `name` resolves to, an annotated tag peeled, or `undefined`. */
+async function commitOf(
+  repository: string,
+  name: string,
+  environment: Environment,
+): Promise<string | undefined> {
+  const found = await git(
+    ["-C", repository, "rev-parse", "--verify", "--quiet", `${name}^{commit}`],
+    environment,
+    { allowFailure: true },
+  );
+  return found.ok ? found.out : undefined;
+}
+
+async function keep(repository: string, name: string, environment: Environment): Promise<string> {
+  const commit = await commitOf(repository, name, environment);
+  if (!commit) throw new Error(`${name} is not a commit`);
+  await git(["-C", repository, "update-ref", `refs/awf/commits/${commit}`, commit], environment);
+  return commit;
+}
+
+/**
+ * `fetch`, again while another run's fetch into the shared cache holds one of git's locks: git
+ * refuses rather than waits. Two minutes covers a large fetch by the other run.
+ */
+async function unlocked(fetch: () => Promise<GitResult>): Promise<GitResult> {
+  for (let attempt = 0; ; attempt++) {
+    const result = await fetch();
+    if (result.ok || !/\.lock'?: File exists/.test(result.err) || attempt >= 480) return result;
+    await Bun.sleep(250);
+  }
+}
+
+/** The directory, relative to the repository's root, whose `SKILL.md` is named `skill`. */
+export async function findSkill(
+  repository: string,
+  commit: string,
+  skill: string,
+  environment: Environment,
+): Promise<string> {
+  // `-z`, or a path outside ASCII comes back quoted and never matches.
+  const listed = await git(
+    ["-C", repository, "ls-tree", "-r", "-z", "--name-only", commit],
+    environment,
+  );
+  const files = listed.out
+    .split("\0")
+    .filter(
+      (path) =>
+        (path === "SKILL.md" || path.endsWith("/SKILL.md")) && !path.includes("node_modules/"),
+    );
+  const matches: string[] = [];
+  const names: string[] = [];
+  for (const file of files) {
+    const text = await git(["-C", repository, "show", `${commit}:${file}`], environment);
+    let name: string | undefined;
+    try {
+      ({ name } = parseSkillFile(text.out, file));
+    } catch {
+      // Not a skill this can load; the one asked for may still be elsewhere.
+    }
+    if (name) names.push(name);
+    if (name === skill) matches.push(file === "SKILL.md" ? "" : file.slice(0, -"/SKILL.md".length));
+  }
+  if (matches.length === 0) {
+    const known = names.length > 0 ? `; it has ${names.slice(0, 10).join(", ")}` : "";
+    throw new Error(`no skill named ${skill} at ${commit.slice(0, 12)}${known}`);
+  }
+  if (matches.length > 1) {
+    throw new Error(`more than one skill is named ${skill}: ${matches.join(", ")}`);
+  }
+  return matches[0]!;
+}
+
+/**
+ * `within` at `commit`, written under `into` from git's objects: every file, where an archive
+ * would drop what `.gitattributes` marks `export-ignore`, and a link or a submodule refused, and
+ * the caps checked, before anything is written.
+ */
+export async function extract(
+  repository: string,
+  commit: string,
+  within: string,
+  into: string,
+  environment: Environment,
+): Promise<void> {
+  const tree = within === "" ? `${commit}^{tree}` : `${commit}:${within}`;
+  const listed = await git(["-C", repository, "ls-tree", "-r", "-z", "-l", tree], environment);
+  const entries: { mode: string; object: string; path: string }[] = [];
+  let bytes = 0;
+  for (const line of listed.out.split("\0").filter(Boolean)) {
+    const match = /^(\d+) (\w+) ([0-9a-f]+) +(-|\d+)\t(.+)$/s.exec(line);
+    if (!match) throw new Error(`cannot read git's listing of ${tree}: ${line}`);
+    const [, mode, , object, size, path] = match as unknown as [
+      string,
+      string,
+      string,
+      string,
+      string,
+      string,
+    ];
+    if (mode === "120000") throw new Error(`skill at ${within || "the root"}: ${path} is a link`);
+    if (mode !== "100644" && mode !== "100755") {
+      throw new Error(`skill at ${within || "the root"}: ${path} is not a file`);
+    }
+    if (path.split("/").some((part) => part === "" || part === "." || part === "..")) {
+      throw new Error(`skill at ${within || "the root"}: ${path} is not a path inside it`);
+    }
+    bytes += Number(size);
+    entries.push({ mode, object, path });
+  }
+  if (bytes > MAX_BYTES || entries.length > MAX_FILES) {
+    throw new Error(
+      `skill at ${within || "the root"} is over ${MAX_FILES} files or ${MAX_BYTES} bytes`,
+    );
+  }
+  const blobs = await readBlobs(
+    repository,
+    entries.map((entry) => entry.object),
+    environment,
+  );
+  for (const [index, entry] of entries.entries()) {
+    const path = join(into, entry.path);
+    await mkdir(dirname(path), { recursive: true, mode: 0o755 });
+    await writeFile(path, blobs[index]!, { mode: entry.mode === "100755" ? 0o755 : 0o644 });
+  }
+}
+
+/** Each object's bytes, in order, from one `cat-file --batch`. */
+async function readBlobs(
+  repository: string,
+  objects: readonly string[],
+  environment: Environment,
+): Promise<Buffer[]> {
+  if (objects.length === 0) return [];
+  const child = Bun.spawn({
+    cmd: ["git", "-C", repository, "cat-file", "--batch"],
+    env: gitEnvironment(environment),
+    stdin: new TextEncoder().encode(`${objects.join("\n")}\n`),
+    stdout: "pipe",
+    stderr: "pipe",
+    timeout: GIT_TIMEOUT_MS,
+  });
+  const [code, out, err] = await Promise.all([
+    child.exited,
+    new Response(child.stdout).arrayBuffer(),
+    new Response(child.stderr).text(),
+  ]);
+  if (code !== 0) throw new Error(`git cat-file failed: ${err.trim()}`);
+  const buffer = Buffer.from(out);
+  const blobs: Buffer[] = [];
+  let at = 0;
+  for (const object of objects) {
+    const end = buffer.indexOf(10, at);
+    const header = buffer.subarray(at, end).toString("utf8");
+    const match = /^([0-9a-f]+) blob (\d+)$/.exec(header);
+    if (!match || match[1] !== object) throw new Error(`git cat-file answered ${header}`);
+    const size = Number(match[2]);
+    blobs.push(buffer.subarray(end + 1, end + 1 + size));
+    at = end + 1 + size + 1;
+  }
+  return blobs;
+}
+
+/**
+ * Never a prompt: a private repository fails instead of waiting for a password nobody types, and
+ * ssh, which ignores git's variable, asks for no passphrase or host key.
+ */
+function gitEnvironment(environment: Environment): Record<string, string | undefined> {
+  return {
+    ...environment,
+    GIT_TERMINAL_PROMPT: "0",
+    GIT_SSH_COMMAND: environment.GIT_SSH_COMMAND ?? "ssh -o BatchMode=yes",
+  };
+}
+
+async function git(
+  args: readonly string[],
+  environment: Environment,
+  options: { allowFailure?: boolean; stdin?: string } = {},
+): Promise<GitResult> {
+  const child = Bun.spawn({
+    cmd: ["git", ...args],
+    env: gitEnvironment(environment),
+    stdin: options.stdin === undefined ? "ignore" : new TextEncoder().encode(options.stdin),
+    stdout: "pipe",
+    stderr: "pipe",
+    timeout: GIT_TIMEOUT_MS,
+  });
+  const [code, out, err] = await Promise.all([
+    child.exited,
+    new Response(child.stdout).text(),
+    new Response(child.stderr).text(),
+  ]);
+  const result = { ok: code === 0, out: out.trim(), err: err.trim() || `exit ${code}` };
+  if (!result.ok && !options.allowFailure) {
+    throw new Error(`git ${args[0] === "-C" ? args[2] : args[0]} failed: ${result.err}`);
+  }
+  return result;
+}

package/src/skills/run-skills.ts

@@ -0,0 +1,181 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, realpath } from "node:fs/promises";
+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 { cachedRepository, extract, fetchCommit, findSkill } from "./fetch";
+import { parseSkillFile, repositoryUrl } from "./sources";
+import { copySkillTree, digestTree } from "./tree";
+
+export { parseSkillFile, readSkillSources } from "./sources";
+
+type Environment = Readonly<Record<string, string | undefined>>;
+
+/** A skill resolved for this run: a checked snapshot every agent naming it is copied from. */
+export type ResolvedSkill = {
+  name: string;
+  /** The run's snapshot, which no agent reaches. */
+  snapshot: string;
+  record: SkillRecord;
+};
+
+/**
+ * A run's skills: each source resolved once, so every agent naming it gets the same files, into a
+ * snapshot under the run directory; then a copy per agent, and the record of what each agent had.
+ */
+export class RunSkills {
+  readonly #resolved = new Map<string, Promise<ResolvedSkill>>();
+  /** Each repository's last fetch in line: git's shallow lock refuses a second one at once. */
+  readonly #fetching = new Map<string, Promise<unknown>>();
+  /** Each (URL, ref)'s commit, so two skills from one repository's `main` get one commit. */
+  readonly #commits = new Map<string, Promise<string>>();
+  readonly #records: AgentSkillsRecord[] = [];
+  readonly #root: string;
+  readonly #cache: string;
+  readonly #environment: Environment;
+
+  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.#cache = resolve(options.cacheRoot ?? defaultCacheRoot(this.#environment));
+  }
+
+  /** Every source resolved and checked, or the first reason one could not be. */
+  async resolve(sources: readonly SkillSource[]): Promise<ResolvedSkill[]> {
+    const resolved = await Promise.all(sources.map((source) => this.#one(source)));
+    const seen = new Set<string>();
+    for (const { name } of resolved) {
+      if (seen.has(name)) throw new Error(`two skills are named ${name}`);
+      seen.add(name);
+    }
+    return resolved;
+  }
+
+  /** What an agent was given, and the home of its own it ran with on the host, if any. */
+  record(agent: string, skills: "operator" | readonly ResolvedSkill[], home?: string): void {
+    this.#records.push({
+      callPath: [],
+      agent,
+      skills: skills === "operator" ? "operator" : skills.map((skill) => ({ ...skill.record })),
+      ...(home === undefined ? {} : { home }),
+    });
+  }
+
+  records(): AgentSkillsRecord[] {
+    return this.#records.map((record) => structuredClone(record));
+  }
+
+  #one(source: SkillSource): Promise<ResolvedSkill> {
+    const key = JSON.stringify(source);
+    let resolving = this.#resolved.get(key);
+    if (!resolving) {
+      resolving = "path" in source ? this.#fromPath(source) : this.#fromRepo(source);
+      this.#resolved.set(key, resolving);
+      // A source that failed is tried again by the next agent that names it, not remembered.
+      resolving.catch(() => {
+        if (this.#resolved.get(key) === resolving) this.#resolved.delete(key);
+      });
+    }
+    return resolving;
+  }
+
+  async #fromPath(source: { path: string }): Promise<ResolvedSkill> {
+    let directory: string;
+    try {
+      directory = await realpath(source.path);
+    } catch {
+      throw new Error(`skill path ${source.path} does not exist`);
+    }
+    const snapshot = await this.#snapshot((into) => copySkillTree(directory, into));
+    const { name, digest } = await checkSkill(snapshot, source.path);
+    return { name, snapshot, record: { name, source: { path: source.path }, digest } };
+  }
+
+  async #fromRepo(source: { repo: string; skill: string; ref?: string }): Promise<ResolvedSkill> {
+    const url = repositoryUrl(source.repo);
+    const repository = await cachedRepository(this.#cache, url, this.#environment);
+    const commit = await this.#commit(repository, url, source.ref);
+    const within = await findSkill(repository, commit, source.skill, this.#environment);
+    const snapshot = await this.#snapshot((into) =>
+      extract(repository, commit, within, into, this.#environment),
+    );
+    const label = `${source.repo}@${source.skill}`;
+    const { name, digest } = await checkSkill(snapshot, label);
+    if (name !== source.skill) throw new Error(`${label}: its SKILL.md is named ${name}`);
+    return {
+      name,
+      snapshot,
+      record: {
+        name,
+        source: { ...source },
+        commit,
+        ...(within === "" ? {} : { within }),
+        digest,
+      },
+    };
+  }
+
+  #commit(repository: string, url: string, ref: string | undefined): Promise<string> {
+    const key = `${url}\0${ref ?? ""}`;
+    let commit = this.#commits.get(key);
+    if (!commit) {
+      const fetch = () => fetchCommit(repository, url, ref, this.#environment);
+      commit = (this.#fetching.get(repository) ?? Promise.resolve()).then(fetch, fetch);
+      this.#fetching.set(
+        repository,
+        commit.catch(() => undefined),
+      );
+      this.#commits.set(key, commit);
+      const settled = commit;
+      settled.catch(() => {
+        if (this.#commits.get(key) === settled) this.#commits.delete(key);
+      });
+    }
+    return commit;
+  }
+
+  /** A fresh directory under the run's, filled by `fill` before it is used. */
+  async #snapshot(fill: (into: string) => Promise<void>): Promise<string> {
+    const snapshot = join(this.#root, "sources", randomUUID());
+    await mkdir(snapshot, { recursive: true, mode: 0o700 });
+    await fill(snapshot);
+    return snapshot;
+  }
+}
+
+/**
+ * Copies each skill into `directory/{name}`. The directory is made even for none: a harness pointed
+ * at it must find it.
+ */
+export async function placeSkills(
+  skills: readonly ResolvedSkill[],
+  directory: string,
+): Promise<void> {
+  await mkdir(directory, { recursive: true });
+  for (const skill of skills) await copySkillTree(skill.snapshot, join(directory, skill.name));
+}
+
+function defaultCacheRoot(environment: Environment): string {
+  const cache = environment.XDG_CACHE_HOME || join(environment.HOME ?? homedir(), ".cache");
+  return join(cache, "awf", "skills");
+}
+
+/**
+ * The name and digest of a checked snapshot: a `SKILL.md` with a `name` and a `description`, and
+ * nothing a copy could carry out of it.
+ */
+async function checkSkill(
+  snapshot: string,
+  label: string,
+): Promise<{ name: string; digest: string }> {
+  let text: string;
+  try {
+    text = await readFile(join(snapshot, "SKILL.md"), "utf8");
+  } catch {
+    throw new Error(`skill ${label} has no SKILL.md`);
+  }
+  const { name } = parseSkillFile(text, label);
+  return { name, digest: await digestTree(snapshot) };
+}

package/src/skills/sources.ts

@@ -0,0 +1,87 @@
+import { isAbsolute } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { SkillSource } from "@agentswf/contract/workflow";
+
+/** The name becomes a directory; claude's rule, which every harness accepts. */
+const SKILL_NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const GITHUB_SHORTHAND = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
+
+/** A workflow is untyped JavaScript at run time: each source is checked, and a relative path refused. */
+export function readSkillSources(skills: unknown): SkillSource[] {
+  if (!Array.isArray(skills)) throw new Error("skills must be an array of skill sources");
+  return skills.map((skill): SkillSource => {
+    if (typeof skill === "string") {
+      throw new Error(
+        `skill ${JSON.stringify(skill)}: name a source, { path } or { repo, skill, ref? }`,
+      );
+    }
+    const source = skill as Record<string, unknown> | null;
+    if (source && "path" in source && !("repo" in source) && !("skill" in source)) {
+      return { path: absoluteSkillPath(source.path) };
+    }
+    if (
+      source &&
+      typeof source.repo === "string" &&
+      typeof source.skill === "string" &&
+      !("path" in source)
+    ) {
+      if (source.ref !== undefined && (typeof source.ref !== "string" || source.ref === "")) {
+        throw new Error(`skill ${source.skill}: ref must be a non-empty string`);
+      }
+      repositoryUrl(source.repo);
+      return {
+        repo: source.repo,
+        skill: source.skill,
+        ...(source.ref === undefined ? {} : { ref: source.ref }),
+      };
+    }
+    throw new Error(
+      `not a skill source: ${JSON.stringify(skill)}; use { path } or { repo, skill }`,
+    );
+  });
+}
+
+function absoluteSkillPath(path: unknown): string {
+  if (path instanceof URL) {
+    if (path.protocol !== "file:") throw new Error(`skill path ${path.href} is not a file: URL`);
+    return fileURLToPath(path);
+  }
+  if (typeof path !== "string" || path === "") throw new Error("a skill path must be a string");
+  if (path.startsWith("file:")) return fileURLToPath(path);
+  if (!isAbsolute(path)) {
+    // Relative to what would differ between a workflow and the one that calls it.
+    throw new Error(
+      `skill path ${path} is relative; use an absolute path, or new URL("${path}", import.meta.url)`,
+    );
+  }
+  return path;
+}
+
+/** `owner/repo` is GitHub's; anything else must already be a URL git fetches. */
+export function repositoryUrl(repo: string): string {
+  if (GITHUB_SHORTHAND.test(repo)) return `https://github.com/${repo}.git`;
+  if (/^(?:https?|ssh|git|file):\/\//.test(repo) || /^[\w.-]+@[\w.-]+:/.test(repo)) return repo;
+  throw new Error(`skill repo ${repo} is neither owner/repo nor a git URL`);
+}
+
+/** The frontmatter every harness reads: a `name` it can be a directory by, and a `description`. */
+export function parseSkillFile(text: string, label: string): { name: string; description: string } {
+  const match = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(text);
+  if (!match) throw new Error(`skill ${label}: SKILL.md has no frontmatter`);
+  let front: unknown;
+  try {
+    front = Bun.YAML.parse(match[1]!);
+  } catch (error) {
+    throw new Error(`skill ${label}: SKILL.md frontmatter is not YAML: ${String(error)}`);
+  }
+  const { name, description } = (front ?? {}) as Record<string, unknown>;
+  if (typeof name !== "string" || !SKILL_NAME.test(name) || name.length > 64) {
+    throw new Error(
+      `skill ${label}: its name must be lowercase letters, digits and hyphens, at most 64`,
+    );
+  }
+  if (typeof description !== "string" || description.trim() === "") {
+    throw new Error(`skill ${label}: SKILL.md has no description`);
+  }
+  return { name, description };
+}

package/src/skills/tree.ts

@@ -0,0 +1,60 @@
+import { createHash } from "node:crypto";
+import { lstat, mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+/** Refused: past these, a skill is not instructions and a few scripts. */
+export const MAX_BYTES = 10 * 1024 * 1024;
+export const MAX_FILES = 2_000;
+
+/**
+ * A skill's files, copied: never a link, which could carry what it points at, `~/.ssh` say, into
+ * a sandbox, nor anything but files and directories, and within the size caps.
+ */
+export async function copySkillTree(from: string, to: string): Promise<void> {
+  const budget = { bytes: 0, files: 0 };
+  await mkdir(to, { recursive: true, mode: 0o755 });
+  const walk = async (at: string) => {
+    for (const entry of await readdir(join(from, at))) {
+      const path = join(at, entry);
+      const found = await lstat(join(from, path));
+      if (found.isSymbolicLink()) throw new Error(`skill ${from}: ${path} is a link`);
+      if (found.isDirectory()) {
+        await mkdir(join(to, path), { mode: 0o755 });
+        await walk(path);
+        continue;
+      }
+      if (!found.isFile()) throw new Error(`skill ${from}: ${path} is not a file`);
+      budget.bytes += found.size;
+      budget.files += 1;
+      if (budget.bytes > MAX_BYTES || budget.files > MAX_FILES) {
+        throw new Error(`skill ${from} is over ${MAX_FILES} files or ${MAX_BYTES} bytes`);
+      }
+      await writeFile(join(to, path), await readFile(join(from, path)), {
+        mode: found.mode & 0o111 ? 0o755 : 0o644,
+      });
+    }
+  };
+  await walk("");
+}
+
+/** Over each file's path, executable bit and bytes, sorted: equal digests, equal skills. */
+export async function digestTree(root: string): Promise<string> {
+  const lines: string[] = [];
+  const walk = async (at: string) => {
+    for (const entry of await readdir(join(root, at))) {
+      const path = join(at, entry);
+      const found = await lstat(join(root, path));
+      if (found.isDirectory()) {
+        await walk(path);
+        continue;
+      }
+      const bytes = await readFile(join(root, path));
+      const hash = createHash("sha256").update(bytes).digest("hex");
+      lines.push(`${path}\0${found.mode & 0o111 ? "x" : "-"}\0${hash}\n`);
+    }
+  };
+  await walk("");
+  const digest = createHash("sha256");
+  for (const line of lines.sort()) digest.update(line);
+  return `sha256:${digest.digest("hex")}`;
+}