@foldrun/core 0.2.0

package/src/confine.ts

@@ -0,0 +1,350 @@
+// Filesystem confinement for an agent's own tools.
+//
+// Scripts already run in containers. The agent's *built-in* tools —
+// Read/Write/Edit/Glob/Grep and friends — do not: they execute in the server
+// process with its full permissions. A run proved this is not theoretical: an
+// agent told to write `outputs/SHIPPED.txt` created it two directories up and
+// invented a whole phantom workspace on the way.
+//
+// The boundary is the WORKSPACE, not the agent. Agents in one workspace are a
+// team — a reviewer legitimately reads what the writer produced — while the
+// workspace is the isolation unit for everything else in the platform, so it
+// is the honest place to draw the line.
+//
+// Inside that boundary, three things are still off limits:
+//   · secrets.json — the encrypted store; an agent gets secrets as env vars,
+//     never as a file it can exfiltrate wholesale
+//   · runs/ — the run journal is the audit trail, and a step that can rewrite
+//     its own history makes every other guarantee unverifiable
+//   · index.md and log.md inside a knowledge/ or memory/ bundle — generated by
+//     the platform on every write. An agent scribbling on one would be undone
+//     by the next syncBundleFor, but until then the index says whatever it was
+//     told to say, and log.md is provenance for the same reason runs/ is.
+//
+// There is no curated index beside the generated one. A bundle has exactly the
+// two reserved files OKF defines, and both are generated.
+//
+// The bundle scoping matters. An earlier draft denied any index.md anywhere,
+// which would have blocked an agent writing outputs/index.md — a perfectly
+// ordinary deliverable — so the rule names the two directories it applies to.
+
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * A path with its symlinks resolved, as far as it exists.
+ *
+ * Both sides of the containment check have to be resolved the same way or the
+ * comparison is between two spellings of one place. On macOS `/var` is a
+ * symlink to `/private/var`, so a workspace under a system temp directory was
+ * handed to the runtime as `/var/folders/…` while every path the agent
+ * produced came back as `/private/var/folders/…`. `path.relative` then said
+ * `..`, and the agent was told its own workspace was outside the workspace —
+ * on every write, for the whole run, while the run still reported success
+ * because the agent gave up politely.
+ *
+ * Falls back a level at a time because the path may not exist yet: a Write
+ * creating a file needs the directory resolved, not the file.
+ */
+function real(p: string): string {
+  try {
+    return fs.realpathSync.native(p);
+  } catch {
+    const parent = path.dirname(p);
+    return parent === p ? p : path.join(real(parent), path.basename(p));
+  }
+}
+
+/** Tool argument names that carry a filesystem path. */
+const PATH_KEYS = [
+  "file_path",
+  "path",
+  "notebook_path",
+  "filePath",
+  "edits", // NotebookEdit-style payloads are checked via file_path too
+];
+
+const DENIED_WITHIN = [
+  /(^|\/)secrets\.json$/,
+  /(^|\/)runs(\/|$)/,
+];
+
+/**
+ * Generated, and therefore not an agent's to edit — but very much an agent's
+ * to read.
+ *
+ * These were denied outright, and a run proved what that costs: an agent told
+ * to start from the index asked for `knowledge/index.md`, was refused, and
+ * spent a turn recovering. The index is the navigational artifact the whole
+ * progressive-disclosure design rests on; refusing to let a reader open it is
+ * the opposite of the intent. The reason they are protected is that a
+ * generated file an agent can edit is one that can lie — which is an argument
+ * about writing, and only about writing.
+ */
+const READ_ONLY_WITHIN = [/(^|\/)(knowledge|memory)\/(.*\/)?(index|log)\.md$/];
+
+export interface ConfineVerdict {
+  ok: boolean;
+  reason?: string;
+  /** Rewritten tool input, when a virtual prefix was expanded. */
+  updatedInput?: Record<string, unknown>;
+}
+
+export interface Roots {
+  /** The agent's own directory — relative paths resolve from here. */
+  agentDir: string;
+  /** The workspace: the read/write boundary. */
+  workspaceRoot: string;
+  /** The account library: readable, never writable. */
+  libraryRoot: string;
+}
+
+// Skills are announced to the agent with virtual prefixes — `workspace/skills/…`
+// for the workspace's, `library/skills/…` for the account's — because a skill
+// at either scope lives outside the agent's own folder. Symlinking them in
+// was tried and reverted: it recursed into the workspace's own file listing.
+// Expanding the prefix here instead keeps one honest path per skill, with no
+// duplication on disk.
+// Two prefixes, named after the two scopes above an agent. There used to be
+// three — `workspace/` meant the workspace root while `shared/` meant the
+// workspace's *scripts*, which is exactly the kind of near-synonym that gets
+// mis-typed. The old spellings still resolve so nothing existing breaks.
+const VIRTUAL = [
+  { prefix: "account/", root: (r: Roots) => r.libraryRoot, readOnly: true },
+  { prefix: "workspace/", root: (r: Roots) => r.workspaceRoot, readOnly: false },
+  // legacy, still accepted
+  { prefix: "library/", root: (r: Roots) => r.libraryRoot, readOnly: true },
+  { prefix: "workspace/", root: (r: Roots) => r.workspaceRoot, readOnly: false },
+];
+
+const WRITE_TOOLS = new Set(["Write", "Edit", "MultiEdit", "NotebookEdit"]);
+
+// Only the built-in filesystem tools get path checks. foldrun's own MCP tools
+// are already confined at their own layer — script paths by resolveRunPath,
+// APIs by their declared base URL — and their arguments are not filesystem
+// paths at all: `call_<api>` takes a *URL* path like "/uuid", which this
+// check would otherwise reject as an escape.
+const FS_TOOLS = new Set([
+  "Read",
+  "Write",
+  "Edit",
+  "MultiEdit",
+  "NotebookEdit",
+  "NotebookRead",
+  "Glob",
+  "Grep",
+  "LS",
+]);
+
+export const isFilesystemTool = (toolName: string) => FS_TOOLS.has(toolName);
+
+/**
+ * The path the agent probably meant. Most escapes are one of three guesses —
+ * an invented `/tmp/outputs/…`, an absolute spelling of a workspace
+ * directory, or a directory a tool made outside the workspace — and a
+ * refusal that names the correction is taken on the next turn, where a
+ * generic one is followed by two more wrong guesses. Nothing here is
+ * enforced; it is advice in the error text.
+ */
+export function suggestPath(raw: string): string {
+  const posix = raw.split(path.sep).join("/");
+  const m = posix.match(/(?:^|\/)(outputs|storage|state|memory|knowledge)\/(.+)$/);
+  if (m) {
+    const [, dir, rest] = m;
+    return dir === "outputs"
+      ? `Did you mean outputs/${rest} (relative to your agent directory)?`
+      : `Did you mean workspace/${dir}/${rest}?`;
+  }
+  if (/^\/tmp\//.test(posix)) {
+    return (
+      `There is no /tmp for you. If a tool cloned or built something there, reach it through that tool ` +
+      `(for example its read or find action); scratch files go to outputs/.`
+    );
+  }
+  return `Use a path relative to your agent directory, or workspace/<dir>/… for the workspace root (workspace/storage/, workspace/state/).`;
+}
+
+/** Expand a virtual prefix to a real absolute path, or null if it has none. */
+export function expandVirtual(raw: string, roots: Roots): { abs: string; readOnly: boolean } | null {
+  for (const v of VIRTUAL) {
+    if (raw.startsWith(v.prefix)) {
+      return { abs: path.resolve(v.root(roots), raw.slice(v.prefix.length)), readOnly: v.readOnly };
+    }
+  }
+  return null;
+}
+
+export function checkPaths(
+  toolName: string,
+  input: Record<string, unknown>,
+  roots: Roots,
+): ConfineVerdict {
+  const workspace = real(path.resolve(roots.workspaceRoot));
+  const library = real(path.resolve(roots.libraryRoot));
+  const isWrite = WRITE_TOOLS.has(toolName);
+  let rewritten: Record<string, unknown> | undefined;
+
+  // Grep's `pattern` is a REGEX, not a location — Grep says where to look
+  // with `path`. Checking it as a path denied an agent searching for the
+  // literal text "/dev/null", reporting a workspace escape for a string it
+  // wanted to find inside the workspace. Glob's `pattern` really is a path
+  // shape, so it stays checked.
+  const keys = [...PATH_KEYS, "glob", ...(toolName === "Grep" ? [] : ["pattern"])];
+  for (const key of keys) {
+    const raw = input[key];
+    if (typeof raw !== "string" || !raw.trim()) continue;
+    // Glob patterns and grep's file filter are only paths when anchored.
+    if ((key === "glob" || key === "pattern") && !raw.startsWith("/") && !expandVirtual(raw, roots)) {
+      continue;
+    }
+
+    const virtual = expandVirtual(raw, roots);
+    const abs = real(virtual ? virtual.abs : path.resolve(roots.agentDir, raw));
+
+    // Knowledge is given, not learned: an agent that rewrites the price list
+    // it was handed has corrupted its own source of truth. What it discovers
+    // goes to memory/, which it owns.
+    if (isWrite && /(^|\/)knowledge\//.test(abs.split(path.sep).join("/"))) {
+      return {
+        ok: false,
+        reason:
+          `${toolName} was denied: knowledge/ is reference material maintained by people, not by ` +
+          `you. If you learned something new, write it to memory/ instead.`,
+      };
+    }
+
+    if (virtual?.readOnly && isWrite) {
+      return {
+        ok: false,
+        reason:
+          `${toolName} was denied: "${raw}" is in the shared library, which is read-only from a ` +
+          `run. Change it in the dashboard under Shared, or write your own copy in this workspace.`,
+      };
+    }
+
+    const inWorkspace = !path.relative(workspace, abs).startsWith("..");
+    const inLibrary = !path.relative(library, abs).startsWith("..");
+    if (!inWorkspace && !inLibrary) {
+      return {
+        ok: false,
+        reason:
+          `${toolName} was denied: "${raw}" is outside this workspace. Agents may only read and ` +
+          `write inside their own workspace. ${suggestPath(raw)}`,
+      };
+    }
+
+    const within = path.relative(inLibrary ? library : workspace, abs).split(path.sep).join("/");
+    if (DENIED_WITHIN.some((re) => re.test(within))) {
+      return {
+        ok: false,
+        reason:
+          `${toolName} was denied: "${raw}" is a protected platform file. Secrets reach you as ` +
+          `environment variables, and the run journal is not yours to read or rewrite.`,
+      };
+    }
+
+    if (isWrite && READ_ONLY_WITHIN.some((re) => re.test(within))) {
+      return {
+        ok: false,
+        reason:
+          `${toolName} was denied: "${raw}" is generated from the files around it and will be ` +
+          `rewritten on the next write. Read it freely — to change what it says, change a ` +
+          `concept file instead.`,
+      };
+    }
+
+    // Hand the real path back to the tool, so the virtual prefix the prompt
+    // advertises is one the agent can actually open.
+    if (virtual) rewritten = { ...(rewritten ?? input), [key]: abs };
+  }
+
+  return { ok: true, updatedInput: rewritten };
+}
+
+// A shell can defeat any argument-level path check, so Bash is handled
+// separately: it runs under the SDK sandbox, and these patterns are a second
+// layer that catches the obvious escapes with a clear message rather than a
+// confusing sandbox error.
+const BASH_ESCAPES = [
+  /\.\.\/\.\.\/\.\.\/\.\.\/\.\.\//, // five levels up leaves even the account
+  /(^|[\s;|&(<>])cd\s+(\/|~)/, // cd to an absolute path or home
+  // `~` was guarded only for `cd`, so `cat ~/.ssh/id_rsa` and
+  // `cp ~/.aws/credentials .` walked straight past — the exact "obvious
+  // escape" this layer exists to name before the sandbox does.
+  /(^|[\s;|&(<>=:"'])~\//, // a home-relative path, whatever the command
+  /(^|[\s;|&(<>])[a-z_]+\s+\/(etc|root|home|Users|var|proc|dev)\b/, // absolute system paths
+  /secrets\.json/,
+  /\.secret-key/,
+  // Don't let a command *print* a credential out — but only that. This used
+  // to match any reference to a secret env var, which denied the entire
+  // point of secrets: `ssh -i "$SSH_KEY"`, `curl -H "Authorization: $TOKEN"`
+  // and `sshpass -e ssh …` all use a credential without emitting it, and all
+  // were being refused. Now only an output builtin fronting the variable is
+  // blocked; the journal redaction layer is the backstop for the rest.
+  /\b(echo|printf|print|cat|head|tail|env|printenv)\b[^\n|;&]*\$\{?[A-Z_]*(TOKEN|KEY|SECRET|PASSWORD)/,
+];
+
+/**
+ * Shapes that modify a file, as opposed to reading one.
+ *
+ * Bash cannot be checked the way a tool call can — there is no path argument,
+ * only a string — so the protections checkPaths applies to Write and Edit have
+ * to be recognised here from the command's shape. That is why `knowledge/` is
+ * matched only alongside one of these: reading the price list is the entire
+ * reason it exists, and a blanket rule would have banned `cat`.
+ */
+const WRITES_TO_A_FILE =
+  /(>>?|\btee\b|\bsed\b[^]*?\s-i\b|\b(rm|mv|cp|truncate|dd|install|ln|chmod|chown|mkdir|rmdir|touch)\b)/;
+
+/** Protections that mirror checkPaths, per command segment. */
+const PROTECTED_BASH: { re: RegExp; writeOnly: boolean; reason: string }[] = [
+  {
+    re: /(^|[\s'"(/])knowledge\//,
+    writeOnly: true,
+    reason:
+      "knowledge/ is reference material maintained by people, not by you. If you learned " +
+      "something new, write it to memory/ instead.",
+  },
+  {
+    // Not write-only: checkPaths denies reading the journal too, and a rule
+    // that differs by tool is a rule an agent can shop around for.
+    re: /(^|[\s'"(/])runs(\/|$)/,
+    writeOnly: false,
+    reason:
+      "the run journal is the audit trail for this run, and is not yours to read or rewrite.",
+  },
+  {
+    re: /(^|[\s'"(/])(knowledge|memory)\/(\S*\/)?(index|log)\.md/,
+    // Write-only, matching checkPaths. A rule that differs by tool is a rule
+    // an agent can shop around for — and reading the index is the point of it.
+    writeOnly: true,
+    reason:
+      "index.md and log.md are generated from the files around them — write the concept file " +
+      "instead.",
+  },
+];
+
+export function checkBash(command: string): ConfineVerdict {
+  for (const re of BASH_ESCAPES) {
+    if (re.test(command)) {
+      return {
+        ok: false,
+        reason:
+          `Bash was denied: this command reaches outside the workspace. Work with paths relative ` +
+          `to your agent directory.`,
+      };
+    }
+  }
+
+  // Per segment, so `cat knowledge/prices.md && echo done` is judged on the
+  // part that touches the path rather than on the whole line.
+  for (const segment of command.split(/[;|&]+|\n/)) {
+    if (!segment.trim()) continue;
+    const writes = WRITES_TO_A_FILE.test(segment);
+    for (const rule of PROTECTED_BASH) {
+      if (rule.writeOnly && !writes) continue;
+      if (rule.re.test(segment)) return { ok: false, reason: `Bash was denied: ${rule.reason}` };
+    }
+  }
+  return { ok: true };
+}

package/src/container.ts

@@ -0,0 +1,220 @@
+// Container execution for scripts.
+//
+// The isolation boundary is the run: one container image per runtime
+// declaration (keyed by the same fingerprint the host path uses), and every
+// script call in a run executes inside a container from that image with the
+// agent's directory mounted. Scripts therefore cannot read other tenants'
+// data, the key file, or anything else on the host.
+//
+// Falls back to host execution when Docker isn't available, so local
+// development keeps working with zero configuration.
+
+import fs from "node:fs";
+import path from "node:path";
+import { dataRoot } from "./paths.ts";
+import { spawnSync, spawn } from "node:child_process";
+import type { RuntimeSpec } from "./runtime.ts";
+import { fingerprint } from "./runtime.ts";
+
+const BUILD_TIMEOUT_MS = 600_000;
+const IMAGE_PREFIX = "foldrun-runtime";
+
+// Any Docker-compatible CLI works — Docker Engine, colima, Podman, nerdctl,
+// OrbStack. Copying files in and out (rather than bind-mounting) is what
+// makes that portability real: no host path has to be shared with a VM.
+const CLI = process.env.FOLDRUN_CONTAINER_CLI ?? "docker";
+
+// "sandbox" means "run the script directly in whatever environment this step
+// is already isolated by" — the run pod under FOLDRUN_RUN_ISOLATION=k8s, or
+// the local process on a laptop. It was called "host", which read as "on the
+// platform's own machine" and made a correct, isolated setup look like a
+// tenant escape to anyone reading a run trace.
+export type Executor = "docker" | "sandbox";
+
+let cachedAvailability: boolean | null = null;
+
+export function dockerAvailable(): boolean {
+  if (process.env.FOLDRUN_EXECUTOR === "host" || process.env.FOLDRUN_EXECUTOR === "sandbox") return false;
+  if (cachedAvailability !== null) return cachedAvailability;
+  const res = spawnSync(CLI, ["info", "--format", "{{.ServerVersion}}"], {
+    encoding: "utf8",
+    timeout: 15_000,
+  });
+  cachedAvailability = res.status === 0;
+  return cachedAvailability;
+}
+
+export function chooseExecutor(): Executor {
+  return dockerAvailable() ? "docker" : "sandbox";
+}
+
+export function imageTag(spec: RuntimeSpec | null): string {
+  return `${IMAGE_PREFIX}:${spec ? fingerprint(spec) : "base"}`;
+}
+
+function imageExists(tag: string): boolean {
+  return spawnSync(CLI, ["image", "inspect", tag], { timeout: 20_000 }).status === 0;
+}
+
+// A minimal image carrying just the declared runtimes and packages.
+function dockerfileFor(spec: RuntimeSpec | null): string {
+  const wantsNode = spec ? spec.node !== undefined || spec.npm.length > 0 : false;
+  const pyVersion = typeof spec?.python === "string" ? spec.python : "3.12";
+
+  const lines: string[] = [];
+  if (wantsNode && !spec?.packages.length && spec?.python === undefined) {
+    lines.push("FROM node:22-slim");
+  } else {
+    lines.push(`FROM python:${pyVersion}-slim`);
+    if (wantsNode) {
+      lines.push(
+        "RUN apt-get update && apt-get install -y --no-install-recommends nodejs npm && rm -rf /var/lib/apt/lists/*",
+      );
+    }
+  }
+
+  if (spec?.packages.length) {
+    lines.push(`RUN pip install --no-cache-dir ${spec.packages.map((p) => `'${p}'`).join(" ")}`);
+  }
+  if (spec?.npm.length) {
+    lines.push("WORKDIR /opt/npm");
+    lines.push(`RUN npm install --no-fund --no-audit ${spec.npm.map((p) => `'${p}'`).join(" ")}`);
+    lines.push("ENV NODE_PATH=/opt/npm/node_modules");
+  }
+
+  // Scripts run as a non-root user with no write access outside the mount.
+  lines.push("RUN useradd -m -u 10001 agent");
+  lines.push("USER agent");
+  lines.push("WORKDIR /workspace");
+  return lines.join("\n") + "\n";
+}
+
+export interface ImageResult {
+  tag: string;
+  built: boolean;
+  error: string | null;
+  log: string[];
+}
+
+export function ensureImage(spec: RuntimeSpec | null): ImageResult {
+  const tag = imageTag(spec);
+  if (imageExists(tag)) return { tag, built: false, error: null, log: [`image ${tag}: cached`] };
+
+  // dataRoot() may not exist yet on a brand-new install or a fresh workspace
+  // whose first-ever step is a script tool — mkdtemp does not create parents,
+  // so without this the first script build dies with ENOENT and the whole run
+  // fails on nothing the author did wrong.
+  fs.mkdirSync(dataRoot(), { recursive: true });
+  const dir = fs.mkdtempSync(path.join(dataRoot(), ".build-"));
+  try {
+    fs.writeFileSync(path.join(dir, "Dockerfile"), dockerfileFor(spec));
+    const res = spawnSync(CLI, ["build", "-q", "-t", tag, dir], {
+      encoding: "utf8",
+      timeout: BUILD_TIMEOUT_MS,
+    });
+    if (res.status !== 0) {
+      return {
+        tag,
+        built: false,
+        error: `image build failed: ${`${res.stderr ?? ""}`.slice(-400)}`,
+        log: [],
+      };
+    }
+    return { tag, built: true, error: null, log: [`image ${tag}: built`] };
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+export interface ContainerRunOptions {
+  /** Host directory mounted at /workspace — the agent's own folder. */
+  agentDir: string;
+  /** Extra read-only mounts: host path → container path. */
+  readOnly?: Record<string, string>;
+  image: string;
+  argv: string[]; // command inside the container
+  env: Record<string, string>;
+  /** Only when the tool.md set one — the platform has no clock of its own. */
+  timeoutMs?: number;
+  /** Allow outbound network (agents that declared APIs need it). */
+  network: boolean;
+  maxOutput: number;
+}
+
+// Files are copied in and out rather than bind-mounted. Bind mounts need the
+// host path to be inside Docker's shared-paths configuration, which fails
+// silently (the mount appears empty) on Docker Desktop for directories it
+// isn't allowed to share. Copying is what CI systems do, needs no host
+// configuration, and has the side benefit that a script cannot corrupt the
+// source tree — only the copy it was given.
+export async function runInContainer(
+  opts: ContainerRunOptions,
+): Promise<{ code: number | null; out: string }> {
+  const docker = (args: string[], timeout = 60_000) =>
+    spawnSync(CLI, args, { encoding: "utf8", timeout });
+
+  const createArgs = [
+    "create",
+    "-i",
+    "--workdir",
+    "/workspace",
+    // Guard rails: no privilege escalation, bounded CPU/memory/processes.
+    "--security-opt",
+    "no-new-privileges",
+    "--cap-drop",
+    "ALL",
+    "--pids-limit",
+    "256",
+    "--memory",
+    "1g",
+    "--cpus",
+    "1",
+  ];
+  if (!opts.network) createArgs.push("--network", "none");
+  for (const [k, v] of Object.entries(opts.env)) createArgs.push("-e", `${k}=${v}`);
+  createArgs.push(opts.image, ...opts.argv);
+
+  const created = docker(createArgs);
+  if (created.status !== 0) {
+    return { code: null, out: `container create failed: ${(created.stderr ?? "").slice(-300)}` };
+  }
+  const cid = (created.stdout ?? "").trim();
+
+  try {
+    // The agent's own directory becomes /workspace…
+    const copied = docker(["cp", `${opts.agentDir}/.`, `${cid}:/workspace`], 120_000);
+    if (copied.status !== 0) {
+      return { code: null, out: `copy in failed: ${(copied.stderr ?? "").slice(-300)}` };
+    }
+    // …and any shared directories land at their declared paths.
+    for (const [host, mount] of Object.entries(opts.readOnly ?? {})) {
+      if (fs.existsSync(host)) docker(["cp", `${host}/.`, `${cid}:${mount}`], 120_000);
+    }
+
+    const result = await new Promise<{ code: number | null; out: string }>((resolve) => {
+      const child = spawn(CLI, ["start", "-a", cid], { timeout: opts.timeoutMs });
+      let out = "";
+      const append = (chunk: Buffer) => {
+        if (out.length < opts.maxOutput) out += chunk.toString();
+      };
+      child.stdout.on("data", append);
+      child.stderr.on("data", append);
+      child.on("error", (err) => resolve({ code: null, out: `container failed: ${err.message}` }));
+      child.on("close", (code) =>
+        resolve({
+          code,
+          out:
+            out.length > opts.maxOutput
+              ? `${out.slice(0, opts.maxOutput)}\n…[truncated]`
+              : out || "(no output)",
+        }),
+      );
+    });
+
+    // Bring deliverables back so outputs/ behaves the same either way.
+    docker(["cp", `${cid}:/workspace/outputs/.`, path.join(opts.agentDir, "outputs")], 120_000);
+    return result;
+  } finally {
+    docker(["rm", "-f", cid], 30_000);
+  }
+}