@foldrun/core 0.2.0 → 0.4.0

package/dist/src/deploy.js

@@ -20,7 +20,7 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import { saveWorkspace, workspaceDir, listRuns, parseFlow, WORKSPACE_DIRS, assertSafeName, } from "./store.js";
+import { saveWorkspace, workspaceDir, listRuns, parseFlow, WORKSPACE_DIRS, assertSafeName, notifyWorkspaceChanged, } from "./store.js";
 import { conformanceIssues } from "./okf.js";
 import { repoDir } from "./gitrepo.js";
 /** Directories a deploy never reads out of a source tree. */
@@ -307,6 +307,8 @@ export function writePushNote(tenant, workspace, note) {
     catch {
         // The note is a record, not the deploy. Losing it must not fail a push.
     }
+    // A push waiting on a run is the scheduler's to apply; tell it there is one.
+    notifyWorkspaceChanged(tenant, workspace, "push");
 }
 /**
  * A push whose deploy was refused only because a run was in flight is not a
@@ -353,7 +355,7 @@ export function deployWorkspace(tenant, workspace, files, opts = {}) {
     const commit = opts.commit ?? null;
     if (commit)
         writeDeployedCommit(tenant, workspace, commit);
-    return { ...plan, applied: true, commit, preserved };
+    return { ...plan, applied: true, commit, preserved }; // saveWorkspace told the platform
 }
 // Which commit a workspace is running.
 //

package/dist/src/egress.d.ts

@@ -1,3 +1,4 @@
+import type { TestEffect } from "./test-mode.ts";
 /** `${NAME}` — the shape a secret reference takes everywhere in foldrun. */
 export declare const PLACEHOLDER: RegExp;
 /** The env var the pod reads to know it should send through a proxy. */
@@ -30,6 +31,11 @@ export interface EgressGrant {
         value: string;
         hosts: string[];
     }>;
+    /** Secret name → the vault entry it came from, as secret-health keys it:
+     *  "account:NAME" or "workspace:<ws>:NAME". Two workspaces each holding an
+     *  API_KEY are two credentials, and one's refusal must not paint the
+     *  other red. Absent for a secret whose origin the runner did not know. */
+    healthKeys?: Record<string, string>;
 }
 export interface EgressLease {
     /** The base the pod sends through: `http://…/e/<token>`. */
@@ -39,21 +45,32 @@ export interface EgressLease {
      *  lease URL first), so a store that is not this process's memory has
      *  to be told when the grant is complete. Call before every attempt. */
     commit(): Promise<void>;
-    /** One line per request, for the run trace. Drained by the runner. */
-    drainLog(): Promise<string[]>;
+    /** One line per request, for the run trace. Drained by the runner. A
+     *  line may carry a test-mode effect beside its text — what the proxy
+     *  refused or redirected on a test lease — for the run page to list. */
+    drainLog(): Promise<EgressLogLine[]>;
     /** The step is over: the lease is void and its values are dropped. */
     release(): Promise<void>;
 }
+export type EgressLogLine = string | {
+    text: string;
+    effect: TestEffect;
+};
 /**
  * The seam the platform fills. `null` from `lease` (or no `egress` at all)
  * means "no proxy here" and the runner falls back to materialising, exactly
  * as it always did.
  */
 export interface EgressHooks {
+    /** `test` — the run is a test run: the proxy applies the outward-write
+     *  policy in test-mode.ts to every request on this lease. Carried on the
+     *  lease, not the request, because the pod is the party not trusted to
+     *  say so. */
     lease(args: {
         tenant: string;
         runId: string;
         grant: EgressGrant;
+        test?: boolean;
     }): Promise<EgressLease | null>;
 }
 /** Strip a header set of the proxy's own and hop-by-hop headers. */

package/dist/src/egress.js

@@ -34,6 +34,7 @@
 // This file is the vocabulary both sides share. The server is the
 // platform's (it needs a long-lived process and a Service); the pod side is
 // here in core, because it is what the runner image runs.
+import { trimSlashes } from "./paths.js";
 /** `${NAME}` — the shape a secret reference takes everywhere in foldrun. */
 export const PLACEHOLDER = /\$\{([A-Z][A-Z0-9_]*)\}/g;
 /** The env var the pod reads to know it should send through a proxy. */
@@ -48,7 +49,7 @@ export const MODEL_KEY_NAME = "FOLDRUN_MODEL_KEY";
 export function viaEgress(egress, target) {
     if (!egress)
         return target;
-    return `${egress.replace(/\/+$/, "")}/${target}`;
+    return `${trimSlashes(egress)}/${target}`;
 }
 /** The names referenced by placeholders in a string. */
 export function placeholderNames(text) {

package/dist/src/evals.d.ts

@@ -38,6 +38,10 @@ export interface EvalInfo {
      *  `manual`: only when a person presses Run or the CLI asks — for a flow
      *  eval that costs a whole run and touches real systems every time. */
     trigger: "deploy" | "manual";
+    /** An eval's runs are test runs — nothing outward, state untouched —
+     *  unless the file says `live: true`. A flow eval that must really send
+     *  to prove itself opts in; nothing opts in by accident. */
+    live: boolean;
     cases: EvalCase[];
 }
 export declare function parseEval(file: string, raw: string): EvalInfo;

package/dist/src/evals.js

@@ -39,7 +39,7 @@ import { spawn } from "node:child_process";
 import { query } from "@anthropic-ai/claude-agent-sdk";
 import { workspaceDir, readRun, writeWorkspaceFile, resolveModel, resolveEffort, assertSafeName, } from "./store.js";
 import { startFlowRun, loadFlow } from "./runner.js";
-import { platform } from "./platform.js";
+import { platform, platformQueues } from "./platform.js";
 const ASSERTION_TYPES = ["contains", "not-contains", "matches", "file", "run", "judge"];
 /**
  * A scalar that may continue onto following lines.
@@ -138,6 +138,7 @@ export function parseEval(file, raw) {
         model: resolveModel(data.model ?? "fast"),
         effort: resolveEffort(data.effort ?? "low"),
         trigger: data.trigger === "manual" ? "manual" : "deploy",
+        live: data.live === true,
         cases,
     };
 }
@@ -226,7 +227,9 @@ export function promoteRunToEval(tenant, workspace, runId, opts = {}) {
     let expect;
     if (opts.expect && opts.expect.length > 0) {
         expect = opts.expect.map((line) => {
-            const m = oneLine(line).match(/^([a-z-]+):\s*(.*)$/);
+            const m = oneLine(line).match(/^([a-z-]+):(.*)$/);
+            if (m)
+                m[2] = m[2].trim();
             if (!m || !ASSERTION_TYPES.includes(m[1]) || !m[2]) {
                 throw refuse(`"${line}" is not an assertion — expected one of ${ASSERTION_TYPES.map((t) => `${t}:`).join(", ")} followed by a value`, 400);
             }
@@ -258,7 +261,7 @@ export function promoteRunToEval(tenant, workspace, runId, opts = {}) {
         if (points.kind !== target.kind || points.name !== target.name) {
             throw refuse(`${rel} tests ${points.kind} ${points.name ?? "(nothing)"}, not ${target.kind} ${target.name} — pick another evalName`, 409);
         }
-        content = `${existing.replace(/\s+$/, "")}\n\n${caseText}`;
+        content = `${existing.trimEnd()}\n\n${caseText}`;
     }
     else {
         // A flow eval costs a whole run and touches real systems, so it waits
@@ -285,19 +288,23 @@ export function promoteRunToEval(tenant, workspace, runId, opts = {}) {
     });
     return { file: rel, created: !existing, caseName };
 }
-/** Wait for a run to finish, with a ceiling so a hung agent can't hang an eval. */
 /**
  * A web replica never drives a run: it has no route to the cluster API and
  * no right to create a pod, by design — so an eval started there (a push,
  * the Run button) queues its run for the worker like any other. From 29 Aug
  * every eval on the split platform died at "pod create failed: connection
  * refused" for exactly this reason. A single process — the CLI, a laptop,
- * FOLDRUN_ROLE unset — still drives it right here, as it always did.
+ * no platform registered — still drives it right here, as it always did.
+ *
+ * The test is whether a platform owns the queue, not which role this
+ * process was started as: on a worker the role read "worker", the eval
+ * started its run in-process, and the run never passed through the
+ * account cap or the lanes the platform enforces on every other run.
  */
-const runsViaQueue = () => process.env.FOLDRUN_ROLE === "web";
-async function beginEvalRun(tenant, workspace, steps, flowName, model, effort) {
+const runsViaQueue = () => platformQueues();
+async function beginEvalRun(tenant, workspace, steps, flowName, model, effort, test = true) {
     if (!runsViaQueue())
-        return startFlowRun(tenant, workspace, steps, flowName, model, [], effort);
+        return startFlowRun(tenant, workspace, steps, flowName, model, [], effort, null, { test });
     // The job carries a model override but no effort one, and driveRun cannot
     // re-read a flow called `eval:<name>`. Put the flow's defaults onto the
     // steps that have none — which is what nearest-wins resolves to anyway.
@@ -306,7 +313,7 @@ async function beginEvalRun(tenant, workspace, steps, flowName, model, effort) {
         ...(s.model || !model ? {} : { model }),
         ...(s.effort || !effort ? {} : { effort }),
     }));
-    return platform.enqueueFlowRun(tenant, workspace, withDefaults, flowName, model ?? null, []);
+    return platform.enqueueFlowRun(tenant, workspace, withDefaults, flowName, model ?? null, [], null, { test });
 }
 // Waits for as long as the run runs. There was a cap here (5 minutes, then
 // 30) and it marked a flow eval "run disappeared" at the cap while the flow
@@ -428,12 +435,14 @@ export async function runEval(tenant, workspace, info) {
                 const steps = flow.steps.map((s, i) => i === 0
                     ? { ...s, instruction: `${s.instruction}\n\n<run_task>\n${testCase.task}\n</run_task>` }
                     : s);
-                run = await beginEvalRun(tenant, workspace, steps, `eval:${info.name}`, flow.model, flow.effort);
+                // Test unless the eval OR the flow says live: an eval that runs a
+                // flow written `live: true` was written by someone who knew.
+                run = await beginEvalRun(tenant, workspace, steps, `eval:${info.name}`, flow.model, flow.effort, !(info.live || flow.live));
             }
             else {
                 if (!target)
                     throw new Error("this eval names neither an agent nor a flow");
-                run = await beginEvalRun(tenant, workspace, [{ agent: target, instruction: testCase.task, group: 1, optional: false }], `eval:${info.name}`);
+                run = await beginEvalRun(tenant, workspace, [{ agent: target, instruction: testCase.task, group: 1, optional: false }], `eval:${info.name}`, undefined, undefined, !info.live);
             }
             runId = run.id;
             const finished = await waitForRun(tenant, workspace, run.id);

package/dist/src/flow-lint.d.ts

@@ -6,6 +6,10 @@ export interface FlowWarning {
     line?: number;
     message: string;
     detail: string;
+    /** "error" for a value the parser could not read — `timeout: abc` — which
+     *  `foldrun check` must fail on rather than note. Absent means advisory,
+     *  which every structural warning in this file is. */
+    level?: "error" | "warn";
 }
 /** What exists in the workspace, when the caller knows. Optional: the lint
  *  is useful without it, and a caller that has the lists gets the reference

package/dist/src/flow-lint.js

@@ -14,6 +14,18 @@
 // Deliberately conservative — a false warning is worse than a missed one,
 // because noisy warnings get ignored and then the real one is invisible too.
 const REFERS_BACK = /\b(both|above|earlier|previous(ly)?|prior|the (changes|draft|research|results|findings|report|article|fixes|work)|what (they|the others?) (found|shipped|wrote|said))\b/i;
+/** One @, something either side, a dot in the domain, no whitespace. Written
+ *  as string checks rather than a regex: the obvious pattern backtracks
+ *  polynomially on a domain full of dots, and a lint that can be made slow
+ *  by a flow file is a lint someone will turn off. */
+function looksLikeAddress(a) {
+    const at = a.indexOf("@");
+    if (at < 1 || at !== a.lastIndexOf("@") || /\s/.test(a))
+        return false;
+    const domain = a.slice(at + 1);
+    const dot = domain.indexOf(".");
+    return dot > 0 && dot < domain.length - 1;
+}
 export function lintFlow(flow, known) {
     const warnings = [];
     const agentNames = known ? new Set(known.agents) : null;
@@ -25,6 +37,68 @@ export function lintFlow(flow, known) {
     // eleven runs where one was meant. Nothing about the expression looks wrong,
     // which is exactly why it needs saying here rather than being discovered on
     // the bill.
+    // An approvers list only one word can satisfy. `approvers: [editors]` is
+    // a role that is not `admins` and not an address; mayApprove would then
+    // refuse every person, and the gate could only ever be answered by an
+    // emailed link. Said here rather than discovered at the gate.
+    const odd = (flow.approvers ?? []).filter((a) => a !== "admins" && !looksLikeAddress(a));
+    if (odd.length) {
+        warnings.push({
+            step: null,
+            message: `approvers: ${odd.join(", ")} — not an email address, and the only role word is admins`,
+            detail: "Each entry is an address that may answer this flow's gates, or the word `admins`. Anything else matches nobody, and a list nobody matches locks every gate.",
+        });
+    }
+    // A flow with an approvers list and no gate at all is a rule the author
+    // believes is in force and which does nothing — the worst kind of safety
+    // control.
+    if (flow.approvers?.length && !flow.steps.some((s) => s.approve || s.ask)) {
+        warnings.push({
+            step: null,
+            message: "approvers: is set but no step in this flow is a gate",
+            detail: "Nothing here waits for a person, so the list has no effect. Mark the step that needs " +
+                "a second pair of eyes with `!` (or `approve: true`), or drop the approvers: line.",
+        });
+    }
+    // A deadline on a gate that does not exist reads as a safety net and is not
+    // one. Same reasoning, said separately because the fix is different.
+    if (flow.approveWithin && !flow.steps.some((s) => s.approve || s.ask)) {
+        warnings.push({
+            step: null,
+            message: "approve_within: is set but no step in this flow is a gate",
+            detail: "Nothing waits for a person, so nothing can expire. Mark a step with `!`, or drop the line.",
+        });
+    }
+    // A throttle no schedule can ever trip: the flow cannot run more often
+    // than its cron fires, so a floor below that interval never fires either.
+    // Cheap to write, silently pointless, and a reader will believe it.
+    if (flow.throttle && flow.trigger === "schedule" && flow.schedule) {
+        warnings.push({
+            step: null,
+            message: `throttle: on a scheduled flow — check it is shorter than the schedule, or it will drop runs you meant to happen`,
+            detail: "A schedule already decides how often this runs. A throttle longer than the gap between " +
+                "fires silently skips them; if that is what you want, say it in the cron instead.",
+        });
+    }
+    // `idempotency:` only has a delivery to read on a trigger that receives
+    // one. On a schedule or a chained flow there is no request and no field,
+    // so the key is inert.
+    if (flow.idempotency && flow.trigger !== "webhook" && flow.trigger !== "email") {
+        warnings.push({
+            step: null,
+            message: `idempotency: has nothing to read on trigger: ${flow.trigger}`,
+            detail: "A delivery id comes off an incoming request, so this only does something for " +
+                "trigger: webhook or trigger: email. On any other trigger it is ignored.",
+        });
+    }
+    // `catchup:` is about a fire that was missed, which only a clock can miss.
+    if (flow.catchup && flow.trigger !== "schedule") {
+        warnings.push({
+            step: null,
+            message: `catchup: has no effect on trigger: ${flow.trigger}`,
+            detail: "Only a schedule can miss a fire. Every other trigger happens when it happens.",
+        });
+    }
     if (flow.schedule) {
         const [, , dom, , dow] = flow.schedule.trim().split(/\s+/);
         if (dom && dow && dom !== "*" && dow !== "*") {
@@ -39,6 +113,9 @@ export function lintFlow(flow, known) {
     }
     // Trigger shapes that can never fire, said at check time rather than
     // discovered as a flow that "never runs".
+    if (flow.budgetProblem) {
+        warnings.push({ step: null, message: flow.budgetProblem, detail: "A flow's `budget:` is the most one run may spend — a number in USD, or `unlimited`. A cap over a day, week or month belongs in the workspace's or the account's AGENTS.md, where it means every run put together." });
+    }
     if (flow.trigger === "once" && !flow.at) {
         warnings.push({ step: null, message: "trigger: once needs an `at:` instant", detail: "Write `at: 2026-09-05T09:00:00+10:00` (ISO 8601). Without a readable instant this flow never fires." });
     }
@@ -62,6 +139,20 @@ export function lintFlow(flow, known) {
     const firstGroup = Math.min(...flow.steps.map((s) => s.group));
     flow.steps.forEach((step, i) => {
         const inFirstGroup = step.group === firstGroup;
+        // A value the parser refused. Not advisory: the run would go ahead on
+        // a number the author never wrote — `timeout: 15m` ran as one second
+        // for as long as this was a coercion — so the check fails instead.
+        for (const problem of step.problems ?? []) {
+            warnings.push({
+                step: i,
+                line: step.line,
+                level: "error",
+                message: problem,
+                detail: "The option is written but its value cannot be read, and a run would not do what the " +
+                    "line says. Durations are seconds or 90s / 30m / 4h / 3d; counts are whole numbers " +
+                    "within the key's cap (retry and loop at most 5, max at most 20).",
+            });
+        }
         // The first group starts with context = null. An instruction that points
         // at earlier output therefore points at nothing.
         if (inFirstGroup && step.instruction && REFERS_BACK.test(step.instruction)) {
@@ -102,6 +193,23 @@ export function lintFlow(flow, known) {
                 });
             }
         }
+        // Two options that read another option to mean anything.
+        if (step.parallel && !step.each) {
+            warnings.push({
+                step: i,
+                line: step.line,
+                message: `"${step.subflow ?? step.agent}" has parallel: but no each:`,
+                detail: "parallel: caps how many instances of a fan-out run at once. Without each: there is one instance, and the line does nothing.",
+            });
+        }
+        if ((step.schema !== undefined || step.schemaPath) && step.output !== "json") {
+            warnings.push({
+                step: i,
+                line: step.line,
+                message: `"${step.subflow ?? step.agent}" has schema: but no output: json`,
+                detail: "schema: describes the JSON value an output: json step returns. Without output: json nothing is parsed, so nothing is checked. Add `output: json`.",
+            });
+        }
         // A step's OTHER agent references — the ones no parser validates,
         // because they are options rather than the step's target. Both fail
         // silently and at the worst possible moment: a misspelled `delegate:`

package/dist/src/host-env.d.ts

@@ -0,0 +1,8 @@
+/** Does this name pass the allowlist? Exported so a test can pin the rule
+ *  rather than the list. */
+export declare function hostEnvAllowed(name: string): boolean;
+/**
+ * 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 declare function hostSafeEnv(from?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;

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/library.js

@@ -10,6 +10,7 @@
 // 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";
@@ -213,7 +214,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) {