@foldrun/core 0.3.0 → 0.5.0

package/dist/src/library.js

@@ -10,9 +10,10 @@
 // Resolution is nearest-wins, the same rule OKF uses for knowledge: an agent's
 // own file beats its workspace's, which beats the account's. So a team can set
 // a house style once and one agent can still override it.
+import { platform } from "./platform.js";
 import fs from "node:fs";
 import path from "node:path";
-import { dataRoot, singleWorkspace } from "./paths.js";
+import { dataRoot, singleWorkspace, singleAccountRoot, MAX_EDITABLE_FILE } from "./paths.js";
 import matter from "gray-matter";
 import { KINDS } from "./kinds.js";
 import { recordRevision, registerTreeReader } from "./history.js";
@@ -27,7 +28,9 @@ export function libraryDir(tenant, kind) {
     // 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");
@@ -50,6 +53,27 @@ function assertLibraryPath(kind, rel) {
     }
     return norm;
 }
+/** 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, prefix) {
+    const out = [];
+    const walk = (at, rel) => {
+        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, kind) {
     const dir = libraryDir(tenant, kind);
     if (!fs.existsSync(dir))
@@ -77,6 +101,7 @@ export function listLibrary(tenant, kind) {
                 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(),
                 });
@@ -103,6 +128,7 @@ export function listLibrary(tenant, kind) {
                     ...describe(skillMd, entry),
                     path: `${entry}/SKILL.md`,
                     hasScripts: fs.existsSync(path.join(full, "scripts")),
+                    files: folderFiles(full, entry),
                     updatedAt: fs.statSync(skillMd).mtime.toISOString(),
                 });
             }
@@ -166,7 +192,9 @@ export function libraryFileExists(tenant, kind, rel) {
     }
 }
 export function writeLibraryFile(tenant, kind, rel, content, meta = {}) {
-    if (content.length > 256 * 1024)
+    // 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"))
@@ -213,7 +241,18 @@ export function deleteLibraryPath(tenant, kind, rel, meta = {}) {
 // ---------- consumed by the runner ----------
 /** Library tool definitions, keyed by name — http or script, both grantable by name in `tools:`. */
 export function libraryTools(tenant) {
-    return readToolDir(libraryDir(tenant, "tools"), "account");
+    // The platform's gallery first, the account's own copies over it: a tool
+    // the platform ships is granted by name in every account without anyone
+    // installing it, and an account that installed (copied) one keeps its
+    // copy — that is what "install to customise" means. Both read at account
+    // scope, so a folder tool's `run:` resolves to /library/tools/<name>/…
+    // in the sandbox either way; the staging step lays the gallery down
+    // first and the account library over it for the same reason.
+    const gallery = platform.galleryDir();
+    return {
+        ...(gallery ? readToolDir(path.join(gallery, "tools"), "account") : {}),
+        ...readToolDir(libraryDir(tenant, "tools"), "account"),
+    };
 }
 /** Shared memory index — derived from the files, like every other scope. */
 export function libraryMemoryIndex(tenant) {

package/dist/src/limits.d.ts

@@ -0,0 +1,84 @@
+export type Limits = Record<string, number>;
+/** The key that caps every call in the step. */
+export declare const TOTAL_KEY = "calls";
+/** 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 declare function normKey(key: string): string;
+/**
+ * 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 declare function readLimits(raw: unknown, where?: string): {
+    limits: Limits;
+    problems: string[];
+};
+/**
+ * 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 declare function cascadeLimits(levels: unknown[]): Limits;
+/** 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 declare function toolOwners(apiOwners: Record<string, string>, scripts: {
+    name: string;
+}[]): Record<string, string>;
+/**
+ * Every key one call counts under, `calls` included. Pure: the SDK's tool
+ * name, its input, and the owners map.
+ */
+export declare function limitKeysFor(toolName: string, input: Record<string, unknown> | undefined, owners?: Record<string, string>): string[];
+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 declare class CallCounter {
+    private readonly limits;
+    private readonly used;
+    refused: number;
+    constructor(limits: Limits | undefined | null);
+    get active(): boolean;
+    take(keys: string[]): LimitRefusal | null;
+    /** Give back a call that was counted and then refused by a later check. */
+    refund(keys: string[]): void;
+    count(key: string): number;
+    /** `limits: web.search 40/40, crm 3/20` — null when no limits are set. */
+    summary(): string | null;
+}
+/**
+ * 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 declare function limitKeyProblems(limits: Limits, ctx: {
+    known: Iterable<string>;
+    granted: Iterable<string>;
+}): {
+    level: "error" | "warn";
+    message: string;
+}[];
+/**
+ * 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 declare function parseStepLimits(text: string): {
+    limits: Limits;
+    problems: string[];
+};

package/dist/src/limits.js

@@ -0,0 +1,287 @@
+// 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.js";
+import { DELEGATE_TOOLS } from "./subagents.js";
+/** 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 = {
+    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 = { files: "write", bash: "code" };
+/** The platform's own in-process servers and the name each is granted as. */
+const PLATFORM_SERVERS = {
+    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) {
+    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, where = "limits") {
+    const limits = {};
+    const problems = [];
+    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 = [];
+    for (const [k, v] of Object.entries(raw)) {
+        if (v && typeof v === "object" && !Array.isArray(v)) {
+            for (const [sub, n] of Object.entries(v))
+                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.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) {
+    const out = {};
+    const at = new Map(); // 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, scripts) {
+    const out = { ...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, input, owners = {}) {
+    const keys = [TOTAL_KEY];
+    const webAction = (action) => {
+        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.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;
+}
+/**
+ * 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 {
+    limits = new Map();
+    used = new Map();
+    refused = 0;
+    constructor(limits) {
+        for (const [k, n] of Object.entries(limits ?? {}))
+            this.limits.set(normKey(k), { key: k, limit: n });
+    }
+    get active() {
+        return this.limits.size > 0;
+    }
+    take(keys) {
+        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) {
+        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) {
+        return this.used.get(normKey(key)) ?? 0;
+    }
+    /** `limits: web.search 40/40, crm 3/20` — null when no limits are set. */
+    summary() {
+        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, ctx) {
+    const out = [];
+    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) {
+    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 = {};
+    const problems = [];
+    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: /, ""))] };
+}

package/dist/src/locale.d.ts

@@ -0,0 +1,47 @@
+export interface RegionChoice {
+    /** ISO 3166-1 alpha-2, upper-case: AU, IR, DE. Null when nobody said and
+     *  the language tag carries none. */
+    region: string | null;
+    from: "agent" | "flow" | "workspace" | "account" | "env" | "language" | "none";
+    lines: string[];
+}
+export declare function normalizeRegion(raw: unknown): string | null;
+export declare function regionProblem(raw: unknown): string | null;
+export declare function resolveRegion(levels: {
+    level: RegionChoice["from"];
+    value: unknown;
+}[], languageTag: string, env?: Record<string, string | undefined>): RegionChoice;
+export type Units = "metric" | "imperial";
+export interface LocaleFacts {
+    /** The BCP-47 tag Intl was asked with, e.g. fa-IR. */
+    tag: string;
+    language: string;
+    region: string | null;
+    currency: string | null;
+    units: Units;
+    /** The calendar in use — Intl's first for the locale, or the override. */
+    calendar: string;
+    /** Other calendars the locale commonly uses, e.g. gregory beside persian. */
+    calendars: string[];
+    /** Today in that calendar, formatted for the locale. Null when it is
+     *  gregory and would only repeat FOLDRUN_DATE. */
+    dateLocal: string | null;
+    /** 1 = Monday … 7 = Sunday, ISO. */
+    weekStart: number | null;
+    weekend: number[];
+    direction: "ltr" | "rtl";
+    hourCycle: "h12" | "h23" | null;
+    /** A sample date, so the model sees the order without being told. */
+    dateSample: string;
+}
+export declare const dayName: (n: number) => string;
+export declare function localeProblems(front: Record<string, unknown>): string[];
+export declare function deriveLocale(language: string, region: string | null, overrides?: {
+    currency?: unknown;
+    calendar?: unknown;
+    units?: unknown;
+}, timeZone?: string, now?: Date): LocaleFacts;
+/** The sentence block the prompt carries. Only what is true for this
+ *  locale; nothing hedged, nothing the model has to guess at. */
+export declare function localeProse(f: LocaleFacts, languageName: string, regionName: string | null): string;
+export declare function regionName(code: string | null): string | null;