@farm.js/webmcp 0.1.0-beta.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2024 Farm.js Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,61 @@
+# @farm.js/webmcp
+
+Explicit, typed browser tools for Farm applications using the experimental WebMCP API.
+
+Farm.js and WebMCP are currently in beta. WebMCP is a Community Group draft, not a W3C Standard.
+
+## Install
+
+```bash
+pnpm add @farm.js/webmcp
+```
+
+## Configure
+
+```ts
+import { defineConfig } from "@farm.js/core";
+import { webmcp } from "@farm.js/webmcp";
+
+export default defineConfig({
+  plugins: [webmcp()],
+});
+```
+
+Define tools in client code and register them only while they are relevant:
+
+```ts
+import { defineWebMCPTool, registerWebMCPTool } from "@farm.js/webmcp/client";
+
+const searchProducts = defineWebMCPTool({
+  name: "search_products",
+  description: "Search products currently available in this store.",
+  inputSchema: {
+    type: "object",
+    properties: { query: { type: "string" } },
+    required: ["query"],
+    additionalProperties: false,
+  },
+  annotations: { readOnlyHint: true },
+  async execute({ query }: { query: string }, { signal }) {
+    const response = await fetch(`/api/products?q=${encodeURIComponent(query)}`, { signal });
+    return response.json();
+  },
+});
+
+const unregister = registerWebMCPTool(searchProducts);
+// Call unregister() when this tool is no longer valid for the current page.
+```
+
+Pass a Zod, Valibot, ArkType, or other Standard Schema validator through `validate` when the input
+must also be checked at runtime. Keep `inputSchema` because that JSON Schema is what the browser
+agent sees.
+
+## Security boundary
+
+The plugin never scans or exposes Farm server functions. Each tool is an explicit browser-side
+registration. JSON Schema and `validate` protect the handler's input shape, but they are not
+authorization. Any API, query, or action called by a tool must still verify the server session and
+permissions exactly like a normal browser request.
+
+Tools stay same-origin by default. The plugin intentionally does not expose the draft `exposedTo`
+option in its first version.

package/dist/client.d.ts

@@ -0,0 +1,37 @@
+import type { FarmWebMCPRuntime, InferWebMCPValidatorOutput, WebMCPJSONValue, WebMCPToolDefinition, WebMCPValidator } from "./types.js";
+export type { FarmWebMCPRuntime, InferWebMCPValidatorOutput, WebMCPInputSchema, WebMCPJSONPrimitive, WebMCPJSONValue, WebMCPSafeParseFailure, WebMCPSafeParseResult, WebMCPSafeParseSuccess, WebMCPStandardSchema, WebMCPToolAnnotations, WebMCPToolDefinition, WebMCPToolExecutionContext, WebMCPToolMetadata, WebMCPValidator, } from "./types.js";
+export type WebMCPUnsupportedBehavior = "ignore" | "warn" | "error";
+export interface StartWebMCPRuntimeOptions {
+    unsupported?: WebMCPUnsupportedBehavior;
+    /** Expose `window.__FARM_WEBMCP__` and log registration failures. */
+    debug?: boolean;
+}
+declare global {
+    interface Window {
+        /** Development inspector enabled by `webmcp({ debug: true })`. */
+        __FARM_WEBMCP__?: FarmWebMCPRuntime;
+    }
+}
+/** An actionable validation failure returned to the invoking browser agent. */
+export declare class WebMCPInputError extends TypeError {
+    readonly toolName: string;
+    readonly issues: unknown;
+    constructor(toolName: string, issues: unknown);
+}
+export declare function defineWebMCPTool<TValidator extends WebMCPValidator, TResult = WebMCPJSONValue>(definition: Omit<WebMCPToolDefinition<Extract<InferWebMCPValidatorOutput<TValidator>, object>, TResult>, "validate"> & {
+    validate: TValidator;
+}): WebMCPToolDefinition<Extract<InferWebMCPValidatorOutput<TValidator>, object>, TResult>;
+export declare function defineWebMCPTool<TInput extends object = Record<string, unknown>, TResult = WebMCPJSONValue>(definition: WebMCPToolDefinition<TInput, TResult>): WebMCPToolDefinition<TInput, TResult>;
+/**
+ * Make one explicit tool available to the active WebMCP runtime.
+ * Call the returned function when the tool is no longer valid for the page.
+ */
+export declare function registerWebMCPTool<TInput extends object, TResult>(definition: WebMCPToolDefinition<TInput, TResult>): () => void;
+/** Validate and register several tools, then return one cleanup function. */
+export declare function registerWebMCPTools(definitions: readonly WebMCPToolDefinition<any, any>[]): () => void;
+/**
+ * Start the browser adapter used by the Farm plugin. Applications normally use
+ * `webmcp()` in `farm.config.ts` instead of calling this directly.
+ */
+export declare function startWebMCPRuntime(options?: StartWebMCPRuntimeOptions): Promise<FarmWebMCPRuntime>;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,iBAAiB,EACjB,0BAA0B,EAE1B,eAAe,EAIf,oBAAoB,EAEpB,eAAe,EAChB,MAAM,YAAY,CAAC;AAEpB,YAAY,EACV,iBAAiB,EACjB,0BAA0B,EAC1B,iBAAiB,EACjB,mBAAmB,EACnB,eAAe,EACf,sBAAsB,EACtB,qBAAqB,EACrB,sBAAsB,EACtB,oBAAoB,EACpB,qBAAqB,EACrB,oBAAoB,EACpB,0BAA0B,EAC1B,kBAAkB,EAClB,eAAe,GAChB,MAAM,YAAY,CAAC;AAEpB,MAAM,MAAM,yBAAyB,GAAG,QAAQ,GAAG,MAAM,GAAG,OAAO,CAAC;AAEpE,MAAM,WAAW,yBAAyB;IACxC,WAAW,CAAC,EAAE,yBAAyB,CAAC;IACxC,qEAAqE;IACrE,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAyCD,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,MAAM;QACd,kEAAkE;QAClE,eAAe,CAAC,EAAE,iBAAiB,CAAC;KACrC;CACF;AAED,+EAA+E;AAC/E,qBAAa,gBAAiB,SAAQ,SAAS;IAC7C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;gBAEb,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO;CAM9C;AAED,wBAAgB,gBAAgB,CAAC,UAAU,SAAS,eAAe,EAAE,OAAO,GAAG,eAAe,EAC5F,UAAU,EAAE,IAAI,CACd,oBAAoB,CAAC,OAAO,CAAC,0BAA0B,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC,EAAE,OAAO,CAAC,EACtF,UAAU,CACX,GAAG;IAAE,QAAQ,EAAE,UAAU,CAAA;CAAE,GAC3B,oBAAoB,CAAC,OAAO,CAAC,0BAA0B,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC,EAAE,OAAO,CAAC,CAAC;AAC1F,wBAAgB,gBAAgB,CAC9B,MAAM,SAAS,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/C,OAAO,GAAG,eAAe,EACzB,UAAU,EAAE,oBAAoB,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,oBAAoB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAO5F;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,SAAS,MAAM,EAAE,OAAO,EAC/D,UAAU,EAAE,oBAAoB,CAAC,MAAM,EAAE,OAAO,CAAC,GAChD,MAAM,IAAI,CAKZ;AAED,6EAA6E;AAC7E,wBAAgB,mBAAmB,CACjC,WAAW,EAAE,SAAS,oBAAoB,CAAC,GAAG,EAAE,GAAG,CAAC,EAAE,GACrD,MAAM,IAAI,CAYZ;AAED;;;GAGG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,GAAE,yBAA8B,GACtC,OAAO,CAAC,iBAAiB,CAAC,CA0F5B"}

package/dist/client.js

@@ -0,0 +1,410 @@
+"use client";
+const TOOL_NAME_PATTERN = /^[A-Za-z0-9_.-]{1,128}$/;
+const registrations = new Map();
+const registryListeners = new Set();
+let nextRegistrationId = 1;
+let activeRuntime;
+/** An actionable validation failure returned to the invoking browser agent. */
+export class WebMCPInputError extends TypeError {
+    toolName;
+    issues;
+    constructor(toolName, issues) {
+        super(`Invalid input for WebMCP tool "${toolName}": ${formatIssues(issues)}`);
+        this.name = "WebMCPInputError";
+        this.toolName = toolName;
+        this.issues = issues;
+    }
+}
+export function defineWebMCPTool(definition) {
+    return normalizeToolDefinition(definition);
+}
+/**
+ * Make one explicit tool available to the active WebMCP runtime.
+ * Call the returned function when the tool is no longer valid for the page.
+ */
+export function registerWebMCPTool(definition) {
+    const normalized = normalizeToolDefinition(definition);
+    return registerNormalizedTool(normalized);
+}
+/** Validate and register several tools, then return one cleanup function. */
+export function registerWebMCPTools(definitions) {
+    const normalized = definitions.map((definition) => normalizeToolDefinition(definition));
+    const cleanups = normalized.map(registerNormalizedTool);
+    let active = true;
+    return () => {
+        if (!active)
+            return;
+        active = false;
+        for (let index = cleanups.length - 1; index >= 0; index--)
+            cleanups[index]();
+    };
+}
+/**
+ * Start the browser adapter used by the Farm plugin. Applications normally use
+ * `webmcp()` in `farm.config.ts` instead of calling this directly.
+ */
+export async function startWebMCPRuntime(options = {}) {
+    activeRuntime?.close();
+    const currentDocument = typeof document === "undefined" ? undefined : document;
+    const modelContext = currentDocument?.modelContext;
+    const behavior = options.unsupported ?? "ignore";
+    if (!modelContext) {
+        const message = "[farm:webmcp] This browser does not expose document.modelContext. " +
+            "The registered tools will remain inactive.";
+        if (behavior === "error")
+            throw new Error(message);
+        if (behavior === "warn")
+            console.warn(message);
+        const unsupportedRuntime = createUnsupportedRuntime();
+        activeRuntime = unsupportedRuntime;
+        exposeDebugRuntime(unsupportedRuntime, options.debug === true);
+        return unsupportedRuntime;
+    }
+    const supportedModelContext = modelContext;
+    const nativeTools = new Map();
+    let closed = false;
+    let syncQueue = Promise.resolve();
+    let unsubscribe = () => { };
+    const runtime = {
+        supported: true,
+        getTools: currentToolMetadata,
+        sync() {
+            const run = syncQueue.then(reconcile, reconcile);
+            syncQueue = run.catch(() => { });
+            return run;
+        },
+        close() {
+            if (closed)
+                return;
+            closed = true;
+            unsubscribe();
+            for (const active of nativeTools.values())
+                active.controller.abort();
+            nativeTools.clear();
+            clearDebugRuntime(runtime);
+            if (activeRuntime === runtime)
+                activeRuntime = undefined;
+        },
+    };
+    async function reconcile() {
+        if (closed)
+            return;
+        const desired = currentToolsByName();
+        for (const [name, active] of nativeTools) {
+            if (desired.get(name)?.id === active.id)
+                continue;
+            active.controller.abort();
+            nativeTools.delete(name);
+        }
+        const failures = [];
+        for (const [name, registration] of desired) {
+            if (closed || nativeTools.has(name))
+                continue;
+            const controller = new AbortController();
+            nativeTools.set(name, { id: registration.id, controller });
+            try {
+                await supportedModelContext.registerTool(toNativeTool(registration.tool, options.debug === true), { signal: controller.signal });
+            }
+            catch (error) {
+                if (nativeTools.get(name)?.id === registration.id)
+                    nativeTools.delete(name);
+                controller.abort();
+                if (!closed) {
+                    failures.push(error);
+                    reportError(`Could not register WebMCP tool "${name}"`, error, true);
+                }
+            }
+        }
+        if (failures.length === 1)
+            throw failures[0];
+        if (failures.length > 1) {
+            throw new AggregateError(failures, "Could not register one or more WebMCP tools");
+        }
+    }
+    unsubscribe = subscribeToRegistry(() => {
+        void runtime.sync().catch(() => { });
+    });
+    activeRuntime = runtime;
+    exposeDebugRuntime(runtime, options.debug === true);
+    await runtime.sync();
+    return runtime;
+}
+function createUnsupportedRuntime() {
+    let closed = false;
+    const runtime = {
+        supported: false,
+        getTools: currentToolMetadata,
+        async sync() { },
+        close() {
+            if (closed)
+                return;
+            closed = true;
+            clearDebugRuntime(runtime);
+            if (activeRuntime === runtime)
+                activeRuntime = undefined;
+        },
+    };
+    return runtime;
+}
+function registerNormalizedTool(tool) {
+    const id = nextRegistrationId++;
+    registrations.set(id, { id, tool });
+    notifyRegistryListeners();
+    let active = true;
+    return () => {
+        if (!active)
+            return;
+        active = false;
+        registrations.delete(id);
+        notifyRegistryListeners();
+    };
+}
+function currentToolsByName() {
+    const current = new Map();
+    for (const registration of registrations.values())
+        current.set(registration.tool.name, registration);
+    return current;
+}
+function currentToolMetadata() {
+    return [...currentToolsByName().values()].map(({ tool }) => ({
+        name: tool.name,
+        ...(tool.title === undefined ? {} : { title: tool.title }),
+        description: tool.description,
+        inputSchema: tool.inputSchema,
+        ...(tool.annotations === undefined ? {} : { annotations: tool.annotations }),
+    }));
+}
+function subscribeToRegistry(listener) {
+    registryListeners.add(listener);
+    return () => registryListeners.delete(listener);
+}
+function notifyRegistryListeners() {
+    for (const listener of registryListeners)
+        listener();
+}
+function toNativeTool(tool, debug) {
+    return {
+        name: tool.name,
+        ...(tool.title === undefined ? {} : { title: tool.title }),
+        description: tool.description,
+        inputSchema: tool.inputSchema,
+        ...(tool.annotations === undefined ? {} : { annotations: tool.annotations }),
+        async execute(input, { signal }) {
+            try {
+                const parsed = tool.validate
+                    ? await validateInput(tool.name, tool.validate, input)
+                    : assertInputObject(tool.name, input);
+                const result = await tool.execute(parsed, { signal });
+                assertJSONValue(result, `Result from WebMCP tool "${tool.name}"`);
+                return result;
+            }
+            catch (error) {
+                reportError(`WebMCP tool "${tool.name}" failed`, error, debug);
+                throw error;
+            }
+        },
+    };
+}
+async function validateInput(toolName, validator, input) {
+    try {
+        let result;
+        if (hasStandardSchema(validator)) {
+            const validated = await validator["~standard"].validate(input);
+            if (validated.issues !== undefined)
+                throw new WebMCPInputError(toolName, validated.issues);
+            result = validated.value;
+        }
+        else if (hasMethod(validator, "safeParseAsync")) {
+            result = unwrapSafeParse(toolName, await validator.safeParseAsync(input));
+        }
+        else if (hasMethod(validator, "safeParse")) {
+            result = unwrapSafeParse(toolName, validator.safeParse(input));
+        }
+        else if (hasMethod(validator, "parseAsync")) {
+            result = await validator.parseAsync(input);
+        }
+        else if (hasMethod(validator, "parse")) {
+            result = validator.parse(input);
+        }
+        else if (typeof validator === "function") {
+            result = await validator(input);
+        }
+        else {
+            throw new TypeError("Unsupported validator");
+        }
+        return assertInputObject(toolName, result);
+    }
+    catch (error) {
+        if (error instanceof WebMCPInputError)
+            throw error;
+        throw new WebMCPInputError(toolName, extractIssues(error));
+    }
+}
+function unwrapSafeParse(toolName, result) {
+    if (result.success)
+        return result.data;
+    throw new WebMCPInputError(toolName, extractIssues(result.error));
+}
+function hasStandardSchema(value) {
+    if (!value || typeof value !== "object" || !("~standard" in value))
+        return false;
+    const standard = value["~standard"];
+    return Boolean(standard &&
+        typeof standard === "object" &&
+        "validate" in standard &&
+        typeof standard.validate === "function");
+}
+function hasMethod(value, name) {
+    return Boolean(value &&
+        (typeof value === "object" || typeof value === "function") &&
+        name in value &&
+        typeof value[name] === "function");
+}
+function assertInputObject(toolName, value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new WebMCPInputError(toolName, "the validated input must be an object");
+    }
+    return value;
+}
+function normalizeToolDefinition(definition) {
+    if (!definition || typeof definition !== "object" || Array.isArray(definition)) {
+        throw new TypeError("A WebMCP tool definition must be an object");
+    }
+    if (!TOOL_NAME_PATTERN.test(definition.name)) {
+        throw new TypeError("A WebMCP tool name must be 1 to 128 ASCII letters, digits, `_`, `-`, or `.`");
+    }
+    if (typeof definition.description !== "string" || !definition.description.trim()) {
+        throw new TypeError(`WebMCP tool "${definition.name}" needs a description`);
+    }
+    if (definition.title !== undefined &&
+        (typeof definition.title !== "string" || !definition.title.trim())) {
+        throw new TypeError(`WebMCP tool "${definition.name}" title must be a non-empty string`);
+    }
+    if (typeof definition.execute !== "function") {
+        throw new TypeError(`WebMCP tool "${definition.name}" needs an execute function`);
+    }
+    if (!definition.inputSchema ||
+        typeof definition.inputSchema !== "object" ||
+        Array.isArray(definition.inputSchema)) {
+        throw new TypeError(`WebMCP tool "${definition.name}" inputSchema must be a JSON object`);
+    }
+    assertJSONValue(definition.inputSchema, `WebMCP tool "${definition.name}" inputSchema`);
+    assertValidator(definition.name, definition.validate);
+    const annotations = normalizeAnnotations(definition.name, definition.annotations);
+    return Object.freeze({
+        name: definition.name,
+        ...(definition.title === undefined ? {} : { title: definition.title }),
+        description: definition.description,
+        inputSchema: cloneJSON(definition.inputSchema),
+        ...(definition.validate === undefined ? {} : { validate: definition.validate }),
+        ...(annotations === undefined ? {} : { annotations }),
+        execute: definition.execute,
+    });
+}
+function assertValidator(name, validator) {
+    if (validator === undefined || typeof validator === "function")
+        return;
+    if (hasStandardSchema(validator) ||
+        hasMethod(validator, "safeParseAsync") ||
+        hasMethod(validator, "safeParse") ||
+        hasMethod(validator, "parseAsync") ||
+        hasMethod(validator, "parse")) {
+        return;
+    }
+    throw new TypeError(`WebMCP tool "${name}" validate must be a supported schema or function`);
+}
+function normalizeAnnotations(name, annotations) {
+    if (annotations === undefined)
+        return undefined;
+    if (!annotations || typeof annotations !== "object" || Array.isArray(annotations)) {
+        throw new TypeError(`WebMCP tool "${name}" annotations must be an object`);
+    }
+    const allowed = new Set(["readOnlyHint", "untrustedContentHint", "consequentialHint"]);
+    for (const [key, value] of Object.entries(annotations)) {
+        if (!allowed.has(key)) {
+            throw new TypeError(`WebMCP tool "${name}" has an unknown annotation "${key}"`);
+        }
+        if (typeof value !== "boolean") {
+            throw new TypeError(`WebMCP tool "${name}" annotation "${key}" must be boolean`);
+        }
+    }
+    return Object.freeze({ ...annotations });
+}
+function assertJSONValue(value, location, seen = new Set()) {
+    if (value === null || typeof value === "string" || typeof value === "boolean")
+        return;
+    if (typeof value === "number") {
+        if (!Number.isFinite(value))
+            throw new TypeError(`${location} contains a non-finite number`);
+        return;
+    }
+    if (!value || typeof value !== "object") {
+        throw new TypeError(`${location} must be JSON-serializable`);
+    }
+    if (seen.has(value))
+        throw new TypeError(`${location} contains a circular reference`);
+    seen.add(value);
+    if (Array.isArray(value)) {
+        for (let index = 0; index < value.length; index++) {
+            if (!(index in value))
+                throw new TypeError(`${location} contains a sparse array`);
+            assertJSONValue(value[index], location, seen);
+        }
+    }
+    else {
+        const prototype = Object.getPrototypeOf(value);
+        if (prototype !== Object.prototype && prototype !== null) {
+            throw new TypeError(`${location} must contain only plain JSON objects`);
+        }
+        for (const entry of Object.values(value))
+            assertJSONValue(entry, location, seen);
+    }
+    seen.delete(value);
+}
+function cloneJSON(value) {
+    return freezeJSON(JSON.parse(JSON.stringify(value)));
+}
+function freezeJSON(value) {
+    if (value && typeof value === "object") {
+        for (const child of Object.values(value))
+            freezeJSON(child);
+        Object.freeze(value);
+    }
+    return value;
+}
+function extractIssues(error) {
+    if (error && typeof error === "object" && "issues" in error) {
+        return error.issues;
+    }
+    return error;
+}
+function formatIssues(issues) {
+    if (Array.isArray(issues)) {
+        const messages = issues.slice(0, 5).map((issue) => {
+            if (!issue || typeof issue !== "object")
+                return String(issue);
+            const record = issue;
+            const path = Array.isArray(record.path) && record.path.length ? `${record.path.join(".")}: ` : "";
+            return `${path}${typeof record.message === "string" ? record.message : "invalid value"}`;
+        });
+        return messages.join("; ") || "input did not match the validation schema";
+    }
+    if (issues instanceof Error)
+        return issues.message;
+    if (typeof issues === "string")
+        return issues;
+    return "input did not match the validation schema";
+}
+function exposeDebugRuntime(runtime, enabled) {
+    if (enabled && typeof window !== "undefined")
+        window.__FARM_WEBMCP__ = runtime;
+}
+function clearDebugRuntime(runtime) {
+    if (typeof window !== "undefined" && window.__FARM_WEBMCP__ === runtime) {
+        delete window.__FARM_WEBMCP__;
+    }
+}
+function reportError(message, error, debug) {
+    if (debug)
+        console.error(`[farm:webmcp] ${message}`, error);
+}

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+export type { FarmWebMCPRuntime } from "./types.js";
+export type { WebMCPUnsupportedBehavior } from "./client.js";
+export interface WebMCPPluginOptions {
+    /** Set false to keep the plugin configured without starting its browser runtime. */
+    enabled?: boolean;
+    /** Behavior when `document.modelContext` is unavailable. Defaults to warn in development. */
+    unsupported?: "ignore" | "warn" | "error";
+    /** Expose `window.__FARM_WEBMCP__` for inspection. Defaults to true in development. */
+    debug?: boolean;
+}
+/** Register Farm's explicit browser tools with the experimental WebMCP API. */
+export declare function webmcp(options?: WebMCPPluginOptions): import("@farm.js/core/plugin").FarmPlugin<undefined, Record<string, never>, import("./types.js").FarmWebMCPRuntime | undefined, {
+    enabled: boolean;
+    unsupported: "ignore" | "warn" | "error" | null;
+    debug: boolean | null;
+}, unknown, false>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,YAAY,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AACpD,YAAY,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAC;AAE7D,MAAM,WAAW,mBAAmB;IAClC,oFAAoF;IACpF,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,6FAA6F;IAC7F,WAAW,CAAC,EAAE,QAAQ,GAAG,MAAM,GAAG,OAAO,CAAC;IAC1C,uFAAuF;IACvF,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,+EAA+E;AAC/E,wBAAgB,MAAM,CAAC,OAAO,GAAE,mBAAwB;;;;mBA6BvD"}

package/dist/index.js

@@ -0,0 +1,46 @@
+import { definePlugin } from "@farm.js/core/plugin";
+/** Register Farm's explicit browser tools with the experimental WebMCP API. */
+export function webmcp(options = {}) {
+    assertOptions(options);
+    return definePlugin({
+        name: "farm:webmcp",
+        client: {
+            public: {
+                enabled: options.enabled ?? true,
+                unsupported: options.unsupported ?? null,
+                debug: options.debug ?? null,
+            },
+            async setup({ public: config, isDev }) {
+                if (!config.enabled)
+                    return undefined;
+                const runtime = await import("@farm.js/webmcp/client");
+                return runtime.startWebMCPRuntime({
+                    unsupported: config.unsupported ?? (isDev ? "warn" : "ignore"),
+                    debug: config.debug ?? isDev,
+                });
+            },
+            navigation: {
+                async rendered({ state }) {
+                    await state?.sync();
+                },
+            },
+            close({ state }) {
+                state?.close();
+            },
+        },
+    });
+}
+function assertOptions(options) {
+    if (options.enabled !== undefined && typeof options.enabled !== "boolean") {
+        throw new TypeError("webmcp enabled must be boolean");
+    }
+    if (options.debug !== undefined && typeof options.debug !== "boolean") {
+        throw new TypeError("webmcp debug must be boolean");
+    }
+    if (options.unsupported !== undefined &&
+        options.unsupported !== "ignore" &&
+        options.unsupported !== "warn" &&
+        options.unsupported !== "error") {
+        throw new TypeError('webmcp unsupported must be "ignore", "warn", or "error"');
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,109 @@
+export type MaybePromise<T> = T | Promise<T>;
+export type WebMCPJSONPrimitive = boolean | number | string | null;
+export type WebMCPJSONValue = WebMCPJSONPrimitive | WebMCPJSONValue[] | {
+    [key: string]: WebMCPJSONValue;
+};
+/** A JSON Schema object sent to the browser agent with a tool definition. */
+export type WebMCPInputSchema = Readonly<Record<string, unknown>>;
+export interface WebMCPToolAnnotations {
+    /** The tool does not change application or external state. */
+    readOnlyHint?: boolean;
+    /** A tool result can contain content supplied by an untrusted party. */
+    untrustedContentHint?: boolean;
+    /** The tool can perform a significant or difficult-to-reverse action. */
+    consequentialHint?: boolean;
+}
+export interface WebMCPToolExecutionContext {
+    /** Aborted when the browser agent cancels this invocation. */
+    signal: AbortSignal;
+}
+export interface WebMCPSafeParseSuccess<T> {
+    success: true;
+    data: T;
+}
+export interface WebMCPSafeParseFailure {
+    success: false;
+    error: unknown;
+}
+export type WebMCPSafeParseResult<T> = WebMCPSafeParseSuccess<T> | WebMCPSafeParseFailure;
+/** Structural subset of Standard Schema used by Zod, Valibot, ArkType, and others. */
+export interface WebMCPStandardSchema<TOutput = unknown> {
+    readonly "~standard": {
+        readonly version: number;
+        readonly vendor: string;
+        readonly validate: (value: unknown) => MaybePromise<{
+            readonly value: TOutput;
+            readonly issues?: undefined;
+        } | {
+            readonly issues: readonly unknown[];
+        }>;
+        readonly types?: {
+            readonly input: unknown;
+            readonly output: TOutput;
+        };
+    };
+}
+export type WebMCPValidator<TOutput = unknown> = WebMCPStandardSchema<TOutput> | {
+    safeParseAsync(value: unknown): MaybePromise<WebMCPSafeParseResult<TOutput>>;
+} | {
+    safeParse(value: unknown): WebMCPSafeParseResult<TOutput>;
+} | {
+    parseAsync(value: unknown): MaybePromise<TOutput>;
+} | {
+    parse(value: unknown): TOutput;
+} | ((value: unknown) => MaybePromise<TOutput>);
+type StandardSchemaOutput<TValidator> = TValidator extends {
+    readonly "~standard": {
+        readonly types?: infer TTypes;
+    };
+} ? NonNullable<TTypes> extends {
+    readonly output: infer TOutput;
+} ? TOutput : never : never;
+/** Infer the value returned by a supported validation schema. */
+export type InferWebMCPValidatorOutput<TValidator> = [StandardSchemaOutput<TValidator>] extends [
+    never
+] ? TValidator extends {
+    readonly _output: infer TOutput;
+} ? TOutput : TValidator extends {
+    parseAsync(value: unknown): MaybePromise<infer TOutput>;
+} ? TOutput : TValidator extends {
+    parse(value: unknown): infer TOutput;
+} ? TOutput : TValidator extends {
+    safeParseAsync(value: unknown): MaybePromise<WebMCPSafeParseResult<infer TOutput>>;
+} ? TOutput : TValidator extends {
+    safeParse(value: unknown): WebMCPSafeParseResult<infer TOutput>;
+} ? TOutput : TValidator extends (value: unknown) => MaybePromise<infer TOutput> ? TOutput : unknown : StandardSchemaOutput<TValidator>;
+export interface WebMCPToolDefinition<TInput extends object = Record<string, unknown>, TResult = WebMCPJSONValue> {
+    /** Stable agent-facing name. Uses ASCII letters, digits, `_`, `-`, and `.`. */
+    name: string;
+    /** Optional human-readable label for browser UI. */
+    title?: string;
+    /** Explain what the tool does and when an agent should use it. */
+    description: string;
+    /** JSON Schema describing the input object presented to the agent. */
+    inputSchema: WebMCPInputSchema;
+    /** Optional runtime validation. This does not replace server authorization. */
+    validate?: WebMCPValidator<TInput>;
+    annotations?: WebMCPToolAnnotations;
+    /** The runtime rejects results that are not JSON-safe. */
+    execute(input: TInput, context: WebMCPToolExecutionContext): MaybePromise<TResult>;
+}
+export interface WebMCPToolMetadata {
+    name: string;
+    title?: string;
+    description: string;
+    inputSchema: WebMCPInputSchema;
+    annotations?: Readonly<WebMCPToolAnnotations>;
+}
+export interface FarmWebMCPRuntime {
+    /** Whether this document provides the current WebMCP API. */
+    readonly supported: boolean;
+    /** Current explicitly registered Farm tools, with execution functions omitted. */
+    getTools(): readonly WebMCPToolMetadata[];
+    /** Reconcile Farm's tool registry with `document.modelContext`. */
+    sync(): Promise<void>;
+    /** Unregister native tools and stop observing Farm registrations. */
+    close(): void;
+}
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@farm.js/webmcp",
+  "version": "0.1.0-beta.0",
+  "description": "Explicit, typed WebMCP tools for Farm.js applications",
+  "keywords": [
+    "agents",
+    "farm.js",
+    "mcp",
+    "webmcp"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/farming-labs/farm.js",
+    "directory": "packages/farm-webmcp"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "import": "./dist/client.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@farm.js/core": "0.1.0-beta.86"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.5",
+    "typescript": "^5.3.3",
+    "vitest": "^3.2.7"
+  },
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "scripts": {
+    "build": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\" && tsc",
+    "dev": "tsc --watch",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}