@foldrun/core 0.3.0 → 0.5.0

package/src/host-env.ts

@@ -0,0 +1,51 @@
+// 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: string): boolean {
+  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: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv {
+  const out: Record<string, string> = {};
+  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 as NodeJS.ProcessEnv;
+}

package/src/json-schema.ts

@@ -0,0 +1,184 @@
+// 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.
+
+export interface SchemaError {
+  /** JSON pointer to the offending value: "" is the root, "/leads/0/url". */
+  path: string;
+  message: string;
+}
+
+type Schema = Record<string, unknown> | boolean;
+
+const MAX_ERRORS = 8;
+
+/** Is `value` what `schema` describes? Empty means yes. */
+export function validateSchema(value: unknown, schema: unknown): SchemaError[] {
+  const errors: SchemaError[] = [];
+  check(value, schema as Schema, "", schema as Schema, errors, 0);
+  return errors.slice(0, MAX_ERRORS);
+}
+
+/** The errors as one sentence for a trace line. */
+export function describeSchemaErrors(errors: SchemaError[]): string {
+  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: unknown): boolean {
+  return typeof schema === "boolean" || (typeof schema === "object" && schema !== null && !Array.isArray(schema));
+}
+
+const typeOf = (v: unknown): string =>
+  v === null ? "null" : Array.isArray(v) ? "array" : typeof v === "number" ? (Number.isInteger(v) ? "integer" : "number") : typeof v;
+
+const matchesType = (v: unknown, t: string): boolean => {
+  const actual = typeOf(v);
+  return t === actual || (t === "number" && actual === "integer");
+};
+
+function resolveRef(ref: string, root: Schema): Schema | null {
+  if (!ref.startsWith("#")) return null;
+  let node: unknown = 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 as Record<string, unknown>)[key];
+  }
+  return typeof node === "object" && node !== null ? (node as Schema) : typeof node === "boolean" ? node : null;
+}
+
+function check(value: unknown, schema: Schema, path: string, root: Schema, errors: SchemaError[], depth: number) {
+  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 as Record<string, unknown>;
+  const fail = (message: string) => 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 as string[]) : [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 as Schema, `${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) as Schema[];
+      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 as Record<string, unknown>;
+    const props = (typeof s.properties === "object" && s.properties !== null ? s.properties : {}) as Record<string, Schema>;
+    if (Array.isArray(s.required)) {
+      for (const key of s.required as string[]) 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 : {}) as Record<string, Schema>;
+    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 as Schema, `${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 as Schema[]) check(value, sub, path, root, errors, depth + 1);
+  }
+  if (Array.isArray(s.anyOf)) {
+    const ok = (s.anyOf as Schema[]).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 as Schema[]).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 as Schema, 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: Schema, root: Schema): Schema {
+  if (typeof sub !== "object" || sub === null || typeof root !== "object" || root === null) return sub;
+  const defs: Record<string, unknown> = {};
+  for (const key of ["$defs", "definitions"]) if (key in (root as Record<string, unknown>)) defs[key] = (root as Record<string, unknown>)[key];
+  return { ...defs, ...(sub as Record<string, unknown>) };
+}
+
+function deepEqual(a: unknown, b: unknown): boolean {
+  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 as object), kb = Object.keys(b as object);
+  if (ka.length !== kb.length) return false;
+  return ka.every((k) => deepEqual((a as Record<string, unknown>)[k], (b as Record<string, unknown>)[k]));
+}

package/src/kinds.ts

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

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

@@ -11,9 +11,10 @@
 // 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.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";
@@ -43,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");
@@ -74,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
@@ -86,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 [];
@@ -112,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(),
         });
@@ -137,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")) {
@@ -204,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);
@@ -255,7 +290,18 @@ export function deleteLibraryPath(
 
 /** Library tool definitions, keyed by name — http or script, both grantable by name in `tools:`. */
 export function libraryTools(tenant: string): Record<string, ToolDef> {
-  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. */