@foldrun/core 0.3.0 → 0.5.0

package/src/script-tools.ts

@@ -20,6 +20,9 @@ import { spawn } from "node:child_process";
 import { z } from "zod";
 import { createSdkMcpServer, tool } from "@anthropic-ai/claude-agent-sdk";
 import { runInContainer } from "./container.ts";
+import { hostSafeEnv } from "./host-env.ts";
+import { workspaceLinkEnv } from "./confine.ts";
+import { platform } from "./platform.ts";
 
 // 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
@@ -38,8 +41,9 @@ export interface ScriptSpec {
   args: Record<string, string>; // arg name → description
   interpreter?: string; // optional override, e.g. "python3", "bash"
   /** 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
@@ -55,6 +59,14 @@ export interface ScriptSpec {
    *  default, `materialised`, is a program that reads values from its
    *  environment and needs them real — a browser seeding cookies. */
   secrets?: "proxied" | "materialised";
+  /** `outward: true` — this program makes something happen outside (sends,
+   *  posts, orders). On a test run a step that grants it is handed no real
+   *  secret at all, whatever their names. */
+  outward?: boolean;
+  /** `test_mode: allow` — a reader that happens to use a send-capable
+   *  secret's name (a GBP reader on a GBP token): on a test run the step
+   *  still gets the real values. An `outward` tool in the same step wins. */
+  testMode?: "allow";
 }
 
 export function parseScripts(raw: unknown): ScriptSpec[] {
@@ -82,12 +94,23 @@ export function parseScripts(raw: unknown): ScriptSpec[] {
       args,
       interpreter: typeof e.interpreter === "string" ? e.interpreter : undefined,
       secrets: e.secrets === "proxied" ? "proxied" : undefined,
+      outward: e.outward === true ? true : undefined,
+      testMode: e.test_mode === "allow" ? "allow" : undefined,
       timeout: Number.isFinite(timeout) && timeout > 0 ? timeout : undefined,
     });
   }
   return out;
 }
 
+/** Interpreter names that mean a language rather than a binary, and the
+ *  extension whose prepared interpreter serves them. */
+const GENERIC_INTERPRETER: Record<string, string> = {
+  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
@@ -99,7 +122,18 @@ export function commandFor(
   abs: string,
   overrides: Record<string, string> = {},
 ): { cmd: string; args: string[] } {
-  if (spec.interpreter) return { cmd: spec.interpreter, args: [abs] };
+  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]) return { cmd: overrides[ext], args: [abs] };
@@ -128,7 +162,7 @@ function containerInterpreter(abs: string): string {
   return byExt[path.extname(abs).toLowerCase()] ?? abs;
 }
 
-function runScript(
+export function runScript(
   cwd: string,
   spec: ScriptSpec,
   values: Record<string, string>,
@@ -229,9 +263,14 @@ function runScript(
       return;
     }
 
+    // Not process.env: on a platform that is every tenant's root key and
+    // the datastore credentials. The child starts from the allowlisted
+    // base and gets what the agent declared, by name — see host-env.ts.
+    // In a run container `env` already carries the container's whole
+    // environment, which is the boundary, so nothing is lost there.
     const child = spawn(cmd, args, {
       cwd,
-      env: { ...process.env, ...env },
+      env: workspaceLinkEnv({ ...hostSafeEnv(), ...env }, cwd),
       timeout: timeoutFor(spec),
     });
     let out = "";
@@ -291,7 +330,17 @@ export function resolveRunPath(agentDir: string, run: string, libraryScripts: st
     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/src/secret-files.ts

@@ -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";
@@ -33,10 +36,10 @@ function writeWrapper(dir: string, name: string, body: string): string {
 }
 
 /**
- * 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: string,
@@ -47,8 +50,10 @@ export function materializeFileSecrets(
   );
   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
@@ -95,7 +100,14 @@ export function materializeFileSecrets(
   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: string | null) {
-  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/src/secret-health.ts

@@ -0,0 +1,230 @@
+// Does this credential still work?
+//
+// The vault knows a secret's name, its scope and its shape. It knows nothing
+// about whether the thing on the other end still accepts it, and that is the
+// only question anyone actually has. A key that has quietly stopped working
+// looks identical to a key nobody has used yet, and both look identical to a
+// key that is fine — three very different situations rendered the same way.
+//
+// Two facts, recorded where they are already known and nowhere else:
+//
+//   when it was last used, and against which host
+//   what the other end said the last time — accepted, or refused
+//
+// The egress proxy sees both for every http tool and every model call,
+// because filling the credential is its whole job. Notifications and the
+// provider check report their own. Nothing new is instrumented, and a secret
+// materialised into a sandbox reports nothing, which the page says plainly
+// rather than guessing.
+//
+// Never the value, never a hash of the value, never the request body. A
+// name, a host, a status and a time.
+
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+import { accountDir } from "./store.ts";
+
+/** How a credential is identified here. A name alone is not enough: the
+ *  account and each workspace can hold a secret by the same name, and they
+ *  are different credentials with different health. */
+export function healthKey(name: string, scope: "account" | "workspace", workspace?: string | null): string {
+  return scope === "workspace" && workspace ? `workspace:${workspace}:${name}` : `account:${name}`;
+}
+
+export interface SecretUse {
+  /** ISO time of the most recent use. */
+  at: string;
+  /** The host it was sent to, so "which of my four keys is this" has an
+   *  answer without opening a run. */
+  host: string;
+  /** The response status, when there was one. */
+  status: number | null;
+  /** Refused means the credential itself was rejected: 401, 402 or 403.
+   *  A 500 is the other end failing, which says nothing about the key. */
+  outcome: "accepted" | "refused" | "error";
+}
+
+export interface SecretRecord {
+  last: SecretUse;
+  /** Consecutive refusals, newest first — one is a fluke, five is a dead
+   *  key. Reset by any acceptance. */
+  refusals: number;
+  /** The last acceptance, kept through a run of refusals so a page can say
+   *  "worked until Tuesday", which is the sentence that dates the breakage. */
+  lastAccepted: string | null;
+}
+
+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>;
+}
+
+const healthFile = (tenant: string) => path.join(accountDir(tenant), "secret-health.json");
+
+function read(tenant: string): HealthFile {
+  try {
+    return JSON.parse(fs.readFileSync(healthFile(tenant), "utf8")) as HealthFile;
+  } catch {
+    return {};
+  }
+}
+
+function write(tenant: string, data: HealthFile): void {
+  const file = healthFile(tenant);
+  if (!fs.existsSync(path.dirname(file))) return;
+  // pid alone is not unique across pods on a shared volume.
+  const tmp = `${file}.${process.pid}.${crypto.randomBytes(4).toString("hex")}`;
+  fs.writeFileSync(tmp, JSON.stringify(data, null, 2));
+  fs.renameSync(tmp, file);
+}
+
+const fileStore: SecretHealthStore = {
+  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: SecretHealthStore = fileStore;
+
+/** The platform's store (Postgres), or back to files with null. */
+export function setSecretHealthStore(next: SecretHealthStore | null): void {
+  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
+// every proxied call — "never blocks" has to be true, not aspirational.
+// One writer per process; the queue drains in order.
+const pending = new Map<string, HealthUpdate[]>();
+let draining = false;
+
+function drain(): void {
+  if (draining) return;
+  draining = true;
+  setImmediate(async () => {
+    try {
+      for (const [tenant, updates] of pending) {
+        pending.delete(tenant);
+        try {
+          await store.apply(tenant, updates);
+        } catch {
+          // best effort, always
+        }
+      }
+    } finally {
+      draining = false;
+      if (pending.size) drain();
+    }
+  });
+}
+
+function apply(data: HealthFile, name: string, use: { host: string; status: number | null; at?: string }): void {
+  const outcome = outcomeFor(use.status);
+  const at = use.at ?? new Date().toISOString();
+  const prev = data[name];
+  data[name] = {
+    last: { at, host: use.host, status: use.status, outcome },
+    // Only a refusal counts against a key. An error at the other end is
+    // the other end's problem and must not accumulate into a false alarm.
+    refusals: outcome === "refused" ? (prev?.refusals ?? 0) + 1 : outcome === "accepted" ? 0 : prev?.refusals ?? 0,
+    lastAccepted: outcome === "accepted" ? at : prev?.lastAccepted ?? null,
+  };
+}
+
+/** 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
+ *  rotate a key that was never the problem. */
+export function outcomeFor(status: number | null): SecretUse["outcome"] {
+  if (status === null) return "error";
+  if (status === 401 || status === 402 || status === 403) return "refused";
+  if (status >= 200 && status < 400) return "accepted";
+  return "error";
+}
+
+/**
+ * Record one use. `key` is a health key (see healthKey), never a bare name.
+ * Never throws and never blocks: the write is queued and happens off the
+ * caller's path, because this runs on every proxied request.
+ */
+export function noteSecretUse(
+  tenant: string,
+  key: string,
+  use: { host: string; status: number | null; at?: string },
+): void {
+  if (!key) return;
+  const list = pending.get(tenant) ?? [];
+  list.push({ key, use: { ...use, at: use.at ?? new Date().toISOString() } });
+  pending.set(tenant, list);
+  drain();
+}
+
+/** Wait for queued writes to land — for tests, and for a process that is
+ *  about to exit. */
+export function flushSecretHealth(): Promise<void> {
+  return new Promise((resolve) => {
+    const check = () => (pending.size === 0 && !draining ? resolve() : setImmediate(check));
+    check();
+  });
+}
+
+/** 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 async function secretHealth(tenant: string): Promise<HealthFile> {
+  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 async function failingSecrets(tenant: string): Promise<{ name: string; record: SecretRecord }[]> {
+  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 async function forgetSecretHealth(tenant: string, name: string): Promise<void> {
+  try {
+    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: string): HealthFile {
+  return read(tenant);
+}