@foldrun/core 0.4.0 → 0.6.0

package/src/language.ts

@@ -0,0 +1,62 @@
+// The language an agent works in — the same cascade as its clock, for the
+// same reason: a value written once at the level it belongs to, inherited
+// below it, and never a hardcoded default inside a tool.
+//
+// Prose in AGENTS.md reaches the model and nothing else. A search engine
+// asked in English answers in English whatever the agent was told, a
+// browser reports en-US to every page, a fetch sends no Accept-Language.
+// `language:` is what those read; the prompt sentence it adds is the small
+// part. English is the default, so nothing changes for an agent that never
+// says.
+
+export interface LanguageChoice {
+  /** BCP-47, normalised: `en`, `en-AU`, `fa`, `pt-BR`. */
+  language: string;
+  from: "agent" | "flow" | "workspace" | "account" | "env" | "default";
+  /** A level that wrote something unreadable, said once and skipped. */
+  lines: string[];
+}
+
+/** `en`, `en-AU`, `en_au`, ` FA-ir ` → `en`, `en-AU`, `en-AU`, `fa-IR`; anything else null. */
+export function normalizeLanguage(raw: unknown): string | null {
+  if (typeof raw !== "string") return null;
+  const m = /^([a-z]{2,3})(?:[-_]([a-z]{2}))?$/i.exec(raw.trim());
+  if (!m) return null;
+  return m[2] ? `${m[1].toLowerCase()}-${m[2].toUpperCase()}` : m[1].toLowerCase();
+}
+
+/** Null when unset (inherit) or readable; else the sentence check prints. */
+export function languageProblem(raw: unknown): string | null {
+  if (raw === undefined || raw === null || raw === "") return null;
+  if (normalizeLanguage(raw)) return null;
+  return `language: ${JSON.stringify(raw)} is not a language tag — write it like \`en\`, \`en-AU\` or \`fa\` (a two-letter language, and optionally a two-letter region).`;
+}
+
+export function resolveLanguage(
+  levels: { level: LanguageChoice["from"]; value: unknown }[],
+  env: Record<string, string | undefined> = process.env,
+): LanguageChoice {
+  const lines: string[] = [];
+  for (const { level, value } of levels) {
+    if (value === undefined || value === null || value === "") continue;
+    const tag = normalizeLanguage(value);
+    if (tag) return { language: tag, from: level, lines };
+    lines.push(`language: ${level} says ${JSON.stringify(value)}, which is not a language tag — using the next level`);
+  }
+  const fromEnv = normalizeLanguage(env.FOLDRUN_LANGUAGE);
+  if (fromEnv) return { language: fromEnv, from: "env", lines };
+  return { language: "en", from: "default", lines };
+}
+
+/** How a person would name it in a prompt: `fa-IR` → "Persian (Iran)". */
+export function languageName(tag: string): string {
+  try {
+    const [lang, region] = tag.split("-");
+    const names = new Intl.DisplayNames(["en"], { type: "language" });
+    const regions = new Intl.DisplayNames(["en"], { type: "region" });
+    const base = names.of(lang) ?? lang;
+    return region ? `${base} (${regions.of(region) ?? region})` : base;
+  } catch {
+    return tag;
+  }
+}

package/src/layout.ts

@@ -0,0 +1,228 @@
+// What shape is this folder?
+//
+// There are two shapes a foldrun tree on a laptop can have, and every command
+// has to answer the same question about the one it was pointed at.
+//
+//   flat                       account
+//   my-desk/                   my-account/
+//   ├── AGENTS.md              ├── AGENTS.md          ← account scope
+//   ├── agents/                ├── library/           ← shared by every workspace
+//   └── flows/                 └── workspaces/
+//                                  └── my-desk/
+//                                      ├── AGENTS.md
+//                                      ├── agents/
+//                                      └── flows/
+//
+// The second is the platform's own layout: `<data>/<account>/library` and
+// `<data>/<account>/workspaces/<name>` are exactly these directories with a
+// tenant directory around them. The first is what `foldrun init` made until
+// today, so it is what every existing user has, and it must keep working
+// forever — a folder shape is a file format.
+//
+// This module is the ONE place that decides. Everything else — the CLI's
+// commands, `accountDir`, `libraryDir` — asks here rather than testing for a
+// `workspaces` directory itself, because the last time that test was written
+// inline it was written as "is my parent called workspaces", which is true of
+// a real installation and of this layout and means something different in
+// each.
+//
+// Deliberately free of every other import: `paths.ts` needs it, and `paths.ts`
+// is what the rest of the codebase imports first.
+
+import fs from "node:fs";
+import path from "node:path";
+
+/** Where an account keeps its workspaces. `projects/` is the pre-rename name,
+ *  still read so an existing tree keeps working. */
+export const WORKSPACES_DIRS = ["workspaces", "projects"] as const;
+
+function isDir(p: string): boolean {
+  try {
+    return fs.statSync(p).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * A workspace is a directory holding `agents/` or `flows/`.
+ *
+ * Not AGENTS.md: an account root has one of those too, and a test that cannot
+ * tell the two apart is the bug this module exists to prevent.
+ */
+export function isWorkspaceDir(dir: string): boolean {
+  return isDir(path.join(dir, "agents")) || isDir(path.join(dir, "flows"));
+}
+
+/** `<dir>/workspaces` when `dir` is an account root, else null. */
+export function accountWorkspacesDir(dir: string): string | null {
+  for (const name of WORKSPACES_DIRS) {
+    const full = path.join(dir, name);
+    if (isDir(full)) return full;
+  }
+  return null;
+}
+
+/** The workspaces under an account root, by name, sorted. */
+export function listWorkspaceDirs(accountRoot: string): string[] {
+  const dir = accountWorkspacesDir(accountRoot);
+  if (!dir) return [];
+  try {
+    return fs
+      .readdirSync(dir)
+      .filter((n) => !n.startsWith("."))
+      .filter((n) => isDir(path.join(dir, n)))
+      .sort();
+  } catch {
+    return [];
+  }
+}
+
+export type LayoutKind = "account" | "workspace-in-account" | "flat" | "empty";
+
+export interface Layout {
+  /**
+   * `account` — an account folder, pointed at its root.
+   * `workspace-in-account` — inside one of its workspaces.
+   * `flat` — a lone workspace, the shape `foldrun init` made until today.
+   * `empty` — neither: a bare or brand-new directory.
+   */
+  kind: LayoutKind;
+  /** Where AGENTS.md and `library/` live — the account scope. */
+  accountRoot: string;
+  /** `<accountRoot>/workspaces`, or null when there is no account layout. */
+  workspacesDir: string | null;
+  /** The workspace we are in, absolute. Null at an account root. */
+  workspaceDir: string | null;
+  /** Its name. Null at an account root. */
+  workspace: string | null;
+  /** Every workspace this account holds, by name. A flat folder holds one. */
+  workspaces: string[];
+}
+
+/** How far up to look before giving up: a project root (`.git`) is a boundary
+ *  a layout does not cross, and so is the filesystem root. */
+function* upward(from: string): Generator<string> {
+  let dir = path.resolve(from);
+  for (;;) {
+    yield dir;
+    if (isDir(path.join(dir, ".git"))) return;
+    const up = path.dirname(dir);
+    if (up === dir) return;
+    dir = up;
+  }
+}
+
+/**
+ * Which of the two shapes `from` is in, and the directories that follow from
+ * the answer.
+ *
+ * Walks up, remembering the first workspace directory it passes and stopping
+ * at the first account root. A path anywhere inside a workspace resolves to
+ * that workspace, so `foldrun status` works from `agents/writer/` the way git
+ * works from anywhere in a checkout.
+ */
+export function detectLayout(from: string): Layout {
+  const start = path.resolve(from);
+  let workspaceDir: string | null = null;
+  let accountRoot: string | null = null;
+
+  for (const dir of upward(start)) {
+    if (!workspaceDir && isWorkspaceDir(dir)) workspaceDir = dir;
+    const ws = accountWorkspacesDir(dir);
+    // An account root holds `workspaces/`. The workspace directory we may
+    // have just found must be *inside* it — a workspace that happens to have
+    // its own `workspaces/` folder of something else is not an account.
+    if (ws && (!workspaceDir || workspaceDir.startsWith(ws + path.sep))) {
+      accountRoot = dir;
+      break;
+    }
+  }
+
+  if (accountRoot) {
+    const workspaces = listWorkspaceDirs(accountRoot);
+    if (workspaceDir) {
+      return {
+        kind: "workspace-in-account",
+        accountRoot,
+        workspacesDir: accountWorkspacesDir(accountRoot),
+        workspaceDir,
+        workspace: path.basename(workspaceDir),
+        workspaces,
+      };
+    }
+    return {
+      kind: "account",
+      accountRoot,
+      workspacesDir: accountWorkspacesDir(accountRoot),
+      workspaceDir: null,
+      workspace: null,
+      workspaces,
+    };
+  }
+
+  if (workspaceDir) {
+    return {
+      kind: "flat",
+      accountRoot: path.dirname(workspaceDir),
+      workspacesDir: null,
+      workspaceDir,
+      workspace: path.basename(workspaceDir),
+      workspaces: [path.basename(workspaceDir)],
+    };
+  }
+
+  return {
+    kind: "empty",
+    accountRoot: path.dirname(start),
+    workspacesDir: null,
+    workspaceDir: start,
+    workspace: path.basename(start),
+    workspaces: [],
+  };
+}
+
+/**
+ * The account scope for a workspace directory.
+ *
+ * For a flat workspace that is simply its parent — `my-desk/` sits beside the
+ * `AGENTS.md` and `library/` that cover it, which is what `libraryDir` has
+ * always assumed. For a workspace inside an account it is two levels up, NOT
+ * one: one level up is `workspaces/`, which holds no library and no config,
+ * and pointing the account scope there is how a local account folder used to
+ * lose its shared library the moment the runtime asked for it.
+ */
+export function accountRootFor(workspaceDir: string): string {
+  const dir = path.resolve(workspaceDir);
+  const parent = path.dirname(dir);
+  if ((WORKSPACES_DIRS as readonly string[]).includes(path.basename(parent))) {
+    return path.dirname(parent);
+  }
+  return parent;
+}
+
+/**
+ * The data root of the installation this account belongs to, or null when the
+ * account is a folder someone made on their laptop.
+ *
+ * `<data>/<tenant>/workspaces/<name>` and `<my-account>/workspaces/<name>` are
+ * the same shape, so the shape cannot tell them apart. What can is the
+ * installation's own marker, which sits at the data root and nowhere else:
+ * `.foldrun-install`, written by the platform at boot. `.secret-key` and
+ * `keys.json` are the older markers — kept for installs from before it, and
+ * no longer enough alone, because keys move into the database and a key held
+ * in FOLDRUN_SECRET_KEY never had a file.
+ */
+export const INSTALL_MARKER = ".foldrun-install";
+
+export function installationDataRoot(accountRoot: string): string | null {
+  const above = path.dirname(path.resolve(accountRoot));
+  for (const marker of [INSTALL_MARKER, ".secret-key", "keys.json"]) {
+    try {
+      if (fs.statSync(path.join(above, marker)).isFile()) return above;
+    } catch {
+      /* not this one */
+    }
+  }
+  return null;
+}

package/src/library.ts

@@ -14,7 +14,7 @@
 import { platform } from "./platform.ts";
 import fs from "node:fs";
 import path from "node:path";
-import { dataRoot, singleWorkspace } from "./paths.ts";
+import { dataRoot, singleWorkspace, singleAccountRoot, MAX_EDITABLE_FILE } from "./paths.ts";
 import matter from "gray-matter";
 import { KINDS } from "./kinds.ts";
 import { recordRevision, registerTreeReader } from "./history.ts";
@@ -44,7 +44,9 @@ export function libraryDir(tenant: string, kind?: LibraryKind) {
   // library is still possible on a laptop without inventing a home directory.
   const single = singleWorkspace();
   if (single) {
-    const base = path.join(path.resolve(single), "..", "library");
+    // The account scope, which is the workspace's parent only when the
+    // workspace is a flat one — see singleAccountRoot.
+    const base = path.join(singleAccountRoot()!, "library");
     return kind ? path.join(base, kind) : base;
   }
   assertSafeName(tenant, "tenant");
@@ -75,6 +77,15 @@ export interface LibraryEntry {
   description: string;
   /** For skills: true when the folder bundles scripts/. */
   hasScripts?: boolean;
+  /**
+   * Every file this entry is made of, relative to the kind's directory,
+   * `path` included. One entry stays one tool — the shelf must not grow a
+   * second row called browser — but a caller copying the library needs the
+   * code beside the manifest, and the listing is the only place that knows
+   * what is in the folder. Absent for a single-file entry, where `path` is
+   * already the whole of it.
+   */
+  files?: string[];
   /**
    * For tools: how this one connects — http, script or mcp. Surfaced so a
    * list of tools reads as one vocabulary with three transports, rather
@@ -87,6 +98,25 @@ export interface LibraryEntry {
   updatedAt: string;
 }
 
+/** Every file inside a folder entry, as paths relative to the kind's
+ *  directory. Depth-first so a nested `scripts/` comes with it. */
+function folderFiles(dir: string, prefix: string): string[] {
+  const out: string[] = [];
+  const walk = (at: string, rel: string) => {
+    for (const e of fs.readdirSync(at, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+      const here = rel ? `${rel}/${e.name}` : e.name;
+      if (e.isDirectory()) walk(path.join(at, e.name), here);
+      else out.push(`${prefix}/${here}`);
+    }
+  };
+  try {
+    walk(dir, "");
+  } catch {
+    return [`${prefix}/tool.md`];
+  }
+  return out;
+}
+
 export function listLibrary(tenant: string, kind: LibraryKind): LibraryEntry[] {
   const dir = libraryDir(tenant, kind);
   if (!fs.existsSync(dir)) return [];
@@ -113,6 +143,7 @@ export function listLibrary(tenant: string, kind: LibraryKind): LibraryEntry[] {
         out.push({
           ...describe(manifest, entry.name),
           path: `${entry.name}/tool.md`,
+          files: folderFiles(full, entry.name),
           ...toolShape(manifest, entry.name),
           updatedAt: fs.statSync(manifest).mtime.toISOString(),
         });
@@ -138,6 +169,7 @@ export function listLibrary(tenant: string, kind: LibraryKind): LibraryEntry[] {
           ...describe(skillMd, entry),
           path: `${entry}/SKILL.md`,
           hasScripts: fs.existsSync(path.join(full, "scripts")),
+          files: folderFiles(full, entry),
           updatedAt: fs.statSync(skillMd).mtime.toISOString(),
         });
       } else if (entry.endsWith(".md")) {
@@ -205,7 +237,9 @@ export function writeLibraryFile(
   content: string,
   meta: { by?: string; message?: string } = {},
 ) {
-  if (content.length > 256 * 1024) throw new Error("file too large");
+  // 512 KB: a folder tool's program is one file, and the gallery browser's is
+  // past 256 KB. Still a file a person edits, not a store for data.
+  if (content.length > MAX_EDITABLE_FILE) throw new Error("file too large");
   const norm = assertLibraryPath(kind, rel);
   if (norm.endsWith(".md")) matter(content); // reject broken frontmatter
   const p = path.join(libraryDir(tenant, kind), norm);

package/src/limits.ts

@@ -0,0 +1,290 @@
+// Per-step call limits: how many times a step may call a tool before the
+// next call is refused.
+//
+//   limits:
+//     web.search: 40      # one action of the web tool
+//     web: 150            # every web action together
+//     crm: 20             # an API, script or MCP tool, by the name it is granted as
+//     calls: 300          # every tool call in the step, whatever the tool
+//
+// Counted per step and enforced in step-exec.ts's PreToolUse hook — the one
+// place every call passes, the step's own and its sub-agents', on the
+// in-process path and inside a run container alike. A call past a limit is
+// refused before it runs: the tool never sees it, so a paid search API is
+// never asked and the cost is capped exactly. The refusal counts toward
+// nothing. A retry of the step starts from zero; so does each fan-out
+// instance, which is its own step.
+//
+// Nearest wins per key: the account's AGENTS.md, then the workspace's, then
+// the agent's own `limits:`, then a flow step's `limits:` option.
+
+import { WEB_ACTIONS } from "./providers.ts";
+import { DELEGATE_TOOLS } from "./subagents.ts";
+
+export type Limits = Record<string, number>;
+
+/** The key that caps every call in the step. */
+export const TOTAL_KEY = "calls";
+
+/** SDK built-ins, counted under the foldrun group that grants them — and
+ *  under their own SDK name, so `Bash: 5` works for a Claude Code file. */
+const BUILTIN_GROUP: Record<string, string> = {
+  Read: "read", Glob: "read", Grep: "read",
+  Write: "write", Edit: "write", MultiEdit: "write", NotebookEdit: "write",
+  Bash: "code",
+};
+
+/** Retired spellings an author may still write as a key. */
+const KEY_ALIASES: Record<string, string> = { files: "write", bash: "code" };
+
+/** The platform's own in-process servers and the name each is granted as. */
+const PLATFORM_SERVERS: Record<string, string> = {
+  foldrun_search: "search",
+  foldrun_history: "history",
+  foldrun_desks: "desks",
+  foldrun_ask: "ask",
+};
+
+/** One spelling for comparing: `desk-email` and `desk_email` are the same
+ *  tool (a script tool's SDK name has its dashes made underscores). */
+export function normKey(key: string): string {
+  const k = key.trim();
+  return (KEY_ALIASES[k] ?? k).replace(/-/g, "_");
+}
+
+const KEY_RE = /^[A-Za-z0-9_-]+(\.[a-z]+)?$/;
+
+/**
+ * A `limits:` block as written: the values that can be read, and a sentence
+ * for each that cannot. Shape only — whether a key names a tool this agent
+ * has is `limitKeyProblems`, which needs the grants.
+ */
+export function readLimits(raw: unknown, where = "limits"): { limits: Limits; problems: string[] } {
+  const limits: Limits = {};
+  const problems: string[] = [];
+  if (raw === undefined || raw === null) return { limits, problems };
+  if (typeof raw !== "object" || Array.isArray(raw)) {
+    problems.push(`${where}: is a block of tool: count, e.g. \`limits: {web.search: 40, calls: 300}\`.`);
+    return { limits, problems };
+  }
+  // A YAML block written `web: {search: 40}` arrives nested; read it as the
+  // dotted keys it means rather than refusing a natural spelling.
+  const flat: [string, unknown][] = [];
+  for (const [k, v] of Object.entries(raw as Record<string, unknown>)) {
+    if (v && typeof v === "object" && !Array.isArray(v)) {
+      for (const [sub, n] of Object.entries(v as Record<string, unknown>)) flat.push([`${k}.${sub}`, n]);
+    } else flat.push([k, v]);
+  }
+  for (const [key, value] of flat) {
+    const k = key.trim();
+    if (!KEY_RE.test(k)) {
+      problems.push(`${where}: "${k}" is not a key — a tool's name, web.<action>, or calls.`);
+      continue;
+    }
+    if (k.includes(".")) {
+      const [head, action] = k.split(".");
+      if (head !== "web" || !(WEB_ACTIONS as readonly string[]).includes(action)) {
+        problems.push(`${where}: "${k}" is not a key — the dotted keys are web.<action>: ${WEB_ACTIONS.map((a) => `web.${a}`).join(", ")}.`);
+        continue;
+      }
+    }
+    const n = typeof value === "number" ? value : typeof value === "string" && /^\s*\d+\s*$/.test(value) ? Number(value) : NaN;
+    if (!Number.isInteger(n) || n < 1) {
+      problems.push(`${where}: ${k}: ${String(value)} — a whole number of calls, 1 or more. To withhold a tool, leave it out of tools:.`);
+      continue;
+    }
+    limits[k] = n;
+  }
+  return { limits, problems };
+}
+
+/**
+ * The limits a step runs under, nearest last: account, workspace, agent,
+ * step. A key set nearer replaces the same key further out; the others
+ * stand. Unreadable values are dropped here — `check` and the deploy gate
+ * say so where they were written.
+ */
+export function cascadeLimits(levels: unknown[]): Limits {
+  const out: Limits = {};
+  const at = new Map<string, string>(); // normalised → the key as last written
+  for (const level of levels) {
+    for (const [k, n] of Object.entries(readLimits(level).limits)) {
+      const nk = normKey(k);
+      const prev = at.get(nk);
+      if (prev !== undefined) delete out[prev];
+      out[k] = n;
+      at.set(nk, k);
+    }
+  }
+  return out;
+}
+
+/** SDK tool name → the foldrun name it is granted as, for the tools whose
+ *  SDK name does not say (an openapi tool's operations, a script whose name
+ *  was made safe). `apiOwners` is api-tools' own record of which API each
+ *  tool was built for — not guessed from the name, which cannot tell `crm`'s
+ *  operation `admin_list` from `crm_admin`'s `list`. Built host-side; plain
+ *  JSON so it crosses into a pod. */
+export function toolOwners(apiOwners: Record<string, string>, scripts: { name: string }[]): Record<string, string> {
+  const out: Record<string, string> = { ...apiOwners };
+  for (const s of scripts) out[`mcp__foldrun_scripts__${s.name}`] = s.name;
+  return out;
+}
+
+/**
+ * Every key one call counts under, `calls` included. Pure: the SDK's tool
+ * name, its input, and the owners map.
+ */
+export function limitKeysFor(toolName: string, input: Record<string, unknown> | undefined, owners: Record<string, string> = {}): string[] {
+  const keys = [TOTAL_KEY];
+  const webAction = (action: unknown) => {
+    keys.push("web");
+    const a = typeof action === "string" ? action.trim().toLowerCase() : "";
+    if (a) keys.push(`web.${a}`);
+  };
+  // A model provider's own search or fetch, standing in for the web tool's.
+  if (toolName === "WebSearch") { webAction("search"); return keys; }
+  if (toolName === "WebFetch") { webAction("fetch"); return keys; }
+  if ((DELEGATE_TOOLS as readonly string[]).includes(toolName)) return keys;
+  const owner = owners[toolName];
+  const mcp = /^mcp__(.+?)__(.+)$/.exec(toolName);
+  const name = owner
+    ?? (mcp
+      ? mcp[1] === "foldrun_scripts" ? mcp[2]
+        : mcp[1] === "foldrun_apis" ? mcp[2].replace(/^call_/, "")
+        : mcp[1] === "foldrun_agents" ? mcp[2].replace(/^consult_/, "")
+        : PLATFORM_SERVERS[mcp[1]] ?? mcp[1]
+      : null);
+  if (name !== null) {
+    if (normKey(name) === "web") webAction(input?.action);
+    else keys.push(name);
+    return keys;
+  }
+  const group = BUILTIN_GROUP[toolName];
+  if (group) keys.push(group);
+  keys.push(toolName);
+  return keys;
+}
+
+export interface LimitRefusal {
+  key: string;
+  used: number;
+  limit: number;
+  message: string;
+}
+
+/**
+ * One step's counts. `take` checks every key the call counts under and
+ * either refuses — counting nothing — or counts it under all of them.
+ */
+export class CallCounter {
+  private readonly limits = new Map<string, { key: string; limit: number }>();
+  private readonly used = new Map<string, number>();
+  refused = 0;
+
+  constructor(limits: Limits | undefined | null) {
+    for (const [k, n] of Object.entries(limits ?? {})) this.limits.set(normKey(k), { key: k, limit: n });
+  }
+
+  get active(): boolean {
+    return this.limits.size > 0;
+  }
+
+  take(keys: string[]): LimitRefusal | null {
+    const norm = [...new Set(keys.map(normKey))];
+    for (const k of norm) {
+      const l = this.limits.get(k);
+      if (!l) continue;
+      const used = this.used.get(k) ?? 0;
+      if (used >= l.limit) {
+        this.refused++;
+        return {
+          key: l.key, used, limit: l.limit,
+          message: `limit reached: ${l.key} ${used} of ${l.limit} in this step — work with what you have, or say what more you would need`,
+        };
+      }
+    }
+    for (const k of norm) this.used.set(k, (this.used.get(k) ?? 0) + 1);
+    return null;
+  }
+
+  /** Give back a call that was counted and then refused by a later check. */
+  refund(keys: string[]): void {
+    for (const k of new Set(keys.map(normKey))) {
+      const n = this.used.get(k) ?? 0;
+      if (n > 0) this.used.set(k, n - 1);
+    }
+  }
+
+  count(key: string): number {
+    return this.used.get(normKey(key)) ?? 0;
+  }
+
+  /** `limits: web.search 40/40, crm 3/20` — null when no limits are set. */
+  summary(): string | null {
+    if (!this.active) return null;
+    const parts = [...this.limits.entries()].map(([k, l]) => `${l.key} ${this.used.get(k) ?? 0}/${l.limit}`);
+    return `limits: ${parts.join(", ")}${this.refused ? ` — ${this.refused} call${this.refused === 1 ? "" : "s"} refused` : ""}`;
+  }
+}
+
+/**
+ * Keys an agent's `limits:` names that it cannot use. `known` is every tool
+ * name in reach (built-ins, the workspace's and library's tools, this
+ * agent's APIs, scripts and MCP servers); `granted` is what this agent's
+ * `tools:` (and `apis:`, `scripts:`, `mcpServers:`) gives it. A key that
+ * names nothing is an error; a real tool this agent does not hold is a
+ * warning — the limit is harmless, and probably a leftover.
+ */
+export function limitKeyProblems(
+  limits: Limits,
+  ctx: { known: Iterable<string>; granted: Iterable<string> },
+): { level: "error" | "warn"; message: string }[] {
+  const out: { level: "error" | "warn"; message: string }[] = [];
+  const builtinKeys = ["read", "write", "code", ...Object.keys(BUILTIN_GROUP), "TodoWrite", "search", "history", "desks", "ask", "web"];
+  const known = new Set([...builtinKeys, ...ctx.known].map(normKey));
+  const granted = new Set([...ctx.granted].flatMap((g) => {
+    const n = normKey(g);
+    // A group grants its members' keys, and `write` holds Read too.
+    if (n === "write") return [n, "read", "Read", "Write", "Edit", "MultiEdit", "NotebookEdit", "Glob", "Grep"];
+    if (n === "read") return [n, "Read", "Glob", "Grep"];
+    if (n === "code") return [n, "Bash"];
+    if (BUILTIN_GROUP[g]) return [n, BUILTIN_GROUP[g]];
+    return [n];
+  }).map(normKey));
+  for (const key of Object.keys(limits)) {
+    if (key === TOTAL_KEY) continue;
+    const base = key.startsWith("web.") ? "web" : key;
+    const n = normKey(base);
+    if (!known.has(n)) {
+      const valid = [TOTAL_KEY, "web", ...WEB_ACTIONS.map((a) => `web.${a}`), ...[...new Set([...ctx.granted].map(String))].filter((g) => g !== "web")];
+      out.push({ level: "error", message: `limits: ${key} — not a tool this agent could call. The keys: ${[...new Set(valid)].join(", ")}.` });
+    } else if (!granted.has(n)) {
+      out.push({ level: "warn", message: `limits: ${key} — this agent is not granted ${base}, so the limit never applies` });
+    }
+  }
+  return out;
+}
+
+/**
+ * A flow step's `limits:` option, written on one line:
+ * `limits: {web.search: 10, calls: 50}` (the braces are optional). Read by
+ * hand rather than as YAML, because `web.search` is a plain key here and one
+ * line is all a step option has.
+ */
+export function parseStepLimits(text: string): { limits: Limits; problems: string[] } {
+  const body = text.trim().replace(/^\{/, "").replace(/\}$/, "").trim();
+  if (!body) return { limits: {}, problems: ["a block of tool: count on one line, e.g. {web.search: 10, calls: 50}"] };
+  const raw: Record<string, unknown> = {};
+  const problems: string[] = [];
+  for (const part of body.split(",")) {
+    const m = /^\s*([^:\s]+)\s*:\s*(\S+)\s*$/.exec(part);
+    if (!m) {
+      problems.push(`"${part.trim()}" is not tool: count`);
+      continue;
+    }
+    raw[m[1]] = m[2];
+  }
+  const read = readLimits(raw, "limits");
+  return { limits: read.limits, problems: [...problems, ...read.problems.map((p) => p.replace(/^limits: /, ""))] };
+}