@valbuild/mcp 0.123.0

package/dist/declarations/src/images/remoteUploadTarget.d.ts

@@ -0,0 +1,70 @@
+import { type SerializedFileSchema, type SerializedImageSchema } from "@valbuild/core";
+import { type ValServerConfig } from "@valbuild/server";
+import { type ValToolError } from "../tools/index.js";
+/**
+ * Where a remote image goes, and what its ref has to say.
+ *
+ * Only one thing here needs the network: a project's `publicProjectId` and its
+ * list of buckets, which `getSettings` answers. Everything else is arithmetic
+ * over bytes the caller already handed us.
+ *
+ * And **no credential comes from the MCP caller**, in either mode. The rule is
+ * `resolveRemoteFileAuth` in `@valbuild/server`, shared with the Studio's own
+ * api routes: the app's api key where there is one, and otherwise — local
+ * development — the developer's own `val login` token off disk. That is the
+ * same precondition `val validate --fix` has, and the same one the Studio has
+ * when it uploads a remote image from a laptop.
+ *
+ * What this does NOT do is upload anything to the content host. A remote
+ * image's bytes go into the patch store like any other pending file, and the
+ * push to `remote.val.build` happens at publish, from
+ * `ValOpsFS.saveOrUploadFiles(mode: "upload-remote")`. See
+ * `docs/plans/mcp-remote-images.md` Part A.
+ */
+export type RemoteUploadTarget = {
+    publicProjectId: string;
+    bucket: string;
+    coreVersion: string;
+    remoteHost: string;
+};
+/**
+ * Resolves the project's remote-file settings, once.
+ *
+ * Cached for the life of the process because the answer does not move — a
+ * project's public id never changes and its bucket list changes when someone
+ * adds a bucket, which is not something an agent's upload should pay a network
+ * round trip to notice. Held as the promise rather than the value so that two
+ * uploads arriving together make one request rather than two.
+ */
+export type RemoteSettingsLoader = () => Promise<{
+    status: "success";
+    publicProjectId: string;
+    buckets: string[];
+} | ValToolError>;
+export declare function createRemoteSettingsLoader(options: ValServerConfig): RemoteSettingsLoader;
+export declare function nextBucket(buckets: string[]): string;
+/** Test seam: the rotation is process-global, so a suite has to be able to reset it. */
+export declare function resetBucketRotation(): void;
+export declare function resolveRemoteUploadTarget(loadSettings: RemoteSettingsLoader): Promise<{
+    status: "success";
+    target: RemoteUploadTarget;
+} | ValToolError>;
+/**
+ * The remote ref for these bytes, under this schema.
+ *
+ * The validation hash is the delicate part, and the reason `schema` is a
+ * parameter rather than something derived here: it is baked into the ref, and
+ * the validator recomputes it from the schema it finds at the path. Hand this
+ * the wrong schema and the upload succeeds and then never validates — see
+ * `docs/plans/mcp-remote-images.md` Part D, and `remoteImageSchemaFor`, which
+ * is where a gallery's synthesized schema comes from.
+ */
+export declare function buildRemoteRef(input: {
+    target: RemoteUploadTarget;
+    bytes: Uint8Array;
+    /** `public/...`, with no leading slash — the shape `createRemoteRef` demands. */
+    filePath: `public/${string}`;
+    fileExt: string;
+    metadata: Record<string, unknown> | undefined;
+    schema: SerializedImageSchema | SerializedFileSchema;
+}): string;

package/dist/declarations/src/images/types.d.ts

@@ -0,0 +1,60 @@
+/**
+ * What the image tool needs from an image library, and nothing else.
+ *
+ * The tool is not given `sharp`. It is given these two functions, because
+ * that is the whole of what uploading an image needs an image library for:
+ * read the dimensions out of the bytes, and re-encode them when the schema
+ * asks. Keeping the contract this narrow is what lets the host choose —
+ * `sharpImageProcessor` from `@valbuild/mcp/sharp` is the one we ship, and a
+ * project that already has an encoder can write its own in twenty lines.
+ *
+ * It also means this package has no native dependency. `sharp` ships a
+ * compiled binary per platform, and a CMS should not put one in every
+ * project's install just so that the projects which want image uploads can
+ * have them.
+ */
+export type ValImageProcessorResult = {
+    width: number;
+    height: number;
+    /** e.g. `image/webp`. */
+    mimeType: string;
+};
+export type ValImageEncodeRequest = {
+    /** The mime type to convert to, e.g. `image/webp`. */
+    mimeType: string;
+    /** Between 0 and 1, as `s.image({ encode: { quality } })` states it. */
+    quality: number;
+    /**
+     * The size to scale down to, or `null` when the image already fits inside
+     * the schema's bounds. Never an upscale: {@link fitWithin} answers `null`
+     * rather than a bigger box.
+     */
+    resizeTo: {
+        width: number;
+        height: number;
+    } | null;
+};
+export type ValImageProcessor = {
+    /**
+     * Width, height and mime type of these bytes.
+     *
+     * `null` when they are not an image this processor can read — which is an
+     * answer, not a failure: the tool reports it to the caller as invalid input
+     * rather than as an internal error, because that is what it is.
+     *
+     * Must not throw. A processor that throws is treated as an internal error.
+     */
+    read(bytes: Uint8Array): Promise<ValImageProcessorResult | null>;
+    /**
+     * Re-encode, or decline to.
+     *
+     * `null` means "I could not, upload the original" — the same answer the
+     * browser gives when a canvas is unavailable. A failed optimisation must
+     * never become a failed upload, so this is a normal outcome and not an
+     * error.
+     */
+    encode(bytes: Uint8Array, request: ValImageEncodeRequest): Promise<{
+        bytes: Uint8Array;
+        mimeType: string;
+    } | null>;
+};

package/dist/declarations/src/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Val's content tools, and the checks that decide whether a request may reach
+ * them, for hosts that speak the Model Context Protocol.
+ *
+ * Nothing in this package imports an MCP SDK. The app owns the transport —
+ * which SDK, which route, which framework — and this owns the parts that must
+ * not be re-decided per app: the tools themselves, whether a request is allowed
+ * to reach them at all, and whose credential it carries.
+ * `docs/plans/mcp.md` Part A has the reasoning; the short version is that the
+ * SDK reorganised itself once already, and the security checks should not move
+ * when it does again.
+ */
+export { createValTools } from "./tools/index.js";
+export type { ValToolsOptions } from "./tools/index.js";
+export type { ValScope, ValToolAuth, ValToolContext, ValToolDefinition, ValToolDefinitionJson, ValToolError, ValToolErrorCode, ValToolResult, ValTools, } from "./tools/index.js";
+export { VAL_SCOPE_READ, VAL_SCOPE_WRITE, authorIdFromVerifiedSubject, } from "./tools/index.js";
+export { defineTool, err, ok, savePatch } from "./tools/index.js";
+export type { OnInvalid, SavePatchData, SavePatchResult, UploadPatchFiles, ValToolDeps, ValToolImpl, ValToolState, } from "./tools/index.js";
+export { createValImageTools } from "./images/index.js";
+export type { ValImageProcessor, ValImageProcessorResult, ValImageEncodeRequest, } from "./images/index.js";
+export { initValMcp } from "./initValMcp.js";
+export type { ValMcp, ValMcpAuthorizationResult } from "./initValMcp.js";
+export type { ValOAuthConfig } from "./valAccessToken.js";
+export type { ValMcpMetadataHandlers } from "./valMcpMetadata.js";

package/dist/declarations/src/initValMcp.d.ts

@@ -0,0 +1,95 @@
+import { ValConfig, ValModules } from "@valbuild/core";
+import { type ValToolContext, type ValToolImpl, type ValTools } from "./tools/index.js";
+import { type ValOAuthConfig } from "./valAccessToken.js";
+import { type ValMcpMetadataHandlers } from "./valMcpMetadata.js";
+/**
+ * Val's tools over MCP, and the two checks that have to happen before a request
+ * gets to them.
+ *
+ * Nothing here imports an MCP SDK. The app owns the transport — which SDK, which
+ * route, which framework — and this owns the parts that must not be re-decided
+ * per app: whether the request is allowed to reach the tools at all, and whose
+ * credential it carries. `docs/plans/mcp.md` Part A has the reasoning; the short
+ * version is that the SDK reorganised itself once already, and the security
+ * checks should not move when it does again.
+ */
+export type ValMcpAuthorizationResult = {
+    status: "ok";
+    tools: ValTools;
+    ctx: ValToolContext;
+} | {
+    status: "refused";
+    response: Response;
+};
+export type ValMcp = {
+    /**
+     * Check a request and, if it is allowed, hand back the tools and the context
+     * to call them with.
+     *
+     * Call this per request — both halves are per request. Refusing early is the
+     * point: a refused request must not reach the protocol layer, let alone a
+     * tool.
+     */
+    valMcpAuthorize: (request: Request | undefined) => Promise<ValMcpAuthorizationResult>;
+    /**
+     * The registry itself, for listing tools at startup.
+     *
+     * Listing needs no credential — it reads no content — so registering tools
+     * with an MCP server can happen once rather than per request.
+     */
+    valMcpTools: () => Promise<ValTools>;
+    /**
+     * The RFC 9728 protected-resource document, for mounting at
+     * `/.well-known/oauth-protected-resource`.
+     *
+     * `null` when no `oauth` config was given: a project that has not been told
+     * where to authorize must not publish a document claiming it knows.
+     */
+    valMcpMetadata: ValMcpMetadataHandlers | null;
+};
+export declare function initValMcp(valModules: ValModules, config: ValConfig, opts?: {
+    formatter?: (code: string, filePath: string) => string | Promise<string>;
+    /**
+     * Where to authorize, and what audience to expect.
+     *
+     * Required for proxy mode, and only omittable in local filesystem mode —
+     * where there is no authorization server to talk to and no backend to
+     * authenticate to, so local development stays a one-liner. Provide it and
+     * every call needs a verified access token, including in fs mode, where a
+     * token is refused rather than ignored: a host that thinks it is
+     * authenticating should never silently get unauthenticated local access.
+     */
+    oauth?: ValOAuthConfig;
+    /**
+     * Tools to serve alongside the built-in ones.
+     *
+     * This is how the image tool gets in. It is not in the default set because
+     * it needs an image library to read the dimensions out of a JPEG and to
+     * re-encode one, and `sharp` is a native dependency that no project should
+     * acquire by installing a CMS. So the host constructs it —
+     * `createValImageTools(sharpImageProcessor(sharp))` — and passes it here,
+     * which is also what makes it the host's decision rather than ours.
+     *
+     * A name that collides with a built-in tool is refused rather than
+     * silently winning or silently losing: an agent that called `get_source`
+     * and reached something else would be a genuinely confusing afternoon.
+     */
+    extraTools?: ValToolImpl[];
+    /**
+     * The Val API route the Studio is mounted on. Only the data layer reads it.
+     */
+    route?: string;
+    /**
+     * Package versions, for a host that has its own.
+     *
+     * `initHandlerOptions` refuses to build a proxy-mode config without both,
+     * so a Next app passes its own version through
+     * (`@valbuild/next/server`'s `initValMcp` does this for you). A host that
+     * is not Next gets this package's version, which is the honest answer: it
+     * is the package serving the request.
+     */
+    versions?: {
+        core?: string;
+        next?: string;
+    };
+}): ValMcp;

package/dist/declarations/src/sharp/index.d.ts

@@ -0,0 +1,46 @@
+import type { ValImageProcessor } from "../images/types.js";
+/**
+ * `sharp`, as the image tool wants it.
+ *
+ * The library is passed IN rather than imported, and that is the whole point of
+ * this file existing separately. `sharp` ships a compiled binary per platform;
+ * importing it here would put one in every project that installs Val, for a
+ * feature most of them will not mount. Instead the project installs `sharp`
+ * itself and writes:
+ *
+ * ```ts
+ * import sharp from "sharp";
+ * import { createValImageTools } from "@valbuild/mcp";
+ * import { sharpImageProcessor } from "@valbuild/mcp/sharp";
+ *
+ * const tools = createValImageTools(sharpImageProcessor(sharp));
+ * ```
+ *
+ * The parameter is typed structurally — {@link SharpLike} — rather than as
+ * `import("sharp")`, for the same reason: a type-only import of a package that
+ * is not installed is still a compile error, and this package must typecheck in
+ * a project that has never heard of sharp. The real `sharp` satisfies it, and
+ * `sharpImageProcessor.test.ts` asserts as much against the actual library so
+ * the structural type cannot drift away from it unnoticed.
+ */
+/** What `sharp(bytes)` gives back, narrowed to what this file calls. */
+export type SharpPipelineLike = {
+    metadata(): Promise<{
+        width?: number | undefined;
+        height?: number | undefined;
+        format?: string | undefined;
+    }>;
+    resize(options: {
+        width?: number | undefined;
+        height?: number | undefined;
+        fit?: "inside" | undefined;
+        withoutEnlargement?: boolean | undefined;
+    }): SharpPipelineLike;
+    rotate(): SharpPipelineLike;
+    webp(options: {
+        quality?: number | undefined;
+    }): SharpPipelineLike;
+    toBuffer(): Promise<Buffer>;
+};
+export type SharpLike = (input: Uint8Array) => SharpPipelineLike;
+export declare function sharpImageProcessor(sharp: SharpLike): ValImageProcessor;

package/dist/declarations/src/tools/createValTools.d.ts

@@ -0,0 +1,47 @@
+import type { ValModules } from "@valbuild/core";
+import { type ValOps, type ValServerConfig } from "@valbuild/server";
+import type { ValToolImpl, ValToolState } from "./defineTool.js";
+import { type ValToolError, type ValTools } from "./types.js";
+export type ValToolsOptions = ValServerConfig;
+/**
+ * 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.
+ */
+export declare function createValTools(valModules: ValModules, options: ValToolsOptions, 
+/**
+ * Tools the host built itself, served alongside the built-in ones.
+ *
+ * The image tool arrives this way: it needs an image library the host has to
+ * install, so it cannot be constructed here. See `createValImageTools`.
+ */
+extraTools?: ValToolImpl[]): ValTools;
+/**
+ * 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.
+ */
+export declare function loadState(ops: ValOps): Promise<{
+    status: "ok";
+    state: ValToolState;
+} | {
+    status: "error";
+    result: ValToolError;
+}>;

package/dist/declarations/src/tools/defineTool.d.ts

@@ -0,0 +1,79 @@
+import type { Json, ModuleFilePath, PatchId, SerializedSchema } from "@valbuild/core";
+import type { z } from "zod";
+import type { ValOps, OrderedPatches, PatchAnalysis, Schemas, Sources, ValServerConfig } from "@valbuild/server";
+import type { ValToolContext, ValToolDefinition, ValToolError, ValToolErrorCode, ValToolResult } from "./types.js";
+/**
+ * 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. */
+export type ValToolDeps = {
+    /**
+     * The data layer for *this call*. In proxy mode it is authenticated as the
+     * caller, so a tool must never reach for an ambient instance instead.
+     */
+    ops: ValOps;
+    /**
+     * How this project is configured — the same object `createValOps` was built
+     * from.
+     *
+     * Here because remote images need it: which credential talks to the content
+     * host about them is a property of the project, not of the caller, and a tool
+     * that had to be handed it separately would be handed a second copy of an
+     * answer the registry already has.
+     */
+    config: ValServerConfig;
+    ctx: ValToolContext;
+    /**
+     * The content as the caller should see it: base sources with pending patches
+     * applied, plus the schemas and the patch analysis that produced them.
+     *
+     * Loaded once per call and shared, because a tool that re-derived it would
+     * both pay for it again and risk reading a different revision than the one it
+     * validated against.
+     */
+    state: ValToolState;
+};
+export type ValToolState = {
+    schemas: Schemas;
+    serializedSchemas: Record<ModuleFilePath, SerializedSchema>;
+    sources: Sources;
+    patches: OrderedPatches;
+    analysis: PatchAnalysis;
+    /**
+     * Pending patches that would not apply, by the module they belong to.
+     *
+     * A module listed here has `sources` that silently lack those changes, so its
+     * content is not what publishing would produce. Reads still return it — it is
+     * what the Studio would show too, and a project has to stay diagnosable — but
+     * a write to such a module is refused, because it would be based on a state
+     * that does not exist.
+     */
+    unappliedPatches: Record<ModuleFilePath, {
+        patchId: PatchId;
+        skipped: boolean;
+        error: {
+            message: string;
+        };
+    }[]>;
+};
+export type ValToolImpl = ValToolDefinition & {
+    handler: (args: unknown, deps: ValToolDeps) => Promise<ValToolResult>;
+};
+/**
+ * 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.
+ */
+export declare function defineTool<S extends z.ZodType>(definition: Omit<ValToolDefinition, "inputSchema"> & {
+    inputSchema: S;
+}, handler: (args: z.infer<S>, deps: ValToolDeps) => Promise<ValToolResult>): ValToolImpl;
+export declare function ok(data: Json): ValToolResult;
+export declare function err(code: ValToolErrorCode, message: string): ValToolError;

package/dist/declarations/src/tools/index.d.ts

@@ -0,0 +1,7 @@
+export { createValTools, type ValToolsOptions } from "./createValTools.js";
+export { defineTool, err, ok } from "./defineTool.js";
+export type { ValToolDeps, ValToolImpl, ValToolState } from "./defineTool.js";
+export { savePatch, mintPatchId, deriveParentRef } from "./writePath.js";
+export type { OnInvalid, SavePatchData, SavePatchResult, UploadPatchFiles, } from "./writePath.js";
+export { VAL_SCOPE_READ, VAL_SCOPE_WRITE, authorIdFromVerifiedSubject, } from "./types.js";
+export type { ValScope, ValToolAuth, ValToolContext, ValToolDefinition, ValToolDefinitionJson, ValToolError, ValToolErrorCode, ValToolResult, ValTools, } from "./types.js";

package/dist/declarations/src/tools/types.d.ts

@@ -0,0 +1,172 @@
+import type { AuthorId } from "@valbuild/server";
+import type { Json } from "@valbuild/core";
+import type { z } from "zod";
+/**
+ * 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. */
+export type ValToolErrorCode = 
+/** No tool of that name is registered. */
+"unknown-tool"
+/** The arguments did not satisfy the tool's `inputSchema`. */
+ | "invalid-args"
+/** The path, module or key the arguments name does not exist. */
+ | "not-found"
+/** The caller is not allowed to do this — wrong credential, or none. */
+ | "forbidden"
+/**
+ * The write was rejected because applying it would leave content invalid.
+ * Nothing was stored. See `docs/plans/mcp.md` Part C on speculative
+ * validation.
+ */
+ | "validation-failed"
+/**
+ * Another writer moved the patch chain first. Callers may re-derive the
+ * parent ref and retry once; the registry does that itself before
+ * surfacing this.
+ */
+ | "conflict"
+/** The tool exists but is not available in this mode (e.g. fs vs http). */
+ | "unsupported"
+/** Anything else, including an upstream failure. */
+ | "internal";
+export type ValToolDefinition = {
+    name: string;
+    title?: string;
+    description: string;
+    /** zod v4 — a Standard Schema, which is what the MCP SDKs consume. */
+    inputSchema: z.ZodType;
+    /**
+     * MCP tool annotations. Hints, not enforcement: a host may show them to a
+     * user or use them to decide what to auto-approve, so they have to be
+     * honest about what the tool does.
+     */
+    annotations?: {
+        readOnlyHint?: boolean;
+        destructiveHint?: boolean;
+        idempotentHint?: boolean;
+    };
+};
+/**
+ * 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.
+ */
+export type ValToolDefinitionJson = Omit<ValToolDefinition, "inputSchema"> & {
+    inputSchema: ReturnType<typeof z.toJSONSchema<z.ZodType>>;
+};
+/**
+ * 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.
+ */
+export type ValToolAuth = {
+    type: "verified-profile";
+    /**
+     * The profile the host **verified** — the `sub` of an access token whose
+     * signature, issuer, audience and expiry were all checked against the
+     * authorization server's published key.
+     *
+     * This field is why an identity field exists at all, and an earlier version
+     * of this file argued none should. That argument was about a specific case
+     * and stated too broadly: an id the host *asserts* on the strength of a
+     * credential it cannot check is an unverified claim dressed as a checked one,
+     * and that is still refused — it is why a relayed token never carried a
+     * profile, and now cannot reach here at all. An id the host *verified*
+     * cryptographically is a different thing, and it is the same standing the
+     * Studio has when it re-signs a session it established itself.
+     */
+    profileId: AuthorId;
+    /**
+     * The token's granted scopes, as the authorization server issued them.
+     *
+     * Enforced here as well as by the backend, deliberately. Two checks on one
+     * grant is not redundancy for its own sake: this one can refuse a write
+     * before it is attempted, so a token that may only read never reaches the
+     * code that builds a patch.
+     */
+    scopes: string[];
+};
+/**
+ * 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.
+ */
+export type ValToolContext = {
+    auth: ValToolAuth | null;
+    /** Groups a run of related edits, when the host has such a notion. */
+    sessionId: string | null;
+};
+/**
+ * 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`.
+ */
+export declare function authorIdFromVerifiedSubject(subject: string): AuthorId;
+/** Read access. Every call needs it, the writes included. */
+export declare const VAL_SCOPE_READ = "val:read";
+/** Write access. Needed *in addition* by any tool not marked `readOnlyHint`. */
+export declare const VAL_SCOPE_WRITE = "val:write";
+export type ValScope = typeof VAL_SCOPE_READ | typeof VAL_SCOPE_WRITE;
+export type ValToolResult = {
+    status: "ok";
+    data: Json;
+} | ValToolError;
+/**
+ * The failure half of {@link ValToolResult}, on its own.
+ *
+ * Named because several internal steps can only fail — speculative validation
+ * rejecting a patch, an upload that did not land — and typing those as the
+ * whole union means the compiler cannot see that an early return is in fact an
+ * error return.
+ */
+export type ValToolError = {
+    status: "error";
+    code: ValToolErrorCode;
+    message: string;
+};
+export type ValTools = {
+    list(): ValToolDefinition[];
+    listJsonSchema(): ValToolDefinitionJson[];
+    call(name: string, args: unknown, ctx: ValToolContext): Promise<ValToolResult>;
+    dispose(): Promise<void>;
+};