@foldrun/core 0.3.0 → 0.5.0

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

package/dist/src/tool-test.js

@@ -17,12 +17,15 @@
 import { spawn } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
-import { resolveSecrets } from "./secrets.js";
+import { resolveSecrets, materializeSecrets } from "./secrets.js";
 import { listAgents, workspaceDir } from "./store.js";
 import { libraryDir } from "./library.js";
 import { secretsUsedByApi } from "./api-tools.js";
+import { attachOperations, prefetchOpenApi } from "./openapi.js";
 import { commandFor, resolveRunPath } from "./script-tools.js";
 import { parseRuntime, prepareRuntime } from "./runtime.js";
+import { hostSafeEnv } from "./host-env.js";
+import { linkWorkspace, workspaceLinkEnv } from "./confine.js";
 const MAX_DETAIL = 4000;
 const TIMEOUT_MS = 15_000;
 // A tool test runs tenant-authored code directly on the host — real runs are
@@ -30,28 +33,34 @@ 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() {
-    const base = {};
-    for (const k of HOST_BASE_ENV_KEYS) {
-        const v = process.env[k];
-        if (v !== undefined)
-            base[k] = v;
-    }
-    return base;
-}
+// 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 = () => hostSafeEnv();
 const clip = (s) => s.length > MAX_DETAIL ? `${s.slice(0, MAX_DETAIL)}\n… truncated` : s;
 /** `${NAME}` → value, for headers and query. Same rule the runtime uses. */
 const substitute = (v, env) => 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, ctx) {
+    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, concrete) {
+    const re = new RegExp("^" + op.path.split(/\{[^/}]+\}/).map((part) => part.replace(/[.*+?^$()|[\]\\]/g, "\\$&")).join("[^/]+") + "$");
+    return re.test(concrete);
+}
 export async function testTool(tenant, workspace, def, input = {}) {
     const probePath = input.path ?? "";
     const started = Date.now();
@@ -59,9 +68,56 @@ export async function testTool(tenant, workspace, def, input = {}) {
     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)) {
@@ -76,7 +132,6 @@ export async function testTool(tenant, workspace, def, input = {}) {
             const headers = {};
             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,
@@ -108,7 +163,7 @@ export async function testTool(tenant, workspace, def, input = {}) {
         }
     }
     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
@@ -126,7 +181,47 @@ export async function testTool(tenant, workspace, def, input = {}) {
         // 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({
                 ok: false, transport: "script", missingSecrets: [],
@@ -135,7 +230,12 @@ export async function testTool(tenant, workspace, def, input = {}) {
             });
         }
         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;
         // Declared args become long flags, exactly as the runtime passes them.
@@ -160,11 +260,25 @@ export async function testTool(tenant, workspace, def, input = {}) {
             });
         }
         const { cmd, args } = commandFor({ interpreter, run: run, name: "", description: "", args: {} }, 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;
+        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.
         const untested = code !== 0 && declared.length > 0 && flags.length === 0;
@@ -177,7 +291,7 @@ export async function testTool(tenant, workspace, def, input = {}) {
                 : code === 0 ? "exited 0" : `exited ${code ?? "with an error"}`,
             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)")),
         });
     }
@@ -214,7 +328,12 @@ export async function testTool(tenant, workspace, def, input = {}) {
     const named = Object.entries(spec.env ?? {})
         .map(([, v]) => String(v).match(/^\$\{([A-Z0-9_]+)\}$/)?.[1])
         .filter((n) => 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 = { ...hostSafeBaseEnv() };
     for (const [k, v] of Object.entries(spec.env ?? {}))
         childEnv[k] = substitute(String(v), env);

package/dist/src/translator.d.ts

@@ -22,6 +22,9 @@ export interface TranslatorSpec {
      *  upstream request goes through it, and `upstreamKey` is a placeholder
      *  the proxy fills. */
     egress?: string;
+    /** The step's own zone, from the clock cascade — what a reset time in a
+     *  refusal is told in. UTC when nothing said otherwise. */
+    timezone?: string;
 }
 export interface RunningTranslator {
     port: number;
@@ -81,7 +84,7 @@ export declare function toResponses(req: Json, opts: {
     params?: Record<string, unknown>;
 }, drop?: Dropped): Json;
 /** A finished Chat Completion as an Anthropic message. Pure. */
-export declare function fromChatCompletion(res: Json, requestedModel: string): Json;
+export declare function fromChatCompletion(res: Json, requestedModel: string, stopSequences?: unknown): Json;
 /**
  * The streaming half: Chat-Completions chunks in, Anthropic SSE events out.
  * A state machine because the two streams disagree about structure — one
@@ -95,11 +98,13 @@ export declare class StreamTranslator {
     private textIndex;
     /** Chat-Completions tool index → Anthropic block index. */
     private tools;
+    /** The last choice's stop fields: finish_reason and any matched stop. */
     private finish;
     private usage;
     private id;
     private readonly model;
-    constructor(model: string);
+    private readonly stops;
+    constructor(model: string, stopSequences?: unknown);
     private event;
     private start;
     private closeText;
@@ -125,6 +130,7 @@ export declare class ResponsesStreamTranslator {
     private usage;
     private incomplete;
     private sawTool;
+    private sawRefusal;
     private id;
     private readonly model;
     constructor(model: string);