@jini-ai/agentic 0.1.2 → 0.3.0

package/dist/core/page-executor.js

@@ -0,0 +1,320 @@
+/**
+ * @module page-executor
+ *
+ * The six `page.*` verbs, as policy over a {@link PageDriver}.
+ *
+ * Every refusal happens here, before the driver is called: schema validation, handle validation,
+ * the field guard, the page allowlist, highlight clamping. A driver is mechanical and is trusted
+ * to be — which means a second driver (same-document, sandboxed frame, a future native host)
+ * inherits identical behavior for free rather than re-deriving it and getting one case wrong.
+ *
+ * Nothing here touches the DOM. That is what makes the interesting half testable without a
+ * browser: "does it refuse to type into a password box" is a unit test, not an integration test.
+ */
+import { findCapabilityInputError, } from './capability.js';
+import { AGENT_ELEMENT_ROLES, isValidElementHandle, } from './element-handles.js';
+import { describeFieldReadRefusal, describeFieldRefusal, findFieldFillRefusal, findFieldReadRefusal, normalizeAgentLabel, } from './guards.js';
+import { PAGE_CAPABILITIES } from './page-capabilities.js';
+/** Default marker lifetime, long enough to notice and short enough not to linger. */
+export const DEFAULT_HIGHLIGHT_MS = 3_000;
+/**
+ * Hard cap on a marker's lifetime. A caller asking for a very long highlight is really asking to
+ * leave a permanent mark on someone else's page, which is a change of appearance rather than a
+ * transient hint — and `page.highlight` is classified `read` precisely because it is transient.
+ */
+export const MAX_HIGHLIGHT_MS = 15_000;
+/**
+ * How many elements `withState` will describe in one call.
+ *
+ * State is per-element work and per-element payload, so an unfiltered `withState` on a large page
+ * is both the slowest and the largest thing this surface can be asked for. The cap turns that into
+ * a bounded answer plus an explicit `stateTruncated`, rather than a caller discovering the limit
+ * as a timeout or a truncated blob. Narrowing with `role`/`query` is the intended way past it.
+ */
+export const MAX_STATEFUL_ELEMENTS = 50;
+function requireHandle(input, key) {
+    const value = input[key];
+    if (typeof value !== 'string' || !isValidElementHandle(value)) {
+        throw new Error(`"${key}" must be a published element handle from page.find_elements — `
+            + 'lowercase words joined by single hyphens, never a CSS selector');
+    }
+    return value;
+}
+function clampHighlightDuration(value) {
+    if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0)
+        return DEFAULT_HIGHLIGHT_MS;
+    return Math.min(value, MAX_HIGHLIGHT_MS);
+}
+function isAgentElementRole(value) {
+    return typeof value === 'string' && AGENT_ELEMENT_ROLES.includes(value);
+}
+/**
+ * Turns a driver's raw reading into what a caller may see.
+ *
+ * The one decision here that is not formatting: whether a field's contents are reportable at all.
+ * That runs on the descriptor the driver supplied, in this layer, for the same reason the fill
+ * guard does — a secrecy rule re-derived by each driver is a secrecy rule that will eventually be
+ * derived wrong. A value arriving with no descriptor to check is withheld rather than trusted.
+ */
+export function projectElementState(raw) {
+    const text = normalizeAgentLabel(raw.text);
+    // Computed once, up front, so `checked` is gated by the exact same refusal as `value` below
+    // rather than being copied through unconditionally. A checkbox/radio's `checked` is a second
+    // secrecy channel, not a formatting detail: for a field like `health_disclosure_password`,
+    // *which* option is ticked is itself the secret, even though it is a boolean and `value` was
+    // already withheld. `text` is deliberately NOT gated here, on purpose, even for a refused
+    // field: for a checkbox/radio, `text` is the option's own visible label (e.g. "I am HIV
+    // positive") — page-authored content the page already renders openly to anyone who looks at
+    // it, exactly like a `<select>`'s `options` below. The secret is which option is checked, not
+    // what the option is called; withholding the label too would blind a caller to the page's own
+    // ontology for no reduction in what actually leaks.
+    const refusal = raw.field !== undefined ? findFieldReadRefusal(raw.field) : null;
+    // The one element whose `text` is NOT page-authored chrome: an editable region, whose contents
+    // are the user's data and whose driver has no `value` to report them as. It is gated by exactly
+    // the rules `value` is gated by below, including the "arrived with nothing to check it against"
+    // one — an unverifiable secret is withheld, not trusted.
+    const withheldText = raw.textIsValue !== true
+        ? undefined
+        : raw.field === undefined
+            ? 'this element reported contents without the attributes needed to check them for secrets'
+            : refusal !== null ? describeFieldReadRefusal(refusal) : undefined;
+    const base = {
+        text: withheldText === undefined ? text.text : '',
+        textTruncated: withheldText === undefined ? text.truncated : false,
+        ...(withheldText !== undefined ? { textWithheld: withheldText } : {}),
+        ...(raw.checked !== undefined && refusal === null ? { checked: raw.checked } : {}),
+        ...(raw.disabled !== undefined ? { disabled: raw.disabled } : {}),
+        ...(raw.visible !== undefined ? { visible: raw.visible } : {}),
+        // Bounded like every other page-authored string, but never withheld: the options a dropdown
+        // offers are part of the UI's shape, not the user's data.
+        ...(raw.options !== undefined
+            ? { options: raw.options.map((option) => normalizeAgentLabel(option).text) }
+            : {}),
+    };
+    if (raw.value === undefined)
+        return base;
+    if (raw.field === undefined) {
+        return {
+            ...base,
+            valueWithheld: 'this element reported a value without the attributes needed to check it for secrets',
+        };
+    }
+    if (refusal !== null)
+        return { ...base, valueWithheld: describeFieldReadRefusal(refusal) };
+    const value = normalizeAgentLabel(raw.value);
+    return { ...base, value: value.text, valueTruncated: value.truncated };
+}
+/**
+ * Whether two readings of the same element are indistinguishable to a caller.
+ *
+ * Compares only what the caller can actually see: a withheld value is compared as "withheld",
+ * so a secret that changed reads as unchanged. That is the honest answer — a change no caller may
+ * observe is not one this can report — and is why the field it feeds is named `targetChanged`.
+ */
+function sameElementState(a, b) {
+    return a.text === b.text
+        // Compared for the same reason `valueWithheld` is: without it, an editable region whose
+        // contents are withheld reads as `text: ''` before and after, and a write into it would
+        // report `targetChanged: false` — an answer that says "nothing happened" rather than the
+        // honest "no caller may observe whether it did".
+        && a.textWithheld === b.textWithheld
+        && a.value === b.value
+        && a.valueWithheld === b.valueWithheld
+        && a.checked === b.checked
+        && a.disabled === b.disabled
+        && a.visible === b.visible;
+}
+/**
+ * Reads one element's state, or `undefined` when there is nothing to read.
+ *
+ * Two different absences collapse here on purpose: a driver that cannot observe at all, and an
+ * element that no longer resolves. A caller distinguishes them from context — `before` present
+ * with `after` absent means the action removed its own target; both absent means the surface does
+ * not report state.
+ */
+async function observeElement(driver, handle) {
+    if (driver.describeState === undefined || !isValidElementHandle(handle))
+        return undefined;
+    const raw = await driver.describeState(handle);
+    return raw === null ? undefined : projectElementState(raw);
+}
+/** Runs a write between two readings of its target, waiting for the surface to settle in between. */
+async function observeWrite(driver, handle, write) {
+    const before = await observeElement(driver, handle);
+    await write();
+    if (driver.settle !== undefined)
+        await driver.settle();
+    const after = await observeElement(driver, handle);
+    return {
+        ...(before !== undefined ? { before } : {}),
+        ...(after !== undefined ? { after } : {}),
+        ...(before !== undefined && after !== undefined
+            ? { targetChanged: !sameElementState(before, after) }
+            : {}),
+    };
+}
+/**
+ * Reads the showing page from the elements themselves, which is where a driver reports it. A
+ * surface that publishes nothing has no page id to report, and says so rather than guessing.
+ */
+async function summarizePage(driver) {
+    const elements = await driver.findElements({});
+    return {
+        page: elements.find((element) => element.page !== undefined)?.page,
+        elementCount: elements.length,
+    };
+}
+/**
+ * Runs one `page.*` capability.
+ *
+ * @param driver - The host's page driver.
+ * @param capabilityId - A `page.*` id from {@link PAGE_CAPABILITIES}.
+ * @param input - Raw caller arguments, validated here against the declared schema.
+ * @returns The capability's result.
+ * @throws If the id is unknown, the input fails validation, a handle is malformed, the target is
+ * a field no automated caller may fill, or the page is not published. Refusals are errors on
+ * purpose: a caller must be told why, not handed a silent no-op it will retry forever.
+ */
+export async function executePageCapability(driver, capabilityId, input) {
+    const capability = PAGE_CAPABILITIES.find((entry) => entry.id === capabilityId);
+    if (capability === undefined)
+        throw new Error(`unknown page capability: ${capabilityId}`);
+    const inputError = findCapabilityInputError(capability, input);
+    if (inputError !== null) {
+        // The schema rides along with the refusal rather than making a caller spend a second
+        // round trip on describe_tool to learn what it already tried to guess — ai-control-plane.md
+        // §29.4's "schema-on-error" requirement, empirically forced by a real run: page.fill was
+        // called with `handle` instead of the argument's old name, `element`, twice before the caller
+        // gave up and looked the schema up separately. One JSON-Schema object, embedded once, turned
+        // that into a same-turn self-correction for every page.* verb this gate guards, not just the
+        // one that got measured — self-correction is why that mismatch was survivable at all, given
+        // every verb here needs a handle from `page.find_elements`, whose own response has always
+        // called this same value `handle` (`AgentElementDescriptor.handle`). The argument itself was
+        // later renamed from `element` to `handle` to match, closing the gap this comment describes
+        // rather than merely papering over it turn by turn.
+        throw new Error(`${capabilityId}: ${inputError}. Expected input: ${JSON.stringify(capability.inputSchema)}`);
+    }
+    switch (capabilityId) {
+        case 'page.find_elements': {
+            const role = input['role'];
+            // The schema's enum check has already run; this narrows the type for the driver.
+            const filter = {
+                ...(isAgentElementRole(role) ? { role } : {}),
+                ...(typeof input['query'] === 'string' ? { query: input['query'] } : {}),
+            };
+            const [found, rawPages] = await Promise.all([driver.findElements(filter), driver.listPages()]);
+            const withState = input['withState'] === true;
+            const observing = withState && driver.describeState !== undefined;
+            const elements = await Promise.all(found.map(async (element, index) => {
+                const label = normalizeAgentLabel(element.label);
+                const base = {
+                    handle: element.handle,
+                    role: element.role,
+                    label: label.text,
+                    labelTruncated: label.truncated,
+                    page: element.page,
+                };
+                if (!observing || index >= MAX_STATEFUL_ELEMENTS)
+                    return base;
+                const state = await observeElement(driver, element.handle);
+                return state === undefined ? base : { ...base, state };
+            }));
+            // `label` is page-authored the same way an element's is — bounded here for the same reason
+            // `page.navigate`'s refusal message bounds it below, rather than trusting a host to have kept
+            // every `data-agent-page` label short and clean.
+            const pages = rawPages.map((page) => ({
+                id: page.id,
+                label: normalizeAgentLabel(page.label).text,
+            }));
+            return {
+                elements,
+                pages,
+                untrustedFields: observing
+                    ? ['elements[].label', 'elements[].state.text', 'elements[].state.value', 'pages[].label']
+                    : ['elements[].label', 'pages[].label'],
+                ...(withState && !observing ? { stateUnavailable: true } : {}),
+                ...(observing && found.length > MAX_STATEFUL_ELEMENTS ? { stateTruncated: true } : {}),
+            };
+        }
+        case 'page.highlight': {
+            const handle = requireHandle(input, 'handle');
+            const durationMs = clampHighlightDuration(input['durationMs']);
+            await driver.highlight(handle, durationMs);
+            return { highlighted: handle, durationMs };
+        }
+        case 'page.scroll_to': {
+            const handle = requireHandle(input, 'handle');
+            await driver.scrollTo(handle);
+            return { scrolledTo: handle };
+        }
+        case 'page.click': {
+            const handle = requireHandle(input, 'handle');
+            const observation = await observeWrite(driver, handle, () => driver.click(handle));
+            return { clicked: handle, ...observation };
+        }
+        case 'page.fill': {
+            const handle = requireHandle(input, 'handle');
+            // Declared required and typed `string` in the manifest, and `findCapabilityInputError`
+            // enforced both above — re-checking here would be an unreachable branch, not a safeguard.
+            const text = input['text'];
+            // Ask the page what this field actually is before writing to it. A handle proves the page
+            // published the element; it says nothing about whether it holds a password.
+            const field = await driver.describeField(handle);
+            if (field === null)
+                throw new Error(`"${handle}" is not a fillable field`);
+            const refusal = findFieldFillRefusal(field);
+            if (refusal !== null) {
+                throw new Error(`refusing to fill "${handle}": ${describeFieldRefusal(refusal)}`);
+            }
+            const observation = await observeWrite(driver, handle, () => driver.fill(handle, text));
+            return { filled: handle, ...observation };
+        }
+        case 'page.select_option': {
+            const handle = requireHandle(input, 'handle');
+            // Required and string-typed by the manifest, already enforced above. See page.fill.
+            const option = input['option'];
+            // Optional and boolean-typed by the manifest; absent means "select it", same as before this
+            // argument existed.
+            const selected = input['selected'] === false ? false : true;
+            // No field guard: a dropdown's options are authored by the page, so choosing one reveals
+            // nothing the page had not already published, and none of the credential field types this
+            // surface refuses can be a `<select>`.
+            const observation = await observeWrite(driver, handle, () => driver.selectOption(handle, option, selected));
+            // `optionSelected` names the boolean rather than reusing `selected`, which already means
+            // "the handle this call acted on" for every verb in this switch (`clicked`, `filled`, …).
+            return { selected: handle, option, optionSelected: selected, ...observation };
+        }
+        case 'page.navigate': {
+            // Required and string-typed by the manifest, already enforced above. See page.fill.
+            const page = input['page'];
+            const pages = await driver.listPages();
+            if (!pages.some((candidate) => candidate.id === page)) {
+                // Every other piece of page-authored (or, here, caller-authored-but-page-shaped) text
+                // this system hands to a model goes through normalizeAgentLabel first — bounded, control-
+                // and bidi-stripped. This refusal was the one path that skipped it: the raw `page`
+                // argument, and the `pages` this host actually publishes (itself read verbatim off
+                // `data-agent-page` attributes with no length bound), were interpolated straight into the
+                // thrown message. A 5000+-char bidi payload survived verbatim as a result. The lookup
+                // above still runs on the raw values — only the text that reaches the message is bounded.
+                //
+                // `id (label)`, not just the id: a refusal is the one moment a caller that guessed wrong
+                // is looking straight at the real menu, so it is worth spending the label here even though
+                // `page.find_elements` already carries the same information — a caller that jumped
+                // straight to `page.navigate` without calling that first still lands on the right id.
+                const safePage = normalizeAgentLabel(page).text;
+                const safePages = pages.map((candidate) => `${normalizeAgentLabel(candidate.id).text} (${normalizeAgentLabel(candidate.label).text})`);
+                throw new Error(`"${safePage}" is not a published page. Available: ${safePages.length > 0 ? safePages.join(', ') : '(none)'}`);
+            }
+            const before = await summarizePage(driver);
+            await driver.navigate(page);
+            if (driver.settle !== undefined)
+                await driver.settle();
+            const after = await summarizePage(driver);
+            return { navigatedTo: page, before, after };
+        }
+        /* c8 ignore next 2 -- unreachable: the id was matched against PAGE_CAPABILITIES above. */
+        default:
+            throw new Error(`unhandled page capability: ${capabilityId}`);
+    }
+}
+//# sourceMappingURL=page-executor.js.map

package/dist/core/page-executor.js.map

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

package/dist/core/webmcp.d.ts

@@ -0,0 +1,202 @@
+/**
+ * @module webmcp
+ *
+ * Projection: {@link CapabilityDef} → a WebMCP tool registration.
+ *
+ * WebMCP (`document.modelContext.registerTool`) is the browser API by which a *page* offers
+ * tools to an agent running inside the browser. It is a W3C Community Group draft, not a
+ * standards-track spec, and it moves: the API relocated from `navigator.modelContext` to
+ * `document.modelContext` on 2026-07-21, Chrome 150 deprecated the `navigator` location while
+ * still serving it during the origin trial (Chrome 149–156), Edge ships it behind a flag, and
+ * Firefox and Safari have made no commitment. Feature detection must therefore check `document`
+ * first and fall back to `navigator`.
+ *
+ * That detection is deliberately NOT here: it touches browser globals, and this package holds
+ * none. Framework bindings own host access; this file owns only the shape translation, so when
+ * the registration shape changes again there is exactly one place to change it.
+ *
+ * Re-verified 2026-07-28 against the primary spec source
+ * (https://webmachinelearning.github.io/webmcp/, `index.bs`). Four real gaps closed this pass,
+ * all additive — none change the confirmation gate below, which is Jini's own addition and has
+ * no spec counterpart:
+ *
+ * 1. **`signal`/`exposedTo`** — `ModelContextRegisterToolOptions`, the *second* positional
+ *    argument to `registerTool(tool, options)`. `signal` is the spec's ONLY unregistration
+ *    mechanism (there is no `unregisterTool()`); aborting it removes the tool and fires
+ *    `toolchange`. `exposedTo` scopes which cross-origin documents in the same tree may see the
+ *    tool. Neither belongs on the `ModelContextTool` dict itself, so they are not fields of
+ *    {@link WebMcpToolRegistration} — they ride along on its optional `registerOptions`, computed
+ *    from {@link ToWebMcpToolOptions}, so a caller has exactly one object to destructure:
+ *    `modelContext.registerTool(reg, reg.registerOptions)`.
+ * 2. **`title`/`annotations`** — real `ModelContextTool` dict fields (`USVString title`,
+ *    `ToolAnnotations annotations`), now on {@link WebMcpToolRegistration}. `annotations.readOnlyHint`
+ *    defaults from {@link CapabilityDef.risk} (`'read'` → `true`) since Jini's manifests already
+ *    carry that judgment; a caller may override or add `untrustedContentHint` via `options.annotations`.
+ * 3. **Tool name validation** — the spec's `registerTool` algorithm rejects (with an
+ *    `InvalidStateError` `DOMException`) a name that is empty, over 128 code points, or contains
+ *    anything outside ASCII alphanumeric plus `_`, `-`, `.`. `capability.id` becomes `name`
+ *    verbatim, so a malformed manifest entry previously surfaced as a cryptic browser-side
+ *    rejection days later; {@link toWebMcpTool} now checks it at projection time and names the
+ *    offending capability.
+ * 4. **Schema-on-error** — WebMCP defines no input validation of its own (the spec's
+ *    `ToolExecuteCallback` is just `Promise<any> (object input)`), and this module's own doc used
+ *    to say so ("the caller is responsible for validating it... WebMCP does not"). That left a
+ *    wrong-schema call to fail deep inside whatever `execute` does, with no way for the caller to
+ *    self-correct in the same turn. `execute` now runs the manifest's own
+ *    {@link findCapabilityInputError} first and, on failure, throws the same
+ *    `"<id>: <reason>. Expected input: <schema>"` shape `page-executor.ts` already uses for
+ *    `page.*` — one discipline, not two.
+ */
+import { type CapabilityDef, type CapabilityInputSchema } from './capability.js';
+/** The registration object `registerTool` accepts. WebMCP names the schema field `inputSchema`. */
+export interface WebMcpToolRegistration {
+    readonly name: string;
+    /**
+     * `ModelContextTool.title` — an optional human-readable label, distinct from `name` (the
+     * machine identifier) and `description` (what an agent reads to decide whether to call it). The
+     * spec recommends localizing it to the user's language; this projection makes no attempt at
+     * that; a caller wanting a localized title supplies it via `options.title`.
+     */
+    readonly title?: string;
+    readonly description: string;
+    readonly inputSchema: CapabilityInputSchema;
+    readonly execute: (args: Record<string, unknown>) => Promise<unknown>;
+    /** `ModelContextTool.annotations` — behavior hints. See {@link WebMcpToolAnnotations}. */
+    readonly annotations?: WebMcpToolAnnotations;
+    /**
+     * The SECOND positional argument `registerTool(tool, options)` expects — the spec's
+     * `ModelContextRegisterToolOptions`, not part of the `ModelContextTool` dict this object
+     * otherwise models. Present only when `options.signal` or `options.exposedTo` was supplied.
+     * Bundled here rather than returned as a second value so `toWebMcpTool`'s output stays a single
+     * object a caller can pass straight through: `modelContext.registerTool(reg, reg.registerOptions)`.
+     */
+    readonly registerOptions?: WebMcpRegisterToolOptions;
+}
+/**
+ * `ToolAnnotations` — optional behavior hints a host UI or agent may use to decide how to treat a
+ * tool without calling it. Both default to `false` in the spec; this projection only ever sets
+ * `readOnlyHint` by default (from {@link CapabilityDef.risk}) and leaves `untrustedContentHint`
+ * unset unless a caller supplies one, since nothing in {@link CapabilityDef} implies it.
+ */
+export interface WebMcpToolAnnotations {
+    /** True when the tool never mutates state. Defaults from `capability.risk === 'read'`. */
+    readonly readOnlyHint?: boolean;
+    /** True when the tool's return value may contain content from outside the page's trust boundary. */
+    readonly untrustedContentHint?: boolean;
+}
+/**
+ * `ModelContextRegisterToolOptions` — the second positional argument to the real
+ * `registerTool(tool, options)`, per the spec IDL:
+ * `dictionary ModelContextRegisterToolOptions { AbortSignal signal; sequence<USVString> exposedTo; }`.
+ */
+export interface WebMcpRegisterToolOptions {
+    /**
+     * Aborting this unregisters the tool and rejects the in-flight `registerTool()` promise with the
+     * signal's abort reason — the spec's ONLY unregistration mechanism. There is no `unregisterTool()`
+     * in the current draft; a host that wants to drop a tool later must have registered it with a
+     * signal in the first place.
+     */
+    readonly signal?: AbortSignal;
+    /** Origins (besides same-origin, always allowed) that may see and call this tool from other documents in the same tree. */
+    readonly exposedTo?: readonly string[];
+}
+/** What a confirmation handler is asked to approve. */
+export interface WebMcpUserInteraction {
+    readonly capability: CapabilityDef;
+    readonly args: Record<string, unknown>;
+}
+/**
+ * Asks the human to approve one call before it runs. Resolve `true` to proceed, `false` to refuse.
+ *
+ * **This is Jini's hook, not the browser's.** Earlier WebMCP drafts floated a
+ * `requestUserInteraction()` on the page's model-context surface; the current draft
+ * (https://webmachinelearning.github.io/webmcp/) does not define one, so there is nothing to
+ * feature-detect and nothing standard to call. A host that wants a confirmed WebMCP tool supplies
+ * this itself.
+ *
+ * Independently re-confirmed 2026-07-28: the reference polyfill `@mcp-b/webmcp-polyfill` (the
+ * `MCP-B`/`WebMCP-org` community project, not the W3C CG spec) DOES pass a second
+ * `client: { requestUserInteraction(callback) }` argument to `execute`, as one of its own
+ * non-standard "MCPB extensions". That is further evidence the idea is real and wanted, and
+ * further confirmation it is NOT part of the standardized `ToolExecuteCallback` — whose IDL is
+ * `Promise<any> (object input)`, one argument. This module's `execute` wrapper below takes one
+ * argument for exactly that reason; a second, ignored argument from a polyfill is harmless.
+ */
+export type RequestUserInteraction = (interaction: WebMcpUserInteraction) => Promise<boolean>;
+export interface ToWebMcpToolOptions {
+    readonly requestUserInteraction?: RequestUserInteraction;
+    /**
+     * `ModelContextTool.title`. Meaningful per-capability, so pass this through {@link toWebMcpTool}
+     * (one capability) rather than {@link toWebMcpTools} (a whole manifest) — the latter shares one
+     * `options` object across every capability in the batch, and a shared title would repeat
+     * verbatim across dissimilar tools.
+     */
+    readonly title?: string;
+    /**
+     * Overrides or extends the default `annotations` (`{ readOnlyHint: capability.risk === 'read' }`).
+     * Fields set here win over the default.
+     */
+    readonly annotations?: WebMcpToolAnnotations;
+    /** See {@link WebMcpRegisterToolOptions.signal}. Safe to share across a whole {@link toWebMcpTools} batch — one `AbortController` per registration session, aborted once on teardown. */
+    readonly signal?: AbortSignal;
+    /** See {@link WebMcpRegisterToolOptions.exposedTo}. Safe to share across a whole {@link toWebMcpTools} batch when every capability in it gets the same scoping. */
+    readonly exposedTo?: readonly string[];
+}
+/** Thrown in place of executing, when a call needed confirmation and did not get it. */
+export declare class WebMcpConfirmationRequiredError extends Error {
+    readonly capabilityId: string;
+    readonly reason: 'declined' | 'no-handler';
+    constructor(capabilityId: string, reason: 'declined' | 'no-handler');
+}
+/** Whether `name` satisfies the spec's tool-name rule. Exported so a caller can pre-check a manifest without registering anything. */
+export declare function isValidWebMcpToolName(name: string): boolean;
+/**
+ * Thrown synchronously by {@link toWebMcpTool} for a capability whose `id` cannot legally become a
+ * WebMCP tool name. Distinct from {@link WebMcpConfirmationRequiredError}: this is a manifest
+ * defect caught before any registration is attempted, not a runtime refusal of a call.
+ */
+export declare class InvalidWebMcpToolNameError extends Error {
+    readonly capabilityId: string;
+    constructor(capabilityId: string);
+}
+/**
+ * Projects one capability into a WebMCP registration.
+ *
+ * **The confirmation gate is fail-closed.** A capability with `requiresConfirmation` will not run
+ * unless `options.requestUserInteraction` is supplied *and* resolves `true`. Omitting the handler
+ * does not silently downgrade to "just run it" — it makes the tool permanently refuse, which is
+ * the only safe reading of a manifest that asked for confirmation.
+ *
+ * This does not make WebMCP governed. It is a page-local gate over a path that still has no run,
+ * no principal, no `ToolExecutor` and no audit trail (see this package's `frontend-session-registry`
+ * note and §11 of the capability report). It closes the *accidental* case — a destructive
+ * capability reaching the page with nothing in front of it — not the authorization gap.
+ *
+ * @param capability - The capability to expose.
+ * @param execute - Runs the capability. Receives the raw argument object, already checked against
+ * `capability.inputSchema` — a caller-supplied value that fails validation never reaches this.
+ * @param options - Optional confirmation handler, title/annotations, and registration options
+ * (`signal`/`exposedTo`); required in practice for any capability declaring `requiresConfirmation`.
+ * @returns The registration object to hand to `registerTool`.
+ * @throws {@link InvalidWebMcpToolNameError} synchronously, if `capability.id` cannot be a WebMCP
+ * tool name.
+ * @throws {@link WebMcpConfirmationRequiredError} from `execute`, when confirmation is required
+ * and is either declined or unobtainable.
+ */
+export declare function toWebMcpTool(capability: CapabilityDef, execute: (id: string, args: Record<string, unknown>) => Promise<unknown>, options?: ToWebMcpToolOptions): WebMcpToolRegistration;
+/**
+ * Projects a whole manifest.
+ *
+ * `options` is shared across every capability — safe for `requestUserInteraction`, `signal`, and
+ * `exposedTo`, which are naturally uniform for one registration session; do not pass `title`
+ * through this one, since it would repeat verbatim across every tool in the manifest (see
+ * {@link ToWebMcpToolOptions.title}).
+ *
+ * @param capabilities - Capabilities to expose, already filtered by whatever policy applies.
+ * @param execute - Shared dispatcher, keyed by capability id.
+ * @returns One registration per capability, in manifest order.
+ * @throws {@link InvalidWebMcpToolNameError} synchronously, for the first capability whose `id`
+ * cannot be a WebMCP tool name.
+ */
+export declare function toWebMcpTools(capabilities: readonly CapabilityDef[], execute: (id: string, args: Record<string, unknown>) => Promise<unknown>, options?: ToWebMcpToolOptions): readonly WebMcpToolRegistration[];
+//# sourceMappingURL=webmcp.d.ts.map

package/dist/core/webmcp.d.ts.map

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