@jini-ai/agentic 0.3.7 → 0.4.1

package/dist/core/annotated-actions-script.js

@@ -0,0 +1,137 @@
+/**
+ * Framework-free script asset for data-toolname/data-tooldescription actions.
+ * Native tool* forms remain the browser's responsibility. No polyfill, transport,
+ * field-value reader, arbitrary selector input or cross-origin exposure is added.
+ * The host owns consent copy and its browser preference key. This string asset
+ * can be inlined into static exports without importing a DOM runtime on Node.
+ */
+export function createAnnotatedActionsScript({ preferenceKey, confirmationMessage = 'Allow this browser-agent action?', confirmationMessages = {} }, _optional = {}) {
+    const config = JSON.stringify({ preferenceKey, confirmationMessage, confirmationMessages }).replace(/</g, '\\u003c');
+    return String.raw `(function install(config) {
+    'use strict';
+    var doc = document;
+    var locale = (doc.documentElement.lang || 'en').toLowerCase();
+    var messages = config.confirmationMessages;
+    var confirmation = Object.keys(messages).find(function (key) { return key.toLowerCase() === locale; });
+    var confirmationMessage = messages[confirmation] || messages[locale.split('-')[0]] || config.confirmationMessage;
+    var stopped = false;
+    var registrations = [];
+    var observer;
+    function enabled() {
+      try { return !config.preferenceKey || localStorage.getItem(config.preferenceKey) !== 'false'; }
+      catch (_) { return true; }
+    }
+    function stripNativeForms() {
+      doc.querySelectorAll('form[toolname]').forEach(function (form) {
+        ['toolname', 'tooldescription', 'toolautosubmit'].forEach(function (name) { form.removeAttribute(name); });
+      });
+    }
+    function stop(event) {
+      stopped = true;
+      registrations.forEach(function (controller) { controller.abort(); });
+      registrations = [];
+      if (observer) observer.disconnect();
+      window.removeEventListener('storage', onStorage);
+      window.removeEventListener('pagehide', stop);
+      // A cached Document executes no scripts when the browser restores it.
+      // Reinstall on pageshow, while old callbacks remain permanently stopped.
+      if (event && event.persisted) window.addEventListener('pageshow', function () { install(config); }, { once: true });
+    }
+    function onStorage(event) {
+      if (event.key !== null && event.key !== config.preferenceKey) return;
+      if (!enabled()) { stripNativeForms(); stop(); }
+    }
+    if (!enabled()) { stripNativeForms(); return; }
+    var context = [doc.modelContext, typeof navigator !== 'undefined' && navigator.modelContext].find(function (value) {
+      return value && typeof value.registerTool === 'function';
+    });
+    if (!context || typeof context.registerTool !== 'function') return;
+    function visible(element) {
+      if (!element.isConnected || element.closest('[hidden], [inert], [aria-hidden="true"], dialog:not([open])')) return false;
+      for (var current = element; current; current = current.parentElement) {
+        var style = window.getComputedStyle(current);
+        if (style.display === 'none' || style.visibility === 'hidden' || style.visibility === 'collapse') return false;
+      }
+      return true;
+    }
+    function descriptor(element) {
+      var name = element.getAttribute('data-toolname') || '';
+      var description = element.getAttribute('data-tooldescription') || '';
+      if (!/^[A-Za-z0-9_.-]{1,128}$/.test(name) || !description.trim() || !visible(element)) return null;
+      if (element.matches(':disabled, [aria-disabled="true"]')) return null;
+      if (element.tagName === 'A') {
+        if (!element.hasAttribute('href') || element.hasAttribute('download')) return null;
+        var url;
+        try { url = new URL(element.getAttribute('href'), doc.baseURI); } catch (_) { return null; }
+        if (!/^https?:$/.test(url.protocol) || url.origin !== window.location.origin || url.username || url.password) return null;
+        return { name: name, description: description, href: url.href };
+      }
+      // Inputs and form submission are intentionally absent: declarative forms
+      // preserve native validation and human submission, with no secret fields.
+      if (element.tagName !== 'BUTTON' || element.type !== 'button') return null;
+      return { name: name, description: description, href: null };
+    }
+    function refresh() {
+      registrations.forEach(function (controller) { controller.abort(); });
+      registrations = [];
+      if (stopped || !enabled()) { stripNativeForms(); stop(); return; }
+      var counts = new Map();
+      doc.querySelectorAll('[data-toolname], form[toolname]').forEach(function (element) {
+        if (!visible(element)) return;
+        var name = element.getAttribute('data-toolname') || element.getAttribute('toolname');
+        counts.set(name, (counts.get(name) || 0) + 1);
+      });
+      doc.querySelectorAll('[data-toolname]').forEach(function (element) {
+        var action = descriptor(element);
+        if (!action || counts.get(action.name) !== 1) return;
+        var controller = new AbortController();
+        registrations.push(controller);
+        function current() {
+          var latest = descriptor(element);
+          var matches = Array.from(doc.querySelectorAll('[data-toolname], form[toolname]')).filter(function (candidate) {
+            return visible(candidate) && (candidate.getAttribute('data-toolname') || candidate.getAttribute('toolname')) === action.name;
+          });
+          if (stopped || controller.signal.aborted || !enabled() || !latest ||
+              matches.length !== 1 || latest.name !== action.name || latest.description !== action.description || latest.href !== action.href) {
+            throw new Error('Browser-agent action is unavailable');
+          }
+        }
+        var tool = {
+          name: action.name,
+          description: action.description,
+          inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+          annotations: { readOnlyHint: action.href !== null },
+          execute: async function (args) {
+            current();
+            if (!args || typeof args !== 'object' || Array.isArray(args) || Object.keys(args).length !== 0) {
+              throw new Error('This action takes no arguments');
+            }
+            if (action.href !== null) {
+              // Navigation has no click-handler side effects and cannot forward
+              // arbitrary agent-supplied URLs or use a theme's cross-origin base.
+              window.location.assign(action.href);
+              return { navigationRequested: true };
+            }
+            if (!window.confirm(confirmationMessage + '\n\n' + action.description)) {
+              throw new Error('Browser-agent action declined');
+            }
+            current();
+            element.click();
+            // Activation acknowledges the UI event, never business success.
+            return { activated: true };
+          }
+        };
+        try {
+          Promise.resolve(context.registerTool(tool, { signal: controller.signal })).catch(function () { controller.abort(); });
+        } catch (_) { controller.abort(); }
+      });
+    }
+    window.addEventListener('pagehide', stop);
+    window.addEventListener('storage', onStorage);
+    refresh();
+    observer = new MutationObserver(refresh);
+    observer.observe(doc.documentElement, { subtree: true, childList: true, attributes: true,
+      attributeFilter: ['data-toolname', 'data-tooldescription', 'toolname', 'href', 'download', 'type', 'disabled', 'aria-disabled', 'hidden', 'inert', 'aria-hidden', 'style', 'class', 'open'] });
+  })(` + config + ');';
+}
+//# sourceMappingURL=annotated-actions-script.js.map

package/dist/core/capability.d.ts

@@ -55,7 +55,10 @@ export interface CapabilityDef {
  * @param id - Capability id to resolve.
  * @returns The definition, or `undefined` when the id is not in the manifest.
  */
-export declare function findCapability(capabilities: readonly CapabilityDef[], id: string): CapabilityDef | undefined;
+export declare function findCapability({ capabilities, id }: {
+    capabilities: readonly CapabilityDef[];
+    id: string;
+}, _optional?: Record<string, never>): CapabilityDef | undefined;
 /**
  * Checks caller input against a capability's declared schema.
  *
@@ -69,7 +72,10 @@ export declare function findCapability(capabilities: readonly CapabilityDef[], i
  * @param input - Raw caller-supplied arguments.
  * @returns An error message, or `null` when the input is acceptable.
  */
-export declare function findCapabilityInputError(capability: CapabilityDef, input: Record<string, unknown>): string | null;
+export declare function findCapabilityInputError({ capability, input }: {
+    capability: CapabilityDef;
+    input: Record<string, unknown>;
+}, _optional?: Record<string, never>): string | null;
 /**
  * The capabilities a caller may use given what is currently connected.
  *
@@ -77,5 +83,8 @@ export declare function findCapabilityInputError(capability: CapabilityDef, inpu
  * @param hasSession - Whether a live frontend session is attached.
  * @returns Only the capabilities that can actually be satisfied right now.
  */
-export declare function availableCapabilities(capabilities: readonly CapabilityDef[], hasSession: boolean): readonly CapabilityDef[];
+export declare function availableCapabilities({ capabilities, hasSession }: {
+    capabilities: readonly CapabilityDef[];
+    hasSession: boolean;
+}, _optional?: Record<string, never>): readonly CapabilityDef[];
 //# sourceMappingURL=capability.d.ts.map

package/dist/core/capability.js

@@ -17,7 +17,7 @@
  * @param id - Capability id to resolve.
  * @returns The definition, or `undefined` when the id is not in the manifest.
  */
-export function findCapability(capabilities, id) {
+export function findCapability({ capabilities, id }, _optional = {}) {
     return capabilities.find((capability) => capability.id === id);
 }
 /**
@@ -33,7 +33,7 @@ export function findCapability(capabilities, id) {
  * @param input - Raw caller-supplied arguments.
  * @returns An error message, or `null` when the input is acceptable.
  */
-export function findCapabilityInputError(capability, input) {
+export function findCapabilityInputError({ capability, input }, _optional = {}) {
     const { properties, required, additionalProperties } = capability.inputSchema;
     for (const name of required ?? []) {
         if (input[name] === undefined)
@@ -73,7 +73,7 @@ export function findCapabilityInputError(capability, input) {
  * @param hasSession - Whether a live frontend session is attached.
  * @returns Only the capabilities that can actually be satisfied right now.
  */
-export function availableCapabilities(capabilities, hasSession) {
+export function availableCapabilities({ capabilities, hasSession }, _optional = {}) {
     return hasSession ? capabilities : capabilities.filter((c) => c.surface === 'server');
 }
 //# sourceMappingURL=capability.js.map

package/dist/core/dom/dom-page-driver.d.ts

@@ -4,15 +4,17 @@ export interface DomPageDriverPage {
     /** Shown to a caller by `page.find_elements`/`page.navigate`'s refusal message — see
      *  `PageSummary.label` for why this exists at all. */
     readonly label: string;
-    readonly navigate: () => void;
+    readonly navigate: (required: Record<string, never>) => void;
 }
-export interface DomPageDriverOptions {
+export interface DomPageDriverRequired {
     /** The subtree to expose. Never pass `document`. */
     readonly root: ParentNode & {
         querySelector: Element['querySelector'];
     };
     /** Page ids this driver may navigate to, each with its label and how to get there. */
     readonly pages: Readonly<Record<string, DomPageDriverPage>>;
+}
+export interface DomPageDriverOptions {
     /**
      * The id of the page currently shown, reported on every element.
      *
@@ -30,7 +32,9 @@ export interface DomPageDriverOptions {
  * @param options - The subtree, the navigable pages, and the current page id.
  * @returns A driver ready to hand to `executePageCapability`.
  */
-export declare function createDomPageDriver(options: DomPageDriverOptions): PageDriver;
+export declare function createDomPageDriver({ root, pages }: DomPageDriverRequired, options?: DomPageDriverOptions): PageDriver;
 /** Reads the current page's `data-agent-page`, for hosts that tag the body. */
-export declare function currentAgentPage(root: ParentNode): string | undefined;
+export declare function currentAgentPage({ root }: {
+    root: ParentNode;
+}, _optional?: Record<string, never>): string | undefined;
 //# sourceMappingURL=dom-page-driver.d.ts.map

package/dist/core/dom/dom-page-driver.js

@@ -228,8 +228,7 @@ function describe(element, page) {
  * @param options - The subtree, the navigable pages, and the current page id.
  * @returns A driver ready to hand to `executePageCapability`.
  */
-export function createDomPageDriver(options) {
-    const { root, pages } = options;
+export function createDomPageDriver({ root, pages }, options = {}) {
     /**
      * The page a specific element belongs to — its own nearest `[data-agent-page]` ancestor, not a
      * single document-wide guess.
@@ -257,7 +256,7 @@ export function createDomPageDriver(options) {
      * publishes the same handle twice makes `find`'s single-match resolution ambiguous — surfaced
      * here so both callers below can refuse rather than silently pick one.
      */
-    const findAll = (handle) => Array.from(root.querySelectorAll(resolveHandleSelector(handle)))
+    const findAll = (handle) => Array.from(root.querySelectorAll(resolveHandleSelector({ handle })))
         .filter((element) => !isPrivate(element));
     /**
      * More than one element answers to the same handle — a page-authoring bug (duplicate
@@ -312,7 +311,7 @@ export function createDomPageDriver(options) {
         return candidate ?? element;
     };
     return {
-        async findElements(filter) {
+        async findElements(_required, filter = {}) {
             const found = Array.from(root.querySelectorAll(`[${AGENT_ELEMENT_ATTRIBUTE}]`))
                 .filter((element) => !isPrivate(element))
                 .map((element) => describe(element, pageOf(element)))
@@ -327,16 +326,16 @@ export function createDomPageDriver(options) {
                     || element.label.toLowerCase().includes(query);
             });
         },
-        async listPages() {
+        async listPages(_required, _optional = {}) {
             // `Object.entries`, same own-enumerable-keys-only guarantee `Object.keys` gives `navigate`'s
             // own `hasOwnProperty` check above — no risk of a `pages.label`/`pages.navigate`-shaped
             // prototype entry leaking in as a fake page id.
             return Object.entries(pages).map(([id, page]) => ({ id, label: page.label }));
         },
-        async describeField(handle) {
+        async describeField({ handle }, _optional = {}) {
             return fieldDescriptorOf(controlOf(find(handle)));
         },
-        async describeState(handle) {
+        async describeState({ handle }, _optional = {}) {
             // Unlike every other method here, a handle that no longer resolves is an answer rather than
             // an error: an element that a click removed is exactly what the caller is asking about. A
             // handle resolving to *more than one* element is a different situation entirely — not an
@@ -402,7 +401,7 @@ export function createDomPageDriver(options) {
          * would hang for the whole life of a backgrounded tab; without the frames every write would
          * report its own target unchanged, because the read would beat the render.
          */
-        async settle() {
+        async settle(_required, _optional = {}) {
             await new Promise((resolve) => {
                 let timer;
                 // No re-entry guard: whichever side loses the race calls this again, and both of its
@@ -422,7 +421,7 @@ export function createDomPageDriver(options) {
                     raf(() => raf(finish));
             });
         },
-        async highlight(handle, durationMs) {
+        async highlight({ handle, durationMs }, _optional = {}) {
             const element = find(handle);
             // Same refusal as `click()`, for the same reason: an SVG (or other non-HTMLElement) target
             // has no `.style` to draw an outline on, so silently returning here drew nothing while
@@ -448,16 +447,16 @@ export function createDomPageDriver(options) {
             }, durationMs);
             highlights.set(handle, { timer, restore });
         },
-        async scrollTo(handle) {
+        async scrollTo({ handle }, _optional = {}) {
             find(handle).scrollIntoView({ behavior: 'smooth', block: 'center' });
         },
-        async click(handle) {
+        async click({ handle }, _optional = {}) {
             const control = controlOf(find(handle));
             if (!(control instanceof HTMLElement))
                 throw new Error(`"${handle}" is not clickable`);
             control.click();
         },
-        async fill(handle, text) {
+        async fill({ handle, text }, _optional = {}) {
             const control = controlOf(find(handle));
             if (isEditableRegion(control)) {
                 // A contenteditable region has no `value`; its content *is* its children, and a real
@@ -483,7 +482,7 @@ export function createDomPageDriver(options) {
             control.dispatchEvent(new Event('input', { bubbles: true }));
             control.dispatchEvent(new Event('change', { bubbles: true }));
         },
-        async selectOption(handle, option, selected = true) {
+        async selectOption({ handle, option }, { selected = true } = {}) {
             const control = controlOf(find(handle));
             if (!(control instanceof HTMLSelectElement)) {
                 throw new Error(`"${handle}" is not a dropdown`);
@@ -518,8 +517,8 @@ export function createDomPageDriver(options) {
                 // the same shape of problem regardless of which side authored it. `handle` needs no
                 // treatment: it is already validated ASCII, length-capped by isValidElementHandle before
                 // this driver is ever called.
-                const safeOption = normalizeAgentLabel(option).text;
-                const available = options.map((entry) => normalizeAgentLabel(entry.text.trim()).text)
+                const safeOption = normalizeAgentLabel({ raw: option }).text;
+                const available = options.map((entry) => normalizeAgentLabel({ raw: entry.text.trim() }).text)
                     .filter((text) => text.length > 0);
                 throw new Error(`"${safeOption}" is not an option of "${handle}". Available: ${available.length > 0 ? available.join(', ') : '(none)'}`);
             }
@@ -535,7 +534,7 @@ export function createDomPageDriver(options) {
                 // ignoring this would tell the caller a deselect happened when nothing changed, and clearing
                 // the control would invent a third state (no selection) that a native <select> cannot hold.
                 throw new Error(`"${handle}" is a single-select; its choice cannot be removed, only replaced — `
-                    + `select a different option instead of deselecting "${normalizeAgentLabel(option).text}"`);
+                    + `select a different option instead of deselecting "${normalizeAgentLabel({ raw: option }).text}"`);
             }
             else {
                 // Same prototype-setter dance as `fill`, for the same reason: React tracks the previous
@@ -549,7 +548,7 @@ export function createDomPageDriver(options) {
             control.dispatchEvent(new Event('input', { bubbles: true }));
             control.dispatchEvent(new Event('change', { bubbles: true }));
         },
-        async navigate(page) {
+        async navigate({ page }, _optional = {}) {
             // `hasOwnProperty`, not `pages[page]`: a plain object literal inherits everything
             // `Object.prototype` contributes, so a bare lookup answered `navigate("constructor")` with
             // the `Object` constructor — a function the host never published, which this then called,
@@ -564,8 +563,8 @@ export function createDomPageDriver(options) {
             // the executor entirely, hands `page` in unsanitized, so the same bound-and-strip treatment
             // applies here too rather than assuming the only caller is the one that already checked.
             if (!published)
-                throw new Error(`"${normalizeAgentLabel(page).text}" is not a published page`);
-            pages[page].navigate();
+                throw new Error(`"${normalizeAgentLabel({ raw: page }).text}" is not a published page`);
+            pages[page].navigate({});
         },
     };
 }
@@ -616,7 +615,7 @@ function fillEditableRegion(control, text) {
     control.dispatchEvent(new Event('input', { bubbles: true }));
 }
 /** Reads the current page's `data-agent-page`, for hosts that tag the body. */
-export function currentAgentPage(root) {
+export function currentAgentPage({ root }, _optional = {}) {
     const tagged = root.querySelector(`[${AGENT_PAGE_ATTRIBUTE}]`);
     return tagged?.getAttribute(AGENT_PAGE_ATTRIBUTE) ?? undefined;
 }

package/dist/core/dom/index.d.ts

@@ -3,15 +3,15 @@
  *
  * The one `PageDriver` (see `@jini-ai/agentic`'s `page-driver.ts`) that reads and writes a real DOM
  * subtree. Split into its own entry point, compiled under its own `DOM`-lib `tsconfig.dom.json`,
- * so the rest of this package can stay provably DOM-free — see source-map.md's "The DOM split".
+ * so the rest of this package can stay provably DOM-free — see archived provenance ledger's "The DOM split".
  *
  * `@jini-ai/chat-react` is this package's one in-repo consumer today.
  */
-export { createDomPageDriver, currentAgentPage, type DomPageDriverOptions, type DomPageDriverPage, } from './dom-page-driver.js';
+export { createDomPageDriver, currentAgentPage, type DomPageDriverRequired, type DomPageDriverOptions, type DomPageDriverPage, } from './dom-page-driver.js';
 /**
  * WebMCP feature detection — moved 2026-07-26 from `@jini-ai/ui`'s `agent-tools/model-context.ts`
  * (plan §8 step 6). See `model-context.ts`'s module doc for why it lives here rather than
  * alongside `../webmcp.ts`'s DOM-free projection.
  */
-export { getAgentModelContext, type AgentModelContextLike, type AgentModelContextToolRegistration, } from './model-context.js';
+export { getAgentModelContext, type AgentModelContextLike, type ModelContextHostPort, type AgentModelContextRegisterToolOptions, type AgentModelContextToolRegistration, } from './model-context.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/core/dom/index.js

@@ -3,7 +3,7 @@
  *
  * The one `PageDriver` (see `@jini-ai/agentic`'s `page-driver.ts`) that reads and writes a real DOM
  * subtree. Split into its own entry point, compiled under its own `DOM`-lib `tsconfig.dom.json`,
- * so the rest of this package can stay provably DOM-free — see source-map.md's "The DOM split".
+ * so the rest of this package can stay provably DOM-free — see archived provenance ledger's "The DOM split".
  *
  * `@jini-ai/chat-react` is this package's one in-repo consumer today.
  */

package/dist/core/dom/model-context.d.ts

@@ -1,8 +1,8 @@
 /**
  * @module dom/model-context
  *
- * Feature-detected access to the browser's (draft) WebMCP surface —
- * `document.modelContext`, falling back to the deprecated `navigator.modelContext`
+ * Host-injected access to the browser's (draft) WebMCP surface —
+ * the host supplies `document.modelContext`, followed by the deprecated `navigator.modelContext`
  * alias (the spec moved the getter from Navigator to Document in 2026;
  * see the polyfill ecosystem's own back-compat posture). No `@mcp-b/*` or
  * other WebMCP package dependency: this module only needs the shape, the
@@ -11,11 +11,11 @@
  * bridges already use.
  * A page that wants `document.modelContext` to actually exist in a browser
  * without native support must load a real polyfill itself (e.g.
- * `@mcp-b/webmcp-polyfill`) — this module only ever reads what's there.
+ * `@mcp-b/webmcp-polyfill`) — this module adapts only the candidates the host supplies.
  *
  * Moved 2026-07-26 from `@jini-ai/ui/src/features/agent-tools/model-context.ts` (plan §4/§8 step 6).
  * Lives under `src/dom/`, not alongside `../webmcp.ts`'s pure `CapabilityDef` → WebMCP-tool
- * projection, because it reads `document`/`navigator` — `webmcp.ts`'s own module doc is explicit
+ * projection, because it adapts the native browser API — `webmcp.ts`'s own module doc is explicit
  * that "that detection is deliberately NOT here: it touches browser globals, and this package
  * holds none," which is exactly the DOM-free guarantee `src/dom/` exists to carve an exception
  * for. See `dom/index.ts`'s re-export of this module.
@@ -56,14 +56,24 @@ export interface AgentModelContextLike {
      * ModelContextRegisterToolOptions options = {})` — it is **async**. Callers must not assume it
      * has taken effect synchronously, and must not let a rejection escape.
      */
-    registerTool(tool: AgentModelContextToolRegistration, options?: AgentModelContextRegisterToolOptions): Promise<void>;
+    registerTool(required: {
+        tool: AgentModelContextToolRegistration;
+    }, options?: AgentModelContextRegisterToolOptions): Promise<void>;
     /**
      * NOT in the spec — the draft's only unregistration mechanism is aborting the `signal` passed to
      * `registerTool`. Kept optional purely so a polyfill that happens to expose one can be used;
      * never rely on its presence, and always pass a `signal` as the real cleanup path.
      */
-    unregisterTool?(name: string): void;
+    unregisterTool?(required: {
+        name: string;
+    }, _optional?: Record<string, never>): void;
 }
-/** Returns the page's WebMCP surface if one is installed (native or polyfilled), or `undefined`. */
-export declare function getAgentModelContext(): AgentModelContextLike | undefined;
+/** Ordered host candidates: modern document first, then any deprecated navigator alias. */
+export interface ModelContextHostPort {
+    candidates(required: Record<string, never>): readonly unknown[];
+}
+/** Adapts the first installed native surface to Jini's argument-object port. */
+export declare function getAgentModelContext({ host }: {
+    host: ModelContextHostPort;
+}, _optional?: Record<string, never>): AgentModelContextLike | undefined;
 //# sourceMappingURL=model-context.d.ts.map

package/dist/core/dom/model-context.js

@@ -1,8 +1,8 @@
 /**
  * @module dom/model-context
  *
- * Feature-detected access to the browser's (draft) WebMCP surface —
- * `document.modelContext`, falling back to the deprecated `navigator.modelContext`
+ * Host-injected access to the browser's (draft) WebMCP surface —
+ * the host supplies `document.modelContext`, followed by the deprecated `navigator.modelContext`
  * alias (the spec moved the getter from Navigator to Document in 2026;
  * see the polyfill ecosystem's own back-compat posture). No `@mcp-b/*` or
  * other WebMCP package dependency: this module only needs the shape, the
@@ -11,11 +11,11 @@
  * bridges already use.
  * A page that wants `document.modelContext` to actually exist in a browser
  * without native support must load a real polyfill itself (e.g.
- * `@mcp-b/webmcp-polyfill`) — this module only ever reads what's there.
+ * `@mcp-b/webmcp-polyfill`) — this module adapts only the candidates the host supplies.
  *
  * Moved 2026-07-26 from `@jini-ai/ui/src/features/agent-tools/model-context.ts` (plan §4/§8 step 6).
  * Lives under `src/dom/`, not alongside `../webmcp.ts`'s pure `CapabilityDef` → WebMCP-tool
- * projection, because it reads `document`/`navigator` — `webmcp.ts`'s own module doc is explicit
+ * projection, because it adapts the native browser API — `webmcp.ts`'s own module doc is explicit
  * that "that detection is deliberately NOT here: it touches browser globals, and this package
  * holds none," which is exactly the DOM-free guarantee `src/dom/` exists to carve an exception
  * for. See `dom/index.ts`'s re-export of this module.
@@ -28,17 +28,14 @@
  * fixture: a raw (non-`toWebMcpTool`) registration carrying a `title` failed TypeScript's
  * excess-property check against the un-widened type here.
  */
-function isModelContext(value) {
-    return typeof value === 'object' && value !== null && typeof value.registerTool === 'function';
-}
-/** Returns the page's WebMCP surface if one is installed (native or polyfilled), or `undefined`. */
-export function getAgentModelContext() {
-    const doc = globalThis.document;
-    if (isModelContext(doc?.modelContext))
-        return doc.modelContext;
-    const nav = globalThis.navigator;
-    if (isModelContext(nav?.modelContext))
-        return nav.modelContext;
+import { adaptNativeModelContext } from './native-model-context.js';
+/** Adapts the first installed native surface to Jini's argument-object port. */
+export function getAgentModelContext({ host }, _optional = {}) {
+    for (const value of host.candidates({})) {
+        const context = adaptNativeModelContext({ value });
+        if (context)
+            return context;
+    }
     return undefined;
 }
 //# sourceMappingURL=model-context.js.map

package/dist/core/dom/native-model-context.d.ts

@@ -0,0 +1,6 @@
+import type { AgentModelContextLike } from './model-context.js';
+/** Preserve native receiver binding and stable port identity across feature detection. */
+export declare function adaptNativeModelContext({ value }: {
+    value: unknown;
+}): AgentModelContextLike | undefined;
+//# sourceMappingURL=native-model-context.d.ts.map

package/dist/core/dom/native-model-context.js

@@ -0,0 +1,19 @@
+const adapters = new WeakMap();
+/** Preserve native receiver binding and stable port identity across feature detection. */
+export function adaptNativeModelContext({ value }) {
+    if (typeof value !== 'object' || value === null || typeof value.registerTool !== 'function')
+        return undefined;
+    const existing = adapters.get(value);
+    if (existing)
+        return existing;
+    const native = value;
+    const adapter = {
+        registerTool: ({ tool }, options) => native.registerTool(tool, options),
+        ...(typeof native.unregisterTool === 'function'
+            ? { unregisterTool: ({ name }) => native.unregisterTool(name) }
+            : {}),
+    };
+    adapters.set(value, adapter);
+    return adapter;
+}
+//# sourceMappingURL=native-model-context.js.map

package/dist/core/element-handles.d.ts

@@ -28,7 +28,9 @@ export declare const AGENT_ELEMENT_ROLES: readonly AgentElementRole[];
  * @param handle - Candidate handle, typically caller-supplied.
  * @returns True when it is safe to interpolate into an attribute selector.
  */
-export declare function isValidElementHandle(handle: string): boolean;
+export declare function isValidElementHandle({ handle }: {
+    handle: string;
+}, _optional?: Record<string, never>): boolean;
 /**
  * Builds the one selector shape this system will ever resolve.
  *
@@ -36,7 +38,9 @@ export declare function isValidElementHandle(handle: string): boolean;
  * @returns The attribute selector for that handle.
  * @throws If the handle is not valid — never fall back to treating it as a raw selector.
  */
-export declare function resolveHandleSelector(handle: string): string;
+export declare function resolveHandleSelector({ handle }: {
+    handle: string;
+}, _optional?: Record<string, never>): string;
 /** A tagged element as described back to a caller. `label` is page-authored, so it is untrusted. */
 export interface AgentElementDescriptor {
     readonly handle: string;

package/dist/core/element-handles.js

@@ -25,7 +25,7 @@ const MAX_HANDLE_LENGTH = 128;
  * @param handle - Candidate handle, typically caller-supplied.
  * @returns True when it is safe to interpolate into an attribute selector.
  */
-export function isValidElementHandle(handle) {
+export function isValidElementHandle({ handle }, _optional = {}) {
     return handle.length > 0 && handle.length <= MAX_HANDLE_LENGTH && HANDLE_PATTERN.test(handle);
 }
 /**
@@ -35,8 +35,8 @@ export function isValidElementHandle(handle) {
  * @returns The attribute selector for that handle.
  * @throws If the handle is not valid — never fall back to treating it as a raw selector.
  */
-export function resolveHandleSelector(handle) {
-    if (!isValidElementHandle(handle)) {
+export function resolveHandleSelector({ handle }, _optional = {}) {
+    if (!isValidElementHandle({ handle })) {
         throw new Error(`invalid element handle "${handle.slice(0, MAX_HANDLE_LENGTH)}": `
             + 'handles are lowercase words joined by single hyphens, and are never CSS selectors');
     }