@foldrun/core 0.4.0 → 0.6.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: ` +
+      `\`workspace/\` is the workspace root, its knowledge is at \`workspace/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/test-mode.ts

@@ -18,7 +18,9 @@
 //     a test run; the env var says TEST_MODE_WITHHELD instead, so a script
 //     that forgot to check fails at the provider with an auth error
 //   - the write-back: state/ and storage/ go INTO the sandbox as usual and
-//     come out into runs/<id>/test-writes/ instead of the real directories
+//     come out into runs/<id>/test-writes/ instead of the real directories;
+//     the next step's copy has those writes laid over it (overlayTestWrites),
+//     so the run reads its own work and the workspace never sees it
 //
 // Nothing here weakens a live run: every function is a no-op unless the run
 // says `test: true`.
@@ -270,25 +272,32 @@ export function snapshotDivertedDirs(wsRoot: string): Map<string, Buffer> {
 
 /** Undo a step's writes to the diverted directories, keeping each changed
  *  or new file under `to` by its workspace-relative path. Deletions are
- *  undone too — the original is put back. Returns what was set aside. */
+ *  undone too — the original is put back. `handed` is what the step was
+ *  given when that was more than the workspace (the run's earlier test
+ *  writes, laid over it): only what the step changed from THAT is its
+ *  write. Returns what was set aside. */
 export function restoreDivertedDirs(
   wsRoot: string,
   before: Map<string, Buffer>,
   to: string,
   note: (rel: string, summary: string) => void,
+  handed: Map<string, Buffer> = before,
 ): string[] {
   const now = snapshotDivertedDirs(wsRoot);
   const aside: string[] = [];
   for (const [rel, next] of now) {
-    const was = before.get(rel) ?? null;
-    if (was && was.equals(next)) continue;
-    const dest = path.join(to, rel);
-    fs.mkdirSync(path.dirname(dest), { recursive: true });
-    fs.writeFileSync(dest, next);
-    aside.push(rel);
-    note(rel, divertedSummary(rel, was, next));
-    if (was) fs.writeFileSync(path.join(wsRoot, rel), was);
-    else fs.rmSync(path.join(wsRoot, rel), { force: true });
+    const given = handed.get(rel) ?? null;
+    if (!(given && given.equals(next))) {
+      const dest = path.join(to, rel);
+      fs.mkdirSync(path.dirname(dest), { recursive: true });
+      fs.writeFileSync(dest, next);
+      aside.push(rel);
+      note(rel, divertedSummary(rel, before.get(rel) ?? null, next));
+    }
+    const orig = before.get(rel);
+    if (orig) {
+      if (!orig.equals(next)) fs.writeFileSync(path.join(wsRoot, rel), orig);
+    } else fs.rmSync(path.join(wsRoot, rel), { force: true });
   }
   for (const [rel, was] of before) {
     if (now.has(rel)) continue;
@@ -300,6 +309,37 @@ export function restoreDivertedDirs(
   return aside;
 }
 
+/**
+ * A test run's later steps see what its earlier steps wrote. Those writes
+ * are kept under runs/<id>/test-writes/, never on the workspace, so each
+ * step's copy of the workspace gets them laid over it — otherwise a step
+ * reads the real files, and a flow that hands work on through storage/
+ * tests something no live run does: on 2026-10-03 a strata-desk test run's
+ * compiler wrote today's PASS report, and the mailer was handed the
+ * morning's FAIL one and refused. Times are kept, so a verify that asks
+ * whether a file is fresh answers for the step that wrote it. Returns the
+ * workspace-relative paths laid over.
+ */
+export function overlayTestWrites(wsCopy: string, from: string): string[] {
+  const laid: string[] = [];
+  for (const dir of TEST_DIVERTED_DIRS) {
+    const root = path.join(from, dir);
+    if (!fs.existsSync(root)) continue;
+    for (const entry of fs.readdirSync(root, { recursive: true, withFileTypes: true })) {
+      if (!entry.isFile()) continue;
+      const abs = path.join(entry.parentPath, entry.name);
+      const rel = path.relative(from, abs).replaceAll("\\", "/");
+      const dest = path.join(wsCopy, rel);
+      fs.mkdirSync(path.dirname(dest), { recursive: true });
+      fs.copyFileSync(abs, dest);
+      const st = fs.statSync(abs);
+      fs.utimesSync(dest, st.atime, st.mtime);
+      laid.push(rel);
+    }
+  }
+  return laid;
+}
+
 /** `[test] ` in front of a headline, once. */
 export function testHeadline(summary: string): string {
   return summary.startsWith("[test]") ? summary : `[test] ${summary}`;

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;
+}
+