@foldrun/core 0.4.0 → 0.6.0

package/dist/src/subagents.d.ts

@@ -0,0 +1,75 @@
+/** 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 declare const DELEGATE_TOOLS: readonly ["Agent", "Task"];
+export declare const DELEGATE_TOOL = "Agent";
+/** The named sub-agents' folders, host-side. Unknown names are reported. */
+export declare function gatherSubagents(workspaceRoot: string, names: unknown): {
+    found: {
+        name: string;
+        dir: string;
+    }[];
+    missing: string[];
+};
+/**
+ * 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 declare function subagentTools(own: string[], parent: string[]): string[];
+/** 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 declare function subagentPrompt(o: {
+    body: string;
+    name: string;
+    parent: string;
+    workspace: string;
+    shared?: string | null;
+}): string;
+/** 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 declare function toAgentDefinitions(specs: SubagentSpec[]): Record<string, {
+    description: string;
+    prompt: string;
+    tools: string[];
+    disallowedTools: string[];
+    model: string;
+}>;
+/** 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 declare function subagentGuard(specs: SubagentSpec[]): (call: GuardedCall) => string | 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 declare function grantedNames(tools: string[]): Set<string>;
+export declare function checkOverlap(parentTools: string[], subTools: string[]): string[];

package/dist/src/subagents.js

@@ -0,0 +1,149 @@
+// 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.js";
+import { TOOL_MAP } from "./tool-names.js";
+/** 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"];
+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, names) {
+    const found = [];
+    const missing = [];
+    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, parent) {
+    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 = [];
+    for (const t of own) {
+        if (DELEGATE_TOOLS.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) {
+    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) {
+    const out = {};
+    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;
+}
+/**
+ * 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) {
+    const by = new Map(specs.map((s) => [s.name, s]));
+    const declared = specs.map((s) => s.name).join(", ");
+    const isDelegate = (tool) => DELEGATE_TOOLS.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) {
+    const out = new Set();
+    for (const t of tools) {
+        for (const n of TOOL_MAP[t] ?? [t])
+            out.add(n);
+    }
+    return out;
+}
+export function checkOverlap(parentTools, subTools) {
+    const parent = grantedNames(parentTools);
+    return [...grantedNames(subTools)].filter((t) => parent.has(t) && !DELEGATE_TOOLS.includes(t));
+}

package/dist/src/test-mode.d.ts

@@ -103,8 +103,23 @@ export declare function divertedSummary(rel: string, was: Buffer | null, next: B
 export declare 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. */
-export declare function restoreDivertedDirs(wsRoot: string, before: Map<string, Buffer>, to: string, note: (rel: string, summary: string) => void): string[];
+ *  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 declare function restoreDivertedDirs(wsRoot: string, before: Map<string, Buffer>, to: string, note: (rel: string, summary: string) => void, handed?: Map<string, Buffer>): string[];
+/**
+ * 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 declare function overlayTestWrites(wsCopy: string, from: string): string[];
 /** `[test] ` in front of a headline, once. */
 export declare function testHeadline(summary: string): string;
 /** The env every test-run sandbox gets, beside its secrets. */

package/dist/src/test-mode.js

@@ -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`.
@@ -247,21 +249,27 @@ export function snapshotDivertedDirs(wsRoot) {
 }
 /** 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. */
-export function restoreDivertedDirs(wsRoot, before, to, note) {
+ *  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, before, to, note, handed = before) {
     const now = snapshotDivertedDirs(wsRoot);
     const aside = [];
     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);
+        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 });
     }
@@ -275,6 +283,38 @@ export function restoreDivertedDirs(wsRoot, before, to, note) {
     }
     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, from) {
+    const laid = [];
+    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) {
     return summary.startsWith("[test]") ? summary : `[test] ${summary}`;

package/dist/src/tool-names.d.ts

@@ -1,9 +1,16 @@
 import { type Ref } from "./refs.ts";
 /** Groups: one word an author can hold in their head, expanded to SDK names. */
 export declare const TOOL_MAP: Record<string, string[]>;
+/** 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 declare const RETIRED_TOOLS: Record<string, string>;
 /** 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 declare const BUILTIN_TOOLS: Set<string>;
 /** The platform's own groups, served in-process rather than by the SDK. */
 export declare const PLATFORM_GROUPS: Set<string>;
@@ -34,6 +41,11 @@ export declare function ownToolNames(front: ToolFrontmatter): string[];
 /** What a file still says under the removed `use:` key — nothing is granted
  *  for these; they exist so the error can quote the exact `tools:` line. */
 export declare function legacyUseNames(front: ToolFrontmatter): string[];
+/** Retired names written bare in `tools:`, deduped. A `[[link]]` is the
+ *  author's own file, so it is never one of these. */
+export declare function retiredToolNames(front: ToolFrontmatter): string[];
+/** The one sentence every reader of a retired name says. */
+export declare function retiredToolError(name: string): string;
 /** The one sentence every reader of a `use:` key says. */
 export declare function legacyUseError(names: string[]): string;
 export {};

package/dist/src/tool-names.js

@@ -12,27 +12,40 @@
 import { refList, refNames } from "./refs.js";
 /** Groups: one word an author can hold in their head, expanded to SDK names. */
 export const TOOL_MAP = {
-    // `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 = {
+    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. */
 export function isRuntimeTool(name) {
@@ -73,6 +86,20 @@ export function ownToolNames(front) {
 export function legacyUseNames(front) {
     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) {
+    const out = [];
+    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) {
+    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) {
     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/dist/src/tool-programs.d.ts

@@ -16,3 +16,29 @@ export interface MissingProgram {
  * call a working account tool broken.
  */
 export declare function missingToolPrograms(tenant: string, workspace: string): MissingProgram[];
+/** The names `import` would use for a declared distribution. */
+export declare function importNamesOf(requirement: string): string[];
+/** Top-level modules a Python file imports; relative imports excluded. */
+export declare function pythonImports(source: string): string[];
+/** Packages a JavaScript file imports or requires; relative and node: excluded. */
+export declare function nodeImports(source: string): string[];
+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 declare function undeclaredImports(tenant: string, workspace: string): UndeclaredImport[];

package/dist/src/tool-programs.js

@@ -14,6 +14,9 @@
 // runner — passing a tool that cannot run, or failing one that can.
 import fs from "node:fs";
 import path from "node:path";
+import { builtinModules } from "node:module";
+import matter from "gray-matter";
+import { parseRuntime } from "./runtime.js";
 import { workspaceDir, workspaceTools } from "./store.js";
 import { libraryDir, libraryTools } from "./library.js";
 import { resolveRunPath } from "./script-tools.js";
@@ -50,3 +53,172 @@ export function missingToolPrograms(tenant, workspace) {
     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 = {
+    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) {
+    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) {
+    const out = new Set();
+    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) {
+    const out = new Set();
+    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"]);
+/**
+ * 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, workspace) {
+    const dir = workspaceDir(tenant, workspace);
+    const from = path.join(dir, "agents", "_probe");
+    const libScripts = libraryDir(tenant, "scripts");
+    const sharedPy = new Set();
+    const sharedNpm = new Set();
+    const addRuntime = (raw) => {
+        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) => {
+        try {
+            return matter(fs.readFileSync(file, "utf8")).data;
+        }
+        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 = [];
+    const scan = (defs, scope) => {
+        for (const [name, def] of Object.entries(defs)) {
+            if (def.kind !== "script")
+                continue;
+            const run = String(def.spec.run ?? "");
+            if (!run)
+                continue;
+            const file = resolveRunPath(from, run, libScripts);
+            if (!fs.existsSync(file))
+                continue;
+            const own = parseRuntime(def.spec.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;
+}