@foldrun/core 0.3.0 → 0.5.0

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,12 +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;
@@ -46,24 +49,11 @@ const TIMEOUT_MS = 15_000;
 // process.env. That env holds FOLDRUN_SECRET_KEY (the global install key that
 // signs every tenant's webhook tokens and git-push secrets), plus the S3/DB/
 // Stripe/GitHub credentials: handing them to a `console.log(process.env)`
-// script tool is cross-tenant compromise. The child instead starts from a
-// minimal host base — only enough for an interpreter to be found and run —
-// and gets the tool's own declared secrets layered on top by the callers.
-const HOST_BASE_ENV_KEYS = [
-  "PATH", "HOME", "TMPDIR", "TMP", "TEMP", "LANG", "LANGUAGE",
-  "LC_ALL", "LC_CTYPE", "TZ", "TERM", "SHELL", "USER", "LOGNAME",
-  "NODE_ENV", // not a secret; some interpreters/tools read it.
-  // Windows equivalents, harmless elsewhere.
-  "SYSTEMROOT", "COMSPEC", "PATHEXT", "WINDIR",
-];
-function hostSafeBaseEnv(): NodeJS.ProcessEnv {
-  const base: Record<string, string> = {};
-  for (const k of HOST_BASE_ENV_KEYS) {
-    const v = process.env[k];
-    if (v !== undefined) base[k] = v;
-  }
-  return base as NodeJS.ProcessEnv;
-}
+// script tool is cross-tenant compromise. The child instead starts from the
+// allowlisted host base (host-env.ts — the same one every in-process script,
+// verify shell and SDK Bash tool starts from) and gets the tool's own
+// declared secrets layered on top by the callers.
+const hostSafeBaseEnv = (): NodeJS.ProcessEnv => hostSafeEnv();
 
 const clip = (s: string) =>
   s.length > MAX_DETAIL ? `${s.slice(0, MAX_DETAIL)}\n… truncated` : s;
@@ -72,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;
@@ -92,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)) {
@@ -110,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,
@@ -144,7 +207,7 @@ export async function testTool(
   }
 
   if (def.kind === "script") {
-    const run = String(def.spec.run ?? "");
+    let run = String(def.spec.run ?? "");
     // A run's working directory is the calling AGENT's folder, not the
     // workspace root — and scripts rely on that. `path.resolve(cwd, "..",
     // "..", "state", f)` is the ordinary way to reach workspace state, and
@@ -163,7 +226,48 @@ export async function testTool(
     // workspace root is wrong but it exists, and the note says so rather
     // than failing a test over a workspace that cannot run anything yet.
     const cwd = caller ? path.join(dir, "agents", caller.name) : dir;
-    const file = resolveRunPath(path.join(dir, "agents", "_probe"), run, libraryDir(tenant, "scripts"));
+
+    // A single-file tool carries its program in a fenced block rather than
+    // in a file: `run:` is empty and `code:` holds it. The RUNTIME writes it
+    // out at call time (script-tools.ts) and has always worked; the tester
+    // only ever looked for a file, so the Test button failed for every one
+    // of them while the same tool ran fine in a flow — which is the worst
+    // possible way round, since that button is where a developer goes to
+    // find out whether their work is broken.
+    //
+    // Materialised the same way and in the same place a call would, so the
+    // test runs the identical program from the identical directory.
+    const inlineCode = typeof def.spec.code === "string" ? def.spec.code : "";
+    const inline = !run && !!inlineCode;
+    if (inline && !caller) {
+      // Nowhere to stand: the file would land at the workspace root, which
+      // is not where a run puts it and not somewhere a deploy diff should
+      // find it. Say what is missing instead.
+      return done({
+        ok: false, transport: "script", missingSecrets: [],
+        summary: "no agent to test it from",
+        detail: "This tool carries its code inline and is materialised inside the calling agent's folder. Grant it to an agent (tools:) and test again.",
+      });
+    }
+    if (inline) {
+      const ext = typeof def.spec.codeExt === "string" ? def.spec.codeExt : ".mjs";
+      const codeDir = path.join(cwd, ".tool-code");
+      try {
+        fs.mkdirSync(codeDir, { recursive: true });
+        fs.writeFileSync(path.join(codeDir, `${def.name}${ext}`), inlineCode, { mode: 0o755 });
+        run = `.tool-code/${def.name}${ext}`;
+      } catch (err) {
+        return done({
+          ok: false, transport: "script", missingSecrets: [],
+          summary: "its inline code could not be written",
+          detail: err instanceof Error ? err.message : String(err),
+        });
+      }
+    }
+
+    // A materialised file was just written into cwd, so it resolves from
+    // there. A declared `run:` keeps resolving exactly as it always has.
+    const file = resolveRunPath(inline ? cwd : path.join(dir, "agents", "_probe"), run, libraryDir(tenant, "scripts"));
 
     if (!fs.existsSync(file)) {
       return done({
@@ -174,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;
@@ -205,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.
@@ -225,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)"),
       ),
     });
@@ -265,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);