@valbuild/server 0.122.0 → 0.123.0

package/dist/valbuild-server.esm.js

@@ -1,21 +1,20 @@
 import ts from 'typescript';
 import { pipe, result, array } from '@valbuild/core/fp';
 import { PatchError, deepEqual, parseAndValidateArrayIndex, isNotRoot, applyPatch, JSONOps, deepClone, sourceToPatchPath } from '@valbuild/core/patch';
-import { derefPatch, Internal, RecordSchema, extractValModules, computeValModuleShas, VAL_EXTENSION, ImageSchema, DEFAULT_CONTENT_HOST, hasRemoteFileSchema, getSourcePathFromRoute } from '@valbuild/core';
+import { derefPatch, Internal, RecordSchema, extractValModules, computeValModuleShas, VAL_EXTENSION, ImageSchema, DEFAULT_CONTENT_HOST, hasRemoteFileSchema } from '@valbuild/core';
 export { hasRemoteFileSchema } from '@valbuild/core';
 import * as path from 'path';
 import path__default from 'path';
 import fs, { promises } from 'fs';
 import vm from 'node:vm';
 import { Module, createRequire } from 'node:module';
-import { resolveSchemaSourceFixForError, Patch, getErrorMessageFromUnknownJson, JSONValue, PatchGroup, newestCommitSha, SerializedSchema, VAL_ENABLE_COOKIE_NAME, VAL_STATE_COOKIE, VAL_SESSION_COOKIE, Api, filterBlockingValidationErrors, describeContainerAtPath, safeParsePatch, buildDuplicatePatch, buildEmptyAtPathPatch, buildRemoveImageGalleryEntryPatch } from '@valbuild/shared/internal';
+import { resolveSchemaSourceFixForError, Patch, getErrorMessageFromUnknownJson, JSONValue, PatchGroup, newestCommitSha, SerializedSchema, VAL_ENABLE_COOKIE_NAME, VAL_STATE_COOKIE, VAL_SESSION_COOKIE, Api } from '@valbuild/shared/internal';
 import { createUIRequestHandler } from '@valbuild/ui/server';
 import crypto$1 from 'crypto';
 import z$1, { z } from 'zod';
 import sizeOf from 'image-size';
 import { fromError } from 'zod-validation-error';
 import os from 'os';
-import { randomUUID } from 'node:crypto';
 import { transform } from 'sucrase';
 import http from 'http';
 import https from 'https';
@@ -1009,7 +1008,7 @@ function errorMessage(e) {
   return String(e);
 }
 
-const jsonOps$3 = new JSONOps();
+const jsonOps$2 = new JSONOps();
 
 /**
  * Classification of a single patch op against a module's serialized schema,
@@ -1264,7 +1263,7 @@ function applyJsonValuesEntryPatches(args) {
           // on an entry that does not exist.
           continue;
         }
-        const applied = applyPatch(deepClone(content), jsonOps$3, [{
+        const applied = applyPatch(deepClone(content), jsonOps$2, [{
           op: "add",
           path: cls.subPath.concat(...(op.nestedFilePath ?? [])).concat("patch_id"),
           value: patchId
@@ -1318,7 +1317,7 @@ function applyJsonValuesEntryPatches(args) {
           patchId
         };
       }
-      const applied = applyPatch(deepClone(content), jsonOps$3, [rebased.value]);
+      const applied = applyPatch(deepClone(content), jsonOps$2, [rebased.value]);
       if (result.isErr(applied)) {
         return {
           kind: "error",
@@ -1601,7 +1600,7 @@ function findJsonEntryFilePath(moduleFilePath, valTsSourceFile, entryKey) {
   return resolveExistingJsonPath(moduleFilePath, entry.importPath);
 }
 
-const jsonOps$2 = new JSONOps();
+const jsonOps$1 = new JSONOps();
 
 /**
  * Substitutes loaded `.jsonValues()` entry content back into a module's root
@@ -1907,7 +1906,7 @@ class Service {
       if (result.isErr(rebased)) {
         throw Error(`Could not apply ${op.op} to jsonValues entry '${entryKey}' of ${moduleFilePath}: ${rebased.error.message}`);
       }
-      const applied = applyPatch(deepClone(content), jsonOps$2, [rebased.value]);
+      const applied = applyPatch(deepClone(content), jsonOps$1, [rebased.value]);
       if (result.isErr(applied)) {
         throw Error(`Could not apply ${op.op} to ${jsonPath}: ${applied.error.message}`);
       }
@@ -1981,7 +1980,7 @@ const EXTERNAL_RESULT = Symbol.for("@valbuild/server/ExternalResult");
  * fails where the helper is used rather than where it is written. Annotate the
  * helper's return type, or inline it.
  */
-function ok$1(value, warnings) {
+function ok(value, warnings) {
   return warnings && warnings.length > 0 ? {
     [EXTERNAL_RESULT]: true,
     kind: "ok",
@@ -1993,7 +1992,7 @@ function ok$1(value, warnings) {
     value
   };
 }
-function err$1(issue) {
+function err(issue) {
   return {
     [EXTERNAL_RESULT]: true,
     kind: "err",
@@ -2253,7 +2252,7 @@ function encodeJwt(payload, sessionKey) {
 }
 
 /* eslint-disable @typescript-eslint/no-unused-vars */
-const jsonOps$1 = new JSONOps();
+const jsonOps = new JSONOps();
 const tsOps = new TSOps(document => {
   return pipe(analyzeValModule(document), result.map(({
     source
@@ -3023,7 +3022,7 @@ class ValOps {
         }
         const patchRes = applyPatch(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$1, applicableOps.concat(...Object.values(fileFixOps)));
+        jsonOps, applicableOps.concat(...Object.values(fileFixOps)));
         if (result.isErr(patchRes)) {
           console.error("Could not apply patch", JSON.stringify({
             path,
@@ -3723,7 +3722,7 @@ class ValOps {
               patchHadError = true;
               break;
             }
-            const applied = applyPatch(deepClone(contentRes.value), jsonOps$1, [rebasedRes.value]);
+            const applied = applyPatch(deepClone(contentRes.value), jsonOps, [rebasedRes.value]);
             if (result.isErr(applied)) {
               collectPatchError(applied.error, patchId, op);
               patchHadError = true;
@@ -8996,6 +8995,59 @@ async function getSettings(projectName, auth) {
   }
 }
 
+function getPersonalAccessTokenPath(root) {
+  return path__default.join(path__default.resolve(root), ".val", "pat.json");
+}
+function parsePersonalAccessTokenFile(content) {
+  if (!content) {
+    return {
+      success: false,
+      error: "Invalid content: undefined"
+    };
+  }
+  let patFileContent;
+  try {
+    patFileContent = JSON.parse(content);
+  } catch {
+    return {
+      success: false,
+      error: `Invalid content: file is not a valid JSON file`
+    };
+  }
+  if (typeof patFileContent !== "object") {
+    return {
+      success: false,
+      error: "Invalid content: not an object"
+    };
+  }
+  if (!patFileContent) {
+    return {
+      success: false,
+      error: "Invalid content: null"
+    };
+  }
+  if (!("pat" in patFileContent)) {
+    return {
+      success: false,
+      error: "Invalid content: key 'pat' is missing"
+    };
+  }
+  const patField = patFileContent.pat;
+  if (typeof patField === "string") {
+    return {
+      success: true,
+      data: {
+        pat: patField
+      }
+    };
+  } else {
+    return {
+      success: false,
+      error: "Invalid content: pat is not a string"
+    };
+  }
+}
+
 /**
  * Resolving how Val is configured, and building the data layer from it.
  *
@@ -9225,57 +9277,77 @@ function warnIfInsecureUrls(urls) {
   }
 }
 
-function getPersonalAccessTokenPath(root) {
-  return path__default.join(path__default.resolve(root), ".val", "pat.json");
-}
-function parsePersonalAccessTokenFile(content) {
-  if (!content) {
-    return {
-      success: false,
-      error: "Invalid content: undefined"
-    };
-  }
-  let patFileContent;
-  try {
-    patFileContent = JSON.parse(content);
-  } catch {
-    return {
-      success: false,
-      error: `Invalid content: file is not a valid JSON file`
-    };
-  }
-  if (typeof patFileContent !== "object") {
+/**
+ * Which credential talks to the content host about REMOTE FILES.
+ *
+ * A separate question from the one `createValOps` answers, and it has to be:
+ * `ValOps` is authenticated per caller, but remote files are project-level —
+ * looking up a project's public id and its buckets, and later pushing bytes to
+ * them, is the same operation whoever asked for it.
+ *
+ * The rule, in order:
+ *
+ * 1. The app's API key, if there is one. Proxy mode always has one; fs mode has
+ *    one when `VAL_API_KEY` is set.
+ * 2. In fs mode, the developer's own `val login` token, read off disk. This is
+ *    the same file `val validate --fix` reads, and it is why local remote
+ *    uploads work with no configuration beyond having logged in.
+ * 3. Nothing, which is an error rather than a fallback.
+ *
+ * Lives here rather than inside `createValServer` because the MCP image tool
+ * needs the same answer, and this is the file that exists so that two callers
+ * cannot disagree about how a project is configured. A registry that decided it
+ * had no credential while the Studio in the same process had one would be a
+ * genuinely confusing afternoon.
+ */
+
+async function resolveRemoteFileAuth(options) {
+  if (options.apiKey) {
     return {
-      success: false,
-      error: "Invalid content: not an object"
+      status: "success",
+      auth: {
+        apiKey: options.apiKey
+      }
     };
   }
-  if (!patFileContent) {
+  if (options.mode !== "fs") {
+    // Unreachable through `initHandlerOptions`, which refuses to build a proxy
+    // config without an api key. Kept because this is exported.
     return {
-      success: false,
-      error: "Invalid content: null"
+      status: "error",
+      errorCode: "project-not-configured",
+      message: "Remote file auth is not configured"
     };
   }
-  if (!("pat" in patFileContent)) {
+  // `options.cwd`, which `initHandlerOptions` sets from `process.cwd()`. The
+  // token lives in the project's own `.val/pat.json`, so this is the same file
+  // `val login` wrote and `val validate --fix` reads.
+  const patPath = getPersonalAccessTokenPath(options.cwd);
+  const fs = await import('fs');
+  let patFile;
+  try {
+    patFile = await fs.promises.readFile(patPath, "utf-8");
+  } catch {
     return {
-      success: false,
-      error: "Invalid content: key 'pat' is missing"
+      status: "error",
+      errorCode: "pat-error",
+      message: "Could not read personal access token file"
     };
   }
-  const patField = patFileContent.pat;
-  if (typeof patField === "string") {
+  const patRes = parsePersonalAccessTokenFile(patFile);
+  if (!patRes.success) {
     return {
-      success: true,
-      data: {
-        pat: patField
-      }
-    };
-  } else {
-    return {
-      success: false,
-      error: "Invalid content: pat is not a string"
+      status: "error",
+      errorCode: "pat-error",
+      message: "Could not parse personal access token file"
     };
   }
+  return {
+    status: "success",
+    auth: {
+      pat: patRes.data.pat
+    }
+  };
 }
 
 /* eslint-disable @typescript-eslint/no-unused-vars */
@@ -9450,6 +9522,14 @@ const ValServer = (valModules, options, callbacks) => {
     };
   };
   let remoteFileAuth = null;
+  /**
+   * The credential for remote-file work, memoised for the life of the server.
+   *
+   * The rule itself is `resolveRemoteFileAuth` in `valServerConfig`, shared with
+   * the MCP image tool — what is left here is the memoisation and the shape the
+   * api routes answer in. Memoised because in fs mode it reads a file off disk,
+   * and every remote image in a gallery would otherwise read it again.
+   */
   const getRemoteFileAuth = async () => {
     if (remoteFileAuth) {
       return {
@@ -9459,59 +9539,17 @@ const ValServer = (valModules, options, callbacks) => {
         }
       };
     }
-    if (options.apiKey) {
-      remoteFileAuth = {
-        apiKey: options.apiKey
-      };
-    } else if (serverOps instanceof ValOpsFS) {
-      const projectRootDir = options.config.root || ".";
-      if (!projectRootDir) {
-        return {
-          status: 400,
-          json: {
-            errorCode: "project-not-configured",
-            message: "Root directory was empty"
-          }
-        };
-      }
-      const fs = await import('fs');
-      const patPath = getPersonalAccessTokenPath(path__default.join(process.cwd()));
-      let patFile;
-      try {
-        patFile = await fs.promises.readFile(patPath, "utf-8");
-      } catch (err) {
-        return {
-          status: 400,
-          json: {
-            errorCode: "pat-error",
-            message: "Could not read personal access token file"
-          }
-        };
-      }
-      const patRes = parsePersonalAccessTokenFile(patFile);
-      if (patRes.success) {
-        remoteFileAuth = {
-          pat: patRes.data.pat
-        };
-      } else {
-        return {
-          status: 400,
-          json: {
-            errorCode: "pat-error",
-            message: "Could not parse personal access token file"
-          }
-        };
-      }
-    }
-    if (!remoteFileAuth) {
+    const resolved = await resolveRemoteFileAuth(options);
+    if (resolved.status === "error") {
       return {
         status: 400,
         json: {
-          errorCode: "project-not-configured",
-          message: "Remote file auth is not configured"
+          errorCode: resolved.errorCode,
+          message: resolved.message
         }
       };
     }
+    remoteFileAuth = resolved.auth;
     return {
       status: 200,
       json: {
@@ -13224,1275 +13262,6 @@ function getCookies(req, cookiesDef) {
   return 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.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.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.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.object({
-      moduleFilePath: ModuleFilePathSchema$1,
-      path: z.array(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.number().int().min(1).default(100).describe("Maximum number of keys to return."),
-      offset: 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.object({
-      moduleFilePath: ModuleFilePathSchema$1,
-      path: z.array(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.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 = 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.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.object({
-      route: z.string().describe('A route on the site, e.g. "/blog/my-post".')
-    }),
-    annotations: {
-      readOnlyHint: true,
-      idempotentHint: true
-    }
-  }, async ({
-    route
-  }, {
-    state
-  }) => {
-    const found = 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 = 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 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 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) {
-  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 = applyPatch(deepClone(current), jsonOps, patch);
-  if (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 = 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;
-  }
-
-  /**
-   * The verified profile, or null when there was nothing to verify.
-   *
-   * An author is written only when somebody checked it. On the token path 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 there, 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.
-   *
-   * Null is what local filesystem mode gets, where there is no credential to
-   * resolve, exactly as the Studio does locally. It is also what the removed
-   * personal-access-token path got, and for a reason worth keeping in view: an
-   * id derived from a credential the app cannot resolve is an unverified claim
-   * dressed up as a checked one. Should another unverified credential ever
-   * reach here, null remains its only honest author.
-   */
-  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 (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.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.object({
-      moduleFilePath: ModuleFilePathSchema,
-      patch: z.array(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 = 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.object({
-      moduleFilePath: ModuleFilePathSchema,
-      sourcePath: z.array(z.string()).describe("Path of the value to copy."),
-      destinationPath: z.array(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 = 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.object({
-      moduleFilePath: ModuleFilePathSchema,
-      destinationPath: z.array(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 = 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.object({
-      moduleFilePath: ModuleFilePathSchema.describe("The gallery module, i.e. one declared with s.images() or s.files()."),
-      filePath: 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 = 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 there is one acceptable answer: the host
- * **checked a signature**.
- *
- * A union of one, deliberately. It carried a second variant — a personal access
- * token relayed to the backend unchecked, on the reasoning that the app cannot
- * resolve one and the backend can. The reasoning held; the shape did not. A
- * credential the host cannot check is one it also cannot refuse, so accepting
- * one made "a deployed endpoint that authenticates nobody" a supported
- * configuration, and it let a host serve these tools without ever being told
- * where callers should authorize. The discriminant stays so that adding a
- * second *verified* kind stays a one-line change at every call site.
- */
-
-/**
- * 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";
-
-/**
- * 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.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 in proxy mode there is
- * exactly one credential it will act on: an access token whose signature,
- * issuer, audience and expiry the host verified against the authorization
- * server's published key. Anything less is refused here rather than forwarded.
- *
- * There used to be a second route — the caller's personal access token, passed
- * through unread on the reasoning that the backend, not the app, is the
- * authority on what it may do. That was true, and it was still the wrong shape:
- * it made an unauthenticated bearer token on a deployed endpoint a supported
- * configuration, and it meant `initValMcp` had a path where an app served MCP
- * without ever being told where to authorize. A host that has not verified
- * anything now gets a refusal that names the missing `oauth` config.
- *
- * What has *not* changed is why a verified token does not become the app's own
- * API key by some other name. The app authenticates to the backend with its own
- * key here, and who did what travels as the patch's `authorId` — so the
- * profile has to be one the host checked cryptographically, never one it was
- * handed. An `authenticate()` that decided a credential's rights inside the app
- * would make every bug in it full access to every project that key can reach.
- */
-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.
-        //
-        // A verified access token is not something the caller chose to send: it
-        // only exists because this app advertised an authorization server, so
-        // the developer seeing this did not do anything wrong — a config file
-        // did, and naming it is the difference between a two-minute fix and an
-        // afternoon.
-        return {
-          status: "error",
-          result: {
-            status: "error",
-            code: "unsupported",
-            message: "This Val project is running in local filesystem mode, so there is nothing to authenticate against, but it is configured with an `oauth` issuer and is therefore asking clients for an access token it cannot use. Remove the `oauth` config (or `VAL_OAUTH_ISSUER` from your local `.env`) for local development."
-          }
-        };
-      }
-      return {
-        status: "ok",
-        ops
-      };
-    };
-  }
-
-  /**
-   * One instance for every verified caller, and 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`.
-   *
-   * One instance is also all proxy mode keeps now. It could not share while a
-   * personal access token reached this function: each token needed its own
-   * `ValOpsHttp` to hold it, each of those cached the project's evaluated
-   * modules, and the bounded cache that kept that memory in check turned an
-   * eviction into a re-evaluation of every module on the next call.
-   */
-  let sharedOps = null;
-  return ctx => {
-    var _ctx$auth;
-    if (((_ctx$auth = ctx.auth) === null || _ctx$auth === void 0 ? void 0 : _ctx$auth.type) !== "verified-profile") {
-      return {
-        status: "error",
-        result: {
-          status: "error",
-          code: "forbidden",
-          message: "This Val project talks to the Val content backend, so every call needs an access token from the Val authorization server. If this endpoint is not asking clients to authorize, it has no `oauth` config — give `initValMcp` one, or run the project in local filesystem mode for development."
-        }
-      };
-    }
-    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
-    };
-  };
-}
-/**
- * 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.
- *
- * Exported for `toolsFixture`, not for consumers: `tools/index.ts` re-exports by
- * name, so this stays inside the package. A test that assembled its own state
- * would be asserting against a view no real call ever sees.
- */
-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.
- *
- * The early return is a call carrying no verified credential, and there is no
- * scope to check because nothing granted one. In Val's own host that means
- * local filesystem mode, where a project writing a developer's own working tree
- * has no wider authority to withhold. A host assembling its own context can
- * also reach it with an unauthenticated proxy-mode call — refused a few lines
- * later, by `resolveOps`, for the credential rather than the scope. Every other
- * caller arrives as a verified profile, carrying the scopes its token was
- * issued with.
- */
-function refuseInsufficientScope(tool, ctx) {
-  var _ctx$auth2, _tool$annotations;
-  if (((_ctx$auth2 = ctx.auth) === null || _ctx$auth2 === void 0 ? void 0 : _ctx$auth2.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"]]];
@@ -16692,4 +15461,4 @@ function readCapturedReport(snapshotDir) {
   return JSON.parse(fs.readFileSync(reportPath, "utf-8"));
 }
 
-export { DEFAULT_LOGIN_EXPIRES_IN_SECONDS, DEFAULT_LOGIN_HOST, DEFAULT_LOGIN_POLL_INTERVAL_SECONDS, EXTERNAL_RESULT, Service, VAL_SCOPE_READ, VAL_SCOPE_WRITE, ValFSHost, ValLoginError, ValModuleLoader, ValOpsFS, ValOpsHttp, ValSourceFileHandler, analyzeValModule, authorIdFromVerifiedSubject, awaitValLoginConfirmation, checkRemoteRef, classifyJsonValuesOp, compareWithCapturedReport, createDefaultValFSHost, createFixPatch, createJsonEntryPathMap, createModulePathMap, createService, createValApiRouter, createValModuleFileInspector, createValOps, createValServer, createValTools, currentFixHandlers, decodeJwtWithoutVerifying, defineExternal, describePatchStoreProblems, downloadFileFromRemote, encodeJwt, err$1 as err, evalValConfigFile, extractFileMetadata, extractImageMetadata, extractJsonValuesEntry, findAndEvalValConfigFile, findJsonEntryFilePath, fixHandlers, formatPatchSourceError, formatSyntaxErrorTree, getCachedRemoteFileDir, getCachedRemoteFilePath, getCompilerOptions, getExpire, getFileExt, getModulePathRange, getPersonalAccessTokenPath, getSettings, getValidationErrorFileRef, handleCheckAllFiles, handleExternalUpload, handleFileMetadata, handleJsonValuesExtractEntry, handleRemoteFileCheck, handleRemoteFileDownload, handleRemoteFileUpload, handleRemoteGalleryFileUpload, handleUniqueFolderCheck, initHandlerOptions, isExternalResult, loadValModules, ok$1 as ok, parsePersonalAccessTokenFile, patchSourceFile, persistPersonalAccessToken, readCapturedReport, readPatchStore, rebaseContentOp, replaySnapshot, safeReadGit, startValLogin, uploadRemoteFile, validateMetadata, verifyJwt };
+export { DEFAULT_LOGIN_EXPIRES_IN_SECONDS, DEFAULT_LOGIN_HOST, DEFAULT_LOGIN_POLL_INTERVAL_SECONDS, EXTERNAL_RESULT, Service, ValFSHost, ValLoginError, ValModuleLoader, ValOpsFS, ValOpsHttp, ValSourceFileHandler, analyzeValModule, awaitValLoginConfirmation, checkRemoteRef, classifyJsonValuesOp, compareWithCapturedReport, createDefaultValFSHost, createFixPatch, createJsonEntryPathMap, createModulePathMap, createService, createValApiRouter, createValModuleFileInspector, createValOps, createValServer, currentFixHandlers, decodeJwtWithoutVerifying, defineExternal, describePatchStoreProblems, downloadFileFromRemote, encodeJwt, err, evalValConfigFile, extractFileMetadata, extractImageMetadata, extractJsonValuesEntry, findAndEvalValConfigFile, findJsonEntryFilePath, fixHandlers, formatPatchSourceError, formatSyntaxErrorTree, getCachedRemoteFileDir, getCachedRemoteFilePath, getCompilerOptions, getExpire, getFileExt, getModulePathRange, getPersonalAccessTokenPath, getSettings, getValidationErrorFileRef, handleCheckAllFiles, handleExternalUpload, handleFileMetadata, handleJsonValuesExtractEntry, handleRemoteFileCheck, handleRemoteFileDownload, handleRemoteFileUpload, handleRemoteGalleryFileUpload, handleUniqueFolderCheck, initHandlerOptions, isExternalResult, loadValModules, ok, parsePersonalAccessTokenFile, patchSourceFile, persistPersonalAccessToken, readCapturedReport, readPatchStore, rebaseContentOp, replaySnapshot, resolveRemoteFileAuth, safeReadGit, startValLogin, uploadRemoteFile, validateMetadata, verifyJwt };