@valbuild/server 0.114.0 → 0.116.0

package/dist/valbuild-server.cjs.dev.js

@@ -17,6 +17,7 @@ var z = require('zod');
 var sizeOf = require('image-size');
 var zodValidationError = require('zod-validation-error');
 var os = require('os');
+var node_crypto = require('node:crypto');
 var sucrase = require('sucrase');
 var http = require('http');
 var https = require('https');
@@ -1040,7 +1041,7 @@ function errorMessage(e) {
   return String(e);
 }
 
-const jsonOps$2 = new patch.JSONOps();
+const jsonOps$3 = new patch.JSONOps();
 
 /**
  * Classification of a single patch op against a module's serialized schema,
@@ -1295,7 +1296,7 @@ function applyJsonValuesEntryPatches(args) {
           // on an entry that does not exist.
           continue;
         }
-        const applied = patch.applyPatch(patch.deepClone(content), jsonOps$2, [{
+        const applied = patch.applyPatch(patch.deepClone(content), jsonOps$3, [{
           op: "add",
           path: cls.subPath.concat(...(op.nestedFilePath ?? [])).concat("patch_id"),
           value: patchId
@@ -1349,7 +1350,7 @@ function applyJsonValuesEntryPatches(args) {
           patchId
         };
       }
-      const applied = patch.applyPatch(patch.deepClone(content), jsonOps$2, [rebased.value]);
+      const applied = patch.applyPatch(patch.deepClone(content), jsonOps$3, [rebased.value]);
       if (fp.result.isErr(applied)) {
         return {
           kind: "error",
@@ -1632,7 +1633,7 @@ function findJsonEntryFilePath(moduleFilePath, valTsSourceFile, entryKey) {
   return resolveExistingJsonPath(moduleFilePath, entry.importPath);
 }
 
-const jsonOps$1 = new patch.JSONOps();
+const jsonOps$2 = new patch.JSONOps();
 
 /**
  * Substitutes loaded `.jsonValues()` entry content back into a module's root
@@ -1923,7 +1924,7 @@ class Service {
       if (fp.result.isErr(rebased)) {
         throw Error(`Could not apply ${op.op} to jsonValues entry '${entryKey}' of ${moduleFilePath}: ${rebased.error.message}`);
       }
-      const applied = patch.applyPatch(patch.deepClone(content), jsonOps$1, [rebased.value]);
+      const applied = patch.applyPatch(patch.deepClone(content), jsonOps$2, [rebased.value]);
       if (fp.result.isErr(applied)) {
         throw Error(`Could not apply ${op.op} to ${jsonPath}: ${applied.error.message}`);
       }
@@ -2092,7 +2093,7 @@ function encodeJwt(payload, sessionKey) {
 }
 
 /* eslint-disable @typescript-eslint/no-unused-vars */
-const jsonOps = new patch.JSONOps();
+const jsonOps$1 = new patch.JSONOps();
 const tsOps = new TSOps(document => {
   return fp.pipe(analyzeValModule(document), fp.result.map(({
     source
@@ -2861,7 +2862,7 @@ class ValOps {
         }
         const patchRes = patch.applyPatch(patch.deepClone(patchedSources[path]),
         // applyPatch mutates the source. On add operations it adds more than once? There is something strange going on... deepClone seems to fix, but is that the right solution?
-        jsonOps, applicableOps.concat(...Object.values(fileFixOps)));
+        jsonOps$1, applicableOps.concat(...Object.values(fileFixOps)));
         if (fp.result.isErr(patchRes)) {
           console.error("Could not apply patch", JSON.stringify({
             path,
@@ -3561,7 +3562,7 @@ class ValOps {
               patchHadError = true;
               break;
             }
-            const applied = patch.applyPatch(patch.deepClone(contentRes.value), jsonOps, [rebasedRes.value]);
+            const applied = patch.applyPatch(patch.deepClone(contentRes.value), jsonOps$1, [rebasedRes.value]);
             if (fp.result.isErr(applied)) {
               collectPatchError(applied.error, patchId, op);
               patchHadError = true;
@@ -7467,6 +7468,227 @@ async function getSettings(projectName, auth) {
   }
 }
 
+/**
+ * Resolving how Val is configured, and building the data layer from it.
+ *
+ * Both live here rather than inside `createValApiRouter` because the MCP tool
+ * registry needs exactly the same answers: which mode we are in, which
+ * credential to use, and which `ValOps` implementation that implies. Two copies
+ * of this would drift, and the failure would be quiet — a registry that decides
+ * it is in fs mode while the Studio decides it is in proxy mode reads different
+ * content from the same project.
+ *
+ * The type-only import from `./ValRouter` is deliberate: it keeps `ValApiOptions`
+ * where its documentation lives without creating a runtime cycle.
+ *
+ * The credential-bearing URL check at the bottom of this file lives here for the
+ * same reason: it is a check on the URLs `initHandlerOptions` resolves, and its
+ * only caller is that function. Leaving it in `./ValRouter` would have meant
+ * importing it back from there, which is the runtime cycle the paragraph above
+ * exists to avoid.
+ */
+
+const DEFAULT_VAL_BUILD_URL = "https://admin.val.build";
+
+/**
+ * Resolve options plus environment into a concrete {@link ValServerConfig}.
+ *
+ * Moved verbatim out of `createValApiRouter`; the precedence rules are load
+ * bearing, so this is the one place they are written down. Note that "proxy"
+ * mode is inferred when `VAL_API_KEY` or `VAL_SECRET` is present and no mode was
+ * given, which is why a project can be pushed into proxy mode by setting an env
+ * var alone.
+ */
+async function initHandlerOptions(route, opts, config) {
+  const maybeApiKey = opts.apiKey || process.env.VAL_API_KEY;
+  const maybeValSecret = opts.valSecret || process.env.VAL_SECRET;
+  const isProxyMode = opts.mode === "proxy" || opts.mode === undefined && (maybeApiKey || maybeValSecret);
+  const valEnableRedirectUrl = opts.valEnableRedirectUrl || process.env.VAL_ENABLE_REDIRECT_URL;
+  const valDisableRedirectUrl = opts.valDisableRedirectUrl || process.env.VAL_DISABLE_REDIRECT_URL;
+  const maybeValProject = opts.project || process.env.VAL_PROJECT;
+  const valBuildUrl = opts.valBuildUrl || process.env.VAL_BUILD_URL || DEFAULT_VAL_BUILD_URL;
+  const valContentUrl = opts.valContentUrl || process.env.VAL_CONTENT_URL || core.DEFAULT_CONTENT_HOST;
+  warnIfInsecureUrls({
+    valBuildUrl,
+    valContentUrl
+  });
+  if (isProxyMode) {
+    var _opts$versions, _opts$versions2;
+    if (!maybeApiKey || !maybeValSecret) {
+      throw new Error("VAL_API_KEY and VAL_SECRET env vars must both be set in proxy mode");
+    }
+    const maybeGitCommit = opts.gitCommit || process.env.VAL_GIT_COMMIT;
+    if (!maybeGitCommit) {
+      throw new Error("VAL_GIT_COMMIT env var must be set in proxy mode");
+    }
+    const maybeGitBranch = opts.gitBranch || process.env.VAL_GIT_BRANCH;
+    if (!maybeGitBranch) {
+      throw new Error("VAL_GIT_BRANCH env var must be set in proxy mode");
+    }
+    if (!maybeValProject) {
+      throw new Error("Proxy mode does not work unless the 'project' option in val.config is defined or the VAL_PROJECT env var is set.");
+    }
+    const coreVersion = (_opts$versions = opts.versions) === null || _opts$versions === void 0 ? void 0 : _opts$versions.core;
+    if (!coreVersion) {
+      throw new Error("Could not determine version of @valbuild/core");
+    }
+    const nextVersion = (_opts$versions2 = opts.versions) === null || _opts$versions2 === void 0 ? void 0 : _opts$versions2.next;
+    if (!nextVersion) {
+      throw new Error("Could not determine version of @valbuild/next");
+    }
+    return {
+      mode: "http",
+      route,
+      apiKey: maybeApiKey,
+      valSecret: maybeValSecret,
+      commit: maybeGitCommit,
+      branch: maybeGitBranch,
+      root: opts.root,
+      project: maybeValProject,
+      valEnableRedirectUrl,
+      valDisableRedirectUrl,
+      valContentUrl,
+      valBuildUrl,
+      config
+    };
+  } else {
+    const cwd = process.cwd();
+    const valBuildUrl = opts.valBuildUrl || process.env.VAL_BUILD_URL || DEFAULT_VAL_BUILD_URL;
+    return {
+      mode: "fs",
+      cwd,
+      route,
+      valDisableRedirectUrl,
+      valEnableRedirectUrl,
+      valBuildUrl,
+      valContentUrl,
+      apiKey: maybeApiKey,
+      valSecret: maybeValSecret,
+      project: maybeValProject,
+      config
+    };
+  }
+}
+
+/**
+ * Build the data layer a {@link ValServerConfig} calls for.
+ *
+ * `auth` decides *whose* credential the http backend sees. Left out, it is the
+ * app's own API key — which is what the Studio wants, because there the app has
+ * already verified a session cookie and is acting on the user's behalf under its
+ * own authority.
+ *
+ * A caller acting for a user it has *not* authenticated itself must pass that
+ * user's personal access token instead, so the backend is the one that decides
+ * what the caller may do. That is the whole of `docs/plans/mcp.md` D.2: the app
+ * stops being an authority and goes back to being a pipe. Passing the app's API
+ * key on such a request is the D.6 confused deputy, and it is worth being blunt
+ * about why it is tempting — it works, and it works for every project the key
+ * can reach, including the ones the caller cannot.
+ */
+function createValOps(valModules, options, auth) {
+  if (options.mode === "fs") {
+    // No credential in fs mode: this reads and writes the developer's own
+    // working tree, and there is no backend to authenticate to. A PAT handed in
+    // here is not ignored quietly — the caller is told, in createValTools.
+    return new ValOpsFS(options.valContentUrl, options.cwd, valModules, {
+      formatter: options.formatter,
+      config: options.config
+    });
+  }
+  if (options.mode === "http") {
+    return new ValOpsHttp(options.valContentUrl, options.project, options.commit, options.branch, auth ?? {
+      apiKey: options.apiKey
+    }, valModules, {
+      formatter: options.formatter,
+      root: options.root,
+      config: options.config
+    });
+  }
+  throw new Error(
+  // The union is exhausted above; this catches a config that came from
+  // somewhere untyped.
+  "Invalid mode: " + (options === null || options === void 0 ? void 0 : options.mode));
+}
+
+/**
+ * Hosts we send credentials to, and what each one puts at risk. They differ:
+ * only `valBuildUrl` hands back the app token that becomes the session cookie,
+ * so a single shared sentence would overstate one and understate the other.
+ */
+
+const CREDENTIAL_BEARING_URLS = ["valBuildUrl", "valContentUrl"];
+const WHAT_IS_AT_RISK = {
+  valBuildUrl: "Val's api key is sent to this host, and the token it returns is what this server signs into the session cookie, " + "so both can be read - and the token replaced - by anyone on the network path.",
+  valContentUrl: "Val's api key, or the caller's personal access token, is sent to this host, " + "so it can be read by anyone on the network path."
+};
+
+// NOTE: `URL.hostname` keeps the brackets on an IPv6 literal, so this is
+// "[::1]" and not "::1" - and `http://[0:0:0:0:0:0:0:1]` normalises to the
+// same short form before it gets here. Dropping the brackets looks like a
+// tidy-up and silently stops matching IPv6 loopback.
+const LOOPBACK_HOSTNAMES = ["localhost", "127.0.0.1", "[::1]"];
+
+/**
+ * The URL as it is safe to print. `http://user:pass@host` is a legal override,
+ * and a warning about credential exposure that puts the password in the log
+ * would be the very thing it is warning about.
+ */
+function forLog(parsed) {
+  if (!parsed.username && !parsed.password) {
+    return parsed.href;
+  }
+  const redacted = new URL(parsed.href);
+  redacted.username = "";
+  redacted.password = "";
+  return `${redacted.href} (credentials redacted)`;
+}
+
+/**
+ * Returns a warning if `url` would send credentials somewhere they can be read
+ * off the wire, or null if it is fine.
+ *
+ * Both URLs default to https, but each is overridable - `opts.valBuildUrl` /
+ * `VAL_BUILD_URL`, `opts.valContentUrl` / `VAL_CONTENT_URL` - and neither
+ * override has ever been scheme-checked. Point one at a plain http host and the
+ * api key goes out in clear text, and whatever comes back is whatever the
+ * network says: for `valBuildUrl` that includes the app token this server
+ * re-signs into the session cookie.
+ *
+ * Loopback over http is exempt: that is a val.build running on the developer's
+ * own machine, and there is no network to be on the wrong side of.
+ *
+ * This warns rather than throws. Both overrides are set by the operator, not by
+ * an attacker, so this is a misconfiguration to surface - not untrusted input to
+ * reject - and refusing to boot would break anyone deliberately pointing at an
+ * internal http host today.
+ */
+function insecureUrlWarning(name, url) {
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    // NOTE: the URL is not echoed here. It did not parse, so there is nothing
+    // to redact with, and an unparseable string can still hold a password.
+    return `Val: ${name} is not a valid URL.`;
+  }
+  if (parsed.protocol === "https:") {
+    return null;
+  }
+  if (parsed.protocol === "http:" && (LOOPBACK_HOSTNAMES.includes(parsed.hostname) || parsed.hostname.endsWith(".localhost"))) {
+    return null;
+  }
+  return `Val: ${name} is set to ${forLog(parsed)}, which is not https. ` + `${WHAT_IS_AT_RISK[name]} ` + `Use https, or a loopback address for local development.`;
+}
+function warnIfInsecureUrls(urls) {
+  for (const name of CREDENTIAL_BEARING_URLS) {
+    const warning = insecureUrlWarning(name, urls[name]);
+    if (warning) {
+      console.warn(warning);
+    }
+  }
+}
+
 function getPersonalAccessTokenPath(root) {
   return path__namespace["default"].join(path__namespace["default"].resolve(root), ".val", "pat.json");
 }
@@ -7540,24 +7762,7 @@ const ValServer = (valModules, options, callbacks) => {
       }).nullable()
     }))
   });
-  let serverOps;
-  if (options.mode === "fs") {
-    serverOps = new ValOpsFS(options.valContentUrl, options.cwd, valModules, {
-      formatter: options.formatter,
-      config: options.config
-    });
-  } else if (options.mode === "http") {
-    serverOps = new ValOpsHttp(options.valContentUrl, options.project, options.commit, options.branch, {
-      apiKey: options.apiKey
-    }, valModules, {
-      formatter: options.formatter,
-      root: options.root,
-      config: options.config
-    });
-  } else {
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    throw new Error("Invalid mode: " + (options === null || options === void 0 ? void 0 : options.mode));
-  }
+  const serverOps = createValOps(valModules, options);
   const getAuthorizeUrl = (publicValApiRe, token) => {
     if (!options.project) {
       throw new Error("Project is not set");
@@ -10338,72 +10543,6 @@ async function createValServer(valModules, route, opts, config, callbacks, forma
     ...valServerConfig
   }, callbacks);
 }
-async function initHandlerOptions(route, opts, config) {
-  const maybeApiKey = opts.apiKey || process.env.VAL_API_KEY;
-  const maybeValSecret = opts.valSecret || process.env.VAL_SECRET;
-  const isProxyMode = opts.mode === "proxy" || opts.mode === undefined && (maybeApiKey || maybeValSecret);
-  const valEnableRedirectUrl = opts.valEnableRedirectUrl || process.env.VAL_ENABLE_REDIRECT_URL;
-  const valDisableRedirectUrl = opts.valDisableRedirectUrl || process.env.VAL_DISABLE_REDIRECT_URL;
-  const maybeValProject = opts.project || process.env.VAL_PROJECT;
-  const valBuildUrl = opts.valBuildUrl || process.env.VAL_BUILD_URL || "https://admin.val.build";
-  const valContentUrl = opts.valContentUrl || process.env.VAL_CONTENT_URL || core.DEFAULT_CONTENT_HOST;
-  if (isProxyMode) {
-    var _opts$versions, _opts$versions2;
-    if (!maybeApiKey || !maybeValSecret) {
-      throw new Error("VAL_API_KEY and VAL_SECRET env vars must both be set in proxy mode");
-    }
-    const maybeGitCommit = opts.gitCommit || process.env.VAL_GIT_COMMIT;
-    if (!maybeGitCommit) {
-      throw new Error("VAL_GIT_COMMIT env var must be set in proxy mode");
-    }
-    const maybeGitBranch = opts.gitBranch || process.env.VAL_GIT_BRANCH;
-    if (!maybeGitBranch) {
-      throw new Error("VAL_GIT_BRANCH env var must be set in proxy mode");
-    }
-    if (!maybeValProject) {
-      throw new Error("Proxy mode does not work unless the 'project' option in val.config is defined or the VAL_PROJECT env var is set.");
-    }
-    const coreVersion = (_opts$versions = opts.versions) === null || _opts$versions === void 0 ? void 0 : _opts$versions.core;
-    if (!coreVersion) {
-      throw new Error("Could not determine version of @valbuild/core");
-    }
-    const nextVersion = (_opts$versions2 = opts.versions) === null || _opts$versions2 === void 0 ? void 0 : _opts$versions2.next;
-    if (!nextVersion) {
-      throw new Error("Could not determine version of @valbuild/next");
-    }
-    return {
-      mode: "http",
-      route,
-      apiKey: maybeApiKey,
-      valSecret: maybeValSecret,
-      commit: maybeGitCommit,
-      branch: maybeGitBranch,
-      root: opts.root,
-      project: maybeValProject,
-      valEnableRedirectUrl,
-      valDisableRedirectUrl,
-      valContentUrl,
-      valBuildUrl,
-      config
-    };
-  } else {
-    const cwd = process.cwd();
-    const valBuildUrl = opts.valBuildUrl || process.env.VAL_BUILD_URL || "https://admin.val.build";
-    return {
-      mode: "fs",
-      cwd,
-      route,
-      valDisableRedirectUrl,
-      valEnableRedirectUrl,
-      valBuildUrl,
-      valContentUrl,
-      apiKey: maybeApiKey,
-      valSecret: maybeValSecret,
-      project: maybeValProject,
-      config
-    };
-  }
-}
 
 // TODO: remove
 async function safeReadGit(cwd) {
@@ -10697,32 +10836,1159 @@ function getCookies(req, cookiesDef) {
   return z.z.object(cookiesDef).safeParse(input);
 }
 
-const JsFileLookupMapping = [
-// NOTE: first one matching will be used
-[".cjs.d.ts", [".esm.js", ".mjs.js"]], [".cjs.js", [".esm.js", ".mjs.js"]], [".cjs", [".mjs"]], [".d.ts", [".js", ".esm.js", ".mjs.js"]]];
-const MAX_CACHE_SIZE = 100 * 1024 * 1024; // 100 mb
-const MAX_OBJECT_KEY_SIZE = 2 ** 27; // https://stackoverflow.com/questions/13367391/is-there-a-limit-on-length-of-the-key-string-in-js-object
+/**
+ * How a tool is written, and what it is handed.
+ *
+ * Tools are defined with {@link defineTool} so that the handler's `args` are
+ * inferred from the tool's own `inputSchema`. Without that the array of tools
+ * would have to be typed at its widest and every handler would start by
+ * re-narrowing `unknown`, which is exactly where a tool and its schema drift
+ * apart unnoticed.
+ */
 
-class ValModuleLoader {
-  constructor(projectRoot, compilerOptions,
-  // TODO: remove this?
-  sourceFileHandler, host = {
-    ...ts__default["default"].sys,
-    writeFile: (fileName, data, encoding) => {
-      fs__default["default"].mkdirSync(path__namespace["default"].dirname(fileName), {
-        recursive: true
-      });
-      fs__default["default"].writeFileSync(fileName, typeof data === "string" ? data : new Uint8Array(data), encoding);
-    },
-    rmFile: fs__default["default"].rmSync,
-    readBuffer: fileName => {
-      try {
-        return fs__default["default"].readFileSync(fileName);
-      } catch {
-        return undefined;
-      }
+/** Everything a tool is allowed to reach. Deliberately narrow. */
+
+/**
+ * Declare a tool, binding its handler to its input schema.
+ *
+ * The handler receives already-parsed arguments: the registry validates against
+ * `inputSchema` before calling, so a handler never sees input its schema would
+ * have rejected.
+ */
+function defineTool(definition, handler) {
+  return {
+    ...definition,
+    handler: (args, deps) => handler(args, deps)
+  };
+}
+function ok(data) {
+  return {
+    status: "ok",
+    data
+  };
+}
+function err(code, message) {
+  return {
+    status: "error",
+    code,
+    message
+  };
+}
+
+/**
+ * The tools that only read.
+ *
+ * Names match the Studio's chat tools exactly. MCP clients namespace by server,
+ * so there is no `val_` prefix to add, and keeping the names identical means
+ * converging the two definitions later is a move rather than a rename.
+ *
+ * All of these read from `deps.state`, which already has pending patches
+ * applied — an agent should see the content as the Studio would show it, not the
+ * last published version.
+ */
+
+const ModuleFilePathSchema$1 = z.z.string().describe('Path of the Val module, e.g. "/content/pages.val.ts". Use get_all_schema to discover these.');
+function readTools() {
+  return [defineTool({
+    name: "get_all_schema",
+    title: "Get all schemas",
+    description: "List every Val module in the project and its schema. Start here: the module paths this returns are what every other tool takes.",
+    inputSchema: z.z.object({}),
+    annotations: {
+      readOnlyHint: true,
+      idempotentHint: true
+    }
+  }, async (_args, {
+    state
+  }) => ok(state.serializedSchemas)), defineTool({
+    name: "get_source",
+    title: "Get source",
+    description: "Read the content of one Val module, with any unpublished changes already applied.",
+    inputSchema: z.z.object({
+      moduleFilePath: ModuleFilePathSchema$1
+    }),
+    annotations: {
+      readOnlyHint: true,
+      idempotentHint: true
+    }
+  }, async ({
+    moduleFilePath
+  }, {
+    state
+  }) => {
+    const path = moduleFilePath;
+    if (!(path in state.serializedSchemas)) {
+      return err("not-found", unknownModuleMessage(path, state));
+    }
+    const source = state.sources[path];
+    return ok(source === undefined ? null : source);
+  }), defineTool({
+    name: "get_record_keys",
+    title: "Get record keys",
+    description: "List the keys of the record or object at a path inside a module, a page at a time. Use this to enumerate entries without reading their contents — and before adding one, so you do not collide with an existing key. Fails on arrays, galleries, richtext and primitives: use count_entries for an array or richtext length, and get_source to read a gallery.",
+    inputSchema: z.z.object({
+      moduleFilePath: ModuleFilePathSchema$1,
+      path: z.z.array(z.z.string()).default([]).describe("Path within the module to the record or object. Empty means the module root."),
+      // Clamped by the schema rather than in the handler: a negative offset
+      // makes `slice` read from the END and a negative limit makes it drop
+      // the last N, so either would return a window that is not the page
+      // asked for while `total` alongside implied it was.
+      limit: z.z.number().int().min(1).default(100).describe("Maximum number of keys to return."),
+      offset: z.z.number().int().min(0).default(0).describe("Number of keys to skip, for paging.")
+    }),
+    annotations: {
+      readOnlyHint: true,
+      idempotentHint: true
     }
-  }, disableCache = false) {
+  }, async ({
+    moduleFilePath,
+    path,
+    limit,
+    offset
+  }, {
+    state
+  }) => {
+    const described = describeContainer(state, moduleFilePath, path);
+    if (described.kind !== "ok") {
+      return described.result;
+    }
+    const {
+      container,
+      value
+    } = described;
+    // Records and objects only, matching the Studio's tool of the same name.
+    // A gallery's keys are file paths whose bytes live elsewhere, and
+    // richtext blocks are positional — neither is a key set to hand back.
+    if (container !== "record" && container !== "object" || !isPlainObject(value)) {
+      return err("invalid-args", `The value at that path is ${article(container)} ${container}. get_record_keys only works on a record or an object — ${container === "array" ? "use count_entries for the array length" : container === "richtext" ? "use count_entries for the number of blocks" : "use get_source to read the gallery's entries"}.`);
+    }
+    const keys = Object.keys(value);
+    return ok({
+      kind: container,
+      keys: keys.slice(offset, offset + limit),
+      // The unpaged size, so a caller can tell a short page from the end of
+      // the record without asking for another one.
+      total: keys.length
+    });
+  }), defineTool({
+    name: "count_entries",
+    title: "Count entries",
+    description: "Count the entries at a path inside a module — record or gallery keys, object fields, array indices, or top-level richtext blocks — without reading them. Use this to answer 'how many?' or to size a record before paging through it.",
+    inputSchema: z.z.object({
+      moduleFilePath: ModuleFilePathSchema$1,
+      path: z.z.array(z.z.string()).default([]).describe("Path within the module to count at. Empty means the module root.")
+    }),
+    annotations: {
+      readOnlyHint: true,
+      idempotentHint: true
+    }
+  }, async ({
+    moduleFilePath,
+    path
+  }, {
+    state
+  }) => {
+    const described = describeContainer(state, moduleFilePath, path);
+    if (described.kind !== "ok") {
+      return described.result;
+    }
+    const {
+      container,
+      value
+    } = described;
+    // Every container `describeContainerAtPath` admits can be counted, so
+    // unlike get_record_keys this does not narrow further. Non-containers
+    // never get this far.
+    if (Array.isArray(value)) {
+      return ok({
+        kind: container,
+        count: value.length
+      });
+    }
+    if (isPlainObject(value)) {
+      return ok({
+        kind: container,
+        count: Object.keys(value).length
+      });
+    }
+    return err("invalid-args", `The value at that path is ${article(container)} ${container}, which has nothing to count.`);
+  }), defineTool({
+    name: "validate_content",
+    title: "Validate content",
+    description: "Check the project's content against its schemas, including unpublished changes. Returns only errors that would block publishing.",
+    inputSchema: z.z.object({
+      moduleFilePath: ModuleFilePathSchema$1.optional().describe("Limit the check to one module. Omit to validate everything.")
+    }),
+    annotations: {
+      readOnlyHint: true
+    }
+  }, async ({
+    moduleFilePath
+  }, {
+    ops,
+    state
+  }) => {
+    const validation = await ops.validateSources(state.schemas, state.sources,
+    // Every module. The third argument filters which modules are
+    // validated at all, so passing the pending-patch analysis would make
+    // a project with no pending changes report `valid: true` without
+    // having checked anything. Scoping to one module, when asked, is done
+    // on the results below.
+    undefined);
+    // `validateSources` hands back the files it could not check on its own;
+    // running them is what turns "this path holds a file" into "that file is
+    // actually there and matches its recorded metadata".
+    const fileErrors = await ops.validateFiles(state.schemas, state.sources, validation.files, state.analysis.fileLastUpdatedByPatchId);
+
+    // Per-module results, flattened to the by-source-path shape the filter
+    // takes. Merged rather than overwritten: a path can pick up an error
+    // from validation and another from its file.
+    const bySourcePath = {};
+    const add = (path, errors) => {
+      bySourcePath[path] = (bySourcePath[path] ?? []).concat(errors);
+    };
+    for (const moduleErrors of Object.values(validation.errors)) {
+      for (const [path, errors] of Object.entries(moduleErrors.validations ?? {})) {
+        add(path, errors);
+      }
+    }
+    for (const [path, errors] of Object.entries(fileErrors)) {
+      add(path, errors);
+    }
+
+    // Drops the errors the Studio would not show either: ones whose only
+    // effect is an offered fix. Left in, an agent would loop trying to
+    // "repair" content that is already publishable.
+    const blocking = internal.filterBlockingValidationErrors(bySourcePath, state.serializedSchemas, state.sources);
+
+    // A module whose source could not be read at all has no source path to
+    // hang an error on, so it is reported separately rather than lost.
+    const unreadable = Object.entries(validation.errors).filter(([, moduleErrors]) => moduleErrors.invalidSource).map(([path, moduleErrors]) => {
+      var _moduleErrors$invalid;
+      return {
+        moduleFilePath: path,
+        message: ((_moduleErrors$invalid = moduleErrors.invalidSource) === null || _moduleErrors$invalid === void 0 ? void 0 : _moduleErrors$invalid.message) ?? "Invalid source"
+      };
+    });
+    const scope = moduleFilePath;
+    const errors = scope === undefined ? blocking : filterKeysByModule(blocking, scope);
+    const unreadableInScope = scope === undefined ? unreadable : unreadable.filter(u => u.moduleFilePath === scope);
+    return ok({
+      valid: Object.keys(errors).length === 0 && unreadableInScope.length === 0,
+      errors: Object.fromEntries(Object.entries(errors).map(([path, errs]) => [path, errs.map(toJsonValidationError)])),
+      // Always present, empty when there are none: a caller should not have
+      // to tell "absent" from "empty" to decide whether content is publishable.
+      unreadableModules: unreadableInScope
+    });
+  }), defineTool({
+    name: "get_patches",
+    title: "Get patches",
+    description: "List the unpublished changes in the project, oldest first, with who made each one. A change reported as not applying is why a module's content may not match what publishing would produce, and why writing to that module is refused.",
+    inputSchema: z.z.object({
+      moduleFilePath: ModuleFilePathSchema$1.optional().describe("Limit to changes touching one module.")
+    }),
+    annotations: {
+      readOnlyHint: true
+    }
+  }, async ({
+    moduleFilePath
+  }, {
+    state
+  }) => {
+    const wanted = moduleFilePath === undefined ? state.patches.patches : state.patches.patches.filter(p => p.path === moduleFilePath);
+    // Which patches would not apply, flattened to one lookup by id: without
+    // this a module's content can silently differ from what publishing
+    // would produce, and nothing anywhere says why.
+    const failures = new Map();
+    for (const unapplied of Object.values(state.unappliedPatches)) {
+      for (const failure of unapplied) {
+        failures.set(failure.patchId, failure.error.message);
+      }
+    }
+    return ok(wanted.map(patch => {
+      const failure = failures.get(patch.patchId);
+      return {
+        patchId: patch.patchId,
+        moduleFilePath: patch.path,
+        createdAt: patch.createdAt,
+        authorId: patch.authorId,
+        // `appliedAt` non-null means this change is already committed, so
+        // it is history rather than something still pending.
+        published: patch.appliedAt !== null,
+        // Always present, so "applies cleanly" is stated rather than
+        // inferred from the absence of a field.
+        appliesCleanly: failure === undefined,
+        ...(failure === undefined ? {} : {
+          applyError: failure
+        })
+      };
+    }));
+  }), defineTool({
+    name: "get_source_path_from_route",
+    title: "Get source path from route",
+    description: "Given a URL path on the site, find the Val module and source path that renders it. Use this when the user names a page rather than a module.",
+    inputSchema: z.z.object({
+      route: z.z.string().describe('A route on the site, e.g. "/blog/my-post".')
+    }),
+    annotations: {
+      readOnlyHint: true,
+      idempotentHint: true
+    }
+  }, async ({
+    route
+  }, {
+    state
+  }) => {
+    const found = core.getSourcePathFromRoute(route, state.serializedSchemas);
+    if (!found) {
+      return err("not-found", `No Val module renders the route ${JSON.stringify(route)}. Routes come from modules with a router configured; get_all_schema shows which have one.`);
+    }
+    return ok(found);
+  })];
+}
+
+/**
+ * Resolve a module and classify the value at a path inside it.
+ *
+ * Shared by `get_record_keys` and `count_entries` so the two cannot drift on
+ * what counts as a missing module, and so both map the same failure to the same
+ * error code: a path that is not there is `not-found`, while a path that is
+ * there but holds a string or an image is `invalid-args` — the caller should
+ * reach for a different tool, not go looking for the path again.
+ */
+function describeContainer(state, moduleFilePath, path) {
+  const modulePath = moduleFilePath;
+  const schema = state.serializedSchemas[modulePath];
+  if (!schema) {
+    return {
+      kind: "error",
+      result: err("not-found", unknownModuleMessage(modulePath, state))
+    };
+  }
+  const described = internal.describeContainerAtPath(schema, state.sources[modulePath], path);
+  if (described.kind === "error") {
+    return {
+      kind: "error",
+      result: err(described.reason === "missing" ? "not-found" : "invalid-args", described.message)
+    };
+  }
+  return described;
+}
+
+/** "a record", but "an object" and "an array". */
+function article(container) {
+  return container === "object" || container === "array" ? "an" : "a";
+}
+function unknownModuleMessage(path, state) {
+  const known = Object.keys(state.serializedSchemas);
+  return `No Val module at ${JSON.stringify(path)}. Known modules: ${known.length === 0 ? "(none)" : known.join(", ")}`;
+}
+
+/**
+ * Project a validation error into something JSON-safe and worth reading.
+ *
+ * `ValidationError.value` is dropped rather than serialized: it is `unknown` (so
+ * not `Json` to begin with) and it holds the offending source value, which can
+ * be arbitrarily large. A caller already has the source path and can read the
+ * value with `get_source` if it needs to — putting it here would bloat every
+ * result for the rare case that wants it.
+ *
+ * `fixes` is kept, because it names what Val already knows how to repair, which
+ * is directly actionable.
+ */
+function toJsonValidationError(error) {
+  return {
+    message: error.message,
+    fixes: error.fixes ? [...error.fixes] : [],
+    typeError: error.typeError === true,
+    schemaError: error.schemaError === true,
+    keyError: error.keyError === true
+  };
+}
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Keep only the entries belonging to one module.
+ *
+ * Keyed by SourcePath, which begins with the module file path, so a prefix match
+ * is the right test — there is no per-module grouping left to index by.
+ */
+function filterKeysByModule(record, moduleFilePath) {
+  const out = {};
+  for (const [path, value] of Object.entries(record)) {
+    if (path.startsWith(moduleFilePath)) {
+      out[path] = value;
+    }
+  }
+  return out;
+}
+
+/**
+ * Everything the Studio does client-side before a patch can be saved, done
+ * server-side.
+ *
+ * Three things had no server equivalent, and each is a way to be quietly wrong:
+ * where the patch id comes from, what the patch says its parent is, and whether
+ * the result would even be valid. `docs/plans/mcp.md` Part C is the design.
+ */
+
+const jsonOps = new patch.JSONOps();
+
+/**
+ * A patch id, minted before the write is attempted.
+ *
+ * Same shape the Studio mints (a v4 UUID), and minting one that never gets used
+ * costs nothing — ids are not registered anywhere until a patch carries them.
+ */
+function mintPatchId() {
+  // A branded string has no constructor; this is the same conversion the Studio
+  // and ValServer both make.
+  return node_crypto.randomUUID();
+}
+
+/**
+ * What the new patch should hang off.
+ *
+ * The last known patch if there is one, otherwise the current head. Note the
+ * asymmetry between the two backends: `ValOpsFS` ignores `parentRef` entirely
+ * because its append-only ordering log defines order, while `ValOpsHttp` sends
+ * it up as `parentPatchId` for optimistic concurrency. So a wrong value here is
+ * invisible locally and a conflict in production — which is why this is derived
+ * fresh rather than remembered.
+ */
+async function deriveParentRef(ops,
+// Only the ids matter, so this accepts either shape `fetchPatches` can
+// return — the metadata-only variant omits the ops but keeps the ids.
+patches) {
+  const last = patches.patches[patches.patches.length - 1];
+  if (last) {
+    return {
+      type: "patch",
+      patchId: last.patchId
+    };
+  }
+  return {
+    type: "head",
+    headBaseSha: await ops.getBaseSha()
+  };
+}
+
+/**
+ * Would this patch leave the content valid?
+ *
+ * Applied to a **clone** of the sources, never the real ones: `applyPatch`
+ * mutates the document it is given, and ValOps carries a standing note that
+ * add operations misbehave without a clone. Validating in place would corrupt
+ * the sources every later call in this process reads.
+ *
+ * Server-side this is strictly better than the Studio's speculative check.
+ * `getSchemas()` returns real `Schema` instances, so the user's own `validate`
+ * closures run — and those are not carried by the serialized schema the browser
+ * has, which means the browser cannot run them at all.
+ */
+async function validateSpeculatively(ops, state, moduleFilePath, patch$1) {
+  const current = state.sources[moduleFilePath];
+  if (current === undefined) {
+    return {
+      status: "unapplicable",
+      result: {
+        status: "error",
+        code: "not-found",
+        message: `No Val module at ${JSON.stringify(moduleFilePath)}.`
+      }
+    };
+  }
+  const applied = patch.applyPatch(patch.deepClone(current), jsonOps, patch$1);
+  if (fp.result.isErr(applied)) {
+    return {
+      status: "unapplicable",
+      result: {
+        status: "error",
+        code: "invalid-args",
+        message: `The patch cannot be applied to ${moduleFilePath}: ${applied.error.message}`
+      }
+    };
+  }
+  const speculativeSources = {
+    ...state.sources,
+    [moduleFilePath]: applied.value
+  };
+  const after = await blockingErrorsIn(ops, state, speculativeSources, moduleFilePath);
+  if (after.length === 0) {
+    return {
+      status: "valid"
+    };
+  }
+
+  // Only the errors this patch *introduces*. A module can already be broken for
+  // reasons this change has nothing to do with -- the example app ships with a
+  // missing image file -- and refusing on the total would make every such module
+  // permanently read-only: an agent could not fix a typo in a file that also
+  // holds a broken image reference. Paid for only when there is something to
+  // refuse, so an ordinary clean edit still validates once.
+  const before = await blockingErrorsIn(ops, state, state.sources, moduleFilePath);
+  const existing = new Set(before.map(identify));
+  const introduced = after.filter(error => !existing.has(identify(error)));
+  if (introduced.length === 0) {
+    return {
+      status: "valid"
+    };
+  }
+  return {
+    status: "invalid",
+    errors: describeErrors(introduced)
+  };
+}
+/** Path and message together: the same message at another path is another problem. */
+function identify(error) {
+  return `${error.path}\u0000${error.message}`;
+}
+
+/**
+ * The publishing-blocking errors in one module, for a given set of sources.
+ *
+ * Scoped to one module by source path, which starts with the module file path.
+ * Errors elsewhere in the project are somebody else's: refusing on them would
+ * let the first broken module in a repo make every other module read-only.
+ */
+async function blockingErrorsIn(ops, state, sources, moduleFilePath) {
+  const validation = await ops.validateSources(state.schemas, sources,
+  // Every module, deliberately -- `patchesByModule` is a FILTER on which
+  // modules get validated, not context for validating them. Passing the
+  // analysis from before this write skips the very module being written
+  // whenever it had no pending patch, so the first change to a module went
+  // unchecked; and a change that breaks a `keyOf` or a router in a *different*
+  // module reports its error there, which a filtered run never visits.
+  undefined);
+  // `validateSources` hands back the files it could not check on its own;
+  // running them is what turns "this path holds a file" into "that file is
+  // actually there and matches its recorded metadata".
+  const fileErrors = await ops.validateFiles(state.schemas, sources, validation.files, state.analysis.fileLastUpdatedByPatchId);
+
+  // Merged rather than overwritten: a path can pick up an error from validation
+  // and another from its file.
+  const bySourcePath = {};
+  const add = (path, errors) => {
+    bySourcePath[path] = (bySourcePath[path] ?? []).concat(errors);
+  };
+  for (const moduleErrors of Object.values(validation.errors)) {
+    for (const [path, errors] of Object.entries(moduleErrors.validations ?? {})) {
+      add(path, errors);
+    }
+  }
+  for (const [path, errors] of Object.entries(fileErrors)) {
+    add(path, errors);
+  }
+  const blocking = internal.filterBlockingValidationErrors(bySourcePath, state.serializedSchemas, sources);
+  const located = [];
+  for (const [path, errors] of Object.entries(blocking)) {
+    if (!path.startsWith(moduleFilePath)) {
+      continue;
+    }
+    for (const error of errors) {
+      located.push({
+        path: path,
+        message: error.message
+      });
+    }
+  }
+  return located;
+}
+function describeErrors(errors) {
+  return errors.map(e => `${e.path}: ${e.message}`).join("; ");
+}
+
+/**
+ * What to do when the change would leave the content invalid.
+ *
+ * `"reject"` for a tool that is editing existing content: an agent should not be
+ * able to break a site, and a rejected patch stores nothing.
+ *
+ * `"report"` for a tool whose whole purpose is to create something incomplete.
+ * `empty_at_path` scaffolds an entry the caller is then expected to fill in, so
+ * on most real schemas — anything with a non-empty string — the value it creates
+ * is invalid by construction. Rejecting that would make the tool useless on
+ * exactly the schemas it exists for, so instead the patch is saved and the
+ * remaining errors come back as a to-do list. This mirrors the Studio, where
+ * creating an empty entry is normal and the errors show until it is filled in.
+ */
+
+/**
+ * Validate, then save — and retry once if someone else got there first.
+ *
+ * The retry exists because the parent ref is derived from a read that happened
+ * before the write. A conflict means the chain moved underneath us, and
+ * re-deriving is usually enough. Once only: a loop here would be an agent
+ * fighting a human editor in the Studio, and losing slowly is worse than
+ * failing clearly.
+ */
+async function savePatch(deps, moduleFilePath, patch, onInvalid = "reject") {
+  const {
+    ops,
+    ctx,
+    state
+  } = deps;
+  const unapplied = state.unappliedPatches[moduleFilePath];
+  if (unapplied && unapplied.length > 0) {
+    // Refused before anything is validated, because the state to validate
+    // against is wrong. `sources` for this module silently lacks these pending
+    // changes, so a patch built on it would be based on content that will never
+    // exist -- and its parent ref would chain onto changes that do not apply.
+    return {
+      status: "error",
+      code: "internal",
+      message: `Cannot write to ${moduleFilePath}: it has ${unapplied.length} pending change${unapplied.length === 1 ? "" : "s"} that will not apply, so what is stored is not what publishing would produce. Resolve or discard ${unapplied.map(u => u.patchId).join(", ")} first -- get_patches shows them.`
+    };
+  }
+  const speculative = await validateSpeculatively(ops, state, moduleFilePath, patch);
+  if (speculative.status === "unapplicable") {
+    // Never negotiable: the patch does not fit the content, so there is nothing
+    // to save whatever the caller's tolerance for invalid results.
+    return speculative.result;
+  }
+  let unresolved = null;
+  if (speculative.status === "invalid") {
+    if (onInvalid === "reject") {
+      return {
+        status: "error",
+        code: "validation-failed",
+        message: `The change was rejected and nothing was saved, because it would leave the content invalid: ${speculative.errors}`
+      };
+    }
+    unresolved = speculative.errors;
+  }
+
+  // Always null, and deliberately so. The app cannot resolve a PAT to a
+  // profile, so any id it put here would be an unverified claim dressed up as a
+  // checked one — and the request already carries the caller's own token, which
+  // is a better answer to "who did this" than anything the app could assert.
+  // Attributing the patch from that token is a backend concern; see
+  // `docs/plans/mcp.md` D.3.
+  const authorId = null;
+  for (let attempt = 0; attempt < 2; attempt++) {
+    const patchId = mintPatchId();
+    // Re-derived on the retry rather than reused: reusing the ref that just
+    // conflicted would conflict again by definition.
+    const patches = attempt === 0 ? state.patches : await ops.fetchPatches({
+      excludePatchOps: true
+    });
+    const parentRef = await deriveParentRef(ops, patches);
+    const saved = await ops.createPatch(moduleFilePath, patch, patchId, parentRef, ctx.sessionId, authorId);
+    if (fp.result.isOk(saved)) {
+      return {
+        status: "ok",
+        data: {
+          patchId: saved.value.patchId,
+          moduleFilePath,
+          createdAt: saved.value.createdAt,
+          // Always present, so a caller does not have to tell "absent" from
+          // "nothing left to do" to know whether the content is publishable.
+          unresolvedValidationErrors: unresolved
+        }
+      };
+    }
+    if (saved.error.errorType === "patch-head-conflict") {
+      continue;
+    }
+    return {
+      status: "error",
+      code: "internal",
+      // Note the nesting: createPatch wraps the underlying flat error as
+      // `{ errorType: "other", error: <that> }`.
+      message: saved.error.error.message
+    };
+  }
+  return {
+    status: "error",
+    code: "conflict",
+    message: "Another change was saved while this one was being written, twice in a row. Read the content again before retrying — it has moved."
+  };
+}
+
+/**
+ * The tools that change content.
+ *
+ * Every one of them goes through {@link savePatch}, so they all inherit the same
+ * guarantees: the change is validated against the real schemas before anything
+ * is stored, a rejected change stores nothing, and a lost race with another
+ * writer is retried once and then reported rather than looped on.
+ *
+ * Images are not here. The Studio's image tools work from a handle into Val's
+ * AI session store — bytes the browser got from the vision system — and MCP has
+ * no equivalent, so they need a different affordance (a local file path, or
+ * inline base64) rather than a port. `docs/plans/mcp.md` Part B has the reasoning.
+ */
+
+const ModuleFilePathSchema = z.z.string().describe('Path of the Val module, e.g. "/content/pages.val.ts".');
+function writeTools() {
+  return [defineTool({
+    name: "create_patch",
+    title: "Create patch",
+    description: "Change content in a Val module by applying JSON Patch operations. The change is validated first and is rejected outright if it would make the content invalid. Text and JSON values only — not files or images.",
+    inputSchema: z.z.object({
+      moduleFilePath: ModuleFilePathSchema,
+      patch: z.z.array(z.z.unknown()).describe('JSON Patch operations, e.g. [{"op":"replace","path":["title"],"value":"New title"}]. Paths are arrays of keys, not slash-separated strings.')
+    }),
+    annotations: {
+      idempotentHint: false
+    }
+  }, async ({
+    moduleFilePath,
+    patch
+  }, deps) => {
+    // Before parsing, not after: a file op that is also malformed should be
+    // told that files are not supported, rather than handed a schema error
+    // about the shape of a thing it was never going to be allowed to do.
+    const rejected = rejectFileOps(patch);
+    if (rejected) {
+      return rejected;
+    }
+    const parsed = internal.safeParsePatch(patch);
+    if (parsed.kind !== "ok") {
+      return fromBuildResult(parsed);
+    }
+    return savePatch(deps, moduleFilePath, parsed.patch);
+  }), defineTool({
+    name: "duplicate_source",
+    title: "Duplicate source",
+    description: "Copy the value at one path in a module to another path. Use this to add an entry modelled on an existing one, rather than composing it field by field.",
+    inputSchema: z.z.object({
+      moduleFilePath: ModuleFilePathSchema,
+      sourcePath: z.z.array(z.z.string()).describe("Path of the value to copy."),
+      destinationPath: z.z.array(z.z.string()).describe("Path to copy it to. Must not already exist.")
+    }),
+    annotations: {
+      idempotentHint: false
+    }
+  }, async ({
+    moduleFilePath,
+    sourcePath,
+    destinationPath
+  }, deps) => {
+    const modulePath = moduleFilePath;
+    const schema = deps.state.serializedSchemas[modulePath];
+    if (!schema) {
+      return err("not-found", `No Val module at ${JSON.stringify(modulePath)}.`);
+    }
+    const built = internal.buildDuplicatePatch({
+      sourcePath,
+      destinationPath
+    }, schema, deps.state.sources[modulePath]);
+    if (built.kind !== "ok") {
+      return fromBuildResult(built);
+    }
+    return savePatch(deps, modulePath, built.patch);
+  }), defineTool({
+    name: "empty_at_path",
+    title: "Create an empty value at a path",
+    description: "Create a new, schema-correct empty value at a path — an empty entry in a record or array, for instance. Prefer this over composing one by hand: it derives the shape from the schema, including required fields. The value it creates is usually not yet publishable; the result lists what still needs filling in, which you can then do with create_patch.",
+    inputSchema: z.z.object({
+      moduleFilePath: ModuleFilePathSchema,
+      destinationPath: z.z.array(z.z.string()).describe("Path to create the empty value at.")
+    }),
+    annotations: {
+      idempotentHint: false
+    }
+  }, async ({
+    moduleFilePath,
+    destinationPath
+  }, deps) => {
+    const modulePath = moduleFilePath;
+    const schema = deps.state.serializedSchemas[modulePath];
+    if (!schema) {
+      return err("not-found", `No Val module at ${JSON.stringify(modulePath)}.`);
+    }
+    const built = internal.buildEmptyAtPathPatch({
+      destinationPath
+    }, schema, deps.state.sources[modulePath]);
+    if (built.kind !== "ok") {
+      return fromBuildResult(built);
+    }
+    // "report", not "reject": an empty entry is invalid by construction on
+    // any schema with a required non-empty field, which is most of them.
+    // See OnInvalid in writePath.ts.
+    return savePatch(deps, modulePath, built.patch, "report");
+  }), defineTool({
+    name: "remove_image_gallery_entry",
+    title: "Remove an image gallery entry",
+    description: "Remove one image from an image gallery module by its file path. This deletes the entry and the file it refers to.",
+    inputSchema: z.z.object({
+      moduleFilePath: ModuleFilePathSchema.describe("The gallery module, i.e. one declared with s.images() or s.files()."),
+      filePath: z.z.string().describe('The gallery key to remove, e.g. "/public/val/photo_a1b2c.jpg".')
+    }),
+    // Destructive: it removes content and the underlying file, so a host
+    // that asks for confirmation should ask here.
+    annotations: {
+      destructiveHint: true,
+      idempotentHint: false
+    }
+  }, async ({
+    moduleFilePath,
+    filePath
+  }, deps) => {
+    const modulePath = moduleFilePath;
+    const schema = deps.state.serializedSchemas[modulePath];
+    if (!schema) {
+      return err("not-found", `No Val module at ${JSON.stringify(modulePath)}.`);
+    }
+    const built = internal.buildRemoveImageGalleryEntryPatch({
+      filePath
+    }, schema, deps.state.sources[modulePath]);
+    if (built.kind !== "ok") {
+      return fromBuildResult(built);
+    }
+    return savePatch(deps, modulePath, built.patch);
+  })];
+}
+
+/**
+ * Turn a helper's build failure into a tool error.
+ *
+ * `wrong-tool` is worth keeping distinct: the helpers can tell that the caller
+ * reached for the wrong tool and which one it should have used, and passing that
+ * through is what lets a model correct itself in one step instead of retrying
+ * the same call.
+ */
+function fromBuildResult(built) {
+  if (built.kind === "wrong-tool") {
+    return {
+      status: "error",
+      code: "invalid-args",
+      message: `${built.reason} Use the ${built.suggestedTool} tool instead.`
+    };
+  }
+  return {
+    status: "error",
+    code: "invalid-args",
+    message: built.message
+  };
+}
+
+/**
+ * File operations are refused rather than half-supported.
+ *
+ * A `file` op carries binary content that has to be uploaded before the patch
+ * is synced — a two-phase flow this pass does not implement. Letting one through
+ * would store a patch referring to bytes that were never uploaded, which fails
+ * later and a long way from the cause.
+ *
+ * Takes the unparsed patch, so this answer does not depend on the op being
+ * otherwise well formed. All it needs is the caller's own claim about what the
+ * op is.
+ */
+function rejectFileOps(patch) {
+  const hasFileOp = patch.some(op => typeof op === "object" && op !== null && "op" in op && op.op === "file");
+  if (!hasFileOp) {
+    return null;
+  }
+  return {
+    status: "error",
+    code: "unsupported",
+    message: "This patch contains a file operation. Uploading files is not supported over MCP yet — only text and JSON values can be changed."
+  };
+}
+
+/**
+ * How many callers' data layers to keep around in proxy mode.
+ *
+ * Each entry holds one `ValOpsHttp`, and each of those caches the project's
+ * evaluated modules once `initSources` has run — so this bounds memory, not just
+ * entry count. Small on purpose: the cost of a miss is re-evaluating the
+ * modules on the next call, which is what happened on *every* call before this
+ * cache existed.
+ */
+const MAX_CACHED_OPS = 8;
+
+/**
+ * Val's server-side tool registry.
+ *
+ * This is the piece Val did not have: the Studio's chat tools are defined *and
+ * executed in the browser*, against its client stores, so nothing here could be
+ * re-exposed. These tools run against {@link ValOps} instead, which is what lets
+ * an MCP server — or a stdio transport, or anything else — drive Val content
+ * without a browser.
+ *
+ * Transport-agnostic on purpose: nothing under `tools/` imports an MCP SDK. A
+ * host adapts {@link ValToolResult} at its own edge.
+ */
+function createValTools(valModules, options) {
+  const resolveOps = createOpsResolver(valModules, options);
+  const tools = [...readTools(), ...writeTools()];
+  const byName = new Map(tools.map(tool => [tool.name, tool]));
+  return {
+    list() {
+      return tools.map(({
+        handler: _handler,
+        ...definition
+      }) => definition);
+    },
+    listJsonSchema() {
+      return tools.map(({
+        handler: _handler,
+        inputSchema,
+        ...rest
+      }) => ({
+        ...rest,
+        // zod 4 derives this itself, so there is no JSON-Schema-to-zod
+        // converter anywhere in the stack and no second description of the
+        // same input to keep in step.
+        inputSchema: z.z.toJSONSchema(inputSchema, {
+          io: "input"
+        })
+      }));
+    },
+    async call(name, args, ctx) {
+      const tool = byName.get(name);
+      if (!tool) {
+        return {
+          status: "error",
+          code: "unknown-tool",
+          message: `No tool named ${JSON.stringify(name)}. Available: ${tools.map(t => t.name).join(", ")}`
+        };
+      }
+      const parsed = tool.inputSchema.safeParse(args ?? {});
+      if (!parsed.success) {
+        return {
+          status: "error",
+          code: "invalid-args",
+          message: describeZodError(parsed.error)
+        };
+      }
+      const resolved = resolveOps(ctx);
+      if (resolved.status === "error") {
+        return resolved.result;
+      }
+      const ops = resolved.ops;
+      try {
+        const state = await loadState(ops);
+        if (state.status === "error") {
+          return state.result;
+        }
+        const deps = {
+          ops,
+          ctx,
+          state: state.state
+        };
+        return await tool.handler(parsed.data, deps);
+      } catch (error) {
+        // A thrown error here is a bug or an unreachable backend, not something
+        // the model can act on — but it still comes back in-band so the client
+        // sees a tool failure rather than a dead transport.
+        return {
+          status: "error",
+          code: "internal",
+          message: error instanceof Error ? error.message : String(error)
+        };
+      }
+    },
+    async dispose() {
+      // Nothing to release today: ValOps holds no handle that needs closing, and
+      // the fs watcher it can start is owned by the Studio's server. Kept in the
+      // contract so hosts wire up teardown now rather than when it starts to
+      // matter.
+    }
+  };
+}
+
+/**
+ * Pick the data layer for a call, which in proxy mode means picking whose
+ * credential the backend will see.
+ *
+ * This is the one place authorization is decided, and it decides it by *not*
+ * deciding: in proxy mode the caller's own personal access token goes to the
+ * backend, which is the only party that can say what that token may do. The app
+ * never inspects it, never caches a verdict about it, and never substitutes its
+ * own API key for a missing one — see `docs/plans/mcp.md` D.2.
+ *
+ * The alternative shape, and the reason this function exists at all, is an
+ * `authenticate()` that checks the PAT once and then acts under the app's key.
+ * That reads as more secure and is strictly less so: the check happens in the
+ * app, so every bug in it becomes full access to every project the app's key
+ * can reach, and the backend's own permission model stops being consulted (D.6).
+ */
+function createOpsResolver(valModules, options) {
+  if (options.mode === "fs") {
+    // One instance, built once: fs mode is a developer's own working tree, so
+    // there is no credential to vary by and no reason to re-evaluate modules.
+    const ops = createValOps(valModules, options);
+    return ctx => {
+      if (ctx.auth) {
+        // Refused rather than ignored. A host that thinks it is passing a
+        // credential should not silently get local filesystem access instead —
+        // and the difference matters, because fs mode writes straight to disk
+        // with no backend permission check at all.
+        return {
+          status: "error",
+          result: {
+            status: "error",
+            code: "unsupported",
+            message: "This Val project is running in local filesystem mode, where there is nothing to authenticate against. Do not send a credential."
+          }
+        };
+      }
+      return {
+        status: "ok",
+        ops
+      };
+    };
+  }
+
+  // Keyed by a hash of the PAT, so the same caller reuses their own instance and
+  // two callers can never share one. Hashing is not a security boundary — the
+  // instance holds the token regardless — but it keeps credentials out of the
+  // key set, which is the thing that ends up in a heap dump or an error dump.
+  const byPatHash = new Map();
+  return ctx => {
+    if (!ctx.auth) {
+      return {
+        status: "error",
+        result: {
+          status: "error",
+          code: "forbidden",
+          message: "This Val project talks to the Val content backend, so every call needs the caller's own personal access token. Run `val login` to get one."
+        }
+      };
+    }
+    const key = node_crypto.createHash("sha256").update(ctx.auth.pat).digest("hex");
+    const cached = byPatHash.get(key);
+    if (cached) {
+      // Re-inserted so eviction drops the least recently used rather than the
+      // oldest — a long-running caller should not be evicted by a burst of
+      // one-off ones.
+      byPatHash.delete(key);
+      byPatHash.set(key, cached);
+      return {
+        status: "ok",
+        ops: cached
+      };
+    }
+    const ops = createValOps(valModules, options, {
+      pat: ctx.auth.pat
+    });
+    byPatHash.set(key, ops);
+    while (byPatHash.size > MAX_CACHED_OPS) {
+      const oldest = byPatHash.keys().next();
+      if (oldest.done) {
+        break;
+      }
+      byPatHash.delete(oldest.value);
+    }
+    return {
+      status: "ok",
+      ops
+    };
+  };
+}
+/**
+ * The content as the caller should see it, loaded once per call.
+ *
+ * Pending patches are applied, because an agent looking at a project mid-edit
+ * should see what the Studio would show rather than the last published state.
+ *
+ * Deliberately not cached across calls. In fs mode a save recomputes the base
+ * sha within the same process, so a cached view would go stale silently — and
+ * the cost of being wrong here is an agent writing a patch against content that
+ * has already moved.
+ */
+async function loadState(ops) {
+  const patches = await ops.fetchPatches({
+    excludePatchOps: false
+  });
+  // fetchPatches resolves with its failures on the result rather than rejecting,
+  // so not checking these reads as "no pending changes" — which would quietly
+  // hand back published content and let a write be based on it.
+  if (patches.unauthorized) {
+    return {
+      status: "error",
+      result: {
+        status: "error",
+        code: "forbidden",
+        message: "Not authorized to read this project's pending changes. Check that the credential is valid and has access."
+      }
+    };
+  }
+  if (patches.networkError) {
+    return {
+      status: "error",
+      result: {
+        status: "error",
+        code: "internal",
+        message: "Could not reach the Val content backend."
+      }
+    };
+  }
+  if (patches.error) {
+    return {
+      status: "error",
+      result: {
+        status: "error",
+        code: "internal",
+        message: patches.error.message
+      }
+    };
+  }
+  const analysis = ops.analyzePatches(patches.patches);
+  // getSourcesWithPatchesApplied, not getSources(analysis): the latter returns
+  // only the modules that had patches, and validating that subset reports
+  // spurious errors for anything that looks across modules, like keyOf or a
+  // router.
+  const sourcesRes = await ops.getSourcesWithPatchesApplied({
+    ...analysis,
+    ...patches
+  });
+  const [schemas, serializedSchemas] = await Promise.all([ops.getSchemas(), ops.getSerializedSchemas()]);
+  return {
+    status: "ok",
+    state: {
+      schemas,
+      serializedSchemas,
+      sources: sourcesRes.sources,
+      patches,
+      analysis,
+      // Which modules hold a pending patch that would not apply. Carried rather
+      // than discarded because their `sources` silently lack that change: the
+      // content here is not what publishing would produce, so a write against
+      // it would be based on a state that does not exist. See
+      // `unappliedPatchesFor`.
+      unappliedPatches: sourcesRes.errors
+    }
+  };
+}
+function describeZodError(error) {
+  return error.issues.map(issue => {
+    const path = issue.path.join(".");
+    return path ? `${path}: ${issue.message}` : issue.message;
+  }).join("; ");
+}
+
+const JsFileLookupMapping = [
+// NOTE: first one matching will be used
+[".cjs.d.ts", [".esm.js", ".mjs.js"]], [".cjs.js", [".esm.js", ".mjs.js"]], [".cjs", [".mjs"]], [".d.ts", [".js", ".esm.js", ".mjs.js"]]];
+const MAX_CACHE_SIZE = 100 * 1024 * 1024; // 100 mb
+const MAX_OBJECT_KEY_SIZE = 2 ** 27; // https://stackoverflow.com/questions/13367391/is-there-a-limit-on-length-of-the-key-string-in-js-object
+
+class ValModuleLoader {
+  constructor(projectRoot, compilerOptions,
+  // TODO: remove this?
+  sourceFileHandler, host = {
+    ...ts__default["default"].sys,
+    writeFile: (fileName, data, encoding) => {
+      fs__default["default"].mkdirSync(path__namespace["default"].dirname(fileName), {
+        recursive: true
+      });
+      fs__default["default"].writeFileSync(fileName, typeof data === "string" ? data : new Uint8Array(data), encoding);
+    },
+    rmFile: fs__default["default"].rmSync,
+    readBuffer: fileName => {
+      try {
+        return fs__default["default"].readFileSync(fileName);
+      } catch {
+        return undefined;
+      }
+    }
+  }, disableCache = false) {
     this.projectRoot = projectRoot;
     this.compilerOptions = compilerOptions;
     this.sourceFileHandler = sourceFileHandler;
@@ -12408,7 +13674,17 @@ async function findAndEvalValConfigFile(projectRoot) {
 }
 
 /**
- * The Val login device flow, as reusable primitives.
+ * The Val login flow, as reusable primitives.
+ *
+ * This is an RFC 8628 device authorization grant. The shape that matters:
+ * {@link ValDeviceAuthorization.deviceCode} is a secret this process holds and
+ * polls with, while {@link ValDeviceAuthorization.userCode} is the short string
+ * the human reads out of the terminal and types into a browser. Only the device
+ * code can collect a token.
+ *
+ * Keep them apart. Show the user code; never print, log or put the device code
+ * in a URL. An earlier version of this flow used one value for both jobs, which
+ * meant anyone who saw the verification link could collect the token it led to.
  *
  * The CLI wraps these with terminal output, and `@valbuild/language-server`
  * wraps them with LSP `window/showDocument` and progress reporting. Neither the
@@ -12422,6 +13698,21 @@ const DEFAULT_LOGIN_HOST = "https://admin.val.build";
 function defaultHost() {
   return process.env.VAL_BUILD_URL || DEFAULT_LOGIN_HOST;
 }
+
+/**
+ * What gets shown on the approval screen so the person can tell which terminal
+ * is asking. Self-reported and therefore a hint, not proof — the server treats
+ * it as untrusted display text.
+ */
+function defaultDeviceName() {
+  try {
+    return `${os__default["default"].hostname()} (${os__default["default"].platform()})`;
+  } catch {
+    // hostname() can throw on locked-down containers. A missing device name is
+    // not worth failing a login over; the server renders "Unknown".
+    return "";
+  }
+}
 class ValLoginError extends Error {
   constructor(code, message, details) {
     super(message);
@@ -12431,20 +13722,24 @@ class ValLoginError extends Error {
   }
 }
 
-/** A login attempt that is waiting for the user to confirm in a browser. */
+/** A login attempt that is waiting for the user to approve it in a browser. */
 
 /**
- * Begin a login attempt. The caller is responsible for getting
- * {@link ValLoginSession.url} in front of the user.
+ * Begin a login attempt. The caller is responsible for getting the user code
+ * and verification URL in front of the user.
  */
 async function startValLogin(options = {}) {
   var _response$headers$get;
   const host = options.host ?? defaultHost();
+  const deviceName = options.deviceName ?? defaultDeviceName();
   const response = await fetch(`${host}/api/login`, {
     method: "POST",
     headers: {
       "Content-Type": "application/json"
-    }
+    },
+    body: JSON.stringify(deviceName ? {
+      device_name: deviceName
+    } : {})
   });
   if (response.status >= 500) {
     const text = await response.text().catch(() => "");
@@ -12455,42 +13750,63 @@ async function startValLogin(options = {}) {
     throw new ValLoginError("unexpected-content-type", "Unexpected failure while trying to login (content type was not JSON).", text ? `Server response: ${text} (status: ${response.status})` : `Status: ${response.status}`);
   }
   const json = await response.json();
-  const nonce = json === null || json === void 0 ? void 0 : json.nonce;
-  const url = json === null || json === void 0 ? void 0 : json.url;
-  if (typeof nonce !== "string" || typeof url !== "string") {
-    throw new ValLoginError("unexpected-response", "Unexpected response from the server.", JSON.stringify(json));
+  const deviceCode = json === null || json === void 0 ? void 0 : json.device_code;
+  const userCode = json === null || json === void 0 ? void 0 : json.user_code;
+  const verificationUri = json === null || json === void 0 ? void 0 : json.verification_uri;
+  if (typeof deviceCode !== "string" || typeof userCode !== "string" || typeof verificationUri !== "string") {
+    throw new ValLoginError("unexpected-response", "Unexpected response from the server. This version of Val may be too old for the login flow on this host — try updating @valbuild/cli.", JSON.stringify(json));
   }
   return {
-    nonce,
-    url
+    deviceCode,
+    userCode,
+    verificationUri,
+    verificationUriComplete: typeof (json === null || json === void 0 ? void 0 : json.verification_uri_complete) === "string" ? json.verification_uri_complete : verificationUri,
+    expiresInSeconds: typeof (json === null || json === void 0 ? void 0 : json.expires_in) === "number" ? json.expires_in : DEFAULT_LOGIN_EXPIRES_IN_SECONDS,
+    intervalSeconds: typeof (json === null || json === void 0 ? void 0 : json.interval) === "number" ? json.interval : DEFAULT_LOGIN_POLL_INTERVAL_SECONDS
   };
 }
-const DEFAULT_LOGIN_MAX_DURATION = 5 * 60 * 1000; // 5 minutes
-const DEFAULT_LOGIN_POLL_INTERVAL = 1000;
+
+/** Fallbacks for a server that omits the optional RFC 8628 timing fields. */
+const DEFAULT_LOGIN_EXPIRES_IN_SECONDS = 600;
+const DEFAULT_LOGIN_POLL_INTERVAL_SECONDS = 5;
 
 /**
- * Poll until the user confirms the login in their browser.
+ * How much to add to the poll interval when the server answers `slow_down`.
+ * RFC 8628 section 3.5 specifies 5 seconds.
+ */
+const SLOW_DOWN_INCREMENT_SECONDS = 5;
+
+/**
+ * Poll until the user approves the login in their browser.
  *
  * Accepts an `AbortSignal` so an editor can cancel the flow when the user
- * dismisses the prompt, instead of leaving a poll loop running for 5 minutes.
+ * dismisses the prompt, instead of leaving a poll loop running to expiry.
  */
-async function awaitValLoginConfirmation(nonce, options = {}) {
+async function awaitValLoginConfirmation(authorization, options = {}) {
   const host = options.host ?? defaultHost();
-  const maxDuration = options.maxDurationMs ?? DEFAULT_LOGIN_MAX_DURATION;
-  const pollInterval = options.pollIntervalMs ?? DEFAULT_LOGIN_POLL_INTERVAL;
+  const maxDuration = options.maxDurationMs ?? authorization.expiresInSeconds * 1000;
   const now = options.now ?? (() => Date.now());
+  // Mutable: `slow_down` widens it as we go, and never narrows it again.
+  let intervalMs = authorization.intervalSeconds * 1000;
   const start = now();
   while (now() - start < maxDuration) {
     var _options$signal, _options$signal2;
     if ((_options$signal = options.signal) !== null && _options$signal !== void 0 && _options$signal.aborted) {
       throw new ValLoginError("aborted", "Login was cancelled.");
     }
-    await new Promise(resolve => setTimeout(resolve, pollInterval));
+    // Wait first: the user has not had time to approve anything yet.
+    await new Promise(resolve => setTimeout(resolve, intervalMs));
     if ((_options$signal2 = options.signal) !== null && _options$signal2 !== void 0 && _options$signal2.aborted) {
       throw new ValLoginError("aborted", "Login was cancelled.");
     }
-    const response = await fetch(`${host}/api/login?token=${nonce}&consume=true`, {
-      method: "POST"
+    const response = await fetch(`${host}/api/login`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify({
+        device_code: authorization.deviceCode
+      })
     });
     if (response.status >= 500) {
       throw new ValLoginError("server-error", "An error occurred on the server.", `Status: ${response.status}`);
@@ -12508,6 +13824,23 @@ async function awaitValLoginConfirmation(nonce, options = {}) {
       }
       throw new ValLoginError("unexpected-response", "Unexpected response from the server.", JSON.stringify(json));
     }
+    const json = await response.json().catch(() => null);
+    const error = typeof (json === null || json === void 0 ? void 0 : json.error) === "string" ? json.error : null;
+    const description = typeof (json === null || json === void 0 ? void 0 : json.error_description) === "string" ? json.error_description : undefined;
+    if (error === "authorization_pending") {
+      continue;
+    }
+    if (error === "slow_down" || response.status === 429) {
+      intervalMs += SLOW_DOWN_INCREMENT_SECONDS * 1000;
+      continue;
+    }
+    if (error === "access_denied") {
+      throw new ValLoginError("access-denied", "The login was declined in the browser.", description);
+    }
+    if (error === "expired_token") {
+      throw new ValLoginError("expired", "The login code expired before it was approved.", description);
+    }
+    throw new ValLoginError("unexpected-response", "Unexpected response from the server.", JSON.stringify(json));
   }
   throw new ValLoginError("timeout", "Login confirmation timed out.");
 }
@@ -12813,9 +14146,9 @@ Object.defineProperty(exports, 'hasRemoteFileSchema', {
   enumerable: true,
   get: function () { return core.hasRemoteFileSchema; }
 });
+exports.DEFAULT_LOGIN_EXPIRES_IN_SECONDS = DEFAULT_LOGIN_EXPIRES_IN_SECONDS;
 exports.DEFAULT_LOGIN_HOST = DEFAULT_LOGIN_HOST;
-exports.DEFAULT_LOGIN_MAX_DURATION = DEFAULT_LOGIN_MAX_DURATION;
-exports.DEFAULT_LOGIN_POLL_INTERVAL = DEFAULT_LOGIN_POLL_INTERVAL;
+exports.DEFAULT_LOGIN_POLL_INTERVAL_SECONDS = DEFAULT_LOGIN_POLL_INTERVAL_SECONDS;
 exports.Service = Service;
 exports.ValFSHost = ValFSHost;
 exports.ValLoginError = ValLoginError;
@@ -12835,7 +14168,9 @@ exports.createModulePathMap = createModulePathMap;
 exports.createService = createService;
 exports.createValApiRouter = createValApiRouter;
 exports.createValModuleFileInspector = createValModuleFileInspector;
+exports.createValOps = createValOps;
 exports.createValServer = createValServer;
+exports.createValTools = createValTools;
 exports.currentFixHandlers = currentFixHandlers;
 exports.decodeJwtWithoutVerifying = decodeJwtWithoutVerifying;
 exports.describePatchStoreProblems = describePatchStoreProblems;
@@ -12867,6 +14202,7 @@ exports.handleRemoteFileDownload = handleRemoteFileDownload;
 exports.handleRemoteFileUpload = handleRemoteFileUpload;
 exports.handleRemoteGalleryFileUpload = handleRemoteGalleryFileUpload;
 exports.handleUniqueFolderCheck = handleUniqueFolderCheck;
+exports.initHandlerOptions = initHandlerOptions;
 exports.loadValModules = loadValModules;
 exports.parsePersonalAccessTokenFile = parsePersonalAccessTokenFile;
 exports.patchSourceFile = patchSourceFile;