@foldrun/core 0.6.0 → 0.7.0

package/src/store.ts

@@ -20,6 +20,7 @@
 //
 // An account is a named directory (per OKF: tenancy is a hosting concern).
 
+import { expandPlatformVars } from "./host-env.ts";
 import type { BrowserPodOutcome } from "./browser-pod.ts";
 import fs from "node:fs";
 import path from "node:path";
@@ -57,7 +58,7 @@ import {
 } from "./okf.ts";
 import { readTransport, KINDS } from "./kinds.ts";
 import { providerPreset, looksOpenAiShaped, PROTECTED_PARAMS, type WireFormat, type AuthShape } from "./providers.ts";
-import { starterFiles, accountFiles } from "./starter.ts";
+import { starterFiles, accountFiles, blankWorkspaceFiles } from "./starter.ts";
 import { trimSlashes, MAX_EDITABLE_FILE } from "./paths.ts";
 
 // Where workspaces live. The hosted app keeps many under data/; the CLI runs
@@ -317,6 +318,19 @@ export function assertCanonicalCase(rel: string) {
 // fire (trigger-log.ts). Before it was listed here every deploy erased it.
 export const PLATFORM_FILES = ["secrets.json", "hooks.json", "hook-deliveries.jsonl", ".repo.json", "trigger-log.jsonl"];
 
+// The agent engine's own home files. Each step's sandbox runs the Claude
+// Agent SDK — the engine, whatever model answers — with its home in the
+// agent's folder, and the engine writes its settings (.claude.json, its
+// backups), plugin caches and the full transcript of every session
+// (.claude/projects/*.jsonl) there. Nothing in foldrun reads them. Copied
+// back after every step, they had piled up to 5,274 files and 19 MB in one
+// agent's folder on the box by 6 Oct 2026, carried every past conversation
+// into every sandbox, and their clashing rewrites were the "write-back
+// conflict on .claude.json" lines (and the big merges) of that day. A
+// workspace's own .claude/agents/*.md — Claude Code subagents an author
+// writes, imported as agents — sits at the workspace root and is untouched.
+const ENGINE_HOME_RE = /^agents\/[^/]+\/\.claude([./]|$)/;
+
 /** True for anything the platform, not the author or the agent, writes. */
 export function isPlatformPath(rel: string): boolean {
   const norm = rel.replaceAll("\\", "/");
@@ -325,6 +339,7 @@ export function isPlatformPath(rel: string): boolean {
   // are the vault, as far as anything outside the platform is concerned.
   if (/(^|\/)secrets\.json\./.test(norm)) return true;
   if (norm === "trigger-log.jsonl.tmp") return true;
+  if (ENGINE_HOME_RE.test(norm)) return true;
   return norm === "runs" || norm.startsWith("runs/") || norm === ".foldrun" || norm.startsWith(".foldrun/");
 }
 
@@ -625,6 +640,27 @@ export function toolIsOutward(data: Record<string, unknown>): boolean {
   return data.outward === true;
 }
 
+/** How much of a tool.md body rides to the model with the tool. */
+export const TOOL_GUIDE_MAX = 6000;
+
+/**
+ * The prose under a tool.md's frontmatter: how to call it, what it refuses,
+ * what its output means. Only `description:` used to reach the model, so
+ * agents invented what the body documented (5 Oct 2026). The fenced program
+ * of a single-file tool is code, not guidance, and stays out.
+ */
+export function toolGuide(body: string | undefined, inlineProgram = false): string | undefined {
+  if (!body) return undefined;
+  let text = body.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, "");
+  // Only a single-file tool's program is cut; in a `run:` tool every fenced
+  // block is an example of a call, which is exactly what the model needs.
+  const inline = inlineProgram ? fencedCodeBlock(text) : null;
+  if (inline) text = text.slice(0, inline.start) + text.slice(inline.end);
+  text = text.trim();
+  if (!text) return undefined;
+  return text.length > TOOL_GUIDE_MAX ? `${text.slice(0, TOOL_GUIDE_MAX)}\n\n[the rest of tool.md is cut here]` : text;
+}
+
 export function parseToolDef(data: Record<string, unknown>, fallbackName: string, body?: string): ToolDef | null {
   const name = typeof data.name === "string" ? data.name : fallbackName;
   // `transport:`, or a legacy `type: http|script|mcp` from before `type:` meant
@@ -659,16 +695,24 @@ export function parseToolDef(data: Record<string, unknown>, fallbackName: string
     };
   }
   if (kind === "script") {
+    // `guide` is the body's, never the frontmatter's: an author's `guide:`
+    // would otherwise ride to the model in place of the manual.
+    if ("guide" in data) { data = { ...data }; delete data.guide; }
     // The program is a run: path, or the file's own fenced code block — the
     // single-file form, which is what lets a script tool read and edit like
     // every other markdown document.
-    if (typeof data.run === "string") return { kind: "script", name, spec: { ...data, name } };
+    if (typeof data.run === "string") {
+      const guide = toolGuide(body);
+      return { kind: "script", name, spec: { ...data, name, ...(guide ? { guide } : {}) } };
+    }
     const inline = body ? fencedCode(body) : null;
     if (!inline) return null;
-    return { kind: "script", name, spec: { ...data, name, code: inline.code, codeExt: inline.ext } };
+    const guide = toolGuide(body, true);
+    return { kind: "script", name, spec: { ...data, name, code: inline.code, codeExt: inline.ext, ...(guide ? { guide } : {}) } };
   }
   const [spec] = parseApis([{ ...data, name }]);
-  return spec ? { kind: "http", name, spec } : null;
+  const guide = toolGuide(body);
+  return spec ? { kind: "http", name, spec: guide ? { ...spec, guide } : spec } : null;
 }
 
 /**
@@ -864,6 +908,8 @@ export interface ApiSpec {
   name: string;
   base: string;
   description: string;
+  /** The tool.md body, for the model (see toolGuide). */
+  guide?: string;
   headers: Record<string, string>; // values may contain ${SECRET_NAME}
   query: Record<string, string>; // always-appended query params (e.g. api keys)
   methods: string[]; // allowed HTTP methods; default GET only
@@ -1136,7 +1182,9 @@ export function parseApis(raw: unknown): ApiSpec[] {
     out.push({
       name: name.replace(/[^a-zA-Z0-9_]/g, "_"),
       ...(Number(e.timeout) > 0 ? { timeout: Number(e.timeout) } : {}),
-      base: trimSlashes(base),
+      // `${FOLDRUN_API_URL}` and `${FOLDRUN_PUBLIC_URL}` are the install's own
+      // addresses, filled here on the host so a desk never names one.
+      base: trimSlashes(expandPlatformVars(base)),
       description: typeof e.description === "string" ? e.description : "",
       headers: asRecordLocal(e.headers),
       query: asRecordLocal(e.query),
@@ -2875,6 +2923,12 @@ export function setWorkspaceDescription(tenant: string, workspace: string, descr
  * this copy still said `type: Agent` after the CLI's had moved to `kind:`,
  * so every workspace made from the dashboard was born in the old format.
  */
+/** What the dashboard's "Create workspace" makes: blank (blankWorkspaceFiles),
+ *  minus the laptop-only files, for the same reason as templateFiles. */
+export function blankTemplateFiles(workspace: string): DeployFile[] {
+  return blankWorkspaceFiles(workspace).filter((f) => f.path === "AGENTS.md" || IN_WORKSPACE_DIR.test(f.path));
+}
+
 export function templateFiles(workspace: string): DeployFile[] {
   // The starter minus what only matters on a laptop's disk: .gitignore
   // guards a local clone's secrets, but the hosted store never keeps
@@ -3388,7 +3442,23 @@ export function runOutputPath(
 
 export function readRun(tenant: string, workspace: string, runId: string): RunRecord | null {
   const p = runFilePath(tenant, workspace, runId);
-  return fs.existsSync(p) ? JSON.parse(fs.readFileSync(p, "utf8")) : null;
+  // EFS/NFS: writeRun() replaces this file by rename, so an open()+read()
+  // here can land on the just-unlinked inode and come back ESTALE (errno
+  // -116, surfaced by Node as "Unknown system error -116", syscall read).
+  // That isn't corruption — the next open() by path sees the committed new
+  // inode — so re-read a few times on ESTALE and rethrow anything else.
+  // (On dev-aws this surfaced as a CLI `--wait` call returning HTTP 500
+  // from waitForRun's poll while the run itself completed fine.)
+  const attempts = 5;
+  for (let i = 1; ; i++) {
+    try {
+      return fs.existsSync(p) ? JSON.parse(fs.readFileSync(p, "utf8")) : null;
+    } catch (e) {
+      const err = e as NodeJS.ErrnoException;
+      if ((err.code === "ESTALE" || err.errno === -116) && i < attempts) continue;
+      throw e;
+    }
+  }
 }
 
 export function writeRun(tenant: string, workspace: string, run: RunRecord) {
@@ -3706,6 +3776,12 @@ export function runCost(run: RunRecord): number {
  * fan-out template is a row in the trace rather than work — billing any of
  * them would charge for steps the customer can see never executed, which is
  * the fastest way to lose an argument about an invoice.
+ *
+ * Tokens count only for steps that ran on the platform's own model
+ * credential. A step on the account's own key (`credential` "provider: …" —
+ * a provider: block, or Settings → Model) was paid for at the provider, and
+ * billing it again here charged a BYOK customer twice. And a carried step's
+ * tokens were billed where it ran, like its compute.
  */
 export function runMeter(run: RunRecord): {
   tokenCostUsd: number;
@@ -3720,17 +3796,19 @@ export function runMeter(run: RunRecord): {
   let computeSecs = 0;
   let smallSecs = 0;
   let netBytes = 0;
+  let tokenCostUsd = 0;
   for (const s of run.steps) {
     if (s.status !== "completed" && s.status !== "failed") continue;
     // A carried step ran — and was billed — in the run it was carried from.
     if (s.carriedFrom) continue;
     steps += 1;
+    if (!(s.credential ?? "").startsWith("provider:")) tokenCostUsd += s.costUsd ?? 0;
     const secs = s.computeSecs ?? 0;
     computeSecs += secs;
     if (s.size === "small") smallSecs += secs;
     netBytes += (s.actual?.rxBytes ?? 0) + (s.actual?.txBytes ?? 0);
   }
-  return { tokenCostUsd: runCost(run), steps, computeSecs, smallSecs, netBytes };
+  return { tokenCostUsd, steps, computeSecs, smallSecs, netBytes };
 }
 
 /**

package/src/tool-names.ts

@@ -49,8 +49,10 @@ export const BUILTIN_TOOLS = new Set([
   "NotebookEdit", "TodoWrite",
 ]);
 
-/** The platform's own groups, served in-process rather than by the SDK. */
-export const PLATFORM_GROUPS = new Set(["search", "history", "desks", "ask"]);
+/** The platform's own groups, served in-process rather than by the SDK.
+ *  `install` is granted to every agent anyway (install-tool.ts); naming it is
+ *  accepted so a file that says so is not flagged. */
+export const PLATFORM_GROUPS = new Set(["search", "history", "desks", "ask", "install"]);
 
 /** 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. */

package/src/tool-test.ts

@@ -277,7 +277,14 @@ export async function testTool(
       });
     }
 
-    const names = Array.isArray(def.spec.secrets) ? def.spec.secrets.map(String) : [];
+    // The tool's own secrets, and the calling agent's `secrets:` — a run
+    // hands a script both. Testing gbp_read (whose agent, not the tool,
+    // declares GBP_OAUTH) said "GBP_OAUTH is not set" while every run of the
+    // same call worked (9 Oct 2026). Only an agent that grants the tool: the
+    // agents[0] stand-in above is there for its depth, not its keys.
+    const own = Array.isArray(def.spec.secrets) ? def.spec.secrets.map(String) : [];
+    const granting = caller && caller.ownTools.includes(def.name) ? caller.secrets : [];
+    const names = [...new Set([...own, ...granting])];
     const { env: stored, missing } = resolveSecrets(tenant, names, workspace);
     const live = await liveSecrets(stored, { tenant, workspace });
     if ("error" in live) {

package/src/zip.ts

@@ -0,0 +1,189 @@
+// A small zip reader and writer — enough for an export package, no dependency.
+//
+// What a person downloads from "Export" has to open with a double-click on
+// any machine, which is a zip, not a tarball. The format here is the plain
+// one: deflate or stored entries, a central directory, no zip64, no
+// encryption. The reader refuses anything outside that rather than guessing,
+// and it is written to be handed untrusted bytes: every offset is bounds
+// checked, sizes are capped before anything is inflated, and a path that
+// climbs out (`..`, absolute, a drive letter) is an error, not a skip.
+
+import zlib from "node:zlib";
+
+export interface ZipEntry {
+  path: string;
+  data: Buffer;
+}
+
+export class ZipError extends Error {}
+
+export interface UnzipLimits {
+  /** Most entries the archive may hold. */
+  maxEntries?: number;
+  /** Largest one file, uncompressed. */
+  maxFileBytes?: number;
+  /** All files together, uncompressed. */
+  maxTotalBytes?: number;
+}
+
+const CRC_TABLE = (() => {
+  const t = new Uint32Array(256);
+  for (let n = 0; n < 256; n++) {
+    let c = n;
+    for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+    t[n] = c >>> 0;
+  }
+  return t;
+})();
+
+export function crc32(buf: Buffer): number {
+  let c = 0xffffffff;
+  for (let i = 0; i < buf.length; i++) c = CRC_TABLE[(c ^ buf[i]!) & 0xff]! ^ (c >>> 8);
+  return (c ^ 0xffffffff) >>> 0;
+}
+
+/** DOS date and time for the entry headers. */
+function dosTime(d: Date): { time: number; date: number } {
+  return {
+    time: (d.getHours() << 11) | (d.getMinutes() << 5) | Math.floor(d.getSeconds() / 2),
+    date: (Math.max(0, d.getFullYear() - 1980) << 9) | ((d.getMonth() + 1) << 5) | d.getDate(),
+  };
+}
+
+export function zip(entries: ZipEntry[], now = new Date()): Buffer {
+  const { time, date } = dosTime(now);
+  const locals: Buffer[] = [];
+  const centrals: Buffer[] = [];
+  let offset = 0;
+  const seen = new Set<string>();
+  for (const e of entries) {
+    const name = safeEntryPath(e.path);
+    if (seen.has(name)) throw new ZipError(`duplicate entry: ${name}`);
+    seen.add(name);
+    const nameBuf = Buffer.from(name, "utf8");
+    const deflated = zlib.deflateRawSync(e.data);
+    const stored = deflated.length >= e.data.length;
+    const body = stored ? e.data : deflated;
+    const crc = crc32(e.data);
+
+    const local = Buffer.alloc(30);
+    local.writeUInt32LE(0x04034b50, 0);
+    local.writeUInt16LE(20, 4); // version needed
+    local.writeUInt16LE(0x0800, 6); // UTF-8 names
+    local.writeUInt16LE(stored ? 0 : 8, 8);
+    local.writeUInt16LE(time, 10);
+    local.writeUInt16LE(date, 12);
+    local.writeUInt32LE(crc, 14);
+    local.writeUInt32LE(body.length, 18);
+    local.writeUInt32LE(e.data.length, 22);
+    local.writeUInt16LE(nameBuf.length, 26);
+    local.writeUInt16LE(0, 28);
+    locals.push(local, nameBuf, body);
+
+    const central = Buffer.alloc(46);
+    central.writeUInt32LE(0x02014b50, 0);
+    central.writeUInt16LE(0x0314, 4); // made by: unix, 2.0
+    central.writeUInt16LE(20, 6);
+    central.writeUInt16LE(0x0800, 8);
+    central.writeUInt16LE(stored ? 0 : 8, 10);
+    central.writeUInt16LE(time, 12);
+    central.writeUInt16LE(date, 14);
+    central.writeUInt32LE(crc, 16);
+    central.writeUInt32LE(body.length, 20);
+    central.writeUInt32LE(e.data.length, 24);
+    central.writeUInt16LE(nameBuf.length, 28);
+    central.writeUInt32LE((0o100644 << 16) >>> 0, 38); // a regular file, rw-r--r--
+    central.writeUInt32LE(offset, 42);
+    centrals.push(central, nameBuf);
+
+    offset += local.length + nameBuf.length + body.length;
+  }
+  const cd = Buffer.concat(centrals);
+  const end = Buffer.alloc(22);
+  end.writeUInt32LE(0x06054b50, 0);
+  end.writeUInt16LE(entries.length, 8);
+  end.writeUInt16LE(entries.length, 10);
+  end.writeUInt32LE(cd.length, 12);
+  end.writeUInt32LE(offset, 16);
+  return Buffer.concat([...locals, cd, end]);
+}
+
+export function unzip(buf: Buffer, limits: UnzipLimits = {}): ZipEntry[] {
+  const maxEntries = limits.maxEntries ?? 2000;
+  const maxFile = limits.maxFileBytes ?? 1024 * 1024;
+  const maxTotal = limits.maxTotalBytes ?? 50 * 1024 * 1024;
+
+  // The end-of-central-directory record: within the last 22 + 65535 bytes.
+  let eocd = -1;
+  for (let i = buf.length - 22; i >= Math.max(0, buf.length - 22 - 0xffff); i--) {
+    if (buf.readUInt32LE(i) === 0x06054b50) {
+      eocd = i;
+      break;
+    }
+  }
+  if (eocd < 0) throw new ZipError("not a zip file");
+  const count = buf.readUInt16LE(eocd + 10);
+  const cdSize = buf.readUInt32LE(eocd + 12);
+  const cdOffset = buf.readUInt32LE(eocd + 16);
+  if (count === 0xffff || cdOffset === 0xffffffff) throw new ZipError("zip64 archives are not supported");
+  if (count > maxEntries) throw new ZipError(`too many files: ${count} (at most ${maxEntries})`);
+  if (cdOffset + cdSize > eocd) throw new ZipError("corrupt zip: central directory out of range");
+
+  const out: ZipEntry[] = [];
+  const seen = new Set<string>();
+  let total = 0;
+  let p = cdOffset;
+  for (let n = 0; n < count; n++) {
+    if (p + 46 > eocd || buf.readUInt32LE(p) !== 0x02014b50) throw new ZipError("corrupt zip: bad central directory entry");
+    const flags = buf.readUInt16LE(p + 8);
+    const method = buf.readUInt16LE(p + 10);
+    const crc = buf.readUInt32LE(p + 16);
+    const csize = buf.readUInt32LE(p + 20);
+    const usize = buf.readUInt32LE(p + 24);
+    const nameLen = buf.readUInt16LE(p + 28);
+    const extraLen = buf.readUInt16LE(p + 30);
+    const commentLen = buf.readUInt16LE(p + 32);
+    const localAt = buf.readUInt32LE(p + 42);
+    if (p + 46 + nameLen > eocd) throw new ZipError("corrupt zip: name out of range");
+    const rawName = buf.subarray(p + 46, p + 46 + nameLen).toString("utf8");
+    p += 46 + nameLen + extraLen + commentLen;
+
+    if (rawName.endsWith("/")) continue; // a directory entry
+    // macOS "Compress" adds these beside every file; they are not content.
+    if (/(^|\/)__MACOSX\//.test(rawName) || /(^|\/)\.DS_Store$/.test(rawName)) continue;
+    if (flags & 0x1) throw new ZipError(`${rawName}: encrypted entries are not supported`);
+    if (method !== 0 && method !== 8) throw new ZipError(`${rawName}: compression method ${method} is not supported`);
+    const name = safeEntryPath(rawName);
+    if (seen.has(name)) throw new ZipError(`duplicate entry: ${name}`);
+    seen.add(name);
+    if (usize > maxFile) throw new ZipError(`${name} is too large (${usize} bytes, at most ${maxFile})`);
+    total += usize;
+    if (total > maxTotal) throw new ZipError(`the files are too large together (more than ${maxTotal} bytes)`);
+
+    if (localAt + 30 > buf.length || buf.readUInt32LE(localAt) !== 0x04034b50) throw new ZipError(`${name}: corrupt local header`);
+    const start = localAt + 30 + buf.readUInt16LE(localAt + 26) + buf.readUInt16LE(localAt + 28);
+    if (start + csize > buf.length) throw new ZipError(`${name}: data out of range`);
+    const raw = buf.subarray(start, start + csize);
+    let data: Buffer;
+    try {
+      // maxOutputLength: the header's size is the attacker's to choose, so the
+      // inflate itself is capped too — a bomb stops here, not in memory.
+      data = method === 0 ? Buffer.from(raw) : zlib.inflateRawSync(raw, { maxOutputLength: maxFile + 1 });
+    } catch {
+      throw new ZipError(`${name}: could not be decompressed`);
+    }
+    if (data.length !== usize) throw new ZipError(`${name}: size does not match its header`);
+    if (crc32(data) !== crc) throw new ZipError(`${name}: checksum mismatch`);
+    out.push({ path: name, data });
+  }
+  return out;
+}
+
+/** A relative, forward-slash path that stays inside the archive's root. */
+function safeEntryPath(raw: string): string {
+  const p = raw.replaceAll("\\", "/");
+  if (p.startsWith("/") || /^[a-zA-Z]:/.test(p) || p.includes("\0")) throw new ZipError(`unsafe path: ${raw}`);
+  const parts = p.split("/").filter((s) => s !== "" && s !== ".");
+  if (parts.length === 0 || parts.some((s) => s === "..")) throw new ZipError(`unsafe path: ${raw}`);
+  return parts.join("/");
+}