@valbuild/server 0.115.0 → 0.117.0

package/dist/valbuild-server.cjs.prod.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,191 +10543,44 @@ 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;
-  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");
+
+// TODO: remove
+async function safeReadGit(cwd) {
+  async function findGitHead(currentDir, depth) {
+    const gitHeadPath = path__namespace.join(currentDir, ".git", "HEAD");
+    if (depth > 1000) {
+      console.error(`Reached max depth while scanning for .git folder. Current working dir: ${cwd}.`);
+      return {
+        commit: undefined,
+        branch: undefined
+      };
     }
-    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();
-    return {
-      mode: "fs",
-      cwd,
-      route,
-      valDisableRedirectUrl,
-      valEnableRedirectUrl,
-      valBuildUrl,
-      valContentUrl,
-      apiKey: maybeApiKey,
-      valSecret: maybeValSecret,
-      project: maybeValProject,
-      config
-    };
-  }
-}
-
-/**
- * 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);
-    }
-  }
-}
-
-// TODO: remove
-async function safeReadGit(cwd) {
-  async function findGitHead(currentDir, depth) {
-    const gitHeadPath = path__namespace.join(currentDir, ".git", "HEAD");
-    if (depth > 1000) {
-      console.error(`Reached max depth while scanning for .git folder. Current working dir: ${cwd}.`);
-      return {
-        commit: undefined,
-        branch: undefined
-      };
-    }
-    try {
-      const headContents = await fs.promises.readFile(gitHeadPath, "utf-8");
-      const match = headContents.match(/^ref: refs\/heads\/(.+)/);
-      if (match) {
-        const branchName = match[1];
-        return {
-          branch: branchName,
-          commit: await readCommit(currentDir, branchName)
-        };
-      } else {
-        return {
-          commit: undefined,
-          branch: undefined
-        };
-      }
-    } catch {
-      const parentDir = path__namespace.dirname(currentDir);
-
-      // We've reached the root directory
-      if (parentDir === currentDir) {
-        return {
-          commit: undefined,
-          branch: undefined
-        };
-      }
-      return findGitHead(parentDir, depth + 1);
+    try {
+      const headContents = await fs.promises.readFile(gitHeadPath, "utf-8");
+      const match = headContents.match(/^ref: refs\/heads\/(.+)/);
+      if (match) {
+        const branchName = match[1];
+        return {
+          branch: branchName,
+          commit: await readCommit(currentDir, branchName)
+        };
+      } else {
+        return {
+          commit: undefined,
+          branch: undefined
+        };
+      }
+    } catch {
+      const parentDir = path__namespace.dirname(currentDir);
+
+      // We've reached the root directory
+      if (parentDir === currentDir) {
+        return {
+          commit: undefined,
+          branch: undefined
+        };
+      }
+      return findGitHead(parentDir, depth + 1);
     }
   }
   try {
@@ -10778,6 +10836,1288 @@ function getCookies(req, cookiesDef) {
   return z.z.object(cookiesDef).safeParse(input);
 }
 
+/**
+ * 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.
+ */
+
+/** 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
+    }
+  }, 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") {
+  var _ctx$auth;
+  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;
+  }
+
+  /**
+   * Null on the PAT path, and the verified profile on the token path.
+   *
+   * The PAT case is unchanged and still deliberate: the app cannot resolve a
+   * PAT, so any id it wrote 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 that patch is the backend's job.
+   *
+   * The token case is the opposite situation, which is why it gets the opposite
+   * answer. The host verified a signature over a key it does not hold, so the
+   * profile is checked rather than claimed, and the backend has no token of its
+   * own to attribute from — the call reaches it under the app's API key. If this
+   * stayed null, every edit made through a signed-in editor's own session would
+   * land with no author at all, which is worse than useless on a CMS whose
+   * review screen is organised by who changed what.
+   */
+  const authorId = ((_ctx$auth = ctx.auth) === null || _ctx$auth === void 0 ? void 0 : _ctx$auth.type) === "verified-profile" ? ctx.auth.profileId : 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."
+  };
+}
+
+/**
+ * The public surface of Val's server-side tool registry.
+ *
+ * Types only, deliberately: this file is the contract that the MCP hosts, the
+ * CLI's stdio transport and the tools themselves are all written against, and
+ * keeping it free of implementation means those can be built in any order
+ * without one of them owning the shape.
+ *
+ * The design this implements is `docs/plans/mcp.md`, Part A. Two constraints
+ * from it are load-bearing and easy to break by accident:
+ *
+ * 1. **Nothing here may import an MCP SDK.** That is what lets hosts other
+ *    than the template consume these tools, and it is not hypothetical
+ *    hygiene — the TypeScript SDK reorganised itself at v2.0.0, and a registry
+ *    coupled to it would have moved with it.
+ * 2. **The result type is deliberately not MCP's `CallToolResult`.** Each host
+ *    adapts {@link ValToolResult} at its own edge, which is also where an
+ *    error becomes an in-band `isError` result the model can recover from
+ *    rather than a transport failure.
+ */
+
+/** Why a tool call failed, in a form a host can map onto its own errors. */
+
+/**
+ * The same definition with `inputSchema` as JSON Schema, for hosts that want the
+ * wire shape rather than a Standard Schema.
+ *
+ * Typed as whatever zod's own converter produces, so deriving it needs no cast
+ * and no second hand-written description of the same input.
+ */
+
+/**
+ * How the caller was established, and it is a union because there are two
+ * genuinely different answers — with different consequences downstream.
+ *
+ * The distinction that matters is **who checked**. A PAT is forwarded to the
+ * backend unchecked, because the app cannot resolve one; an access token is
+ * verified by the app itself, against a public key it does not hold and
+ * therefore cannot forge. The first is a credential being relayed. The second
+ * is a signature that has already been checked.
+ */
+
+/**
+ * Who is calling, established once per request by the host.
+ *
+ * `null` means local fs mode, where there is no credential to hold and patches
+ * are written with no author, exactly as the Studio does locally (D.1). In
+ * proxy mode `null` is refused rather than falling back to the app's own API
+ * key: that key can do more than any single user, and quietly substituting it
+ * would turn a missing credential into full access.
+ */
+
+/**
+ * Brand a verified subject as an {@link AuthorId}.
+ *
+ * `AuthorId` is a branded string so that an id cannot be conjured from any
+ * string that happens to be lying around — which is exactly the mistake this
+ * type is guarding against. That makes one assertion unavoidable at the boundary
+ * where a real id enters the system, so it lives here, once, with a name that
+ * says what makes it legitimate: the caller has *verified* this subject, not
+ * received it.
+ *
+ * Do not reach for this to satisfy a type. If you are holding a string you did
+ * not verify, the honest value is `null`.
+ */
+function authorIdFromVerifiedSubject(subject) {
+  return subject;
+}
+
+/** Read access. Every call needs it, the writes included. */
+const VAL_SCOPE_READ = "val:read";
+/** Write access. Needed *in addition* by any tool not marked `readOnlyHint`. */
+const VAL_SCOPE_WRITE = "val:write";
+
+/**
+ * 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 insufficient = refuseInsufficientScope(tool, ctx);
+      if (insufficient) {
+        return insufficient;
+      }
+      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();
+  /**
+   * One instance for every verified caller, and unlike the PAT map that is
+   * correct rather than a shortcut: this instance authenticates with the app's
+   * own API key, so there is nothing per-caller in it to keep apart. Who did
+   * what travels as the patch's `authorId` instead — see `writePath`.
+   */
+  let sharedOps = null;
+  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 a credential: an access token from the Val authorization server, or the caller's own personal access token from `val login`."
+        }
+      };
+    }
+    if (ctx.auth.type === "verified-profile") {
+      if (!options.apiKey) {
+        // Proxy mode is inferred from the api key being present, so this is
+        // unreachable through `initHandlerOptions`. It stays because the
+        // alternative to refusing is building ops with no credential at all.
+        return {
+          status: "error",
+          result: {
+            status: "error",
+            code: "forbidden",
+            message: "This Val project has no API key configured, so a verified access token cannot be exchanged for backend access."
+          }
+        };
+      }
+      if (!sharedOps) {
+        sharedOps = createValOps(valModules, options);
+      }
+      return {
+        status: "ok",
+        ops: sharedOps
+      };
+    }
+    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("; ");
+}
+
+/**
+ * Refuse a call the token was not granted, before anything is attempted.
+ *
+ * Derived from `readOnlyHint` rather than from a second list of tool names,
+ * because a second list is a thing that drifts. The derivation also fails in
+ * the safe direction: a tool that forgets the hint is treated as a write and
+ * demands the wider scope, rather than a write slipping through as a read.
+ *
+ * Only the verified-token path is checked. A PAT carries no scopes here by
+ * design — the backend resolves it and decides — so there is nothing to
+ * enforce, and inventing a default would be this app claiming an authority it
+ * does not have.
+ */
+function refuseInsufficientScope(tool, ctx) {
+  var _ctx$auth, _tool$annotations;
+  if (((_ctx$auth = ctx.auth) === null || _ctx$auth === void 0 ? void 0 : _ctx$auth.type) !== "verified-profile") {
+    return null;
+  }
+  // Read is needed by every call, including the writes: a tool that changes
+  // content reads it first, and `ValToolAuth` says as much. Checking only the
+  // wider scope would let a write-but-not-read token through here — today's
+  // verifier refuses such a token before this point, but `createValTools` is
+  // exported and another host may not.
+  const needed = (_tool$annotations = tool.annotations) !== null && _tool$annotations !== void 0 && _tool$annotations.readOnlyHint ? [VAL_SCOPE_READ] : [VAL_SCOPE_READ, VAL_SCOPE_WRITE];
+  const granted = ctx.auth.scopes;
+  const missing = needed.filter(scope => !granted.includes(scope));
+  if (missing.length === 0) {
+    return null;
+  }
+  return {
+    status: "error",
+    code: "forbidden",
+    message: `This access token does not have the ${missing.join(" and ")} scope, which ${tool.name} requires. Granted: ${granted.length > 0 ? granted.join(" ") : "(none)"}.`
+  };
+}
+
 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"]]];
@@ -12965,6 +14305,8 @@ exports.DEFAULT_LOGIN_EXPIRES_IN_SECONDS = DEFAULT_LOGIN_EXPIRES_IN_SECONDS;
 exports.DEFAULT_LOGIN_HOST = DEFAULT_LOGIN_HOST;
 exports.DEFAULT_LOGIN_POLL_INTERVAL_SECONDS = DEFAULT_LOGIN_POLL_INTERVAL_SECONDS;
 exports.Service = Service;
+exports.VAL_SCOPE_READ = VAL_SCOPE_READ;
+exports.VAL_SCOPE_WRITE = VAL_SCOPE_WRITE;
 exports.ValFSHost = ValFSHost;
 exports.ValLoginError = ValLoginError;
 exports.ValModuleLoader = ValModuleLoader;
@@ -12972,6 +14314,7 @@ exports.ValOpsFS = ValOpsFS;
 exports.ValOpsHttp = ValOpsHttp;
 exports.ValSourceFileHandler = ValSourceFileHandler;
 exports.analyzeValModule = analyzeValModule;
+exports.authorIdFromVerifiedSubject = authorIdFromVerifiedSubject;
 exports.awaitValLoginConfirmation = awaitValLoginConfirmation;
 exports.checkRemoteRef = checkRemoteRef;
 exports.classifyJsonValuesOp = classifyJsonValuesOp;
@@ -12983,7 +14326,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;
@@ -13015,6 +14360,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;