@foldrun/core 0.4.0 → 0.6.0

package/dist/src/language.d.ts

@@ -0,0 +1,17 @@
+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 declare function normalizeLanguage(raw: unknown): string | null;
+/** Null when unset (inherit) or readable; else the sentence check prints. */
+export declare function languageProblem(raw: unknown): string | null;
+export declare function resolveLanguage(levels: {
+    level: LanguageChoice["from"];
+    value: unknown;
+}[], env?: Record<string, string | undefined>): LanguageChoice;
+/** How a person would name it in a prompt: `fa-IR` → "Persian (Iran)". */
+export declare function languageName(tag: string): string;

package/dist/src/language.js

@@ -0,0 +1,55 @@
+// 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.
+/** `en`, `en-AU`, `en_au`, ` FA-ir ` → `en`, `en-AU`, `en-AU`, `fa-IR`; anything else null. */
+export function normalizeLanguage(raw) {
+    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) {
+    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, env = process.env) {
+    const lines = [];
+    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) {
+    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/dist/src/layout.d.ts

@@ -0,0 +1,69 @@
+/** Where an account keeps its workspaces. `projects/` is the pre-rename name,
+ *  still read so an existing tree keeps working. */
+export declare const WORKSPACES_DIRS: readonly ["workspaces", "projects"];
+/**
+ * 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 declare function isWorkspaceDir(dir: string): boolean;
+/** `<dir>/workspaces` when `dir` is an account root, else null. */
+export declare function accountWorkspacesDir(dir: string): string | null;
+/** The workspaces under an account root, by name, sorted. */
+export declare function listWorkspaceDirs(accountRoot: string): string[];
+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[];
+}
+/**
+ * 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 declare function detectLayout(from: string): Layout;
+/**
+ * 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 declare function accountRootFor(workspaceDir: string): string;
+/**
+ * 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 declare const INSTALL_MARKER = ".foldrun-install";
+export declare function installationDataRoot(accountRoot: string): string | null;

package/dist/src/layout.js

@@ -0,0 +1,200 @@
+// 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"];
+function isDir(p) {
+    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) {
+    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) {
+    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) {
+    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 [];
+    }
+}
+/** 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) {
+    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) {
+    const start = path.resolve(from);
+    let workspaceDir = null;
+    let accountRoot = 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) {
+    const dir = path.resolve(workspaceDir);
+    const parent = path.dirname(dir);
+    if (WORKSPACES_DIRS.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) {
+    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/dist/src/library.d.ts

@@ -9,6 +9,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

package/dist/src/library.js

@@ -13,7 +13,7 @@
 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";
@@ -28,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");
@@ -51,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))
@@ -78,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(),
                 });
@@ -104,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(),
                 });
             }
@@ -167,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"))

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[];
+};