@foldrun/core 0.4.0 → 0.5.0

package/src/subagents.ts

@@ -0,0 +1,189 @@
+// Sub-agents: delegate a job to a colleague with its OWN context and its own
+// tools, inside the step that asked.
+//
+//   agents: [editor]          # consult: a quick opinion, no tools (agent-tools.ts)
+//   subagents: [researcher]   # delegate: own context, own tools
+//
+// Built on the Agent SDK's native sub-agents (query()'s `agents` option and
+// its Agent tool), so a delegation behaves as it does in Claude Code: a fresh
+// context does the work — reads forty pages, runs the checks — and hands back
+// a summary, keeping the parent's context on its own job.
+//
+// What keeps it the platform's and not a second, wider agent:
+//   - never wider than the parent: a sub-agent's tools are its own `tools:`
+//     resolved exactly as a step's, INTERSECTED with what the parent step
+//     holds — and always an explicit list: the SDK gives a definition with
+//     no `tools` every tool the parent has
+//   - depth one: the Agent/Task tool is never in a sub-agent's list, so it
+//     cannot delegate again
+//   - the same step: same sandbox, files, secrets, egress lease, and the
+//     parent's hooks — the SDK runs a sub-agent's tool calls through the
+//     session's PreToolUse and canUseTool (tagged agent_id/agent_type), so
+//     confinement applies unchanged; subagentGuard() below refuses anything
+//     outside the sub-agent's own list there too, belt and braces
+//   - cost and trace land on the parent step; flows still decide what runs
+//     next — a sub-agent is a helper inside one step, never a step.
+
+import fs from "node:fs";
+import path from "node:path";
+import { refNames } from "./refs.ts";
+import { TOOL_MAP } from "./tool-names.ts";
+
+/** Plain JSON: this crosses into the run container. */
+export interface SubagentSpec {
+  name: string;
+  description: string;
+  prompt: string;
+  /** Always explicit — never absent, never inherited. */
+  tools: string[];
+  disallowedTools: string[];
+  /** A model alias (haiku/sonnet/opus, remapped by the step's provider like
+   *  the step's own) or "inherit". */
+  model: string;
+}
+
+/** The SDK's delegation tool, under both names it has had. Never granted to a
+ *  sub-agent: that is what makes the depth one. */
+export const DELEGATE_TOOLS = ["Agent", "Task"] as const;
+export const DELEGATE_TOOL = "Agent";
+
+const NAME = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+
+/** The named sub-agents' folders, host-side. Unknown names are reported. */
+export function gatherSubagents(
+  workspaceRoot: string,
+  names: unknown,
+): { found: { name: string; dir: string }[]; missing: string[] } {
+  const found: { name: string; dir: string }[] = [];
+  const missing: string[] = [];
+  for (const name of refNames(names)) {
+    const dir = path.join(workspaceRoot, "agents", name);
+    if (!NAME.test(name) || !fs.existsSync(path.join(dir, "agent.md"))) missing.push(name);
+    else if (!found.some((f) => f.name === name)) found.push({ name, dir });
+  }
+  return { found, missing };
+}
+
+/**
+ * A sub-agent's tools: its own, only where the parent holds them too. An MCP
+ * tool is held when the parent holds that exact name or its whole server
+ * (`mcp__<server>` / `mcp__<server>__*`). The delegate tool never passes.
+ */
+export function subagentTools(own: string[], parent: string[]): string[] {
+  const held = new Set(parent);
+  const servers = new Set(
+    parent.filter((t) => /^mcp__[^_]/.test(t)).map((t) => t.replace(/__\*$/, "")).filter((t) => !t.slice(5).includes("__")),
+  );
+  const out: string[] = [];
+  for (const t of own) {
+    if ((DELEGATE_TOOLS as readonly string[]).includes(t) || out.includes(t)) continue;
+    const server = /^mcp__([^_].*?)__/.exec(t)?.[1];
+    if (held.has(t) || (server && servers.has(`mcp__${server}`))) out.push(t);
+  }
+  return out;
+}
+
+/** The sub-agent's system prompt: its own prose, told where it stands. It
+ *  works in the PARENT's directory — the SDK shares the session's cwd. */
+export function subagentPrompt(o: {
+  body: string;
+  name: string;
+  parent: string;
+  workspace: string;
+  shared?: string | null;
+}): string {
+  return [
+    o.body.trim(),
+    `# Where you are\n\n` +
+      `You are ${o.name}, a sub-agent started by ${o.parent} to do one job and report back. ` +
+      `You work in ${o.parent}'s directory, \`agents/${o.parent}/\` in the \`${o.workspace}\` workspace: ` +
+      `\`../../\` is the workspace root, its knowledge is at \`../../knowledge/\`, and absolute paths are refused. ` +
+      `You have only the tools listed for you. When the job is done, reply with what you found or made — ` +
+      `your reply is all ${o.parent} sees of your work, so put the facts and file paths in it.`,
+    ...(o.shared?.trim() ? [o.shared.trim()] : []),
+  ].join("\n\n");
+}
+
+/** SDK definitions. `tools` is always set — an absent list inherits every
+ *  tool the parent has, which is the one thing this module exists to stop. */
+export function toAgentDefinitions(specs: SubagentSpec[]): Record<string, {
+  description: string;
+  prompt: string;
+  tools: string[];
+  disallowedTools: string[];
+  model: string;
+}> {
+  const out: Record<string, { description: string; prompt: string; tools: string[]; disallowedTools: string[]; model: string }> = {};
+  for (const s of specs) {
+    out[s.name] = {
+      description: s.description,
+      prompt: s.prompt,
+      tools: [...s.tools],
+      disallowedTools: [...new Set([...s.disallowedTools, ...DELEGATE_TOOLS])],
+      model: s.model || "inherit",
+    };
+  }
+  return out;
+}
+
+/** One tool call as the parent's PreToolUse hook sees it. */
+export interface GuardedCall {
+  /** The SDK's agent_id: set when the call comes from inside a sub-agent. */
+  agentId?: string;
+  /** The SDK's agent_type: which sub-agent. */
+  agentType?: string;
+  tool: string;
+  input: Record<string, unknown>;
+}
+
+/**
+ * For the parent's PreToolUse hook, on a step that has sub-agents: a reason
+ * to refuse the call — or null.
+ *
+ * Only DECLARED sub-agents may run. The SDK also offers its built-ins
+ * (general-purpose and the rest, with every tool the session has); they are
+ * switched off in executeStep, and refused here too. A call from inside a
+ * sub-agent whose type is missing or not declared used to pass unjudged —
+ * `general-purpose` was a way round every sub-agent's own list.
+ */
+export function subagentGuard(specs: SubagentSpec[]): (call: GuardedCall) => string | null {
+  const by = new Map(specs.map((s) => [s.name, s]));
+  const declared = specs.map((s) => s.name).join(", ");
+  const isDelegate = (tool: string) => (DELEGATE_TOOLS as readonly string[]).includes(tool);
+  return ({ agentId, agentType, tool, input }) => {
+    if (!agentId) {
+      // The main thread: its tools are canUseTool's business — except the
+      // delegation itself, which may name only a declared sub-agent.
+      if (!isDelegate(tool)) return null;
+      const to = typeof input.subagent_type === "string" ? input.subagent_type : "";
+      if (by.has(to)) return null;
+      return `${to ? `"${to}" is not a sub-agent this step declared` : "name the sub-agent to delegate to"} — subagent_type must be one of: ${declared}`;
+    }
+    const s = agentType ? by.get(agentType) : undefined;
+    if (!s) return `${agentType ? `"${agentType}"` : "an unnamed sub-agent"} is not declared in subagents: for this step (only ${declared}) — its calls are refused`;
+    if (isDelegate(tool)) {
+      return `${s.name} is a sub-agent and cannot start another — do the work with your own tools`;
+    }
+    if (s.disallowedTools.includes(tool)) return `${tool} is disallowed for ${s.name}`;
+    if (subagentTools([tool], s.tools).length === 0) return `${tool} is not one of ${s.name}'s tools`;
+    return null;
+  };
+}
+
+/**
+ * What `foldrun check` can say without running anything: the SDK and built-in
+ * tool names two `tools:` lists grant, and their overlap. Own tools compare by
+ * name. Used to warn when a sub-agent would be left with nothing.
+ */
+export function grantedNames(tools: string[]): Set<string> {
+  const out = new Set<string>();
+  for (const t of tools) {
+    for (const n of TOOL_MAP[t] ?? [t]) out.add(n);
+  }
+  return out;
+}
+
+export function checkOverlap(parentTools: string[], subTools: string[]): string[] {
+  const parent = grantedNames(parentTools);
+  return [...grantedNames(subTools)].filter((t) => parent.has(t) && !(DELEGATE_TOOLS as readonly string[]).includes(t));
+}

package/src/tool-names.ts

@@ -14,29 +14,43 @@ import { refList, refNames, type Ref } from "./refs.ts";
 
 /** Groups: one word an author can hold in their head, expanded to SDK names. */
 export const TOOL_MAP: Record<string, string[]> = {
-  // `web` includes Anthropic's server-side WebSearch, the one built-in tool
-  // that runs off the box and bills per call. `fetch` is the local half only:
-  // an agent that searches through the account's own `websearch` tool and
-  // reads pages with WebFetch never leaves the box for anything but tokens.
-  web: ["WebSearch", "WebFetch"],
-  fetch: ["WebFetch"],
-  // `read` is deliberately separate from `files`: an agent that may inspect a
-  // repository but must never modify it is a real and common design.
+  // The web is one tool of ours, `web` — search, fetch, browse, crawl, map,
+  // extract, answer, monitor, served from the gallery and on the run record
+  // whichever model is driving. So `web` is deliberately NOT here: a name in
+  // TOOL_MAP shadows a real tool of the same name (see runner.ts).
+  // `read` is deliberately separate from `write`: an agent that may inspect a
+  // repository but must never modify it is a real and common design. The pair
+  // says what it grants. `files` and `bash` were the old names for `write`
+  // and `code` (`code`, because it is not only shell — anything in the
+  // sandbox runs through it); both are retired, below.
   read: ["Read", "Glob", "Grep"],
+  write: ["Read", "Write", "Edit", "Glob", "Grep"],
   files: ["Read", "Write", "Edit", "Glob", "Grep"],
+  code: ["Bash"],
   bash: ["Bash"],
 };
 
+/** Names an author may no longer write, and what to write instead. They are
+ *  still granted, so nothing deployed breaks; `check` and the run log say the
+ *  rewrite. */
+export const RETIRED_TOOLS: Record<string, string> = {
+  files: "write",
+  bash: "code",
+};
+
 /** Exact SDK tool names, accepted alongside the group aliases so a Claude Code
  *  subagent's `tools: Read, Grep` works unchanged. The aliases exist because
- *  vendors rename tools; `web` survives a rename that `WebSearch` would not. */
+ *  vendors rename tools; `write` survives a rename that `Write` would not.
+ *  The SDK's WebSearch and WebFetch are not here: the web is our `web` tool,
+ *  and a model provider's own search (`web: {search: zai}`) is the runtime's
+ *  to swap in, not the author's to name. */
 export const BUILTIN_TOOLS = new Set([
   "Read", "Write", "Edit", "MultiEdit", "Glob", "Grep", "Bash",
-  "WebSearch", "WebFetch", "NotebookEdit", "TodoWrite",
+  "NotebookEdit", "TodoWrite",
 ]);
 
 /** The platform's own groups, served in-process rather than by the SDK. */
-export const PLATFORM_GROUPS = new Set(["search", "history", "desks"]);
+export const PLATFORM_GROUPS = new Set(["search", "history", "desks", "ask"]);
 
 /** Would this name resolve to something the runtime provides? Built-ins win a
  *  clash, so a tool file of the same name is shadowed rather than granted. */
@@ -85,6 +99,21 @@ export function legacyUseNames(front: ToolFrontmatter): string[] {
   return refNames(front.use);
 }
 
+/** Retired names written bare in `tools:`, deduped. A `[[link]]` is the
+ *  author's own file, so it is never one of these. */
+export function retiredToolNames(front: ToolFrontmatter): string[] {
+  const out: string[] = [];
+  for (const ref of toolRefs(front)) {
+    if (!ref.linked && RETIRED_TOOLS[ref.name] && !out.includes(ref.name)) out.push(ref.name);
+  }
+  return out;
+}
+
+/** The one sentence every reader of a retired name says. */
+export function retiredToolError(name: string): string {
+  return `tools: "${name}" is retired — use ${RETIRED_TOOLS[name]} instead: the same grant, under the name that says what it does. It is still granted for now.`;
+}
+
 /** The one sentence every reader of a `use:` key says. */
 export function legacyUseError(names: string[]): string {
   return `\`use:\` is no longer read — write \`tools: [${names.join(", ")}]\` instead (scripts/migrate-use-to-tools.mjs rewrites every agent). Nothing was granted for it.`;

package/src/tool-programs.ts

@@ -15,6 +15,9 @@
 
 import fs from "node:fs";
 import path from "node:path";
+import { builtinModules } from "node:module";
+import matter from "gray-matter";
+import { parseRuntime } from "./runtime.ts";
 
 import { workspaceDir, workspaceTools, type ToolDef } from "./store.ts";
 import { libraryDir, libraryTools } from "./library.ts";
@@ -63,3 +66,179 @@ export function missingToolPrograms(tenant: string, workspace: string): MissingP
   scan(workspaceTools(tenant, workspace), "workspace");
   return out;
 }
+
+// ---------------------------------------------------------------- imports
+
+/**
+ * The Python standard library, top-level names: CPython's
+ * sys.stdlib_module_names, plus what 3.13 removed (the image's python is
+ * older than the list's). Never a declaration's business.
+ */
+const PY_STDLIB = new Set(
+  `
+  abc aifc annotationlib antigravity argparse array ast asynchat asyncio
+  asyncore atexit audioop base64 bdb binascii bisect builtins bz2 cProfile
+  calendar cgi cgitb chunk cmath cmd code codecs codeop collections colorsys
+  compileall compression concurrent configparser contextlib contextvars copy
+  copyreg crypt csv ctypes curses dataclasses datetime dbm decimal difflib
+  dis distutils doctest email encodings ensurepip enum errno faulthandler
+  fcntl filecmp fileinput fnmatch fractions ftplib functools gc genericpath
+  getopt getpass gettext glob graphlib grp gzip hashlib heapq hmac html http
+  idlelib imaplib imghdr imp importlib inspect io ipaddress itertools json
+  keyword lib2to3 linecache locale logging lzma mailbox mailcap marshal math
+  mimetypes mmap modulefinder msilib msvcrt multiprocessing netrc nis nntplib
+  nt ntpath nturl2path numbers opcode operator optparse os ossaudiodev
+  pathlib pdb pickle pickletools pipes pkgutil platform plistlib poplib posix
+  posixpath pprint profile pstats pty pwd py_compile pyclbr pydoc pydoc_data
+  pyexpat queue quopri random re readline reprlib resource rlcompleter runpy
+  sched secrets select selectors shelve shlex shutil signal site smtpd
+  smtplib sndhdr socket socketserver spwd sqlite3 sre_compile sre_constants
+  sre_parse ssl stat statistics string stringprep struct subprocess sunau
+  symtable sys sysconfig syslog tabnanny tarfile telnetlib tempfile termios
+  textwrap this threading time timeit tkinter token tokenize tomllib trace
+  traceback tracemalloc tty turtle turtledemo types typing unicodedata
+  unittest urllib uu uuid venv warnings wave weakref webbrowser winreg
+  winsound wsgiref xdrlib xml xmlrpc zipapp zipfile zipimport zlib zoneinfo
+`
+    .trim()
+    .split(/\s+/),
+);
+
+/** Distributions whose import name is not their own name, lower-cased. */
+const PY_IMPORT_ALIASES: Record<string, string[]> = {
+  beautifulsoup4: ["bs4"],
+  pillow: ["PIL"],
+  pyyaml: ["yaml"],
+  "python-dateutil": ["dateutil"],
+  "scikit-learn": ["sklearn"],
+  "opencv-python": ["cv2"],
+  "opencv-python-headless": ["cv2"],
+  "python-docx": ["docx"],
+  "python-pptx": ["pptx"],
+  pymupdf: ["fitz", "pymupdf"],
+  "google-api-python-client": ["googleapiclient"],
+  "google-auth": ["google"],
+  protobuf: ["google"],
+  "psycopg2-binary": ["psycopg2"],
+  "psycopg-binary": ["psycopg"],
+  attrs: ["attr", "attrs"],
+  "python-dotenv": ["dotenv"],
+  pyjwt: ["jwt"],
+  "typing-extensions": ["typing_extensions"],
+};
+
+/** The names `import` would use for a declared distribution. */
+export function importNamesOf(requirement: string): string[] {
+  const dist = requirement.split(/[[<>=!~@ ;]/)[0].trim().toLowerCase();
+  return PY_IMPORT_ALIASES[dist] ?? [dist.replace(/[-.]/g, "_")];
+}
+
+/** Top-level modules a Python file imports; relative imports excluded. */
+export function pythonImports(source: string): string[] {
+  const out = new Set<string>();
+  for (const line of source.split("\n")) {
+    const from = /^\s*from\s+([A-Za-z_][\w.]*)\s+import\b/.exec(line);
+    if (from) out.add(from[1].split(".")[0]);
+    const imp = /^\s*import\s+([A-Za-z_][\w.]*(?:\s+as\s+\w+)?(?:\s*,\s*[A-Za-z_][\w.]*(?:\s+as\s+\w+)?)*)/.exec(line);
+    if (imp) for (const part of imp[1].split(",")) out.add(part.trim().split(/\s+/)[0].split(".")[0]);
+  }
+  return [...out];
+}
+
+/** Packages a JavaScript file imports or requires; relative and node: excluded. */
+export function nodeImports(source: string): string[] {
+  const out = new Set<string>();
+  const re = /(?:\bfrom\s*|\bimport\s*\(\s*|\brequire\s*\(\s*|^\s*import\s+)["']([^"'./][^"']*)["']/gm;
+  for (const m of source.matchAll(re)) {
+    const spec = m[1];
+    if (spec.startsWith("node:")) continue;
+    out.add(spec.startsWith("@") ? spec.split("/").slice(0, 2).join("/") : spec.split("/")[0]);
+  }
+  return [...out];
+}
+
+/** What the runner image provides without a declaration (run-container.ts). */
+const IMAGE_NODE_MODULES = new Set(["playwright", "playwright-core", "axe-core", "@foldrun/core"]);
+
+export interface UndeclaredImport {
+  name: string;
+  scope: "workspace" | "account";
+  file: string;
+  modules: string[];
+  language: "python" | "node";
+}
+
+/**
+ * Script tools whose program imports a package nothing declares. Advisory: a
+ * warning, because the import may be satisfied some way this cannot see (a
+ * vendored module in a subfolder, a package the agent's own `runtime:`
+ * brings). What it catches is the common case — a tool that `import openpyxl`
+ * with no `runtime:` anywhere, which runs fine on the laptop that has it and
+ * fails on the platform on its first call.
+ *
+ * Declared means: the tool's own runtime (tool.md, requirements.txt,
+ * package.json), the workspace's AGENTS.md runtime, or any agent's runtime
+ * in the workspace — the union, so an agent-level declaration is trusted.
+ */
+export function undeclaredImports(tenant: string, workspace: string): UndeclaredImport[] {
+  const dir = workspaceDir(tenant, workspace);
+  const from = path.join(dir, "agents", "_probe");
+  const libScripts = libraryDir(tenant, "scripts");
+  const sharedPy = new Set<string>();
+  const sharedNpm = new Set<string>();
+  const addRuntime = (raw: unknown) => {
+    const rt = parseRuntime(raw);
+    if (!rt) return;
+    for (const p of rt.packages) for (const n of importNamesOf(p)) sharedPy.add(n.toLowerCase());
+    for (const n of rt.npm) sharedNpm.add(n.replace(/^(@[^/]+\/[^@]+|[^@]+).*$/, "$1"));
+  };
+  const readFront = (file: string) => {
+    try {
+      return matter(fs.readFileSync(file, "utf8")).data as Record<string, unknown>;
+    } catch {
+      return {};
+    }
+  };
+  addRuntime(readFront(path.join(dir, "AGENTS.md")).runtime);
+  addRuntime(readFront(path.join(dir, "project.md")).runtime);
+  const agentsRoot = path.join(dir, "agents");
+  if (fs.existsSync(agentsRoot)) {
+    for (const a of fs.readdirSync(agentsRoot)) addRuntime(readFront(path.join(agentsRoot, a, "agent.md")).runtime);
+  }
+
+  const out: UndeclaredImport[] = [];
+  const scan = (defs: Record<string, ToolDef>, scope: "workspace" | "account") => {
+    for (const [name, def] of Object.entries(defs)) {
+      if (def.kind !== "script") continue;
+      const run = String((def.spec as { run?: unknown }).run ?? "");
+      if (!run) continue;
+      const file = resolveRunPath(from, run, libScripts);
+      if (!fs.existsSync(file)) continue;
+      const own = parseRuntime((def.spec as { runtime?: unknown }).runtime);
+      const ext = path.extname(file).toLowerCase();
+      const source = fs.readFileSync(file, "utf8");
+      const siblings = new Set(
+        fs.readdirSync(path.dirname(file)).map((f) => f.replace(/\.(py|mjs|cjs|js|ts)$/, "").toLowerCase()),
+      );
+      if (ext === ".py" || (!ext && /^#!.*python/.test(source))) {
+        const declared = new Set(sharedPy);
+        for (const p of own?.packages ?? []) for (const n of importNamesOf(p)) declared.add(n.toLowerCase());
+        const missing = pythonImports(source).filter(
+          (m) => !PY_STDLIB.has(m) && !declared.has(m.toLowerCase()) && !siblings.has(m.toLowerCase()),
+        );
+        if (missing.length) out.push({ name, scope, file: run, modules: missing, language: "python" });
+      } else if ([".js", ".mjs", ".cjs", ".ts"].includes(ext)) {
+        const declared = new Set(sharedNpm);
+        for (const n of own?.npm ?? []) declared.add(n.replace(/^(@[^/]+\/[^@]+|[^@]+).*$/, "$1"));
+        const missing = nodeImports(source).filter(
+          (m) => !builtinModules.includes(m) && !declared.has(m) && !IMAGE_NODE_MODULES.has(m),
+        );
+        if (missing.length) out.push({ name, scope, file: run, modules: missing, language: "node" });
+      }
+    }
+  };
+  scan(libraryTools(tenant), "account");
+  scan(workspaceTools(tenant, workspace), "workspace");
+  return out;
+}
+

package/src/tool-test.ts

@@ -19,13 +19,15 @@ import { spawn } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
 
-import { resolveSecrets } from "./secrets.ts";
+import { resolveSecrets, materializeSecrets } from "./secrets.ts";
 import { listAgents, workspaceDir, type ToolDef } from "./store.ts";
 import { libraryDir } from "./library.ts";
 import { secretsUsedByApi } from "./api-tools.ts";
+import { attachOperations, prefetchOpenApi, type OperationSpec } from "./openapi.ts";
 import { commandFor, resolveRunPath } from "./script-tools.ts";
 import { parseRuntime, prepareRuntime } from "./runtime.ts";
 import { hostSafeEnv } from "./host-env.ts";
+import { linkWorkspace, workspaceLinkEnv } from "./confine.ts";
 
 export interface ToolTestResult {
   ok: boolean;
@@ -60,6 +62,32 @@ const clip = (s: string) =>
 const substitute = (v: string, env: Record<string, string>) =>
   v.replace(/\$\{([A-Z0-9_]+)\}/g, (_, k) => env[k] ?? "");
 
+/**
+ * The secrets as a run would hand them over: an oauth2 or service-account
+ * secret swapped for a live access token. Without this the tester passed the
+ * stored `@oauth2 {…}` recipe itself, so every tool behind Google OAuth failed
+ * its Test button while working in every run (gbp-desk review_candidates,
+ * 2026-09-28). A refresh that fails is the tester's answer, not a throw.
+ */
+async function liveSecrets(
+  env: Record<string, string>,
+  ctx: { tenant: string; workspace?: string },
+): Promise<{ env: Record<string, string> } | { error: string }> {
+  try {
+    return { env: await materializeSecrets(env, ctx) };
+  } catch (err) {
+    return { error: err instanceof Error ? err.message : String(err) };
+  }
+}
+
+/** Does a concrete path fit an operation's template (`/contacts/{id}`)? */
+function matchesTemplate(op: OperationSpec, concrete: string): boolean {
+  const re = new RegExp(
+    "^" + op.path.split(/\{[^/}]+\}/).map((part) => part.replace(/[.*+?^$()|[\]\\]/g, "\\$&")).join("[^/]+") + "$",
+  );
+  return re.test(concrete);
+}
+
 export interface ToolTestInput {
   /** http: the path to try, appended to `base:`. */
   path?: string;
@@ -80,10 +108,58 @@ export async function testTool(
   if (def.kind === "http") {
     const api = def.spec;
     const needed = secretsUsedByApi(api);
-    const { env, missing } = resolveSecrets(tenant, needed, workspace);
+    const { env: stored, missing } = resolveSecrets(tenant, needed, workspace);
+    const live = await liveSecrets(stored, { tenant, workspace });
+    if ("error" in live) {
+      return done({ ok: false, transport: "http", missingSecrets: missing, summary: "a secret could not be refreshed", detail: live.error });
+    }
+    const env = live.env;
 
     try {
-      const rel = probePath.startsWith("/") || probePath === "" ? probePath : `/${probePath}`;
+      let rel = probePath.startsWith("/") || probePath === "" ? probePath : `/${probePath}`;
+      let method = api.methods.includes("GET") ? "GET" : api.methods[0];
+
+      // An `operations:` allowlist binds the tester exactly as it binds a run:
+      // the probe may only be a GET to one of the listed operations, and an
+      // allowlist that resolves nothing is a failure, as it is in a run. A
+      // tester that reached the whole API would be the one door the allowlist
+      // left open, and would report "working" for a tool a run cannot use.
+      if (api.operations?.length) {
+        const fetched = await prefetchOpenApi(tenant, api.openapi ? [api.openapi] : []);
+        const { specs, warnings } = attachOperations([api], tenant, workspaceDir(tenant, workspace));
+        const ops = specs[0].resolvedOperations ?? [];
+        if (!ops.length) {
+          return done({
+            ok: false, transport: "http", missingSecrets: missing,
+            summary: "its operations: allowlist resolved no operations, so a run gets no tools from it",
+            detail: [...fetched, ...warnings].join("\n"),
+          });
+        }
+        const listed = ops.map((o) => `${o.method} ${o.path}`).join("\n");
+        const gets = ops.filter((o) => o.method === "GET");
+        const pathOnly = rel.split("?")[0];
+        if (pathOnly === "") {
+          const plain = gets.find((o) => !o.path.includes("{"));
+          if (!plain) {
+            return done({
+              ok: false, transport: "http", missingSecrets: missing,
+              summary: gets.length
+                ? "every GET operation takes a parameter; give a path, like " + gets[0].path
+                : "the allowlist has no GET operation, and the tester only sends GET: it will not probe a write",
+              detail: `operations:\n${listed}`,
+            });
+          }
+          rel = plain.path;
+        } else if (!gets.some((o) => matchesTemplate(o, pathOnly))) {
+          return done({
+            ok: false, transport: "http", missingSecrets: missing,
+            summary: "that path is not one of the tool's GET operations",
+            detail: `path: ${pathOnly}\noperations:\n${listed}`,
+          });
+        }
+        method = "GET";
+      }
+
       const url = new URL(api.base + rel);
       // Same confinement the agent gets: a probe can't reach another host.
       if (!url.href.startsWith(api.base)) {
@@ -98,7 +174,6 @@ export async function testTool(
       const headers: Record<string, string> = {};
       for (const [k, v] of Object.entries(api.headers)) headers[k] = substitute(v, env);
 
-      const method = api.methods.includes("GET") ? "GET" : api.methods[0];
       const res = await fetch(url, {
         method,
         headers,
@@ -203,7 +278,12 @@ export async function testTool(
     }
 
     const names = Array.isArray(def.spec.secrets) ? def.spec.secrets.map(String) : [];
-    const { env, missing } = resolveSecrets(tenant, names, workspace);
+    const { env: stored, missing } = resolveSecrets(tenant, names, workspace);
+    const live = await liveSecrets(stored, { tenant, workspace });
+    if ("error" in live) {
+      return done({ ok: false, transport: "script", missingSecrets: missing, summary: "a secret could not be refreshed", detail: live.error });
+    }
+    const env = live.env;
     // The runtime's own choice of interpreter, not a second table beside it.
     const interpreter =
       typeof def.spec.interpreter === "string" ? def.spec.interpreter : undefined;
@@ -234,11 +314,24 @@ export async function testTool(
       file,
       toolRuntime.interpreters,
     );
-    const { code, out } = await runOnce(cmd, [...args, ...flags], cwd, {
-      ...hostSafeBaseEnv(),
-      ...toolRuntime.env,
-      ...env,
-    });
+    // The `workspace` link a step holds, held for the test too — a tool
+    // whose code says `workspace/state/x` found nothing here while the same
+    // call worked in a flow. Only from an agent's folder: at the workspace
+    // root there is no depth for it to stand at (the note below says so).
+    const link = caller ? linkWorkspace(cwd, dir) : null;
+    let ran: Awaited<ReturnType<typeof runOnce>>;
+    try {
+      ran = await runOnce(cmd, [...args, ...flags], cwd, workspaceLinkEnv({
+        ...hostSafeBaseEnv(),
+        ...toolRuntime.env,
+        ...env,
+      }, cwd));
+    } finally {
+      link?.release();
+      // A private build (a concurrent one was wedged) is this test's alone.
+      toolRuntime.dispose?.();
+    }
+    const { code, out } = ran;
 
     // A script that needs arguments and got none has not failed — it has not
     // been tested. Saying "exited 2" would send someone looking for a bug.
@@ -254,7 +347,7 @@ export async function testTool(
       detail: clip(
         (caller
           ? `ran from agents/${caller.name}/, where a run runs\n\n`
-          : `ran from the workspace root — there is no agent to stand in for, so a script that reaches ../../ will look one level too high\n\n`) +
+          : `ran from the workspace root — there is no agent to stand in for, so a script that reaches workspace/ or ../../ will not find the workspace there\n\n`) +
           (out || "(no output)"),
       ),
     });
@@ -294,7 +387,12 @@ export async function testTool(
   const named = Object.entries(spec.env ?? {})
     .map(([, v]) => String(v).match(/^\$\{([A-Z0-9_]+)\}$/)?.[1])
     .filter((n): n is string => Boolean(n));
-  const { env, missing } = resolveSecrets(tenant, named, workspace);
+  const { env: stored, missing } = resolveSecrets(tenant, named, workspace);
+  const live = await liveSecrets(stored, { tenant, workspace });
+  if ("error" in live) {
+    return done({ ok: false, transport: "mcp", missingSecrets: missing, summary: "a secret could not be refreshed", detail: live.error });
+  }
+  const env = live.env;
   const childEnv: NodeJS.ProcessEnv = { ...hostSafeBaseEnv() };
   for (const [k, v] of Object.entries(spec.env ?? {})) childEnv[k] = substitute(String(v), env);