@foldrun/core 0.2.0

package/src/library.ts

@@ -0,0 +1,419 @@
+// The account library: shared skills, scripts, memory and tool definitions
+// that every workspace in the account can use.
+//
+//   data/<tenant>/library/
+//   ├── skills/<name>/SKILL.md   Agent Skills format, shared
+//   ├── scripts/<file>           shared executables
+//   ├── memory/*.md              organisation-wide knowledge
+//   └── tools/<name>.md          reusable API definitions (frontmatter = ApiSpec)
+//
+// Resolution is nearest-wins, the same rule OKF uses for knowledge: an agent's
+// own file beats its workspace's, which beats the account's. So a team can set
+// a house style once and one agent can still override it.
+
+import fs from "node:fs";
+import path from "node:path";
+import { dataRoot, singleWorkspace } from "./paths.ts";
+import matter from "gray-matter";
+import { KINDS } from "./kinds.ts";
+import { recordRevision, registerTreeReader } from "./history.ts";
+import {
+  assertSafeName,
+  assertCanonicalCase,
+  buildMemoryIndex,
+  parseToolDef,
+  readToolDir,
+  syncBundleFor,
+  listWorkspaces,
+  listAgents,
+  workspaceDir,
+  type ToolDef,
+} from "./store.ts";
+
+
+export type LibraryKind = "skills" | "scripts" | "memory" | "knowledge" | "tools";
+// Same order as the workspace nav and asset pages — one list, one order.
+// Order matters and is asserted: it is the order every noun list in the
+// product uses. Tools then scripts, because a script is material a tool
+// points at — see the KINDS table, which is where the order is declared.
+export const LIBRARY_KINDS: LibraryKind[] = ["tools", "knowledge", "memory", "skills", "scripts"];
+
+export function libraryDir(tenant: string, kind?: LibraryKind) {
+  // Alongside the workspace in single-workspace mode: ./library, so a shared
+  // library is still possible on a laptop without inventing a home directory.
+  const single = singleWorkspace();
+  if (single) {
+    const base = path.join(path.resolve(single), "..", "library");
+    return kind ? path.join(base, kind) : base;
+  }
+  assertSafeName(tenant, "tenant");
+  return kind
+    ? path.join(dataRoot(), tenant, "library", kind)
+    : path.join(dataRoot(), tenant, "library");
+}
+
+const TEXT_EXT = /\.(md|py|sh|[mc]?js|ts|rb|sql|txt|json|ya?ml|toml)$/i;
+
+function assertLibraryPath(kind: LibraryKind, rel: string) {
+  const norm = path.normalize(rel);
+  assertCanonicalCase(norm);
+  if (norm.startsWith("..") || path.isAbsolute(norm)) throw new Error(`illegal path: ${rel}`);
+  if (!TEXT_EXT.test(norm)) throw new Error(`unsupported file type: ${rel}`);
+  // A flat tool is a lone .md; a folder tool is tool.md plus the code it
+  // runs, so anything is allowed one level down inside a tool's own folder.
+  if (kind === "tools" && !norm.endsWith(".md") && !norm.includes("/")) {
+    throw new Error("a tool is a .md definition, or a folder holding tool.md and its code");
+  }
+  return norm;
+}
+
+export interface LibraryEntry {
+  /** Path relative to this kind's directory. */
+  path: string;
+  name: string;
+  description: string;
+  /** For skills: true when the folder bundles scripts/. */
+  hasScripts?: boolean;
+  /**
+   * For tools: how this one connects — http, script or mcp. Surfaced so a
+   * list of tools reads as one vocabulary with three transports, rather
+   * than a page of names whose differences are invisible until you open
+   * them. For a script tool it also names the file it runs, which is the
+   * link between this shelf and the code shelf.
+   */
+  transport?: "http" | "script" | "mcp";
+  runs?: string;
+  updatedAt: string;
+}
+
+export function listLibrary(tenant: string, kind: LibraryKind): LibraryEntry[] {
+  const dir = libraryDir(tenant, kind);
+  if (!fs.existsSync(dir)) return [];
+  const out: LibraryEntry[] = [];
+
+  const describe = (file: string, fallback: string) => {
+    try {
+      const { data } = matter(fs.readFileSync(file, "utf8"));
+      return { name: data.name ?? fallback, description: data.description ?? "" };
+    } catch {
+      return { name: fallback, description: "" };
+    }
+  };
+
+  // A folder tool is one entry named by its manifest, and its code is not a
+  // separate row: listing tools/browser/run.mjs beside tools/browser/tool.md
+  // says there are two tools called browser, one of which cannot be granted.
+  if (kind === "tools") {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        const manifest = path.join(full, "tool.md");
+        if (!fs.existsSync(manifest)) continue;
+        out.push({
+          ...describe(manifest, entry.name),
+          path: `${entry.name}/tool.md`,
+          ...toolShape(manifest, entry.name),
+          updatedAt: fs.statSync(manifest).mtime.toISOString(),
+        });
+      } else if (entry.name.endsWith(".md")) {
+        out.push({
+          ...describe(full, entry.name.replace(/\.md$/, "")),
+          path: entry.name,
+          ...toolShape(full, entry.name),
+          updatedAt: fs.statSync(full).mtime.toISOString(),
+        });
+      }
+    }
+    return out.sort((a, b) => a.path.localeCompare(b.path));
+  }
+
+  if (kind === "skills") {
+    for (const entry of fs.readdirSync(dir).sort()) {
+      const full = path.join(dir, entry);
+      if (fs.statSync(full).isDirectory()) {
+        const skillMd = path.join(full, "SKILL.md");
+        if (!fs.existsSync(skillMd)) continue;
+        out.push({
+          ...describe(skillMd, entry),
+          path: `${entry}/SKILL.md`,
+          hasScripts: fs.existsSync(path.join(full, "scripts")),
+          updatedAt: fs.statSync(skillMd).mtime.toISOString(),
+        });
+      } else if (entry.endsWith(".md")) {
+        out.push({
+          ...describe(full, entry.replace(/\.md$/, "")),
+          path: entry,
+          hasScripts: false,
+          updatedAt: fs.statSync(full).mtime.toISOString(),
+        });
+      }
+    }
+    return out;
+  }
+
+  for (const entry of fs.readdirSync(dir, { recursive: true })) {
+    const rel = String(entry);
+    const full = path.join(dir, rel);
+    if (!fs.statSync(full).isFile() || !TEXT_EXT.test(rel)) continue;
+    // The memory index is generated, so it isn't an entry in its own list.
+    if ((kind === "memory" || kind === "knowledge") &&
+        ["index.md", "log.md"].includes(rel)) continue;
+    out.push({
+      ...describe(full, rel),
+      path: rel,
+      updatedAt: fs.statSync(full).mtime.toISOString(),
+    });
+  }
+  return out.sort((a, b) => a.path.localeCompare(b.path));
+}
+
+/** How a tool connects, and (for a script tool) the code it runs. */
+function toolShape(file: string, rel: string): { transport?: LibraryEntry["transport"]; runs?: string } {
+  try {
+    const { data } = matter(fs.readFileSync(file, "utf8"));
+    const def = parseToolDef(data as Record<string, unknown>, rel.replace(/\.md$/, ""));
+    if (!def) return {};
+    return {
+      transport: def.kind,
+      ...(def.kind === "script" ? { runs: (def.spec as { run?: string }).run } : {}),
+    };
+  } catch {
+    return {}; // a malformed definition gets no badge, not a broken page
+  }
+}
+
+export function readLibraryFile(tenant: string, kind: LibraryKind, rel: string): string {
+  const p = path.join(libraryDir(tenant, kind), assertLibraryPath(kind, rel));
+  if (!fs.existsSync(p)) throw new Error(`not found: ${rel}`);
+  return fs.readFileSync(p, "utf8");
+}
+
+/** Is there already something here? For refusing to create over it. */
+export function libraryFileExists(tenant: string, kind: LibraryKind, rel: string): boolean {
+  try {
+    return fs.existsSync(path.join(libraryDir(tenant, kind), assertLibraryPath(kind, rel)));
+  } catch {
+    return false; // an illegal path does not exist, and write will refuse it
+  }
+}
+
+export function writeLibraryFile(
+  tenant: string,
+  kind: LibraryKind,
+  rel: string,
+  content: string,
+  meta: { by?: string; message?: string } = {},
+) {
+  if (content.length > 256 * 1024) throw new Error("file too large");
+  const norm = assertLibraryPath(kind, rel);
+  if (norm.endsWith(".md")) matter(content); // reject broken frontmatter
+  const p = path.join(libraryDir(tenant, kind), norm);
+  const existed = fs.existsSync(p);
+  const before = existed ? fs.readFileSync(p, "utf8") : null;
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.writeFileSync(p, content);
+  // Executable where code lives: the scripts shelf, a skill's bundled
+  // scripts/, and now a folder tool's own code — a tool whose run.mjs is not
+  // executable fails at the exec, which reads as "the tool is broken".
+  if (kind === "scripts" || /scripts\//.test(norm) || (kind === "tools" && !norm.endsWith(".md"))) {
+    fs.chmodSync(p, 0o755);
+  }
+  syncBundleFor(p, existed ? "Update" : "Creation");
+  // The account shelf has one history, keyed by kind/path.
+  recordRevision(tenant, "@library", [{ path: `${kind}/${norm}`, before, after: content }], meta);
+}
+
+export function deleteLibraryPath(
+  tenant: string,
+  kind: LibraryKind,
+  rel: string,
+  meta: { by?: string; message?: string } = {},
+) {
+  const norm = path.normalize(rel);
+  if (norm.startsWith("..") || path.isAbsolute(norm)) throw new Error(`illegal path: ${rel}`);
+  const target = path.join(libraryDir(tenant, kind), norm);
+  const gone: { path: string; before: string | null; after: null }[] = [];
+  if (fs.existsSync(target)) {
+    const entries = fs.statSync(target).isFile()
+      ? [target]
+      : fs.readdirSync(target, { recursive: true }).map((e) => path.join(target, String(e)));
+    for (const e of entries) {
+      try {
+        if (fs.statSync(e).isFile()) {
+          gone.push({ path: `${kind}/${path.relative(libraryDir(tenant, kind), e).split(path.sep).join("/")}`, before: fs.readFileSync(e, "utf8"), after: null });
+        }
+      } catch {
+        // skip
+      }
+    }
+  }
+  fs.rmSync(target, { recursive: true, force: true });
+  recordRevision(tenant, "@library", gone, { message: `deleted ${kind}/${norm}`, ...meta });
+}
+
+// ---------- consumed by the runner ----------
+
+/** Library tool definitions, keyed by name — http or script, both grantable by name in `tools:`. */
+export function libraryTools(tenant: string): Record<string, ToolDef> {
+  return readToolDir(libraryDir(tenant, "tools"), "account");
+}
+
+/** Shared memory index — derived from the files, like every other scope. */
+export function libraryMemoryIndex(tenant: string): string | null {
+  // The prefix matters: without it the index names bare filenames that don't
+  // exist relative to the agent, so it guesses and gets denied.
+  return buildMemoryIndex(libraryDir(tenant, "memory"), "../../../../library/memory/");
+}
+
+/**
+ * Account-scope creation, expressed as a path inside `library/<kind>/`.
+ *
+ * The content comes from KINDS — an account skill and a workspace skill are
+ * the same document in a different place, and used to be two templates that
+ * drifted. `file()` returns a path from the scope root (`skills/x/SKILL.md`);
+ * here the kind directory is already the root, so the leading segment goes.
+ */
+export const LIBRARY_TEMPLATES: Record<LibraryKind, (name: string) => { path: string; content: string }> =
+  Object.fromEntries(
+    LIBRARY_KINDS.map((kind) => [
+      kind,
+      (name: string) => ({
+        path: KINDS[kind].file(name).replace(new RegExp(`^${kind}/`), ""),
+        content: KINDS[kind].template(name),
+      }),
+    ]),
+  ) as Record<LibraryKind, (name: string) => { path: string; content: string }>;
+
+// ---------------------------------------------------------------- usage
+
+/**
+ * Who actually depends on a shared file.
+ *
+ * The account library is the one place where editing a single file changes
+ * behaviour in workspaces you are not looking at, and nothing in the product
+ * could answer "if I rotate this credential, what breaks?" The graph shows
+ * containment — a library tool hangs off the account node — never consumption,
+ * so the edge that matters was the one edge missing.
+ *
+ * Two relations, because the shared scopes work in two different ways:
+ *
+ *   use       an explicit grant. Only tools have one (`tools: [name]`), which
+ *             is exactly why tools are the kind worth tracing: a credential
+ *             reaches precisely the agents that named it, and no others.
+ *
+ *   shadowed  a nearer file of the same name wins. This is the quiet one — the
+ *             account file still exists, still looks live on this page, and is
+ *             not what runs in that workspace. Resolution is nearest-wins, so
+ *             a name collision is a silent override rather than an error.
+ *
+ * Everything else (memory, knowledge) is indexed for every agent in scope with
+ * no per-agent opt-in, so "used by" is "everyone" — true, and not information.
+ * Those kinds report shadowing only.
+ */
+export interface LibraryUse {
+  workspace: string;
+  /** The agent that opted in or overrides it; null when it is workspace-wide. */
+  agent: string | null;
+  relation: "use" | "shadowed";
+}
+
+/** The file a kind would occupy at a given scope root, relative to that root. */
+function localPath(kind: LibraryKind, name: string): string {
+  return KINDS[kind].file(name);
+}
+
+export function libraryUsage(tenant: string, kind: LibraryKind, name: string): LibraryUse[] {
+  const out: LibraryUse[] = [];
+
+  for (const ws of listWorkspaces(tenant)) {
+    const dir = workspaceDir(tenant, ws.name);
+    const agents = listAgents(tenant, ws.name);
+
+    // Explicit grant. Only tools have one.
+    if (kind === "tools") {
+      for (const a of agents) {
+        if (a.ownTools.includes(name)) out.push({ workspace: ws.name, agent: a.name, relation: "use" });
+      }
+    }
+
+    // Nearest-wins: a workspace file of the same name, or an agent's own.
+    if (fs.existsSync(path.join(dir, localPath(kind, name)))) {
+      out.push({ workspace: ws.name, agent: null, relation: "shadowed" });
+    }
+    for (const a of agents) {
+      const own = path.join(dir, "agents", a.name, localPath(kind, name));
+      if (fs.existsSync(own)) {
+        out.push({ workspace: ws.name, agent: a.name, relation: "shadowed" });
+      }
+    }
+  }
+
+  return out;
+}
+
+// The account shelf as one tree, kind/path — see registerTreeReader.
+registerTreeReader((tenant, scope) => {
+  if (scope !== "@library") return null;
+  const out: { path: string; before: null; after: string }[] = [];
+  for (const kind of LIBRARY_KINDS) {
+    const dir = libraryDir(tenant, kind);
+    if (!fs.existsSync(dir)) continue;
+    for (const entry of fs.readdirSync(dir, { recursive: true })) {
+      const rel = String(entry).split(path.sep).join("/");
+      const full = path.join(dir, rel);
+      try {
+        if (!fs.statSync(full).isFile() || !TEXT_EXT.test(rel)) continue;
+        out.push({ path: `${kind}/${rel}`, before: null, after: fs.readFileSync(full, "utf8") });
+      } catch {
+        // skip
+      }
+    }
+  }
+  return out;
+});
+
+
+/**
+ * Make the shelf match a tree — what a push to the library repository does.
+ * Written with plain fs and recorded as ONE revision at the end: going
+ * through writeLibraryFile per file would commit each one on top of the
+ * pushed commit, and the history would show a push as fifty edits.
+ */
+export function syncLibraryFromTree(tenant: string, files: { path: string; content: string }[], meta: { by?: string; commit?: string | null } = {}) {
+  const wanted = new Map<string, string>();
+  for (const f of files) {
+    const [kind, ...rest] = f.path.split("/");
+    if (!LIBRARY_KINDS.includes(kind as LibraryKind) || rest.length === 0) continue;
+    wanted.set(f.path, f.content);
+  }
+  const changes: { path: string; before: string | null; after: string | null }[] = [];
+  for (const kind of LIBRARY_KINDS) {
+    const dir = libraryDir(tenant, kind);
+    if (!fs.existsSync(dir)) continue;
+    for (const entry of fs.readdirSync(dir, { recursive: true })) {
+      const rel = `${kind}/${String(entry).split(path.sep).join("/")}`;
+      const full = path.join(dir, String(entry));
+      try {
+        if (!fs.statSync(full).isFile() || !TEXT_EXT.test(rel)) continue;
+      } catch {
+        continue;
+      }
+      if (!wanted.has(rel)) {
+        changes.push({ path: rel, before: fs.readFileSync(full, "utf8"), after: null });
+        fs.rmSync(full, { force: true });
+      }
+    }
+  }
+  for (const [rel, content] of wanted) {
+    const [kind, ...rest] = rel.split("/");
+    const full = path.join(libraryDir(tenant, kind as LibraryKind), assertLibraryPath(kind as LibraryKind, rest.join("/")));
+    const before = fs.existsSync(full) ? fs.readFileSync(full, "utf8") : null;
+    if (before === content) continue;
+    fs.mkdirSync(path.dirname(full), { recursive: true });
+    fs.writeFileSync(full, content);
+    if (kind === "scripts" || /scripts\//.test(rel) || (kind === "tools" && !rel.endsWith(".md"))) fs.chmodSync(full, 0o755);
+    changes.push({ path: rel, before, after: content });
+  }
+  recordRevision(tenant, "@library", changes, { by: meta.by ?? "deploy", message: meta.commit ? `deployed ${meta.commit.slice(0, 7)}` : "synced from push", commit: meta.commit ?? null });
+  return changes.length;
+}

package/src/linkable.ts

@@ -0,0 +1,123 @@
+// What [[ ]] can name, as one list.
+//
+// This existed twice and the two copies disagreed. The runner's resolver
+// indexed the file store under its real directory name (`storage/`), while
+// the editor offered the same files as `files/…` — a label left over from
+// before the rename. Accepting that suggestion produced a link that matched
+// nothing, so the model received two literal brackets where a path was meant.
+// The same rename had already caused one silent failure elsewhere; this is
+// the second, and the reason the list now has one definition.
+//
+// The rule this encodes: the editor may only offer what the runner can
+// resolve. tests/doclinks-consistency.test.ts asserts the round trip on a
+// real workspace, so a future rename fails a test instead of a run.
+
+import fs from "node:fs";
+import path from "node:path";
+import matter from "gray-matter";
+
+import { STORAGE_DIR } from "./store.ts";
+
+export interface LinkableDoc {
+  /** What a person types between the brackets. */
+  name: string;
+  /** Shown beside it in the list. */
+  hint: string;
+}
+
+/** The directories a bare [[name]] may point at, matching the resolver. */
+export const LINKABLE_DIRS = [STORAGE_DIR, "state", "knowledge", "memory", "skills", "outputs"];
+
+/**
+ * Everything [[ ]] resolves to in this workspace, in the order a person
+ * would want it: documents first, then the file store, then the folders.
+ *
+ * `workspaceRoot` is the workspace directory itself. `storageFiles` is the
+ * hosted store's listing when there is one; local installs pass nothing and
+ * the plain `storage/` directory on disk is walked instead — the same two
+ * sources, in the same order, that the resolver consults.
+ */
+export function linkableDocs(
+  workspaceRoot: string,
+  storageFiles: { path: string }[] = [],
+  limit = 300,
+): LinkableDoc[] {
+  const out: LinkableDoc[] = [];
+
+  for (const kind of ["knowledge", "memory"] as const) {
+    const dir = path.join(workspaceRoot, kind);
+    if (!fs.existsSync(dir)) continue;
+    for (const entry of fs.readdirSync(dir, { recursive: true }).map(String)) {
+      if (!entry.endsWith(".md")) continue;
+      // index.md and log.md are generated views of the bundle, not concepts
+      // to link at — offering them invites a link to a file that will be
+      // rewritten under it.
+      const base = path.basename(entry);
+      if (base === "index.md" || base === "log.md") continue;
+      let title = "";
+      try {
+        const data = matter(fs.readFileSync(path.join(dir, entry), "utf8")).data as Record<string, unknown>;
+        for (const key of ["title", "name"] as const) {
+          if (typeof data?.[key] === "string" && data[key]) {
+            title = data[key] as string;
+            break;
+          }
+        }
+      } catch {
+        // unparseable frontmatter still links by filename
+      }
+      out.push({
+        name: entry.split(path.sep).join("/").replace(/\.md$/, ""),
+        hint: `${kind}${title ? ` — ${title}` : ""}`,
+      });
+    }
+  }
+
+  // state/ — what a recurring flow reads from its own past runs. Offered by
+  // path, like the file store and unlike knowledge/, because these are data
+  // files rather than documents with a title.
+  const stateDir = path.join(workspaceRoot, "state");
+  if (fs.existsSync(stateDir)) {
+    for (const entry of fs.readdirSync(stateDir, { recursive: true }).map(String)) {
+      try {
+        if (!fs.statSync(path.join(stateDir, entry)).isFile()) continue;
+      } catch {
+        continue;
+      }
+      out.push({ name: `state/${entry.split(path.sep).join("/")}`, hint: "state" });
+    }
+  }
+
+  // The file store, under the directory the resolver actually indexes.
+  const seen = new Set<string>();
+  for (const f of storageFiles) {
+    if (seen.has(f.path)) continue;
+    seen.add(f.path);
+    out.push({ name: `${STORAGE_DIR}/${f.path}`, hint: "file" });
+  }
+  const filesDir = path.join(workspaceRoot, STORAGE_DIR);
+  if (fs.existsSync(filesDir)) {
+    for (const entry of fs.readdirSync(filesDir, { recursive: true }).map(String)) {
+      const fwd = entry.split(path.sep).join("/");
+      if (fwd.startsWith(".store/") || seen.has(fwd)) continue;
+      try {
+        if (!fs.statSync(path.join(filesDir, entry)).isFile()) continue;
+      } catch {
+        continue;
+      }
+      seen.add(fwd);
+      out.push({ name: `${STORAGE_DIR}/${fwd}`, hint: "file" });
+    }
+  }
+
+  // The folders themselves. The resolver has always accepted these — an
+  // instruction that says WHERE without naming a file is a real thing to
+  // write — and nothing offered them, so the capability was undiscoverable.
+  for (const dir of LINKABLE_DIRS) {
+    if (fs.existsSync(path.join(workspaceRoot, dir))) {
+      out.push({ name: dir, hint: "the whole folder" });
+    }
+  }
+
+  return out.slice(0, limit);
+}

package/src/model-probe.ts

@@ -0,0 +1,112 @@
+// "Can this model hold a tool loop?" — answered by running one, not by
+// reading a spec sheet.
+//
+// The catalogue's `tools` flag is the gateway's claim; this is the ground
+// truth. The probe hands the model exactly one tool, whose result is a nonce
+// invented per run, and asks it to call the tool and repeat the nonce back.
+// A model that can drive an agent loop does this in two turns. A model that
+// cannot — no tool support, tool calls narrated as prose, a gateway route
+// that strips tool blocks — has no other way to learn the nonce, so the
+// verdict cannot be faked by a model that merely talks about calling tools.
+// That distinction is the entire reason the probe exists: it is the same
+// failure the run-start gate guards against, demonstrated live through
+// whatever provider env the caller passes.
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { randomBytes } from "node:crypto";
+import { tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";
+import { z } from "zod";
+import { executeStep } from "./step-exec.ts";
+import type { Effort } from "./store.ts";
+
+export interface ProbeReport {
+  model: string;
+  /** The model made a real tool call — the handler ran. */
+  calledTool: boolean;
+  /** The nonce came back in the reply: the loop closed end to end. */
+  echoedNonce: boolean;
+  /** calledTool && echoedNonce — what "can drive an agent" actually means. */
+  ok: boolean;
+  status: "completed" | "failed";
+  costUsd: number | null;
+  durationMs: number;
+  /** The reply itself, for the human reading a failure. */
+  reply: string | null;
+}
+
+const PROBE_TIMEOUT_SEC = 120;
+
+/**
+ * Run the tool-loop probe against one model, through whatever endpoint the
+ * env points at — pass the same env a step would get (provider base URL,
+ * token, tier remaps) and the probe exercises the exact path a run takes.
+ */
+export async function probeModel(
+  model: string,
+  env: Record<string, string | undefined>,
+  effort: Effort | null = null,
+): Promise<ProbeReport> {
+  const nonce = `probe-${randomBytes(6).toString("hex")}`;
+  let calledTool = false;
+
+  const probeTool = tool(
+    "probe_fetch_token",
+    "Returns a secret token. Call it exactly once.",
+    {
+      // One required argument, because a loop that can't pass arguments
+      // can't run real tools either — echoing a fixed call is the easiest
+      // possible tool use, and we deliberately don't test the easiest.
+      purpose: z.string().describe("Why you are fetching the token, in a few words"),
+    },
+    async () => {
+      calledTool = true;
+      return { content: [{ type: "text" as const, text: nonce }] };
+    },
+  );
+
+  // Homeless on purpose, like a consult: the probe reads and writes nothing,
+  // and a throwaway cwd means even a confused model call has no tree to touch.
+  const scratch = fs.mkdtempSync(path.join(os.tmpdir(), "foldrun-probe-"));
+  const started = Date.now();
+  try {
+    const outcome = await executeStep({
+      agentDir: scratch,
+      workspaceRoot: scratch,
+      libraryRoot: scratch,
+      prompt:
+        "Call the probe_fetch_token tool once, then reply with exactly the token it " +
+        "returns and nothing else. If you cannot call tools, reply CANNOT.",
+      model,
+      effort,
+      systemPrompt:
+        "You are a connectivity probe. Follow the instruction literally. Do not explain.",
+      allowed: [],
+      mcpNames: ["foldrun_probe"],
+      mcpServers: {
+        foldrun_probe: createSdkMcpServer({
+          name: "foldrun_probe",
+          version: "1.0.0",
+          tools: [probeTool],
+        }),
+      },
+      env,
+      timeoutSec: PROBE_TIMEOUT_SEC,
+      emit: () => {}, // the probe's transcript is the report, not a run log
+    });
+    const echoedNonce = (outcome.result ?? "").includes(nonce);
+    return {
+      model,
+      calledTool,
+      echoedNonce,
+      ok: calledTool && echoedNonce,
+      status: outcome.status,
+      costUsd: outcome.costUsd,
+      durationMs: Date.now() - started,
+      reply: outcome.result,
+    };
+  } finally {
+    fs.rmSync(scratch, { recursive: true, force: true });
+  }
+}