@foldrun/core 0.5.0 → 0.7.0

package/dist/src/test-mode.js

@@ -18,7 +18,9 @@
 //     a test run; the env var says TEST_MODE_WITHHELD instead, so a script
 //     that forgot to check fails at the provider with an auth error
 //   - the write-back: state/ and storage/ go INTO the sandbox as usual and
-//     come out into runs/<id>/test-writes/ instead of the real directories
+//     come out into runs/<id>/test-writes/ instead of the real directories;
+//     the next step's copy has those writes laid over it (overlayTestWrites),
+//     so the run reads its own work and the workspace never sees it
 //
 // Nothing here weakens a live run: every function is a no-op unless the run
 // says `test: true`.
@@ -247,21 +249,27 @@ export function snapshotDivertedDirs(wsRoot) {
 }
 /** Undo a step's writes to the diverted directories, keeping each changed
  *  or new file under `to` by its workspace-relative path. Deletions are
- *  undone too — the original is put back. Returns what was set aside. */
-export function restoreDivertedDirs(wsRoot, before, to, note) {
+ *  undone too — the original is put back. `handed` is what the step was
+ *  given when that was more than the workspace (the run's earlier test
+ *  writes, laid over it): only what the step changed from THAT is its
+ *  write. Returns what was set aside. */
+export function restoreDivertedDirs(wsRoot, before, to, note, handed = before) {
     const now = snapshotDivertedDirs(wsRoot);
     const aside = [];
     for (const [rel, next] of now) {
-        const was = before.get(rel) ?? null;
-        if (was && was.equals(next))
-            continue;
-        const dest = path.join(to, rel);
-        fs.mkdirSync(path.dirname(dest), { recursive: true });
-        fs.writeFileSync(dest, next);
-        aside.push(rel);
-        note(rel, divertedSummary(rel, was, next));
-        if (was)
-            fs.writeFileSync(path.join(wsRoot, rel), was);
+        const given = handed.get(rel) ?? null;
+        if (!(given && given.equals(next))) {
+            const dest = path.join(to, rel);
+            fs.mkdirSync(path.dirname(dest), { recursive: true });
+            fs.writeFileSync(dest, next);
+            aside.push(rel);
+            note(rel, divertedSummary(rel, before.get(rel) ?? null, next));
+        }
+        const orig = before.get(rel);
+        if (orig) {
+            if (!orig.equals(next))
+                fs.writeFileSync(path.join(wsRoot, rel), orig);
+        }
         else
             fs.rmSync(path.join(wsRoot, rel), { force: true });
     }
@@ -275,6 +283,38 @@ export function restoreDivertedDirs(wsRoot, before, to, note) {
     }
     return aside;
 }
+/**
+ * A test run's later steps see what its earlier steps wrote. Those writes
+ * are kept under runs/<id>/test-writes/, never on the workspace, so each
+ * step's copy of the workspace gets them laid over it — otherwise a step
+ * reads the real files, and a flow that hands work on through storage/
+ * tests something no live run does: on 2026-10-03 a strata-desk test run's
+ * compiler wrote today's PASS report, and the mailer was handed the
+ * morning's FAIL one and refused. Times are kept, so a verify that asks
+ * whether a file is fresh answers for the step that wrote it. Returns the
+ * workspace-relative paths laid over.
+ */
+export function overlayTestWrites(wsCopy, from) {
+    const laid = [];
+    for (const dir of TEST_DIVERTED_DIRS) {
+        const root = path.join(from, dir);
+        if (!fs.existsSync(root))
+            continue;
+        for (const entry of fs.readdirSync(root, { recursive: true, withFileTypes: true })) {
+            if (!entry.isFile())
+                continue;
+            const abs = path.join(entry.parentPath, entry.name);
+            const rel = path.relative(from, abs).replaceAll("\\", "/");
+            const dest = path.join(wsCopy, rel);
+            fs.mkdirSync(path.dirname(dest), { recursive: true });
+            fs.copyFileSync(abs, dest);
+            const st = fs.statSync(abs);
+            fs.utimesSync(dest, st.atime, st.mtime);
+            laid.push(rel);
+        }
+    }
+    return laid;
+}
 /** `[test] ` in front of a headline, once. */
 export function testHeadline(summary) {
     return summary.startsWith("[test]") ? summary : `[test] ${summary}`;

package/dist/src/tool-names.d.ts

@@ -12,7 +12,9 @@ export declare const RETIRED_TOOLS: Record<string, string>;
  *  and a model provider's own search (`web: {search: zai}`) is the runtime's
  *  to swap in, not the author's to name. */
 export declare const BUILTIN_TOOLS: Set<string>;
-/** The platform's own groups, served in-process rather than by the SDK. */
+/** 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 declare const PLATFORM_GROUPS: Set<string>;
 /** 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/dist/src/tool-names.js

@@ -44,8 +44,10 @@ export const BUILTIN_TOOLS = new Set([
     "Read", "Write", "Edit", "MultiEdit", "Glob", "Grep", "Bash",
     "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. */
 export function isRuntimeTool(name) {

package/dist/src/tool-test.js

@@ -229,7 +229,14 @@ export async function testTool(tenant, workspace, def, input = {}) {
                 detail: `looked for ${file}\n\nThis is the commonest way to get a tool that silently never loads.`,
             });
         }
-        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/dist/src/zip.d.ts

@@ -0,0 +1,17 @@
+export interface ZipEntry {
+    path: string;
+    data: Buffer;
+}
+export declare 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;
+}
+export declare function crc32(buf: Buffer): number;
+export declare function zip(entries: ZipEntry[], now?: Date): Buffer;
+export declare function unzip(buf: Buffer, limits?: UnzipLimits): ZipEntry[];

package/dist/src/zip.js

@@ -0,0 +1,184 @@
+// 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 class ZipError extends Error {
+}
+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) {
+    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) {
+    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, now = new Date()) {
+    const { time, date } = dosTime(now);
+    const locals = [];
+    const centrals = [];
+    let offset = 0;
+    const seen = new Set();
+    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, limits = {}) {
+    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 = [];
+    const seen = new Set();
+    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;
+        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) {
+    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("/");
+}

package/index.ts

@@ -13,6 +13,7 @@
 export * from "./src/layout.ts";
 export * from "./src/paths.ts";
 export * from "./src/store.ts";
+export * from "./src/model-credential.ts";
 export * from "./src/starter.ts";
 export * from "./src/runner.ts";
 export * from "./src/okf.ts";
@@ -33,6 +34,8 @@ export * from "./src/linkable.ts";
 export * from "./src/refs.ts";
 export * from "./src/tool-names.ts";
 export * from "./src/history.ts";
+export * from "./src/zip.ts";
+export * from "./src/package.ts";
 export * from "./src/gitrepo.ts";
 export * from "./src/storage.ts";
 export * from "./src/secrets.ts";
@@ -42,6 +45,7 @@ export * from "./src/notify.ts";
 export * from "./src/webhook.ts";
 export * from "./src/approvals.ts";
 export * from "./src/deploy.ts";
+export * from "./src/agent-import.ts";
 export * from "./src/account.ts";
 export * from "./src/tar.ts";
 export * from "./src/git.ts";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foldrun/core",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Agents are just folders. The format, the runner, the checks.",
   "license": "Apache-2.0",
   "type": "module",

package/src/agent-import.ts

@@ -0,0 +1,154 @@
+// Bring an agent you already have into another workspace of the same account.
+//
+// A new workspace starts blank (blankWorkspaceFiles), and the agents worth
+// having in it are usually ones already written and tuned elsewhere — a
+// researcher from one desk, a reviewer from another. Copying them by hand
+// meant opening each file, and missing the skills and scripts that live in
+// the agent's own folder. This copies the folder: what the agent IS, never
+// what it has accumulated.
+//
+// Copied: agents/<name>/agent.md and everything authored beside it — its own
+// skills/, scripts/, knowledge/. Not copied: memory/ (what it learned in the
+// other workspace's runs), outputs/, state/, the step's workspace link, and
+// the SDK's .claude session files. A fresh copy starts with no lessons that
+// were about somebody else's desk.
+
+import fs from "node:fs";
+import path from "node:path";
+import matter from "gray-matter";
+import {
+  assertSafeName,
+  listWorkspaceFiles,
+  readWorkspaceFile,
+  writeWorkspaceFile,
+  workspaceDir,
+  workspaceTools,
+  listWorkspaces,
+} from "./store.ts";
+import { libraryDir, libraryTools } from "./library.ts";
+import { isRuntimeTool, toolEntryName } from "./tool-names.ts";
+import { discoverSkills } from "./runner.ts";
+import { listSecrets } from "./secrets.ts";
+
+export interface AgentImportResult {
+  /** The name the agent has in the target workspace. */
+  name: string;
+  /** Workspace-relative paths written. */
+  files: string[];
+  /** What the copy refers to that the target workspace does not have. The
+   *  import still happens: a missing secret is set in a minute, and refusing
+   *  would make the person copy the file by hand instead. */
+  warnings: string[];
+}
+
+/** An error the API layer turns into a status rather than a 500. */
+export class AgentImportError extends Error {
+  readonly status: number;
+  constructor(message: string, status: number) {
+    super(message);
+    this.status = status;
+  }
+}
+
+/** Accumulated or generated, not authored — never carried to another workspace. */
+const NOT_COPIED = /^agents\/[^/]+\/(memory|outputs|state|workspace|\.claude)(\/|$)|^agents\/[^/]+\/\.claude\.json$/;
+
+/** The files `importAgent` would copy, without writing anything. */
+export function agentSourceFiles(tenant: string, from: string, agent: string): string[] {
+  const prefix = `agents/${agent}/`;
+  return listWorkspaceFiles(tenant, from).filter((p) => p.startsWith(prefix) && !NOT_COPIED.test(p));
+}
+
+const list = (v: unknown): string[] =>
+  Array.isArray(v) ? v.map((x) => toolEntryName(x)).filter(Boolean) : typeof v === "string" && v.trim() ? [v.trim()] : [];
+
+export function importAgent(
+  tenant: string,
+  from: string,
+  agent: string,
+  to: string,
+  opts: { as?: string; by?: string } = {},
+): AgentImportResult {
+  assertSafeName(from, "workspace");
+  assertSafeName(to, "workspace");
+  assertSafeName(agent, "agent");
+  const name = opts.as?.trim() || agent;
+  assertSafeName(name, "agent");
+  const known = new Set(listWorkspaces(tenant).map((w) => w.name));
+  if (!known.has(from)) throw new AgentImportError(`no workspace called "${from}" in this account`, 404);
+  if (!known.has(to)) throw new AgentImportError(`no workspace called "${to}" in this account`, 404);
+  if (from === to && name === agent) {
+    throw new AgentImportError(`${agent} is already in ${to} — give the copy another name with "as"`, 409);
+  }
+
+  const files = agentSourceFiles(tenant, from, agent);
+  if (!files.includes(`agents/${agent}/agent.md`)) {
+    throw new AgentImportError(`no agent called "${agent}" in ${from}`, 404);
+  }
+  if (fs.existsSync(path.join(workspaceDir(tenant, to), "agents", name))) {
+    throw new AgentImportError(
+      `${to} already has an agent called "${name}" — import it under another name with "as"`,
+      409,
+    );
+  }
+
+  const written: string[] = [];
+  const message = `import agents/${agent} from ${from}${name !== agent ? ` as ${name}` : ""}`;
+  let front: Record<string, unknown> = {};
+  for (const src of files) {
+    let content = readWorkspaceFile(tenant, from, src);
+    const rel = src.slice(`agents/${agent}/`.length);
+    if (rel === "agent.md") {
+      front = matter(content).data as Record<string, unknown>;
+      // The folder is the name flows address; a `name:` that disagrees with
+      // it is the first thing check would complain about.
+      if (name !== agent) content = content.replace(/^(---\r?\n(?:[\s\S]*?\r?\n)?)name:[^\n]*$/m, `$1name: ${name}`);
+    }
+    const dest = `agents/${name}/${rel}`;
+    writeWorkspaceFile(tenant, to, dest, content, { ...(opts.by ? { by: opts.by } : {}), message });
+    written.push(dest);
+  }
+
+  return { name, files: written, warnings: missingFor(tenant, to, name, front) };
+}
+
+/** What the imported agent names that the target workspace cannot provide. */
+function missingFor(tenant: string, to: string, name: string, front: Record<string, unknown>): string[] {
+  const out: string[] = [];
+  const ws = workspaceDir(tenant, to);
+
+  const tools = { ...libraryTools(tenant), ...workspaceTools(tenant, to) };
+  const noTool = list(front.tools).filter((t) => !isRuntimeTool(t) && !tools[t]);
+  if (noTool.length) out.push(`tools not in ${to} or the account library: ${noTool.join(", ")} — import or add them under tools/`);
+
+  const skills = new Set<string>();
+  for (const [base, sub] of [
+    [path.join(ws, "agents", name), "skills"],
+    [ws, "skills"],
+    [ws, ".agents/skills"],
+    [libraryDir(tenant), "skills"],
+  ] as const) {
+    for (const s of discoverSkills(base, sub)) skills.add(s.name);
+  }
+  const noSkill = list(front.skills).filter((s) => !skills.has(s));
+  if (noSkill.length) out.push(`skills not in ${to} or the account library: ${noSkill.join(", ")}`);
+
+  const scripts = list(front.scripts).filter(
+    (s) =>
+      !fs.existsSync(path.join(ws, "agents", name, "scripts", s)) &&
+      !fs.existsSync(path.join(ws, "scripts", s)) &&
+      !fs.existsSync(path.join(libraryDir(tenant), "scripts", s)),
+  );
+  if (scripts.length) out.push(`scripts not in ${to}: ${scripts.join(", ")} — copy them into scripts/`);
+
+  let have: Set<string>;
+  try {
+    have = new Set(listSecrets(tenant, to).map((s) => s.name));
+  } catch {
+    have = new Set();
+  }
+  const noSecret = list(front.secrets).filter((s) => !have.has(s));
+  if (noSecret.length) out.push(`secrets not set for ${to}: ${noSecret.join(", ")} — add them with \`foldrun secrets set\` or Settings → Secrets`);
+
+  return out;
+}

package/src/api-tools.ts

@@ -299,7 +299,8 @@ function genericTool(api: ApiSpec, env: Record<string, string>, bucket: TokenBuc
       `Allowed methods: ${api.methods.join(", ")}. Provide only the path after the base URL. ` +
       `Authentication is added automatically — never ask the user for credentials.` +
       typed +
-      rateSentence(api),
+      rateSentence(api) +
+      (api.guide ? `\n\nHow to use it (from its tool.md):\n${api.guide}` : ""),
     {
       method: z.enum(api.methods as [string, ...string[]]).describe("HTTP method"),
       path: z.string().describe("Path appended to the base URL, e.g. /customers/123/campaigns"),
@@ -369,6 +370,17 @@ export function buildApiTools(
       continue;
     }
 
+    // A base still holding `${FOLDRUN_API_URL}` was not filled: this install
+    // has no public address configured (a laptop, usually). Say so rather
+    // than hand the model a URL that cannot resolve.
+    if (/\$\{[A-Z_]+\}/.test(api.base)) {
+      promptLines.push(
+        `- **${api.name}** — unavailable this run: its base \`${api.base}\` names a variable this ` +
+          `install does not set (FOLDRUN_API_URL or FOLDRUN_PUBLIC_URL). Report it as blocked.`,
+      );
+      continue;
+    }
+
     const typedNames: string[] = [];
     for (const op of ops) {
       tools.push(typedTool(api, op, env, bucket, log));
@@ -394,6 +406,9 @@ export function buildApiTools(
           `. Credentials are injected for you.${rateLine}`,
         ...listed,
         ...more,
+        // Typed-only (an `operations:` allowlist) has no generic tool whose
+        // description could carry the guide, so it rides here.
+        ...(!withGeneric && api.guide ? [`  How to use it (from its tool.md):\n${api.guide}`] : []),
       );
     } else {
       promptLines.push(

package/src/approvals.ts

@@ -356,24 +356,31 @@ export async function expireStaleGate(
  *
  * Only steps waiting on an event are released: a run that is also asking a
  * person a question keeps asking.
+ *
+ * `by` names who delivered it when that is known — a signed-in person or a
+ * key through the dashboard's approve route — and `step` releases one
+ * waiting step rather than all of them.
  */
 export async function deliverEvent(
   tenant: string,
   workspace: string,
   runId: string,
   payload: string,
+  opts: { by?: string; step?: number } = {},
 ): Promise<{ run: RunRecord; steps: number[] }> {
   const run = readRun(tenant, workspace, runId);
   if (!run) throw new ApprovalError("run not found", 404);
   const waiting = run.steps
     .map((s, i) => ({ s, i }))
-    .filter(({ s }) => s.status === "awaiting-approval" && s.waitFor === "event");
-  if (waiting.length === 0) throw new ApprovalError("this run is not waiting for an event", 409);
+    .filter(({ s, i }) => s.status === "awaiting-approval" && s.waitFor === "event" && (opts.step === undefined || opts.step === i));
+  if (waiting.length === 0) {
+    throw new ApprovalError(opts.step === undefined ? "this run is not waiting for an event" : `step ${opts.step} is not waiting for an event`, 409);
+  }
   for (const { s } of waiting) s.eventPayload = payload.slice(0, 20_000);
   writeRun(tenant, workspace, run);
   let decided: number[] = [];
   for (const { i } of waiting) {
-    const out = await decideApproval(tenant, workspace, runId, { decision: "approve", step: i, by: "by an external event" });
+    const out = await decideApproval(tenant, workspace, runId, { decision: "approve", step: i, by: opts.by ?? "by an external event" });
     decided = decided.concat(out.steps);
   }
   return { run: readRun(tenant, workspace, runId) ?? run, steps: decided };