@foldrun/core 0.3.0 → 0.5.0

package/dist/src/host-env.js

@@ -0,0 +1,48 @@
+// The environment a step's children start from, on the in-process path.
+//
+// Scripts, `verify:` shells and the SDK's own Bash tool used to inherit the
+// whole of process.env — which on a platform holds FOLDRUN_SECRET_KEY (the
+// key every tenant's vault and hook token derives from), the database URL,
+// the object-store and mail credentials, the Stripe key. `console.log(
+// process.env)` in a script tool was cross-tenant compromise. tool-test.ts
+// built a stripped base for the Test button; this is that base, made the one
+// definition, used everywhere a child is spawned host-side.
+//
+// A run container needs none of this: its process.env IS the boundary,
+// assembled from an allowlist on the host before the container started.
+//
+// What passes is what an interpreter needs to be found and to run, the
+// locale, the clock, the network's proxy settings, and the identifiers the
+// runner stamps on a step (FOLDRUN_RUN_*, FOLDRUN_STEP_*) so a script can
+// say which run made its records. The secrets an agent declares are layered
+// on top by the caller — by name, from the vault, never from the host.
+const EXACT = new Set([
+    "PATH", "HOME", "TMPDIR", "TMP", "TEMP", "LANG", "LANGUAGE",
+    "TZ", "TERM", "SHELL", "USER", "LOGNAME",
+    // The host's way to the network is the child's way to the network.
+    "HTTP_PROXY", "HTTPS_PROXY", "NO_PROXY", "http_proxy", "https_proxy", "no_proxy",
+    "SSL_CERT_FILE", "SSL_CERT_DIR",
+    // Windows equivalents, harmless elsewhere.
+    "SYSTEMROOT", "COMSPEC", "PATHEXT", "WINDIR",
+]);
+const PREFIXES = ["LC_", "NODE_", "FOLDRUN_RUN_", "FOLDRUN_STEP_"];
+/** Does this name pass the allowlist? Exported so a test can pin the rule
+ *  rather than the list. */
+export function hostEnvAllowed(name) {
+    return EXACT.has(name) || PREFIXES.some((p) => name.startsWith(p));
+}
+/**
+ * process.env, reduced to the allowlist. A fresh object every call, so a
+ * caller that layers secrets on top never writes into the host's own env.
+ */
+export function hostSafeEnv(from = process.env) {
+    const out = {};
+    for (const [k, v] of Object.entries(from)) {
+        if (typeof v === "string" && hostEnvAllowed(k))
+            out[k] = v;
+    }
+    // Typed as ProcessEnv, not a string map: a host whose type augmentation
+    // makes a key required (Next declares NODE_ENV so) refuses a plain map at
+    // every spawn. The value is the same either way.
+    return out;
+}

package/dist/src/json-schema.d.ts

@@ -0,0 +1,12 @@
+export interface SchemaError {
+    /** JSON pointer to the offending value: "" is the root, "/leads/0/url". */
+    path: string;
+    message: string;
+}
+/** Is `value` what `schema` describes? Empty means yes. */
+export declare function validateSchema(value: unknown, schema: unknown): SchemaError[];
+/** The errors as one sentence for a trace line. */
+export declare function describeSchemaErrors(errors: SchemaError[]): string;
+/** Is this a schema at all? An object (or a boolean, which JSON Schema
+ *  allows) — not a string, not a list. */
+export declare function looksLikeSchema(schema: unknown): boolean;

package/dist/src/json-schema.js

@@ -0,0 +1,202 @@
+// A JSON Schema validator small enough to read, with no dependency.
+//
+// `schema:` beside `output: json` says what shape the reply's value must
+// have, and a value that does not have it fails the step with a sentence
+// naming the field. The subset here is the part of JSON Schema people write
+// by hand for a handoff — types, required fields, enums, ranges, patterns,
+// arrays, the combinators, and `$ref` to a definition in the same document.
+// Formats (`date-time`, `email`) are accepted and not checked; a check that
+// needs one belongs in a `verify:`. Anything the validator does not know is
+// ignored, the way JSON Schema itself says unknown keywords are.
+//
+// Not ajv: it sits in node_modules as a dependency of a dependency, which is
+// nothing to build on, and the whole of it is far more than a step needs.
+const MAX_ERRORS = 8;
+/** Is `value` what `schema` describes? Empty means yes. */
+export function validateSchema(value, schema) {
+    const errors = [];
+    check(value, schema, "", schema, errors, 0);
+    return errors.slice(0, MAX_ERRORS);
+}
+/** The errors as one sentence for a trace line. */
+export function describeSchemaErrors(errors) {
+    return errors.map((e) => `${e.path || "the value"}: ${e.message}`).join("; ");
+}
+/** Is this a schema at all? An object (or a boolean, which JSON Schema
+ *  allows) — not a string, not a list. */
+export function looksLikeSchema(schema) {
+    return typeof schema === "boolean" || (typeof schema === "object" && schema !== null && !Array.isArray(schema));
+}
+const typeOf = (v) => v === null ? "null" : Array.isArray(v) ? "array" : typeof v === "number" ? (Number.isInteger(v) ? "integer" : "number") : typeof v;
+const matchesType = (v, t) => {
+    const actual = typeOf(v);
+    return t === actual || (t === "number" && actual === "integer");
+};
+function resolveRef(ref, root) {
+    if (!ref.startsWith("#"))
+        return null;
+    let node = root;
+    for (const raw of ref.slice(1).split("/").filter(Boolean)) {
+        const key = raw.replaceAll("~1", "/").replaceAll("~0", "~");
+        if (typeof node !== "object" || node === null)
+            return null;
+        node = node[key];
+    }
+    return typeof node === "object" && node !== null ? node : typeof node === "boolean" ? node : null;
+}
+function check(value, schema, path, root, errors, depth) {
+    if (errors.length >= MAX_ERRORS || depth > 64)
+        return;
+    if (schema === true)
+        return;
+    if (schema === false)
+        return void errors.push({ path, message: "nothing is allowed here" });
+    if (typeof schema !== "object" || schema === null)
+        return;
+    const s = schema;
+    const fail = (message) => errors.push({ path, message });
+    if (typeof s.$ref === "string") {
+        const target = resolveRef(s.$ref, root);
+        if (target === null)
+            return fail(`schema: unresolvable $ref ${s.$ref}`);
+        check(value, target, path, root, errors, depth + 1);
+        return;
+    }
+    // type — one, or a list of alternatives; "nullable: true" (OpenAPI's
+    // spelling) lets null through.
+    if (s.type !== undefined) {
+        const types = Array.isArray(s.type) ? s.type : [String(s.type)];
+        const ok = types.some((t) => matchesType(value, t)) || (s.nullable === true && value === null);
+        if (!ok)
+            return fail(`expected ${types.join(" or ")}, got ${typeOf(value)}`);
+    }
+    if (Array.isArray(s.enum) && !s.enum.some((e) => deepEqual(e, value))) {
+        return fail(`must be one of ${s.enum.map((e) => JSON.stringify(e)).join(", ")}`);
+    }
+    if ("const" in s && !deepEqual(s.const, value))
+        return fail(`must be ${JSON.stringify(s.const)}`);
+    if (typeof value === "string") {
+        if (typeof s.minLength === "number" && value.length < s.minLength)
+            fail(`shorter than ${s.minLength} characters`);
+        if (typeof s.maxLength === "number" && value.length > s.maxLength)
+            fail(`longer than ${s.maxLength} characters`);
+        if (typeof s.pattern === "string") {
+            try {
+                if (!new RegExp(s.pattern, "u").test(value))
+                    fail(`does not match ${s.pattern}`);
+            }
+            catch {
+                fail(`schema: invalid pattern ${s.pattern}`);
+            }
+        }
+    }
+    if (typeof value === "number") {
+        if (typeof s.minimum === "number" && value < s.minimum)
+            fail(`below the minimum ${s.minimum}`);
+        if (typeof s.maximum === "number" && value > s.maximum)
+            fail(`above the maximum ${s.maximum}`);
+        if (typeof s.exclusiveMinimum === "number" && value <= s.exclusiveMinimum)
+            fail(`must be above ${s.exclusiveMinimum}`);
+        if (typeof s.exclusiveMaximum === "number" && value >= s.exclusiveMaximum)
+            fail(`must be below ${s.exclusiveMaximum}`);
+        if (typeof s.multipleOf === "number" && s.multipleOf > 0 && Math.abs(value / s.multipleOf - Math.round(value / s.multipleOf)) > 1e-9) {
+            fail(`not a multiple of ${s.multipleOf}`);
+        }
+    }
+    if (Array.isArray(value)) {
+        if (typeof s.minItems === "number" && value.length < s.minItems)
+            fail(`fewer than ${s.minItems} items`);
+        if (typeof s.maxItems === "number" && value.length > s.maxItems)
+            fail(`more than ${s.maxItems} items`);
+        if (s.uniqueItems === true) {
+            const seen = new Set(value.map((v) => JSON.stringify(v)));
+            if (seen.size !== value.length)
+                fail("items are not unique");
+        }
+        if (s.items !== undefined && !Array.isArray(s.items)) {
+            value.forEach((item, i) => check(item, s.items, `${path}/${i}`, root, errors, depth + 1));
+        }
+        else if (Array.isArray(s.items) || Array.isArray(s.prefixItems)) {
+            const tuple = (Array.isArray(s.prefixItems) ? s.prefixItems : s.items);
+            tuple.forEach((sub, i) => i < value.length && check(value[i], sub, `${path}/${i}`, root, errors, depth + 1));
+        }
+    }
+    if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+        const obj = value;
+        const props = (typeof s.properties === "object" && s.properties !== null ? s.properties : {});
+        if (Array.isArray(s.required)) {
+            for (const key of s.required)
+                if (!(key in obj))
+                    fail(`missing required field "${key}"`);
+        }
+        for (const [key, sub] of Object.entries(props)) {
+            if (key in obj)
+                check(obj[key], sub, `${path}/${key.replaceAll("~", "~0").replaceAll("/", "~1")}`, root, errors, depth + 1);
+        }
+        const patterns = (typeof s.patternProperties === "object" && s.patternProperties !== null ? s.patternProperties : {});
+        for (const key of Object.keys(obj)) {
+            if (key in props)
+                continue;
+            const pattern = Object.entries(patterns).find(([re]) => {
+                try {
+                    return new RegExp(re, "u").test(key);
+                }
+                catch {
+                    return false;
+                }
+            });
+            if (pattern) {
+                check(obj[key], pattern[1], `${path}/${key}`, root, errors, depth + 1);
+            }
+            else if (s.additionalProperties === false) {
+                fail(`unexpected field "${key}"`);
+            }
+            else if (typeof s.additionalProperties === "object" && s.additionalProperties !== null) {
+                check(obj[key], s.additionalProperties, `${path}/${key}`, root, errors, depth + 1);
+            }
+        }
+        if (typeof s.minProperties === "number" && Object.keys(obj).length < s.minProperties)
+            fail(`fewer than ${s.minProperties} fields`);
+        if (typeof s.maxProperties === "number" && Object.keys(obj).length > s.maxProperties)
+            fail(`more than ${s.maxProperties} fields`);
+    }
+    if (Array.isArray(s.allOf)) {
+        for (const sub of s.allOf)
+            check(value, sub, path, root, errors, depth + 1);
+    }
+    if (Array.isArray(s.anyOf)) {
+        const ok = s.anyOf.some((sub) => validateSchema(value, withRoot(sub, root)).length === 0);
+        if (!ok)
+            fail("matches none of the allowed shapes (anyOf)");
+    }
+    if (Array.isArray(s.oneOf)) {
+        const n = s.oneOf.filter((sub) => validateSchema(value, withRoot(sub, root)).length === 0).length;
+        if (n !== 1)
+            fail(n === 0 ? "matches none of the allowed shapes (oneOf)" : `matches ${n} of the shapes, must match exactly one (oneOf)`);
+    }
+    if (s.not !== undefined && validateSchema(value, withRoot(s.not, root)).length === 0)
+        fail("matches a shape that is not allowed (not)");
+}
+/** A sub-schema checked on its own still resolves `$ref` against the
+ *  document it came from: carry the root's definitions along. */
+function withRoot(sub, root) {
+    if (typeof sub !== "object" || sub === null || typeof root !== "object" || root === null)
+        return sub;
+    const defs = {};
+    for (const key of ["$defs", "definitions"])
+        if (key in root)
+            defs[key] = root[key];
+    return { ...defs, ...sub };
+}
+function deepEqual(a, b) {
+    if (a === b)
+        return true;
+    if (typeof a !== typeof b || a === null || b === null || typeof a !== "object")
+        return false;
+    if (Array.isArray(a) !== Array.isArray(b))
+        return false;
+    const ka = Object.keys(a), kb = Object.keys(b);
+    if (ka.length !== kb.length)
+        return false;
+    return ka.every((k) => deepEqual(a[k], b[k]));
+}

package/dist/src/kinds.js

@@ -62,7 +62,7 @@ name: ${name}
 description: What this agent is for, in one line.
 model: fast
 effort: high
-tools: [files]
+tools: [write]
 ---
 
 # ${name}

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