@foldrun/core 0.4.0 → 0.6.0

package/dist/src/script-tools.d.ts

@@ -9,8 +9,9 @@ export interface ScriptSpec {
     args: Record<string, string>;
     interpreter?: string;
     /** Seconds this script may run — for the crawl that legitimately takes
-     *  five minutes. Defaults to 120, capped at 600: a limit an author can
-     *  raise is a budget; one they can remove is a hang. */
+     *  five minutes. Unset means no platform clock; there was a two-minute
+     *  default and a ten-minute cap here and both were removed (see the note
+     *  above `timeoutFor`). */
     timeout?: number;
     /** The script itself, when the tool is a single markdown file with its
      *  code in a fenced block. Materialised to a file at call time — the
@@ -44,6 +45,20 @@ export declare function runScript(cwd: string, spec: ScriptSpec, values: Record<
     code: number | null;
     out: string;
 }>;
+/**
+ * A host path as the script's container sees it: under the agent's own
+ * directory it is /workspace, under a mounted folder it is that mount, and
+ * anything else (an argument that only looks like a path) is left alone.
+ * Containment, not a text prefix: `<ws>/scripts-old/x.py` is not under
+ * `<ws>/scripts`. The longest mount wins, so a nested one is not shadowed.
+ */
+export declare function containerPath(p: string, agentDir: string, mounts: Record<string, string>): string;
+/** Where a `workspace/…` script argument is staged in a script container,
+ *  or null when it is not one (or climbs out of the workspace). */
+export declare function stageWorkspaceArg(arg: string, workspaceRoot: string): {
+    host: string;
+    container: string;
+} | null;
 export interface ExecutionContext {
     /** "docker" nests each script in its own container; "sandbox" spawns it
      *  directly inside the isolation the step already has. */

package/dist/src/script-tools.js

@@ -20,6 +20,8 @@ import { z } from "zod";
 import { createSdkMcpServer, tool } from "@anthropic-ai/claude-agent-sdk";
 import { runInContainer } from "./container.js";
 import { hostSafeEnv } from "./host-env.js";
+import { workspaceLinkEnv } from "./confine.js";
+import { platform } from "./platform.js";
 // A script's only clock is the `timeout:` its own tool.md declares. There
 // was a two-minute default and a ten-minute cap here; both were the
 // platform's opinion about how long a person's script may take, and the
@@ -63,6 +65,14 @@ export function parseScripts(raw) {
     }
     return out;
 }
+/** Interpreter names that mean a language rather than a binary, and the
+ *  extension whose prepared interpreter serves them. */
+const GENERIC_INTERPRETER = {
+    python: ".py",
+    python3: ".py",
+    "/usr/bin/python3": ".py",
+    "/usr/bin/env python3": ".py",
+};
 // Pick how to execute a file when no interpreter is declared.
 //
 // Exported because the tool tester has to make the same choice, and used to
@@ -70,8 +80,19 @@ export function parseScripts(raw) {
 // Test button spawned every .mjs tool as a program and reported EACCES for a
 // tool that runs perfectly. Two tables, one of them wrong.
 export function commandFor(spec, abs, overrides = {}) {
-    if (spec.interpreter)
+    if (spec.interpreter) {
+        // `interpreter: python3` names the language, not a particular binary, and
+        // it is how most tool files are written. Taken literally it ran the bare
+        // system python beside a venv built for this very tool, and the tool
+        // died on its first import ("No module named openpyxl") while the log
+        // above it said the runtime was cached. A generic python name is served
+        // by the prepared venv when there is one; a path or anything else is
+        // still obeyed as written.
+        const lang = GENERIC_INTERPRETER[spec.interpreter.trim()];
+        if (lang && overrides[lang])
+            return { cmd: overrides[lang], args: [abs] };
         return { cmd: spec.interpreter, args: [abs] };
+    }
     const ext = path.extname(abs).toLowerCase();
     // A prepared runtime (venv, npm prefix) wins over the host interpreter.
     if (overrides[ext])
@@ -162,14 +183,18 @@ export function runScript(cwd, spec, values, env, libraryScripts, interpreters,
         // Container path: same command, executed inside an isolated container
         // with only the agent's directory (plus declared shared dirs) mounted.
         if (exec && exec.executor === "docker") {
+            // `workspace/…` is the workspace root on the host (the step's link)
+            // and in a run container; here there is no link, so each such
+            // argument is staged: copied in, pointed at, and copied back after.
+            const workspaceRoot = path.resolve(cwd, "..", "..");
+            const staged = [];
             const inContainer = (p) => {
-                if (p.startsWith(path.resolve(cwd)))
-                    return p.replace(path.resolve(cwd), "/workspace");
-                for (const [host, mount] of Object.entries(exec.mounts)) {
-                    if (p.startsWith(host))
-                        return p.replace(host, mount);
-                }
-                return p;
+                const w = stageWorkspaceArg(p, workspaceRoot);
+                if (!w)
+                    return containerPath(p, cwd, exec.mounts);
+                if (!staged.some((s) => s.host === w.host))
+                    staged.push(w);
+                return w.container;
             };
             const argv = [
                 // The interpreter inside the image, not the host's venv path.
@@ -182,6 +207,7 @@ export function runScript(cwd, spec, values, env, libraryScripts, interpreters,
             runInContainer({
                 agentDir: path.resolve(cwd),
                 readOnly: exec.mounts,
+                staged,
                 image: exec.image,
                 argv,
                 env,
@@ -198,7 +224,7 @@ export function runScript(cwd, spec, values, env, libraryScripts, interpreters,
         // environment, which is the boundary, so nothing is lost there.
         const child = spawn(cmd, args, {
             cwd,
-            env: { ...hostSafeEnv(), ...env },
+            env: workspaceLinkEnv({ ...hostSafeEnv(), ...env }, cwd),
             timeout: timeoutFor(spec),
         });
         let out = "";
@@ -217,6 +243,41 @@ export function runScript(cwd, spec, values, env, libraryScripts, interpreters,
         }));
     });
 }
+/**
+ * A host path as the script's container sees it: under the agent's own
+ * directory it is /workspace, under a mounted folder it is that mount, and
+ * anything else (an argument that only looks like a path) is left alone.
+ * Containment, not a text prefix: `<ws>/scripts-old/x.py` is not under
+ * `<ws>/scripts`. The longest mount wins, so a nested one is not shadowed.
+ */
+export function containerPath(p, agentDir, mounts) {
+    if (!path.isAbsolute(p))
+        return p;
+    const under = (root) => {
+        const rel = path.relative(root, p);
+        return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel)) ? rel : null;
+    };
+    const own = under(path.resolve(agentDir));
+    if (own !== null)
+        return path.posix.join("/workspace", own.split(path.sep).join("/"));
+    const hit = Object.entries(mounts)
+        .map(([host, mount]) => ({ mount, rel: under(path.resolve(host)), len: host.length }))
+        .filter((m) => m.rel !== null)
+        .sort((a, b) => b.len - a.len)[0];
+    return hit ? path.posix.join(hit.mount, hit.rel.split(path.sep).join("/")) : p;
+}
+/** Where a `workspace/…` script argument is staged in a script container,
+ *  or null when it is not one (or climbs out of the workspace). */
+export function stageWorkspaceArg(arg, workspaceRoot) {
+    if (arg !== "workspace" && !arg.startsWith("workspace/"))
+        return null;
+    const rel = arg.slice("workspace".length).replace(/^\/+/, "");
+    const host = path.resolve(workspaceRoot, rel);
+    const within = path.relative(workspaceRoot, host);
+    if (within.startsWith("..") || path.isAbsolute(within))
+        return null;
+    return { host, container: path.posix.join("/workspace-root", within.split(path.sep).join("/")) };
+}
 // `run:` accepts:
 //   scripts/x.py              this agent's own script
 //   workspace/tools/<t>/x.py  a folder tool's own code, in this workspace
@@ -236,7 +297,18 @@ export function resolveRunPath(agentDir, run, libraryScripts) {
         return path.resolve(workspaceRoot, "tools", run.slice("workspace/tools/".length));
     }
     if (run.startsWith("account/tools/")) {
-        return path.resolve(libraryRoot, "tools", run.slice("account/tools/".length));
+        const rel = run.slice("account/tools/".length);
+        const own = path.resolve(libraryRoot, "tools", rel);
+        // A gallery tool nobody installed has no copy in the library. In a
+        // sandbox the gallery is laid down under the library, so the path above
+        // is it; a run on the host has no such merge, so it looks on the shelf.
+        const gallery = platform.galleryDir();
+        if (!fs.existsSync(own) && gallery) {
+            const shelf = path.resolve(gallery, "tools", rel);
+            if (fs.existsSync(shelf))
+                return shelf;
+        }
+        return own;
     }
     // Canonical prefixes, then the legacy spellings they replaced.
     for (const p of ["workspace/scripts/", "shared/"]) {

package/dist/src/secret-files.d.ts

@@ -1,12 +1,13 @@
 /**
- * Turn any @file/@ssh/@api values in `env` into files under
- * `<agentDir>/.secret-files`, rewriting each to its path. Returns the
- * directory written (for cleanup) and the transformed env. Plain values
- * pass through untouched.
+ * Turn any @file/@ssh/@api values in `env` into files under a fresh
+ * `<agentDir>/.secret-files/step-XXXXXX`, rewriting each to its path.
+ * Returns the directory written (for cleanup) and the transformed env.
+ * Plain values pass through untouched.
  */
 export declare function materializeFileSecrets(agentDir: string, env: Record<string, string>): {
     env: Record<string, string>;
     dir: string | null;
 };
-/** Best-effort removal of a materialised secret-files directory. */
+/** Best-effort removal of a materialised secret-files directory — this
+ *  step's own, and the shared parent once no other step is using it. */
 export declare function cleanupFileSecrets(dir: string | null): void;

package/dist/src/secret-files.js

@@ -9,9 +9,12 @@
 // `"$PROD_VM" 'uptime'` or `"$STRIPE" /v1/charges` and never learns whether
 // it was key or password, one header or five.
 //
-// Everything lands in a per-run scratch directory inside the agent's own
+// Everything lands in a per-step scratch directory inside the agent's own
 // tree (so it crosses into a container with the workspace) but dot-prefixed
-// and never archived or copied back — it holds live credentials.
+// and never archived or copied back — it holds live credentials. Per step,
+// not per agent: two steps of one agent run in parallel on the in-process
+// path (a fan-out), and with one shared directory the first to finish
+// deleted the keys the other was still using.
 import fs from "node:fs";
 import path from "node:path";
 import { isFileValue, fileContent, isSshValue, sshConfigOf, isApiValue, apiConfigOf, } from "./secrets.js";
@@ -25,17 +28,19 @@ function writeWrapper(dir, name, body) {
     return file;
 }
 /**
- * Turn any @file/@ssh/@api values in `env` into files under
- * `<agentDir>/.secret-files`, rewriting each to its path. Returns the
- * directory written (for cleanup) and the transformed env. Plain values
- * pass through untouched.
+ * Turn any @file/@ssh/@api values in `env` into files under a fresh
+ * `<agentDir>/.secret-files/step-XXXXXX`, rewriting each to its path.
+ * Returns the directory written (for cleanup) and the transformed env.
+ * Plain values pass through untouched.
  */
 export function materializeFileSecrets(agentDir, env) {
     const entries = Object.entries(env).filter(([, v]) => typeof v === "string" && (isFileValue(v) || isSshValue(v) || isApiValue(v)));
     if (entries.length === 0)
         return { env, dir: null };
-    const dir = path.join(agentDir, ".secret-files");
-    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const parent = path.join(agentDir, ".secret-files");
+    fs.mkdirSync(parent, { recursive: true, mode: 0o700 });
+    const dir = fs.mkdtempSync(path.join(parent, "step-"));
+    fs.chmodSync(dir, 0o700);
     const out = { ...env };
     for (const [name, value] of entries) {
         // Lowercased name as the filename keeps it predictable without leaking
@@ -85,8 +90,16 @@ export function materializeFileSecrets(agentDir, env) {
     }
     return { env: out, dir };
 }
-/** Best-effort removal of a materialised secret-files directory. */
+/** Best-effort removal of a materialised secret-files directory — this
+ *  step's own, and the shared parent once no other step is using it. */
 export function cleanupFileSecrets(dir) {
-    if (dir)
-        fs.rmSync(dir, { recursive: true, force: true });
+    if (!dir)
+        return;
+    fs.rmSync(dir, { recursive: true, force: true });
+    try {
+        fs.rmdirSync(path.dirname(dir));
+    }
+    catch {
+        // another step's directory is still in there
+    }
 }

package/dist/src/secret-health.d.ts

@@ -23,7 +23,30 @@ export interface SecretRecord {
      *  "worked until Tuesday", which is the sentence that dates the breakage. */
     lastAccepted: string | null;
 }
-type HealthFile = Record<string, SecretRecord>;
+export type HealthFile = Record<string, SecretRecord>;
+/** One use to fold into a record. */
+export interface HealthUpdate {
+    key: string;
+    use: {
+        host: string;
+        status: number | null;
+        at: string;
+    };
+}
+/**
+ * Where health is kept. A file per account by default — what the CLI and a
+ * single-box install use. The platform plugs in Postgres
+ * (setSecretHealthStore), where each use is one atomic upsert: two pods
+ * recording at once on a shared file was last-writer-wins, and a refusal
+ * could vanish.
+ */
+export interface SecretHealthStore {
+    apply(tenant: string, updates: HealthUpdate[]): Promise<void>;
+    read(tenant: string): Promise<HealthFile>;
+    forget(tenant: string, key: string): Promise<void>;
+}
+/** The platform's store (Postgres), or back to files with null. */
+export declare function setSecretHealthStore(next: SecretHealthStore | null): void;
 /** 401, 402 and 403 are the credential being refused. Everything else is
  *  the request, the model or the provider — none of which is the key's
  *  fault, and calling them a credential failure would send people to
@@ -45,15 +68,16 @@ export declare function flushSecretHealth(): Promise<void>;
 /** Everything known about this account's credentials, by name. Names the
  *  vault holds but nothing has used are simply absent, which is the honest
  *  answer: unused is not the same as broken. */
-export declare function secretHealth(tenant: string): HealthFile;
+export declare function secretHealth(tenant: string): Promise<HealthFile>;
 /** The credentials worth saying something about: refused the last time they
  *  were used. Sorted worst first — most consecutive refusals, then oldest
  *  last-success, which is the order someone would work through them. */
-export declare function failingSecrets(tenant: string): {
+export declare function failingSecrets(tenant: string): Promise<{
     name: string;
     record: SecretRecord;
-}[];
+}[]>;
 /** Drop what is known about a secret — for a delete, and for a rotation,
  *  where the old key's refusals say nothing about the new one. */
-export declare function forgetSecretHealth(tenant: string, name: string): void;
-export {};
+export declare function forgetSecretHealth(tenant: string, name: string): Promise<void>;
+/** The account's file, for the platform's one-time import into its store. */
+export declare function readSecretHealthFile(tenant: string): HealthFile;

package/dist/src/secret-health.js

@@ -47,6 +47,29 @@ function write(tenant, data) {
     fs.writeFileSync(tmp, JSON.stringify(data, null, 2));
     fs.renameSync(tmp, file);
 }
+const fileStore = {
+    async apply(tenant, updates) {
+        const data = read(tenant);
+        for (const { key, use } of updates)
+            apply(data, key, use);
+        write(tenant, data);
+    },
+    async read(tenant) {
+        return read(tenant);
+    },
+    async forget(tenant, key) {
+        const data = read(tenant);
+        if (!(key in data))
+            return;
+        delete data[key];
+        write(tenant, data);
+    },
+};
+let store = fileStore;
+/** The platform's store (Postgres), or back to files with null. */
+export function setSecretHealthStore(next) {
+    store = next ?? fileStore;
+}
 // Writes are queued and coalesced off the caller's path. The egress proxy
 // notes a use per secret per request, before it streams the response body,
 // and a synchronous read-modify-write of a JSON file there is latency on
@@ -58,19 +81,18 @@ function drain() {
     if (draining)
         return;
     draining = true;
-    setImmediate(() => {
+    setImmediate(async () => {
         try {
-            for (const [tenant, uses] of pending) {
+            for (const [tenant, updates] of pending) {
                 pending.delete(tenant);
-                const data = read(tenant);
-                for (const { name, use } of uses)
-                    apply(data, name, use);
-                write(tenant, data);
+                try {
+                    await store.apply(tenant, updates);
+                }
+                catch {
+                    // best effort, always
+                }
             }
         }
-        catch {
-            // best effort, always
-        }
         finally {
             draining = false;
             if (pending.size)
@@ -112,7 +134,7 @@ export function noteSecretUse(tenant, key, use) {
     if (!key)
         return;
     const list = pending.get(tenant) ?? [];
-    list.push({ name: key, use: { ...use, at: use.at ?? new Date().toISOString() } });
+    list.push({ key, use: { ...use, at: use.at ?? new Date().toISOString() } });
     pending.set(tenant, list);
     drain();
 }
@@ -127,29 +149,29 @@ export function flushSecretHealth() {
 /** Everything known about this account's credentials, by name. Names the
  *  vault holds but nothing has used are simply absent, which is the honest
  *  answer: unused is not the same as broken. */
-export function secretHealth(tenant) {
-    return read(tenant);
+export async function secretHealth(tenant) {
+    return store.read(tenant);
 }
 /** The credentials worth saying something about: refused the last time they
  *  were used. Sorted worst first — most consecutive refusals, then oldest
  *  last-success, which is the order someone would work through them. */
-export function failingSecrets(tenant) {
-    return Object.entries(read(tenant))
+export async function failingSecrets(tenant) {
+    return Object.entries(await store.read(tenant))
         .filter(([, r]) => r.last.outcome === "refused")
         .map(([name, record]) => ({ name, record }))
         .sort((a, b) => b.record.refusals - a.record.refusals || (a.record.lastAccepted ?? "").localeCompare(b.record.lastAccepted ?? ""));
 }
 /** Drop what is known about a secret — for a delete, and for a rotation,
  *  where the old key's refusals say nothing about the new one. */
-export function forgetSecretHealth(tenant, name) {
+export async function forgetSecretHealth(tenant, name) {
     try {
-        const data = read(tenant);
-        if (!(name in data))
-            return;
-        delete data[name];
-        write(tenant, data);
+        await store.forget(tenant, name);
     }
     catch {
         // best effort
     }
 }
+/** The account's file, for the platform's one-time import into its store. */
+export function readSecretHealthFile(tenant) {
+    return read(tenant);
+}

package/dist/src/secrets.d.ts

@@ -16,6 +16,24 @@ export declare function installKeyMaterial(): string;
  *  are refreshed into live tokens, "file"/"ssh"/"api" are materialised into
  *  the run's scratch. Plain values have no kind. */
 export type SecretKind = "oauth2" | "service-account" | "file" | "ssh" | "api";
+interface StoredSecret {
+    iv: string;
+    tag: string;
+    data: string;
+    updatedAt: string;
+    kind?: SecretKind;
+    /** Which key opens this. Absent means the install key, which is what every
+     *  record written before per-account keys existed is encrypted with — so an
+     *  old vault stays readable without a migration having to run first. */
+    k?: "tenant";
+}
+type SecretsFile = Record<string, StoredSecret>;
+/**
+ * Change one vault file safely: `change` gets what is stored now and returns
+ * the new contents, or null to leave the file untouched. Returns what is
+ * stored after.
+ */
+export declare function mutateVaultFile(file: string, change: (all: SecretsFile) => SecretsFile | null): SecretsFile;
 export declare const SECRET_NAME: RegExp;
 export declare function setSecret(tenant: string, name: string, value: string, workspace?: string, kind?: SecretKind): void;
 /** Encrypt one value for an account — the same envelope secrets use, exported
@@ -163,3 +181,4 @@ export declare function rewrapTenantSecrets(tenant: string): {
     moved: number;
     unreadable: string[];
 };
+export {};